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
- Gergely Orosz: Shipping 10x PRs With AI Agents, Sites Fill With Small Regressions — ducha_aiki · 2026-09-11
- Kernel integrates Stripe Link so browser agents can pay with one API call — jeff_weinstein · 2026-09-11
- Same Echo Maze prompt, three frontier models: all passed visually but shipped the same hidden bug — eyishazyer · 2026-09-11
- The full prompt-to-3D-game workflow: Hyper3D Rodin MCP plus Codex, no reference image — FellMentKE · 2026-09-11
- Building a 3D landing page with GPT-6 Astra and Hyper3D Rodin MCP, no modeling needed — FellMentKE · 2026-09-11
- Astra storyboards plus Minimax H3 per-shot generation boost video success rates — Hailuo_AI · 2026-09-11