A document is not living just because it is online
A page in a collaborative editor can still become stale. The problem is not the file format; it is the absence of a reliable change process. When a decision changes in chat, a ticket, or a meeting, someone must know which part of the specification it affects and how the new decision becomes authoritative.
A living specification makes that path visible. The current published version is stable, proposed edits are distinguishable from accepted decisions, and older revisions remain available when the team needs to understand why behavior changed.
The four properties that make a spec durable
Useful living specifications share a small set of operational properties. They do not need to predict every implementation detail, but they do need to remove ambiguity around product behavior.
- Structure: flows, roles, data models, terms, and test cases have explicit relationships instead of living only in prose.
- Review: proposed changes have an owner and an approval decision before they become the published source of truth.
- History: revisions show what changed and preserve the context needed to revisit earlier decisions.
- Access: people and tools can retrieve the relevant slice of the specification without copying the whole document into a new prompt.
What belongs in the specification
Start with behavior and constraints. A flow should identify its trigger, actors, ordered steps, decision branches, and observable outcomes. Roles should state permissions and responsibilities. Data models should name fields, types, and relationships. Test cases should connect expected behavior to the flow they verify.
Implementation choices belong in the spec when they are product constraints or cross-team contracts. Local coding decisions that can safely remain inside the codebase should stay there. The goal is shared intent, not a second copy of the source code.
How to keep it alive without creating process theatre
Tie specification changes to moments when the team already makes decisions: discovery, design review, backlog refinement, implementation, and QA. A small change should remain small. The review path should become more rigorous only when a decision affects security, permissions, billing, data retention, or several teams.
After shipping, capture accepted behavior changes and meaningful exceptions. Do not rewrite the spec to pretend the original plan was perfect. The revision history is useful precisely because software development produces new information.
Living specs and coding agents
Coding agents are most reliable when they receive bounded, current context. A structured specification lets an agent retrieve the relevant flow, role, model, and test cases for a task. That is safer than pasting a long planning document whose status and internal contradictions are unclear.
The human approval boundary still matters. Agents can propose specification edits when implementation reveals a missing case, but the published intent should change only after a person accepts the consequence.
Review checklist
- Can a new teammate identify the currently approved behavior?
- Can reviewers see a proposed change before it becomes authoritative?
- Can each test case be traced to a flow or requirement?
- Can a coding agent retrieve only the context needed for its task?
- Can the team explain why a behavior changed six months later?