Skip to main content
To keep codebase documentation current when AI agents write code, update it as part of the same change as the implementation. Start from current repository context, approve the intended change, capture material discoveries while the agent works, verify the result against executable behavior, and merge the documentation update with the code. Keep the original RFC as history. Use the maintained product and technical documents to explain what is true now. Last reviewed July 18, 2026. Maintained by the Plannotator project. A large retrospective written after the pull request is less reliable. The agent may have to reconstruct intent from stale plans, partial chat history, and code it did not personally execute.
An AI coding agent and a human reviewer update a living codebase handbook from the current code diff and validation while preserving an earlier RFC as history.

​
Separate current documentation from historical records

Living documentation records the behavior and constraints that future engineers and agents should trust. It might include:
  • a PRODUCT.md that explains user-visible behavior and product boundaries;
  • a TECH.md that explains system components, data flow, and operational constraints;
  • an API contract generated from, or checked against, the implementation;
  • a searchable handbook under docs/;
  • runbooks for deploying, observing, and recovering the system;
  • repository instructions for coding agents.
It should not contain every discussion that produced the system. Review threads, RFCs, plans, and agent progress logs remain useful, but they answer historical questions: What did we propose? Which alternatives did we reject? What happened during execution? Maintained documentation answers a different question:
If I need to change or operate this system today, what should I believe?
A repository can accumulate detailed feature directories without identifying which one describes current behavior. Maintainers need to designate the current source. GitHub’s Spec Kit persistence guidance makes this choice explicit. A team can keep feature artifacts as immutable history, continuously reconcile them with implementation discoveries, or treat a living specification as the contract. Whichever model a team chooses, contributors need to know which documents are historical and which are authoritative.
Documentation roles

Two records, two questions

Current documentation

What is true now?

  • PRODUCT.md
  • TECH.md
  • API contract
  • Handbook and runbooks

Decision history

How did we get here?

  • RFC and approved plan
  • Review thread
  • Progress log
  • Superseded decisions

Link current truth to its rationale without forcing agents to reconstruct the present from old discussions.

​
Put documentation in the implementation loop

Spec-driven tools already create structured context before code. GitHub Spec Kit, for example, uses a Spec → Plan → Tasks → Implement workflow. Those artifacts help an agent avoid jumping directly from an issue to a patch. Once implementation begins, code exposes details the plan could not know: an old client depends on undocumented behavior, a database invariant differs from the architecture diagram, or a browser interaction fails in a state the acceptance criteria missed. Feed those discoveries back into the maintained documents without rewriting history:
1

Begin from maintained context

Link the change request to the current product, technical, API, and operational documents. If those sources disagree before work starts, resolve the disagreement or name it as part of the requested change.
2

Review the intended change

Review the consequential product and engineering decisions before broad agent execution. Pin the exact version in Git or the project system when other people need a durable record. How to Approve AI Coding Plans Before Execution explains Plannotator’s local feedback, Plan Diff, and Approve loop.
3

Capture implementation discoveries near the work

When an agent finds a material contradiction or missing decision, record it in the pull request or live draft while the evidence is available. Do not bury a changed product rule inside a code comment or an agent chat.
4

Verify behavior before rewriting the explanation

Run the relevant unit, integration, contract, migration, and end-to-end checks. Review the implementation and its code review artifacts, such as screenshots, browser traces, or test output. A generated explanation is a claim until executable behavior supports it.
5

Update current documents in the same change

Edit only the maintained pages affected by the accepted behavior. Link to the historical RFC for rationale instead of copying its entire narrative into the handbook.
6

Preserve the decision trail

Keep the approved request, important deviations, implementation revision, validation evidence, and final decision connected. Mark superseded documents clearly rather than deleting the evidence or leaving two sources that both appear current.
GitHub’s guidance for evolving Spec Kit artifacts tells teams to decide whether an implementation discovery changes intended behavior, implementation strategy, task breakdown, or only code, then reconcile the artifacts that now disagree.

​
A repository-based example

Consider a team replacing a single-request upload API with resumable uploads for large files. Its repository contains:
The RFC proposes multipart upload sessions, resumable offsets, a 24-hour cleanup rule, and compatibility for clients that still send one request. Product, API, storage, and operations owners record the accepted revision in their project system. A coding agent implements against that checkpoint. During retry testing, the agent finds that the mobile client reuses an idempotency key after a network timeout, behavior absent from both the plan and uploads.md. The discovery changes the compatibility contract and the server state machine. The team should not let the agent invent retry semantics or rewrite the documentation to match the easiest implementation. It should return the discovery for a decision and approve the new direction. The agent then implements the idempotency rule and provides a handoff naming the exact revision, tests, risks, and documentation impact. See What Should an AI Coding Agent Hand Back After It Changes Code?. Before merge, reviewers check four things together:
  1. Contract and retry tests demonstrate the accepted upload and resume behavior.
  2. Expiration, cleanup, storage-failure, and rollback behavior match the reviewed plan.
  3. docs/PRODUCT.md, docs/TECH.md, and docs/uploads.md describe the shipped system.
  4. specs/017-resumable-uploads/RFC.md remains an immutable decision record and links to the final implementation.
The RFC explains how the team reached the result. The maintained documents explain how uploads work after it ships. Tests and running behavior determine whether either explanation is accurate. Warp offers a concrete example of splitting feature intent from implementation detail: its public APP-2527 specification contains separate PRODUCT.md and TECH.md files. A team still needs a convention for carrying accepted behavior into whichever documentation future contributors read first.

​
Repository files make the maintenance rule enforceable

Keeping documentation near code enables several maintenance checks:
  • A pull request can show code and documentation changes together.
  • CODEOWNERS or required reviewers can route affected documents to the right owners.
  • CI can build the documentation, check links, validate schemas, and test code samples.
  • Git history can show when an explanation changed and which implementation changed with it.
  • Agent instructions can identify the maintained documents that must be read before a particular system is modified.
mdBook is one lightweight example: it turns repository Markdown into a navigable, searchable site. Its CLI can also test Rust code samples, allowing teams to check some documentation claims automatically. Repository placement also gives coding agents normal file access. Clear entry points are still required. A large docs/ tree with contradictory pages gives an agent more material but no reliable source.

​
Verify generated documentation

An agent can inventory changed files, draft release notes, update examples, and identify stale documents. It can also confidently describe behavior the program does not have. Anthropic’s work on long-running coding-agent harnesses found that progress files and Git history helped later sessions recover context, but it also found agents could mark work complete without proper end-to-end testing. Explicit browser testing exposed failures that code inspection and narrower checks missed. Check generated documentation against:
  • the approved request for intended behavior;
  • the code diff for the mechanism;
  • tests and runtime evidence for observed behavior;
  • domain owners for product and operational meaning.
The agent’s narrative is a draft, not independent proof. For dense comparisons or interactive explanations, an agent may produce HTML alongside durable Markdown. When Should AI Coding Agents Produce HTML Instead of Markdown? explains when that improves understanding and when it merely adds maintenance cost.

​
Skip documentation updates when behavior does not change

Not every edit changes durable behavior. A typo fix, local refactor, dependency patch with no contract change, or test-only cleanup may require no handbook update. Use one short question in the pull request or agent handoff:
Does this change alter a user-visible behavior, public or internal contract, system constraint, operating procedure, or fact that future contributors rely on?
If the answer is no, record no durable documentation impact and continue. Do not make the agent perturb an unrelated page merely to satisfy a checklist. If the answer is yes, name the exact maintained files and update them with the implementation. A small documentation impact field is enough to identify the required work without adding a separate approval process.

​
Limitations

Living documentation cannot make every repository fact current automatically.
  • Some behavior exists only at runtime or in external infrastructure.
  • Tests can be incomplete or encode the wrong expectation.
  • Generated API references may be accurate but still fail to explain intent.
  • A document owner can approve prose without noticing a contradictory implementation.
  • Fast-moving teams may accept temporary drift during incidents or migrations.
  • Historical records can expose sensitive design or security details and may need access controls.
Readers should be able to identify which source is current, how the team verified it, and where to look when code and documentation disagree.

​
Frequently asked questions

​
What is living documentation for AI coding agents?

It is maintained product, technical, API, and operational context that changes with the system and is available to both people and agents. It describes current behavior rather than only preserving the plan for one completed feature.

​
Should an RFC be updated after implementation?

Usually, preserve an approved RFC as decision history and update separate maintained documentation with the shipped behavior. If your team intentionally uses a living-spec model, revise the specification and keep its derived plan and tasks consistent. State the convention explicitly.

​
Should an AI agent update documentation automatically?

It can draft the update and identify likely affected pages. A reviewer should compare the draft with the approved request, code, tests, and observed behavior before treating it as current documentation.

​
How do you prevent codebase documentation from becoming stale?

Put a documentation-impact decision in the implementation and review workflow, update affected documents in the same pull request, assign owners, and add automated checks for build failures, broken links, schemas, and executable examples where those checks are possible.

​
Does every AI-generated code change need a documentation update?

No. Changes that do not alter durable behavior, contracts, constraints, or operating procedures should use the fast path and record that there is no documentation impact.

​
Are repository Markdown files enough for coding agents?

They work well as a default because they are portable, versioned, searchable, and easy for agents to read. They are not enough when the files conflict, lack clear ownership, omit runtime facts, or cannot express a comparison or interaction that would be clearer in another artifact.

​
When a consequential change is complete

Treat a consequential change as complete when the code, executable evidence, and maintained explanation agree. If they do not agree, record the remaining disagreement. The workflow in How Teams Understand AI-Generated Code Before Shipping It shows how teams check that agreement. Future engineers and agents can start from the system the team operates while retaining the original request and decision trail for historical context.

Annotate maintained documents

Open Markdown, text, HTML, or a folder in Plannotator and return annotations to the active coding agent.
Last modified on July 19, 2026