Shipping, documenting and maintaining an agent-built project
Write documentation a person can follow, be honest about authorship in review, and pay down generated debt before a rewrite is the cheaper option.
Documentation that survives
An agent can read your code, so documentation is not for the agent. It is for the person who joins in six months, and for you when you have forgotten why a decision was made. That means it should record intent and constraints, not restate the code.
# README
## What this is
One paragraph: the problem, and who uses it.
## Running it
- Requirements: Node 22, Docker for the local database
- Setup: cp .env.example .env && npm install && npm run db:up
- Dev: npm run dev, then open http://localhost:3000
- Tests: npm test; end-to-end: npm run e2e
## Decisions
- Money is stored in integer minor units with an explicit currency.
Chosen because floating point rounding produced wrong invoices.
- Webhooks are verified before parsing, not after.
- The scheduler is a single process by design; scaling out needs a lock.- Record the decisions that a competent reader would otherwise question, and the reason behind each one.
- Keep the run instructions accurate; a README that does not work is worse than no README.
- Write down what is deliberately not done, so it is not 'fixed' by the next person.
- Do not document what the code already says clearly.
💡
Write the decision record while the reasoning is fresh. An agent will happily regenerate the implementation tomorrow, but nobody can regenerate why you chose integer minor units over a decimal type - and that is the knowledge that prevents a costly reversal.
Authorship and review
- Say when a change was agent-written. A reviewer reads differently when they know nobody has read it yet.
- Never write 'reviewed' on a diff you have only skimmed - it moves the risk onto a colleague who trusts your label.
- Keep the prompt or the spec in the pull request when it explains the intent; the diff shows what, the spec shows why.
- Attribute the human responsible, not the tool. An agent cannot answer a question about a line it wrote last month.
- Reject the framing that generated code needs less review. It needs the same review and more attention to the error paths.
PR description:
Written with an agent from this prompt:
"Add rate limiting to /api/public/*: 60 requests per minute per
token, using the existing redis client, returning 429 with
Retry-After. Log the token id, never the token."
I have read the diff and verified: 429 on the 61st request, the header
is present, and the log line contains no token value.
Not verified: behaviour under multiple instances.That last line is what makes the disclosure useful. Stating what you did not verify is more valuable to a reviewer than any amount of confidence about what you did.
Paying down generated debt
| Symptom | Debt | Cheapest path |
|---|---|---|
| Three ways to call the same API | Duplication drift | Consolidate to one wrapper |
| Tests that assert on implementation | False confidence | Rewrite against behaviour |
| Dead code from abandoned attempts | Read cost on every change | Delete it; git remembers |
| Validation repeated in three layers | Rules drift apart | One schema, reused |
| Inconsistent structure across features | Every change needs re-learning | Extract one reference pattern |
- Reserve a slice of each week for debt, or it becomes a rewrite by default.
- Fix the pattern, not the instance: consolidate the second copy before writing the third.
- Delete generated code that is not used. Its only cost was already paid at generation time.
- Add a check that prevents the debt from returning - a lint rule, a test, a codegen step.
- Consider a rewrite only when the structure blocks the next feature, not when it merely offends taste.
Rewrite when:
- Every new feature touches the same three files in the same painful way.
- The tests cannot be made meaningful without rewriting them first.
- Nobody can predict what a change will break.
Refactor instead when:
- The behaviour is right and only the shape is wrong.
- There is a clear extraction that would fix several symptoms.Agent-written projects drift faster than hand-written ones because the volume of code is higher and the intent behind each piece is thinner. The countermeasure is not less generation - it is consolidating sooner, deleting more readily, and writing down the decisions that the code cannot express.
FAQ
Should I tell reviewers that an agent wrote the code?
Yes. The information changes how the diff should be read - specifically, that the error paths, boundaries and authorisation checks need attention. Hiding it means a reviewer applies the wrong assumptions, which is exactly how a defect survives review.
How do I stop generated debt accumulating?
Keep the codebase conventional, consolidate the second occurrence of any pattern rather than the third, delete unused code promptly, and add a check for each mistake you have fixed once. Debt accumulates fastest where the same problem is solved twice.
Related
Security, secrets and dependencies Reviewing generated code like an owner
Last refreshed 2026-09-18.