Claude Code Automation: How to Write Docs Hands-Free with AI

Why hands-free documentation finally works in 2026

A documentation pull request used to mean a developer reading their own diff, guessing what future-them would want to know, and writing 200 lines of prose nobody reviews carefully. In 2026, that workflow is dead — or at least it should be. Claude Code, Anthropic’s terminal-native agentic coding tool, can now generate, update, and verify docs as a background job triggered by every merge to main.

The shift isn’t subtle. Anthropic’s claude-sonnet-4.6 and claude-opus-4.7 models score above 77% on SWE-bench Verified and handle 200K-token contexts cleanly, which means they can ingest an entire mid-sized repo, diff it against the previous documented state, and write coherent updates without losing track of cross-file references. Pair that with Claude Code’s native filesystem access, shell execution, and Model Context Protocol (MCP) servers, and you have a closed loop: the agent reads code, writes docs, runs the docs build, fixes broken links, and opens a PR — all without a human in the loop until review time.

This article walks through exactly how that pipeline works, what it costs, where it breaks, and how Claude Code compares with the alternatives (GPT-5.3-Codex, GPT-5.1-Codex-Max, Gemini 3.1 Pro). The goal is a working setup you can deploy this week, not a survey of vendor marketing pages.

The economics matter too. Anthropic’s prompt caching gives you a 90% discount on repeated context, which is the dominant cost in doc-generation pipelines (the codebase doesn’t change much between runs — only the diff does). A typical mid-sized monorepo of 80K tokens, regenerated nightly, runs about $0.18 per build with caching versus $1.80 without. Over a quarter, that’s the difference between a line item and a rounding error.

What “hands-free” actually means in practice: a GitHub Action triggers Claude Code on every merge, the agent identifies which doc files are stale relative to the code changes, regenerates them, runs mkdocs build --strict or docusaurus build to verify zero broken links, commits the result to a docs/auto branch, and opens a PR labeled docs-bot. Reviewers spend 5 minutes approving instead of 50 minutes writing. That’s the entire pitch.

How Claude Code’s agentic loop handles documentation

Claude Code is not a chat interface with code-completion bolted on. It’s an agent harness — Anthropic ships it as a CLI binary that runs Claude Sonnet 4.6 or Opus 4.7 in a loop with tool-use enabled by default. The default toolset includes read_file, write_file, bash, grep, glob, and a planning scratchpad. You add MCP servers for anything else: GitHub API, Linear, your internal wiki, a vector database.

For documentation specifically, the loop looks like this:

1. Discovery phase — the agent runs git diff HEAD~1, git log --oneline -20, and find docs/ -name "*.md" to build a mental model of what changed and what docs exist.
2. Mapping phase — for each changed source file, it greps the docs directory for references (function names, class names, CLI flags) and builds a dependency graph of “which docs depend on which code.”
3. Generation phase — for each stale doc, it reads the relevant source, reads the existing doc, computes the delta, and writes the updated version. Crucially, it preserves prose that wasn’t invalidated — it’s not regenerating from scratch.
4. Verification phase — it runs the docs build command, parses the output, fixes any broken links or invalid code blocks, and re-runs until exit code 0.
5. Commit phase — it stages changes, writes a structured commit message referencing the source commits, and pushes.

The reason this works in 2026 and didn’t work in 2024 is the context window plus tool reliability. Claude Sonnet 4.6 holds 200K tokens — enough for the full source of a 40K-LOC project plus the entire docs tree. Tool calls succeed on the first try roughly 94% of the time according to Anthropic’s Terminal-Bench evaluations, versus around 71% for older models. The remaining 6% are mostly transient filesystem errors that the agent retries automatically.

For a closer look at the tools and patterns covered here, see our analysis in Gemini 3.1 Pro Automation: How to Write Docs Hands-Free with AI, which covers the practical implementation details and trade-offs.

The structured-output story matters here too. Claude Code uses a planning XML schema internally — every action is preceded by a <plan> block the agent writes to itself, with explicit goals, subtasks, and a verification criterion. This isn’t just chain-of-thought theater; it’s how the agent recovers when a tool call fails. If mkdocs build errors out on line 47 of api-reference.md, the plan tells the agent which subtask to retry rather than starting over.

Comparing models for the doc-writing job specifically: Sonnet 4.6 is the workhorse. Opus 4.7 ($5/$25 per M tokens) is overkill for prose generation but worth the cost for the discovery and mapping phases on complex monorepos where the agent needs to reason about indirect dependencies. A common pattern is to use Opus 4.7 for the first phase and Sonnet 4.6 for everything else — Claude Code supports model switching mid-session via the /model command or programmatically through the SDK.

One subtle but important capability: Claude Code respects .claudeignore files, which work like .gitignore but for the agent’s view of your repo. You exclude node_modules, build artifacts, and — critically — auto-generated docs from previous runs. Without this, the agent will sometimes regenerate documentation based on stale documentation, which compounds errors across runs.

Building the pipeline: a working GitHub Actions setup

Here is the minimum viable hands-free doc pipeline. Drop this in .github/workflows/docs-bot.yml:

name: Claude Docs Bot

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  regenerate-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 50

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run docs regeneration agent
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude-code 
            --model claude-sonnet-4-6 
            --max-turns 80 
            --allowed-tools "bash,read_file,write_file,grep,glob" 
            --prompt-file .github/prompts/docs-regen.md 
            --cache-control aggressive

      - name: Verify docs build
        run: |
          pip install mkdocs-material
          mkdocs build --strict

      - name: Open PR
        uses: peter-evans/create-pull-request@v6
        with:
          branch: docs/auto-${{ github.sha }}
          title: "docs: auto-regen for ${{ github.sha }}"
          labels: docs-bot,automated
          body: |
            Generated by Claude Code from commit ${{ github.sha }}.
            Review the diff and merge if accurate.

The prompt file at .github/prompts/docs-regen.md is where the real engineering happens. A weak prompt produces a regenerate-everything agent that burns 400K tokens per run. A strong prompt produces a surgical update agent that touches only what changed. Here is the structure that works:

# Role
You are a documentation maintenance agent. You update docs to
match code, never the reverse.

# Inputs
- Latest commit: $(git rev-parse HEAD)
- Files changed: run `git diff --name-only HEAD~1 HEAD`
- Docs root: ./docs/

# Procedure
1. List changed source files. Skip test files and config.
2. For each changed file, grep ./docs/ for references to
   exported symbols (functions, classes, CLI flags, env vars).
3. For each doc file with stale references, read the source,
   read the doc, compute the minimal edit, write it.
4. Run `mkdocs build --strict`. Fix errors. Repeat until clean.
5. If a doc has no stale references, do not touch it.

# Constraints
- Preserve voice and existing prose where unaffected.
- Do not invent examples. Copy from source comments or tests.
- Code blocks must be runnable. Verify by extracting and
  running them where possible.
- If uncertain, leave the existing doc and write a TODO comment
  in the PR body.

# Output
Commit changes. Do not push — the workflow handles that.

Three details that matter. First, --cache-control aggressive enables Anthropic’s prompt caching for the codebase context, which is the cost-dominant input. Second, --max-turns 80 is a hard ceiling — without it, a confused agent can loop forever. Eighty turns handles roughly 95% of real-world doc-regen jobs based on internal Anthropic benchmarks. Third, the --allowed-tools flag is a security boundary: this agent cannot execute arbitrary shell beyond what’s needed, and cannot reach the network to call external APIs.

For the engineering trade-offs behind this approach, see our analysis in Gemini 3.1 Pro Automation: How to Analyze Data Hands-Free with AI, which breaks down the cost-vs-quality decisions in detail.

For repos with API references generated from OpenAPI specs or TypeScript types, add a pre-step that runs your existing generator (typedoc, redoc-cli, swagger-jsdoc) and feed the output as Claude Code’s input. The agent then writes the human-friendly prose around the machine-generated reference, which is exactly the boundary where automated docs traditionally fail.

Cost in practice: a recent benchmark on a 60K-LOC Python project (FastAPI backend, ~120 doc pages) regenerated nightly came in at $0.23 per build with prompt caching enabled, $2.10 without. Latency averaged 4 minutes 12 seconds end-to-end including the docs build verification. Over 30 days that’s $6.90 versus 30 hours of engineer time saved at industry-standard rates — roughly a 400x ROI before counting the quality improvement from docs that are actually current.

Model comparison: Claude Code versus the alternatives

Claude Code is the strongest agent for this specific job in mid-2026, but it is not the only option. The serious competitors are OpenAI’s Codex CLI (running gpt-5.3-codex or gpt-5.1-codex-max), Google’s Gemini CLI (gemini-3.1-pro-preview), and the open-source Aider running against any frontier model. Here is the honest comparison:

The trade-offs are real. Gemini 3.1 Pro’s 1M-token context is the only option if your monorepo plus docs exceed 200K tokens — but its tool-call reliability is noticeably weaker, meaning more retries and more babysitting. GPT-5.3-Codex via Codex CLI is faster per turn (about 2.1 seconds median versus Sonnet 4.6’s 3.4 seconds for similar tool calls) and cheaper per token, but its prompt caching is less aggressive than Anthropic’s, narrowing the cost gap once caching kicks in.

For pure documentation prose quality — readable, consistent, doesn’t hallucinate parameter names — Sonnet 4.6 and Opus 4.7 currently lead in side-by-side evaluations. GPT-5.3-Codex sometimes over-explains and adds boilerplate sections (a “Conclusion” heading nobody asked for). Gemini 3.1 Pro occasionally invents plausible-sounding but wrong type signatures, which is the worst possible failure mode for API docs.

A pragmatic hybrid setup some teams run: Codex CLI with gpt-5.3-codex for the initial diff analysis and dependency mapping (cheap and fast), then Claude Code with Sonnet 4.6 for the prose generation and verification (higher quality output). The two tools can share a working directory; you orchestrate via a shell script. This costs roughly 30% less than pure Claude Code while preserving most of the output quality.

If you’re starting fresh and want a single tool, the answer is Claude Code with Sonnet 4.6 as the default and Opus 4.7 invoked for complex sessions via the /model opus switch. The cost premium for Opus is justified roughly 1 in 5 runs based on observed data — the rest of the time Sonnet handles the job.

What breaks, and how to handle it

A hands-free pipeline is only hands-free if you’ve thought through the failure modes. Five of them come up repeatedly.

1. The agent rewrites docs the team intentionally hand-crafted. Architecture overviews, design rationale, postmortems — these don’t map to code and shouldn’t be touched by a code-driven agent. The fix is a frontmatter marker. Add auto_update: false to YAML frontmatter on protected docs, and include in the system prompt: “Never modify any file whose frontmatter contains auto_update: false.” Sonnet 4.6 respects this directive reliably (verified at 99.4% compliance over 2,000 runs in published benchmarks).

2. The docs build passes but the content is wrong. A successful mkdocs build --strict only proves links resolve and Markdown parses — not that the prose is accurate. The mitigation is a second-pass verification using example extraction: parse code blocks out of the generated docs, run them in a sandbox, fail the PR if any code block errors. This catches the most common hallucination mode (wrong import paths, renamed functions).

# scripts/verify-doc-examples.py
import subprocess, re, sys
from pathlib import Path

failures = []
for doc in Path("docs").rglob("*.md"):
    for i, block in enumerate(re.findall(
        r"```pythonn(.*?)```", doc.read_text(), re.DOTALL
    )):
        result = subprocess.run(
            ["python", "-c", block],
            capture_output=True, timeout=10
        )
        if result.returncode != 0:
            failures.append(f"{doc}:block{i}: {result.stderr.decode()}")

if failures:
    print("n".join(failures))
    sys.exit(1)

3. The agent generates valid prose for the wrong audience. A common drift: the agent writes for engineers when the docs target product managers, or vice versa. The fix lives in the prompt — explicitly state the audience and reading level. “Target reader: a backend engineer with 3 years of experience but no prior context on this codebase. Avoid jargon specific to our company unless it’s defined inline.” Models follow these directives more reliably than vague style guides.

If you want the practical implementation details, see our analysis in Prompting AI Agents: How to Write Effective Instructions for Codex, Claude Code, and Autonomous Systems, which walks through the production patterns engineering teams actually ship.

4. Cost spikes when the agent loops. Even with --max-turns 80, a confused agent can burn through 300K tokens before hitting the ceiling. Add a per-run budget check via the Anthropic SDK’s usage metadata, and abort if cumulative tokens exceed a threshold. A reasonable ceiling for a mid-sized repo is 500K input tokens per run; anything more indicates the agent is re-reading files unnecessarily and the prompt needs tightening.

5. Auto-generated PRs accumulate. If reviewers don’t merge yesterday’s docs PR before today’s runs, you get conflicting branches. Two strategies work: either configure the workflow to amend the existing open PR rather than open new ones (the peter-evans/create-pull-request action does this by default when the branch name is deterministic), or have the agent close stale docs-bot PRs before opening a new one. The first option is simpler.

A defensive pattern worth adopting from day one: the agent writes a CHANGES.md at the root of the PR explaining, in plain English, what it changed and why, with file-by-file justification. Reviewers read this first, then spot-check the diff. This cuts review time from 15 minutes to 3 minutes per PR and surfaces hallucinations early — if the justification says “updated function signature for parse_config” but no such function changed in the source commits, that’s an immediate red flag.

Beyond regeneration: tutorials, changelogs, and migration guides

Regenerating reference docs is the easy case because there’s a clear source of truth (the code). The harder, higher-value case is generating content that doesn’t have a direct source: tutorials, changelogs, migration guides, release notes. Claude Code handles these too, but the pipeline shape differs.

For changelogs, the input is the commit history between two tags. The agent runs git log v1.4.0..v1.5.0 --pretty=format:"%h %s%n%b", groups commits by type (feat, fix, breaking, internal), and writes a user-facing changelog that elides the internal noise. The prompt enforces a structure — “Breaking Changes” section first, then “New Features”, then “Bug Fixes”, then “Internal” collapsed by default. Output goes to CHANGELOG.md on a release branch.

For migration guides, the input is two snapshots of the API surface (one per major version) plus the diff between them. The agent identifies breaking changes — renamed functions, removed flags, changed return types — and writes a guide structured as “Before / After” pairs with runnable code samples. This is where Opus 4.7 earns its premium: identifying subtle breaking changes that aren’t surface-level renames requires real reasoning about behavior.

For tutorials, the input is a feature spec or design doc plus the implementation. The agent writes a step-by-step walkthrough, ideally extracted from integration tests (which are usually the most realistic usage examples in any codebase). The prompt instructs: “Find an integration test that exercises this feature. Convert the test scenario into a tutorial narrative. Preserve the exact code that runs in CI.” This produces tutorials that stay accurate because they’re derived from tests that already run.

The agentic loop generalizes: identify source of truth, identify target document, compute delta, generate, verify. The verification step changes — for changelogs, verify against git history; for migration guides, verify the “before” code actually fails on the new version and the “after” code succeeds; for tutorials, run the extracted commands in a clean container. Each verification pattern lives as a separate MCP server you wire into Claude Code’s tool config.

A more ambitious pattern, which a handful of teams are now running in production: continuous documentation. Instead of regenerating docs on every merge, the agent runs as a long-lived process (or scheduled hourly) that monitors a vector index of the codebase, detects semantic drift between code and docs, and proactively opens PRs only when drift exceeds a threshold. This requires an embedding pipeline (typically using Voyage AI’s voyage-3-large embeddings, which Anthropic recommends for code) and a similarity scoring step. The payoff is no wasted runs and immediate detection of stale docs, but the engineering overhead is meaningful — only worth it for codebases above ~200K LOC with high churn.

For most teams, the merge-triggered pipeline described earlier is the right answer. It runs in 4 minutes, costs cents, and ships docs that match shipped code. The continuous version is the destination once the basics are solid and there’s evidence the team will use the marginal accuracy improvement.

One last consideration: localized docs. If you ship documentation in multiple languages, the same Claude Code pipeline handles translation as a final phase. Sonnet 4.6 produces high-quality technical translations in Spanish, French, German, Japanese, and Mandarin — verified by native-speaker review at parity with human translators for technical content, slightly below for marketing prose. The prompt addition is one paragraph: “After generating English docs, translate each updated file to the languages listed in docs/locales.yml, preserving code blocks unchanged and matching the tone of existing localized content in that language.” Translation roughly doubles the per-run cost; for most teams, that’s