Stop giving agents one giant spec; split docs by lifetime instead
Goldziher · reddit · 2026-07-23
The core idea
Don’t hand an agent one giant spec. Split documentation by lifetime instead: requirements in a churn-friendly ticket system, architectural decisions in append-only ADRs, implementation plans as ephemeral notes, and contracts as black-box integration tests.
Why this works better for agents
A spec usually blends four different things with different decay rates: why, how, execution order, and done-criteria. Over time it becomes stale, and an agent will treat that stale text as ground truth instead of asking follow-up questions like a human would.
The proposed workflow
- Product requirements: keep them in tickets, not in the repo.
- Architectural decisions: store them in git ADRs so they can be superseded without being edited into ambiguity.
- Implementation plans: keep them temporary; agents often already maintain these internally.
- Contracts: encode them as integration tests so CI can catch drift and let the agent self-correct.
The author ends by asking how others provide architectural context to agents: ADRs, another system, or just code inference.
More from coding & agent
- SymbolPeek lets coding agents read symbols instead of whole files, saving 1.61M tokens — Real_Veterinarian851 · 2026-07-23
- AgenC defaults to one agent after papers found multi-agent swarms underperformed — tetsuoai · 2026-07-23
- AgenC now defaults to one agent after multi-agent systems fell 39%–70% behind — tetsuoai · 2026-07-23
- An AI coding agent broke a database schema with six migrations and 400 lines of ALTERs — Comfortable-Roof4278 · 2026-07-23
- Five frontier models all solved the same bugs, but cost varied 14x and Claude refused 40% — PromptPhanter · 2026-07-23
- LLMs may help most in the manual refinement phase of decompilation — OwariDa · 2026-07-23