Docs from code

Documentation rots quietly, and the damage shows up as support tickets months later. The useful agent here does not write your docs, it tells you precisely where the docs and the code disagree.

The job on one screen

Runs when	On merge to the main branch, for changes touching public interfaces.
Reads	Function and endpoint signatures, existing docs, examples in the docs.
Decides	Which differences are real drift and which are formatting.
Produces	A drift report, and a proposed patch for the mechanical parts.
Stops when	Report produced. Prose changes go to a human writer.
Tools it needs	Repository API, docs site API, code parser.
Autonomy to start at	Approve. It does the work and stops before the irreversible step.

Optional: load a real model

Run it

The fields it pulls

Required fields are never guessed. If one is missing the run stops and a person gets the document, which is the difference between an extraction agent and a wrong database row.

Field	Required	How it is found
Method and path	yes	`\b(GET\|POST\|PUT\|PATCH\|DELETE)\s+(/[\w{}/.-]+)`
Required body fields	yes	`body:\s\{([^}])\}`
Success status	yes	`returns\s+(\d{3})`
Error codes	optional	`errors:\s*([^\n]+)`
Default values	optional	`=\s(\d+\|\"[^\"]\")`

Where this one goes wrong

Rewriting prose

An agent that rewrites explanations produces bland docs that lose the one paragraph that made it clear. Patch the mechanical parts, report the rest.

Documenting internals

Everything public gets docs, everything private does not. Signature visibility is the rule, and it must be checked.

Examples that do not run

A generated example that fails is worse than no example. If you generate examples, execute them in CI.

How you would know it is working

Measure	Why that one
Drift found per release	Rising means the code moves faster than the docs, which is a staffing answer, not a tooling one.
Support tickets citing docs	The outcome measure and the reason anyone funds this.
Patch acceptance rate	How often the mechanical patch is merged unchanged.

Earning more rope

Assist	Produce a drift report for the docs owner.
Approve	Open a patch PR for signatures, parameters, and error codes only. Right level.
Auto	Auto-merge signature-only patches in reference sections, never in guides.

Report drift, do not silently fix it. Docs that change without a human noticing are how a wrong example gets an authoritative URL.

Related: Change log writing · PR review · Backlog grooming · all agent jobs · Agent Lab home

Free from AI School - no signup, everything runs in your browser.