Write documentation with AI: READMEs to changelogs

To write documentation with AI, let a coding agent read the code and run the commands it documents, give each document a clear audience, and check every function, flag and example it mentions against the repository. Agents such as Claude Code and Codex are good at the tedious parts of documentation: turning a codebase into a README, filling in docstrings, summarizing a release from git history. Their weak spot is confidence: they will describe an option that sounds right but was never implemented.

This guide covers what to document with an agent, prompts that work for each kind of doc, generating changelogs from git log, keeping docs in sync, where AGENTS.md fits, and how to review AI-written docs for invented APIs.

Agent, not chat window

The biggest quality jump comes from where the model writes. Pasting a file into a chat window and asking for docs gives the model one file and no way to check anything. A coding agent running in your repository can:

• open the files that the code calls into, not only the one you pasted;
• run --help, the test suite or the example it just wrote;
• search for every place a function is used;
• read the existing docs and match their style.

Every prompt below assumes the agent is running in the repository. If you haven’t set one up, how to use Claude Code and how to use Codex CLI get you there.

Decide the audience first

“Write docs for this project” produces a generic page. Each kind of document has a different reader and a different source of truth:

Put the reader and the source in the prompt. It changes the result more than any style instruction.

README

A good README answers four questions quickly: what is this, how do I install it, how do I use it, and how do I contribute. Ask the agent to verify as it writes:

Write README.md for this repository. Audience: a developer seeing it
for the first time. Sections: what it does (2-3 sentences), requirements,
install, quick start, configuration, running tests, project layout.

Rules:
- Take commands from package.json scripts and the CI workflow; run each
  install and quick-start command and fix the README if one fails.
- List only environment variables that are actually read in the code;
  cite the file for each.
- No badges, no marketing language, no features that aren't in the code.

“Run each command” is what turns a plausible README into a correct one. If the agent can’t run something (it needs credentials, say), ask it to mark that step as unverified so you check it by hand.

API reference

For libraries and services, generate as much reference material as possible from the source, and use the agent for the parts generators can’t write: overviews, examples and explanations of tricky behaviour.

For an HTTP API, ask the agent to build the reference from the route definitions themselves:

Document every HTTP endpoint in src/routes. For each: method, path,
auth requirement, request body and query parameters with types,
response shape, error status codes. Read the handler and the
validation schema; don't infer from names. Add one curl example per
endpoint and run it against the local dev server.

If the project already uses OpenAPI, have the agent update the spec file instead of writing a separate Markdown reference, and let your existing tooling render it. One source of truth is easier to keep honest than two.

Docstrings and JSDoc

Agents are fast at filling in docstrings across a module, and this is where they most often describe what a function should do instead of what it does. Ask for behaviour that is visible in the body:

Add JSDoc to every exported function in src/billing/. For each:
one-line summary, @param with type and meaning, @returns, and @throws
for every error the function can actually throw (read the body and
the functions it calls). Add an @example only if you run it.
Don't change any code.

Two cheap checks make docstrings trustworthy:

• TypeScript in JS projects: with // @ts-check at the top of a file or checkJs in tsconfig.json, TypeScript type-checks JSDoc types, so a wrong @param type shows up as an error.
• Python: examples written in doctest format (>>> lines) can be run with python -m doctest module.py -v, so an example that drifts from the code fails.

A useful rule of thumb: a docstring should say why and what for, not repeat the signature. “Returns the user” on getUser(id): User is noise; “Returns null for soft-deleted users; callers must handle it” is worth having. Tell the agent that.

Architecture notes

Architecture docs are where agents save the most time, because the hard part is reading a lot of code and summarizing it. They are also where hallucinations hide best, since nobody checks a diagram line by line. Constrain it:

Write docs/architecture.md for engineers new to the codebase.
Cover: the main modules and what each owns, how a request flows from
the HTTP layer to the database, background jobs, and external services.
For every claim, cite the file (and function) it comes from.
Include a Mermaid diagram of the request flow.
Mark anything you're unsure about with "TODO: verify".

The citations are the point: they let a reviewer spot-check claims in seconds, and they show which parts will go stale when those files change. Record why decisions were made, not only what exists; a short decision log (ADR-style: context, decision, consequences) ages better than a description of the current code. A codebase map for AI agents covers the related problem of giving agents an overview they can navigate.

Changelogs from git log

Release notes are a perfect agent task: the raw material is in git, and the job is filtering and rewriting for users. Start from the range since the last tag:

git describe --tags --abbrev=0
git log v1.4.0..HEAD --no-merges --pretty=format:'%h %s%n%b'

Then the prompt:

Write the CHANGELOG.md entry for the next release from
git log v1.4.0..HEAD --no-merges. Audience: users upgrading.
Use the Keep a Changelog headings (Added, Changed, Deprecated,
Removed, Fixed, Security). Skip refactors, tests, CI and chores.
Rewrite each entry in user terms, put breaking changes first with
upgrade steps, and keep the short hash next to each entry.

If your team writes Conventional Commits (feat:, fix:, feat!: for breaking changes), mention it; the agent can sort by type reliably. If commit messages are terse, let the agent read the diff (git show <hash>) or the linked pull request for the entries that matter. Keeping the hash next to each line makes review fast: you check an entry by opening its commit.

Keeping docs in sync

Docs rot because they are updated in a separate step that nobody schedules. The fix is to make docs part of the change:

1. Same change, same agent. Add one line to your agent rules: “When you change behaviour, flags, env vars or public APIs, update the related docs in the same commit.”

2. Ask for a docs check at the end of every task:

   List every doc, README section, docstring and example that mentions
   the code you changed. Update the ones that are now wrong.

3. Check a branch before merging: give the agent the diff (git diff main...HEAD) and the docs folder and ask which statements in the docs the diff makes false.

4. Run examples as tests. Doctests, a script that runs README snippets, or type-checked JSDoc turn outdated docs into failing builds.

5. Generate what you can. CLI help text, OpenAPI specs and type references generated from source can’t drift.

AGENTS.md is not your documentation

AGENTS.md (read by Codex and many other agents) and CLAUDE.md (read by Claude Code) are instruction files for coding agents. They are loaded into every session, so they should be short: build and test commands, conventions, folders to leave alone. Running /init in Claude Code or Codex generates a first version.

Your human documentation has a different job and can be as long as it needs to be. Mixing them causes two problems: a long AGENTS.md wastes the agent’s context on every task, and a README full of agent rules confuses people. Keep them apart and link between them:

# AGENTS.md
## Commands
- Test: pnpm test
## Docs
- Architecture overview: docs/architecture.md (read before changing modules)
- When you change public APIs, update docs/api.md in the same commit.

CLAUDE.md vs AGENTS.md explains what belongs in these files and how to share one set of rules across agents.

Review AI-written docs for hallucinated APIs

The most damaging doc bug is an API that doesn’t exist: a config option, a CLI flag or a method that the model made up because similar projects have it. Readers trust docs, so they lose time before they suspect the docs are wrong. Review for it on purpose:

• Grep every name. Ask the agent (or a second agent) to extract every function, option, flag, env var and endpoint mentioned in the new docs and search the code for each. Anything not found goes.

  Extract every identifier, CLI flag, config key and env var from
  docs/api.md. For each, show where it is defined in the code with
  file:line, or say NOT FOUND. Don't edit anything.

• Run every example. Code blocks that were never executed are guesses.

• Check defaults and limits. Numbers (timeouts, sizes, retries) are often invented; each one should be traceable to a constant in the code.

• Watch for “also supports”. Lines like “also supports YAML config” or “can be used with Redis” are classic filler. Ask for the code that does it.

• Use a second reviewer. A separate agent reviewing docs against the code is less attached to them than the one that wrote them. AI code review covers setting that up.

Documentation with AgentVera

AgentVera is a desktop app for macOS, Windows and Linux that runs Claude Code, Codex, Gemini CLI and other CLI agents side by side. A few of its tools help with docs:

• Writer and checker side by side: run one agent writing the docs and a second one checking them against the code in the same workspace, or give the docs work its own worktree.
• Specs tab: lists the repo’s Markdown files, newest first, sorted into specs, plans and documents, including uncommitted files agents wrote in other worktrees. Markdown opens in preview.
• Brain: reads your README, ARCHITECTURE, CHANGELOG, ADRs, commits and PRs, lists decisions with their reasons and flags the ones whose code terms no longer appear in the code, a useful signal for stale docs.
• Project tour: a read-only Claude Code run that summarizes a repository’s stack, modules and key files, a good starting draft for architecture notes.
• Code review: review an agent’s doc changes with the Claude model you pick, with findings linked to file and line.
• Git panel: browse the history you build changelogs from, and let Claude Haiku write commit messages in your repo’s style, which makes the next changelog easier.

Wrapping up

AI makes documentation cheap to write, which makes accuracy the real work. Run the agent inside the repository, tell it who the reader is and where the truth lives, have it run commands and examples, and build changelogs from git log with the hashes kept. Update docs in the same change as the code, keep AGENTS.md for agents and docs for people, and grep every documented name before you publish. When a doc reveals a bug instead, debugging code with AI picks up from there.