Get an AI Coding Agent to Update the Docs

Six weeks into using a coding agent daily, most teams notice the same thing: the code is fine and the docs are a fossil. Getting an AI coding agent to update the docs turns out not to be a prompting problem, which is why telling it to be thorough never works. The README describes an install flow that changed twice, the API reference lists two parameters that no longer exist, and a new arrival follows the getting-started guide into an error.

It is a scoping problem. "Add pagination to the users endpoint" is a request about the users endpoint. The documentation was not in scope, it was not in context, and nothing failed when it went untouched.

Four changes fix it, in increasing order of how much they cost to set up.

1. Name the documentation in the request

The cheapest fix is the most obvious one and it is worth stating because it works. An agent updates what you point it at.

Instead of:

Add cursor-based pagination to GET /api/users.

Write:

Add cursor-based pagination to GET /api/users. Update docs/api/users.md with the new query parameters and the response envelope, and update the example in README.md if it calls that endpoint.

Naming the file matters more than naming the task. An agent asked to "update the docs" will search, guess, and frequently write a new section in the wrong file rather than editing the existing one. An agent given a path edits that path.

2. Write down where the documentation lives

If you name the file every time, you will forget, and anyone else using the agent will not know which file to name. Put the mapping in the file your agent reads at the start of every session. Most tools now read an AGENTS.md or a similar project file; the AGENTS.md convention is the closest thing to a shared standard.

What to write there is a list of surfaces and their documentation, not a paragraph about caring:

## Documentation

Update alongside the code in the same change:

| If you change | Update |
| --- | --- |
| `src/api/routes/*` | `docs/api/<resource>.md` |
| Any env var read in `src/config.ts` | `README.md` env table, `.env.example` |
| A CLI flag in `src/cli/` | `docs/cli.md` and the `--help` string |
| A database column | `docs/schema.md` |

Do not create new documentation files. Edit the existing one for that
surface. If none exists, say so in the summary rather than inventing a
location.

That last instruction earns its place. Without it, agents resolve "there is no obvious doc for this" by creating docs/pagination.md, and six months later you have forty orphan files nobody links to.

The reasons this does not always take are the same reasons a style guide does not always take, which we cover in why your AI coding agent ignores your style guide. The short version: rules stated as preferences get deprioritised under a long task, and rules stated as file mappings do not.

Why a mapping beats an instruction

It is worth being precise about why the table works where "keep the docs up to date" does not. An agent working a long task is managing a budget: context, steps, and its own sense of when the job is finished. A general instruction competes with everything else in that budget and loses, because nothing tells it that this particular request had documentation in scope. A mapping row does not compete. It converts an open-ended obligation into a lookup that either matches the files in the diff or does not, and a lookup costs almost nothing to honour.

The same reasoning explains why the mapping should be exhaustive rather than illustrative. A table that lists three of your seven documented surfaces teaches the agent that documentation is sometimes required, which is the ambiguity you were trying to remove.

3. Make the docs the input, not the afterthought

There is a sequencing trick that changes the failure rate more than any amount of instruction. Ask for the documentation change first.

First, update docs/api/users.md to describe cursor-based pagination on GET /api/users as you intend to implement it. Show me that diff. Then implement it to match.

Two things happen. You get a design review at the point where changing your mind is free, in prose you can actually read, rather than after 300 lines of implementation. And the documentation cannot drift from the code, because the code was written to match a document that already existed.

This works especially well for anything with a public surface: API endpoints, CLI flags, configuration, webhook payloads. It works less well for internal refactors, where there is nothing user-visible to describe.

4. Fail the build when a surface changes without its docs

Instructions degrade. A check does not. This is the step that makes the problem stay fixed, because it turns documentation from something a reviewer has to notice into something the agent's own feedback loop catches before you ever see the diff.

The check does not need to be clever. Compare the paths touched against the paths that should have been touched:

#!/usr/bin/env bash
# ci/check-docs.sh - fail if a public surface moved without its documentation.
set -euo pipefail

BASE="${1:-origin/main}"
changed="$(git diff --name-only "$BASE"...HEAD)"

fail=0
check() {  # check <code-glob> <docs-glob> <label>
  if grep -qE "$1" <<<"$changed" && ! grep -qE "$2" <<<"$changed"; then
    echo "FAIL: $3 changed but $2 was not updated"
    fail=1
  fi
}

check '^src/api/routes/'  '^docs/api/'    'an API route'
check '^src/cli/'         '^docs/cli\.md' 'a CLI command'
check '^src/config\.ts'   '^(README\.md|\.env\.example)' 'configuration'

exit "$fail"

Run it in CI and, if your agent runs tests locally, in the pre-commit path too. An agent that sees `FAIL: an API route changed but ^docs/api/ was not updated` will go and update the docs without being asked, because it now has a failing check to fix and that is the one kind of instruction agents never ignore. If you already run a pre-commit hook with an AI reviewer, this slots in alongside it.

The check is deliberately dumb. It verifies that a file was touched, not that the touch was correct. That is fine. It catches the entire class of "forgot completely," which is essentially all of the problem, and a human reviewer can still judge quality.

What to check in the output

A check that a file was touched does not tell you the touch was any good. Four failure patterns show up often enough to look for deliberately, and all four are fast to spot.

Documentation written for the diff rather than the reader. An agent that just changed a function will write "the `limit` parameter now defaults to 50 instead of 25," which is a changelog entry. The reference should say what `limit` does and what its default is, with no memory of what it used to be. Changelog belongs in the changelog.

Invented rationale. Agents fill explanatory gaps confidently. A sentence like "cursor pagination was chosen for consistency under concurrent writes" may be exactly right, or may be a plausible reason the model generated because the paragraph needed one. If you did not say why, treat any stated why as a draft.

Examples that were never run. Code samples in documentation are the most-copied text you publish and the least tested. If a sample appears in a diff, run it. A broken example is worse than no example, because someone will assume the error is theirs.

Silent deletion. Agents sometimes rewrite a documentation page wholesale rather than editing it, and a section that was not related to the change disappears. Read documentation diffs for what left, not only for what arrived.

Keep the changes small enough to review

All of this is easier when the diff is small. A change that touches four endpoints and their four documentation files is reviewable. A change that touches forty files is not, and the documentation in it will be skimmed and approved whether or not it is right. The habits in getting an agent to write smaller pull requests do more for documentation quality than any documentation-specific instruction, and the same is true of commit messages that say what changed and why.

FAQ

Why do AI coding agents skip documentation by default?

Because it is out of scope as stated. The request names a code change, the documentation files are not in context, and nothing fails when they go untouched. Agents optimise for the task and the checks in front of them.

Should I let an agent write documentation on its own?

For reference material generated from a surface you can verify, such as parameters, flags and response shapes, yes. For conceptual explanations and tutorials, treat the output as a draft. Agents write confident prose about intent they are inferring rather than recalling.

Where should the docs mapping live?

In the project file your agent reads automatically at the start of a session, such as AGENTS.md. A mapping in a wiki nobody loads into context has no effect. Broader guidance on getting the most from these tools is in our overview of AI coding tools.