Claude Code for documentation: write, update and check docs from your code

Can Claude Code write and maintain documentation?

Yes. Claude Code reads your actual code, so it can write docstrings, READMEs, API references, runbooks and architecture explainers that match what the code does, and it can update them when the code changes. Your job shifts from writing every line to reviewing for accuracy and deciding what readers need.

Documentation is a good fit for an agent because the source of truth sits right next to it. Claude Code can read the function, run the example to check it works, and edit the doc in the same session. This guide covers what it can do, a workflow, prompts, helpful skills, how to keep docs in sync automatically, and the limits to watch.

What documentation can Claude Code produce?

• Code comments and docstrings. The common workflows page walks through finding undocumented functions, adding JSDoc comments, improving them with examples and checking them against your project standards.
• READMEs and onboarding guides. Claude explores the repo, works out how to install and run it, and writes it down. Ask it to actually run the setup steps so the README is tested, not guessed.
• Architecture explainers. Anthropic's prompt library includes "explain how the payment retry logic works as an HTML page with a diagram, then open it in my browser." On Pro, Max, Team and Enterprise plans, Claude Code can also publish pages like that as artifacts you can share.
• Runbooks. In Anthropic's write-up on how its teams use Claude Code, "The Security Engineering team has Claude ingest multiple documentation sources to create markdown runbooks and troubleshooting guides."
• Docs sites. Claude Code works in any directory, including a documentation folder or any collection of Markdown files, where it can search, edit and reorganize content.
• Changelogs and release notes. Pipe recent commits into claude -p and ask for a summary written for users.

What does a good documentation workflow look like?

1. Set the house style. Run /init, then add your docs rules to CLAUDE.md: audience, voice, heading style, terminology and how code samples look. The CLAUDE.md guide covers the format.
2. Find the gaps first. Ask Claude to list undocumented public functions, outdated pages or broken examples before it writes anything. Use a subagent for a big repo so the exploration doesn't fill your main context.
3. Draft from the code. Have Claude write the docs, quoting real function names, flags and defaults from the source.
4. Test what can be tested. Ask it to run code samples and setup steps and fix any that fail.
5. Review for meaning. Check that the docs say why, not just what, and that nothing describes behavior the code doesn't have.
6. Keep it in sync. Automate a docs check on pull requests (below).

A docs section in CLAUDE.md might read:

## Documentation rules
- Audience: developers integrating our API. Assume they know HTTP, not our internals.
- Second person, present tense, short sentences. Sentence-case headings.
- Every code sample must run as written. Test it before adding it.
- Use names exactly as they appear in the code. Never invent flags or defaults.
- Docs live in docs/ as MDX with frontmatter: title, description.

Which prompts work well for documentation?

List every exported function in src/api/ that has no docstring or an outdated one. Then add docstrings in our existing style, with one short example each, and run the examples to confirm they work.

Write a README for this repo for a new contributor: what it does, how to install and run it, how to run tests, and where the main code lives. Follow the steps yourself in a clean shell and fix anything that fails.

Explain how authentication works in this codebase as a single Markdown page for new engineers, with a sequence diagram in Mermaid. Link each step to the file and function that handles it.

Compare docs/cli.md with the actual CLI flags in src/cli/. List every flag that is missing, renamed or described wrongly, then fix the doc.

Read the last 30 commits and write user-facing release notes grouped by New, Improved and Fixed. Skip internal refactors. Keep each item to one sentence.

The documentation prompts collection has more, including prompts for ADRs, API reference and runbooks.

Which skills and tools help with documentation?

Anthropic's MCP docs use Notion as their example of a remote server:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Claude also reads PDFs directly. For PDFs longer than 10 pages it reads in ranges of up to 20 pages, which needs pdftoppm from poppler-utils on your machine, as the tools reference explains.

How do you keep docs in sync with code automatically?

Docs drift because nobody updates them when the code changes. Claude Code gives you a few places to catch that:

• On every pull request. The Claude Code GitHub Action can run a prompt on PR events, such as "list docs that this diff makes outdated and suggest edits."
• On a schedule. Cloud scheduled tasks run even when your computer is off and can trigger on a schedule, API calls or GitHub events. The scheduled tasks guide compares them with Desktop tasks and /loop.
• In a script. The headless docs show a package.json script that pipes git diff main into claude -p as a typo linter. The same pattern works for a docs check:

git diff main --name-only | claude -p "list the files in docs/ that these code changes make outdated, one per line, with a reason"

Anthropic's tip for scheduled prompts applies here too: be explicit about what success looks like and what to do with results, since the task runs on its own.

What are the limits?

• Plausible is not correct. Generated docs read well even when they are wrong. Check flags, defaults and behavior against the code, and prefer docs that quote the code over docs that paraphrase it.
• It documents what is, not why. Design reasons, tradeoffs and history usually aren't in the code. Give Claude that context or write those parts yourself.
• Automated runs need review. Have scheduled or CI runs open pull requests, not push to main.
• Inputs can carry prompt injection. When Claude reads issues, wikis or web pages, text there can try to steer it. Keep permission prompts on for automated docs jobs that read outside content.

Can Codex or Cursor help with documentation too?

Yes. Both edit files and read your code, and both read AGENTS.md, so docs rules you put there apply across tools. Claude Code reads AGENTS.md when there is no CLAUDE.md, or through an @AGENTS.md import. Docs platforms also publish tool-specific setup: Mintlify's Claude Code guide includes a CLAUDE.md template for docs repos.

How do you reuse your best documentation prompts?

The prompts that produce good docs for your codebase, with your audience and style rules baked in, are worth keeping and sharing. Kipt stores prompts and Agent Skills as Markdown in your own private GitHub repo, with {{name}} blanks for things like module or audience, and installs your skills into Claude Code or Codex with npx skills add. To turn a docs prompt into a skill now, use the free SKILL.md generator.