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
- First-ever Three.js Conference lands in Paris, with a panel on AI-shortened design workflows — OdinLovis · 2026-09-11
- Data engineering, not agent frameworks, is the real bottleneck for enterprise AI agents — dhruv2038 · 2026-09-11
- GPT-6 Astra beats Factorio with enemies in 44 in-game hours at ~$4,500 API cost — liminal_bardo · 2026-09-11
- Investment Analyst Asks How to Build a Claude-Based Diligence Agent Stack — Careless_Tie2286 · 2026-09-11
- Treating agents like 50 First Dates: a 3-layer context system so every conversation doesn't start from zero — evielync · 2026-09-11
- Running the Firefox MCP on Android via Termux, ngrok, and mcp-proxy — Nervous-Strain7544 · 2026-09-11