English
Build your map

AI-built

Can I trust documentation that a coding agent generated?

Fluent, extensive, and indistinguishable from documentation somebody checked. That last property is the whole problem.

Build your map
Guide Reviewed Written by Mikhail Piskunov

Short answer

Treat it as a claim to be tested rather than as a source. Take five specific, checkable statements from it and verify each against the code; if two are wrong, the document is a hypothesis and should be labelled as one. Keep what survives, mark what was verified and by whom, and delete what cannot be checked — because unverified documentation is more dangerous than none, on the simple grounds that people act on it.

#The specific problem

Documentation written by a person carries an implicit signal: somebody thought this was worth their time, and they knew something about it. It is often wrong, and its wrongness has a texture — it is out of date, or it is vague where the author was unsure.

Generated documentation has no such texture. It is uniformly confident, uniformly detailed, and uniformly well written whether the underlying statement was read from the code or inferred from a naming convention. There is no vagueness to signal uncertainty, because there was no uncertainty in the writing — only in the knowing.

Why this is worse than no documentation

People act on documentation. A team with none knows it has none and behaves accordingly: it checks. A team with forty pages of confident, unverified documentation behaves as though the questions have been answered, and finds out otherwise at the point of a decision.

#How to test it in an hour

  1. Pick five checkable statements

    Specific ones: “payments are retried three times”, “the export runs at 02:00”, “authentication uses a bearer token issued by the storefront”. Not “the system is modular”.

    A statement that cannot be checked is not a claim; it is decoration, and it should be deleted rather than tested.

  2. Verify each against the code

    Open the file. Read the lines. Record for each: correct, wrong, or cannot tell.

  3. Score it

    Five of five correct: probably worth keeping, and worth re-testing after the next big change. Three or four: keep it, label it unverified, and test the rest. Two or fewer: it is a hypothesis, not a document.

  4. Check the negative space

    What does it not mention? Scheduled jobs, external integrations and failure handling are the three things generated documentation most often omits entirely, because they are least visible in the code it was reading.

Testing five claims from a generated README Invented example — not a customer 
1. "Failed payments are retried three times."
   → CORRECT.  app/Jobs/SettlePayment.php:22  $tries = 3

2. "Retries use exponential backoff."
   → CANNOT TELL. No backoff is configured. The framework
     default may be exponential; the document states it as fact.

3. "All API endpoints require authentication."
   → WRONG.  Two routes in routes/api.php are outside the
     auth middleware group. One of them accepts a write.

4. "The nightly export writes to S3."
   → CANNOT TELL. The destination comes from EXPORT_DEST,
     which is not set in this repository.

5. "The system uses PostgreSQL."
   → CORRECT.

Score: 2 correct, 1 wrong, 2 unverifiable.
Verdict: hypothesis. Claim 3 is a live problem discovered
by reading the document sceptically rather than by using it.

An hour, and it found an unauthenticated write endpoint. That is a good hour — and note that it was found by doubting the documentation rather than by reading it.

#What to keep, and how to mark it

Three states, and every page should be in exactly one of them:

  • Verified — somebody checked these claims, on this date. Name and date on the page. This is the only state in which a document should be acted on without further checking.
  • Unverified — generated and not checked. Keep it if it is useful for orientation, and say so at the top in one line: "Generated, not verified. Check anything you intend to act on."
  • Deleted — cannot be checked, or was tested and mostly wrong. Deleting documentation feels wasteful and is usually correct: a page that misleads costs more than the blank space it occupied.

The labelling matters more than the content. A reader who knows a page is unverified uses it as a starting point; the same reader, given the same page unlabelled, uses it as an answer.

#What generated documentation is genuinely good at

This page is sceptical rather than hostile. Three things it does well, and they are worth having:

  • Orientation. A new person needs to know roughly where things are before they can ask a good question. A generated overview is fine for that, provided nobody makes a decision on it.
  • Coverage of the boring parts. Nobody was ever going to hand-write a description of every module. A generated one covers the long tail that would otherwise be blank.
  • A first draft to correct. Correcting a wrong description is far faster than writing one, and the corrections are where the real knowledge ends up.

The failure is not generating it. The failure is generating it and then treating the result as though somebody had checked.

#A better arrangement

Rather than generating prose about a system, generate a structured account of it that carries three things prose cannot:

  1. A locator for every claim — the file and lines it came from, or an explicit mark that it is inference.
  2. An unknowns section that is not empty. What it could not establish, and why.
  3. A coverage statement — what was actually looked at, and what was skipped.

This is the same work and a different output shape, and it removes the exact property that makes generated documentation dangerous: you can now see which statements were read and which were guessed. Evidence covers why that distinction is the important one, and the Evidence Package is one concrete way to encode it.

#What goes wrong

Regenerating it when it goes stale.

Instead Regenerating produces a new unverified document. If nothing checks it, the second one is exactly as trustworthy as the first.

Keeping unverified documentation unlabelled because it looks professional.

Instead One line at the top costs nothing and changes how every reader uses it.

Testing vague statements.

Instead Test specific ones. “The system is modular” cannot be wrong, which is why it is not worth reading either.

Assuming volume implies coverage.

Instead Check the negative space. Scheduled jobs, integrations and failure handling are usually missing entirely, and length disguises that.

Deleting nothing.

Instead Delete what cannot be checked. A page that misleads costs more than the gap it filled.

#What this does not cover

What this does not do

  • User-facing documentation, where accuracy matters differently and the audience is not your team.
  • API reference documentation generated from code annotations, which is a different thing and is usually reliable because it is derived mechanically.
  • Whether to use agents to write documentation at all. Use them; check the result.
  • Comment quality inside the code, which is a code review question.

Find out what you actually own.

No repository access. No source-code upload. No card.

Build your project map — free