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
- HeyGen + Canva MCP turns slide speaker notes into an avatar presentation video — HeyGen · 2026-10-27
- 10 practical ways to run Astra computer use on Premiere Pro for video editing — beechinour · 2026-10-27
- Dev ships a delightful free shadcn UI for agent run and tool-call traces — round · 2026-10-27
- Phil Schmid launches Gemini API CLI: a stateless multimodal tool belt for your existing coding agent — _philschmid · 2026-10-27
- Musk hails Grok Bot as 'incredibly competent chief of staff' as user automates inbox triage — elonmusk · 2026-10-27
- shadcn's /improve skill paired with Grok on SuperGrok Heavy for plowing through issues — shadcn · 2026-10-27