How to Generate Documentation With Claude Code
To generate documentation with Claude Code, do it in three ordered moves. First, tell it exactly which files to read and nothing else, so its picture of the project comes from the code rather than from your description of it. Second, ask for the specific document you want, in a named format, written only from what it just read. Third, make it go back and attach a file path and a function or route name to every factual claim it made. The third move is not optional polish. It is the step that converts a plausible document into an accurate one.
The reason this order matters is that documentation is the one output where being wrong is worse than being absent. A missing README costs a new person twenty minutes of reading code. A README that describes an endpoint which no longer exists costs them an afternoon and a certain amount of trust in every other document in the repository. Generated docs fail in that specific direction, so the process has to push back in that specific direction.
Why Generated Docs Go Wrong
Generated documentation goes wrong because the agent fills gaps instead of reporting them. If it has read six of your twenty files and you ask for a complete architecture overview, it will produce a complete-looking architecture overview. The missing fourteen files get replaced by the most conventional version of what those files usually contain in a project like yours. The output reads well precisely because it is generic.
This shows up in a few recognisable ways once you know to look. Setup instructions list environment variables that were renamed. A feature list includes something that was cut and never removed from an old comment. An API reference documents the parameters a function should logically take rather than the ones in its signature. In every case the sentence is reasonable and the code disagrees.
- Stale features: described because an old file, comment, or branch still mentions them.
- Conventional invention: filled in from how projects like yours usually work, not from your code.
- Silent scope gaps: whole modules the agent never opened, summarised anyway.
- Drift on names: a variable, flag, or route renamed in code but not in the doc it was generated from.
None of that is a reason to write docs by hand. It is a reason to treat the first draft as a draft. The agent is genuinely excellent at reading a large amount of code quickly and turning it into clear prose. It is unreliable at knowing the edge of its own knowledge, so you supply that edge.
The Read-Write-Prove Loop
Read-Write-Prove is the loop I use for every generated document, from a one-page README to a full internal handbook. It is three prompts, not one, and the separation is the whole point. Asking for all three at once collapses them back into a single confident guess.
- READ - name the files. Read these specific paths, nothing else, summarise what each one does, and list anything you could not determine from these files alone. That last clause is what produces an honest gap list.
- WRITE - name the document. Using only what you just read, write the API reference as a table of endpoint, method, required parameters, and what it returns. Naming the format stops it padding with narrative it cannot support.
- PROVE - demand a citation per claim. For each row, give the file and the exact function or handler name it came from. If a row has no source, delete the row and say what is undocumented. Deletion, not hedging.
The PROVE step is where the value lives, and it is the step people skip because the draft already looks finished. When I started running it properly on my own projects, the consistent result was not a small correction. It was a handful of rows deleted per document and a short list of things that genuinely had no source, which is exactly the list I actually needed. The undocumented list is more useful than the documentation, because it tells you where the code is unclear enough that a careful reader could not work it out.
Which Documents Are Worth Generating
Not every document benefits equally. The ones worth generating are the ones whose content is fully determined by the code, because those are the ones where PROVE has something to check against. The ones worth writing yourself are the ones that encode a decision, because no amount of reading source files reveals why you chose one approach over another.
Where generation helps and where it does not
| Document | Generate or write | Why |
|---|---|---|
| API or CLI reference | Generate | Every claim traces to a signature or handler, so the prove step is mechanical and thorough. |
| Setup and install steps | Generate, then run them | Fully determined by config files, and you can verify by following the steps on a clean checkout. |
| Module or folder overview | Generate | The agent reads faster than you do and structure is visible in the files themselves. |
| Architecture decisions | Write yourself | The reasoning behind a tradeoff is not in the code, so the agent will invent a plausible rationale. |
| Runbook for an incident | Write yourself | Depends on what actually broke in production, which no file records. |
| Contribution and review rules | Write yourself | These are preferences, and generated preferences are just the industry average. |
The split is easy to remember: generate description, write judgement. If a careful reader with your whole repository open could reconstruct the document, generate it. If they could not, it has to come from you, and that is also the part worth your time.
Keeping Docs From Drifting Again
Generated docs decay the same way handwritten ones do, only faster, because they were cheap to produce and nobody feels ownership of them. The fix is to attach regeneration to a moment that already happens rather than to a resolution to be diligent. Two moments work well: the point where you finish a feature, and the point where you review a change.
The practical version is a single instruction in your project convention file saying that any change to a route, a command, a flag, or an environment variable requires the matching document to be regenerated in the same session. Because the instruction lives in the file the agent reads every time, it applies without you remembering it. The guide to the [Claude Code CLAUDE.md file](/blog/claude-code-claude-md-file) covers what belongs in it, and [CLAUDE.md templates by project type](/blog/claude-md-templates-by-project-type) has starting points you can adapt.
For anything that can be executed, add one more check: run the doc. Setup instructions that were generated and never followed are a guess. Following them on a clean clone takes ten minutes and is the only way to find the step that was true six weeks ago. This is the same instinct behind [reviewing Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship).
A Working Prompt Sequence
Here is the sequence in the form I actually use, for a README on a small service. Run it in the desktop app with the project open. The terminal works identically if you prefer it, but nothing here requires it.
- Read package.json, the entry file, the config file, and every file the entry file imports directly. List each one and what it does in a single line. Then list every question about this service you cannot answer from those files.
- Write a README with these sections and nothing else: what this service does, how to run it locally, required environment variables, available commands. Use only what you read. Where you have a gap from your list, write TODO and the specific question.
- Now audit your own README. For every environment variable and command, give the file and line where it is defined. Delete anything you cannot locate and list what you deleted.
- Follow your own local setup section on a fresh clone and tell me the first step that fails.
Four prompts, and the last two are the ones that make the difference. If you only have appetite for one extra step beyond the draft, make it the audit. Consistently, the audit is what removes the sentence that would have cost somebody an afternoon. Getting sharper at writing these read-scopes is mostly a prompting skill, and [how to prompt Claude Code](/blog/how-to-prompt-claude-code) covers the general shape.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Can Claude Code write a README from scratch on a project it has never seen?
Yes, and it will be readable immediately. The risk is that readable and accurate come apart. Give it an explicit list of files to read rather than letting it decide what is relevant, then make it cite a source for every factual statement. A README generated from a named read-scope and audited afterwards is genuinely reliable. One generated from a sentence about what your project does is a well-written guess.
How do I stop generated documentation from describing features that no longer exist?
Make citation mandatory and deletion the penalty. Ask for the file and function behind each claim, and instruct it to remove any claim it cannot locate rather than hedge it. Stale features almost always come from an old comment, a dead file, or a stale branch that the agent read in good faith, so the citation step is what surfaces them.
Should documentation live in the repository or somewhere else?
In the repository, next to the code it describes. Documentation in a separate wiki drifts because updating it is a different task in a different tool, whereas a file in the repo can be regenerated in the same session as the change that invalidated it. The exception is anything a non-technical audience needs, which belongs wherever they already look.
Is it worth generating docs for a solo project?
Yes, and the reason is not future teammates. Generated module overviews are the fastest way to give an agent accurate context in later sessions, so the doc pays for itself the next time you come back to a part of the project you have forgotten. On a solo project, the reader you are writing for is mostly yourself in three months, plus the agent working alongside you.
How often should I regenerate documentation?
Tie it to the change rather than the calendar. Any edit to a route, command, flag, or environment variable should regenerate the matching document in the same session, which you can enforce with a line in your project convention file. Scheduled quarterly reviews sound disciplined and get skipped; the change-triggered version happens because the trigger is already in front of you.
Last reviewed by David Iya on August 17, 2026
