Your Agent Docs Need a Cleanup Rule

Keep a document when it supports a decision, guides implementation or helps someone judge the result. In his article on AI-assisted engineering, Armando Picón uses that practical test and asks who will maintain the document. His concern is the work required to understand and reconcile generated text, even when producing it is easy.

That gives you a better starting point than counting pages. A long compatibility explanation may protect a public interface. A short status note may repeat information already recorded elsewhere. Length alone tells you little about which would hurt to lose. Ask what someone would get wrong if the document disappeared.

Picón presents an engineering approach, not a measured productivity result. He also distinguishes excessive paperwork from specifications that genuinely support feedback. The useful lesson for a buyer is to inspect what the documentation does before paying to generate more of it or deciding to throw it away.

Compare the decisions and conditions a page preserves with the material you intend to keep. Similar wording isn't enough to establish duplication. A summary may repeat a conclusion while leaving out the condition under which that conclusion is valid.

Consider a hypothetical export feature. A task note says the export must run locally. A design note explains that selected records must remain on the device. Deleting the design note because both pages mention local execution loses the reason. A later agent could move the work to a remote service while believing it preserved the feature.

Preserve that condition in the authoritative design record, then let the task point to it. Record which explanation replaces the retired page. As Architecture Has to Become Agent Context argues, architectural guidance needs to reach the work it governs. Cleanup should shorten that route while keeping its meaning intact.

Find what reads the page, move any unique guidance to its maintained home and update the route that supplies it. That includes project instructions, task templates, search indexes and verification commands. A document can look unused to a person while an agent's startup instructions still depend on it.

Picón makes a related distinction: a guide file doesn't automatically reach an agent just because it exists. You have to connect it through the tool's supported instructions or include it deliberately. After consolidation, inspect the assembled task input. Ask the agent to explain the relevant constraint before implementation, then verify the work against that constraint. A correct paraphrase is useful feedback, not proof of compliance.

If the documents disagree, pause consolidation long enough for the responsible person to settle the rule. Don't let a summarizing agent pick whichever version reads most smoothly. Our context selection discussion covers how stale guidance and current authority can become mixed together. Deleting the evidence of disagreement doesn't resolve it.

Keep required history in a record that clearly separates past decisions from current instructions. Retiring a page from active agent context and destroying its history are different actions. Your retention requirements determine what must remain available and who may remove it.

For ordinary repository guidance, version history may preserve the old text while a replacement notice identifies the current rule. Material kept for an audit or a continuing compatibility obligation may need a different home. Check those obligations before cleanup. An agent assigned to reduce clutter has no authority to erase required evidence.

Give the surviving guidance an owner and a reason to be revisited. A changed interface, a retired feature or a failed check can trigger that review. Picón's maintenance question matters here: consolidating abandoned pages into a larger abandoned page hasn't made the guidance dependable.

Check whether representative work still receives the necessary constraints and produces acceptable behavior. Start with a recurring change in a repository you own. Compare the guidance delivered before and after cleanup, and preserve the verification evidence. Keep the approval decision with the person responsible for that work.

If you want to claim a saving, include the time spent reviewing, repairing and maintaining the new arrangement. Picón explicitly cautions against treating reduced input as a complete cost comparison. A shorter prompt can still require more correction. Report what you measured and leave broader productivity claims out of it.

The factory should assemble the current guidance and run the checks; people decide what the software should do and whether the result is right. Documentation earns its place by helping those decisions survive the next task. Keep what does that work. Retire what only makes the pile taller.