What is an agent scope doc?
- Agent scope doc
- An agent scope doc is one page, written before the PRD, that defines an AI agent's world. It says what the agent can see, what it can do, what it must never do, when it must stop and ask, and how we'll know it's good.
What goes in an agent scope doc?
Five sections, on one page.
- What it can see. Which data, which tools, which history.
- What it can do. Every action, with the rung of earned autonomy each starts on.
- What it must never do. The short list that matters most.
- When it must stop and ask. The triggers for handing back to a person.
- How we'll know it's good. An eval set. Real examples with acceptable and unacceptable answers, run before every change.
Why write it before the PRD?
Every section of the usual PRD template assumes software does the same thing every time. Agents don't. The same input can produce a different output, the agent decides its own steps, and the most important behaviour is what it does when nothing in the spec applies. A feature template gives you a document that reads well and tells engineering almost nothing.
With the scope doc in place, the PRD can stick to what it's good at. The problem, the users, why now and what success looks like for the business. The behaviour lives in the scope doc and the eval set, where engineering can test against it.
How is it different from user stories and acceptance criteria?
| Feature PRD | Agent scope doc |
|---|---|
| User stories describe one path | The agent chooses its own path, so the doc sets what it can see and do |
| Acceptance criteria assume one right answer | An eval set holds a range of acceptable answers and a set of unacceptable ones |
| Success metrics measure the happy path | The number that matters is often a failure rate, like confident wrong answers or actions taken that shouldn't have been |
What does it look like in practice?
Take "As a user I want to cancel my subscription". That's fine for a button. For an agent, the hard part is the forty ways a person might ask, and the ten things it should check before it cancels anything. The scope doc is where those checks, the actions the agent may take on its own and the moments it hands back to a person get written down.
Where does the idea come from?
I set it out in Your PRD template is wrong for agents in October 2026. If your agent spec has acceptance criteria but no eval set, no "must never" list and no escalation triggers, it isn't finished. Those three sections are where agent products succeed or fail.
Related ideas
- Earned autonomy. How each action in the scope doc moves up and down the ladder, one person at a time. In earned autonomy.
- The Yes Machine. Confident wrong answers come from systems nobody checks. In The Yes Machine.
FAQ
What is an agent scope doc? An agent scope doc is one page, written before the PRD, that defines an AI agent's world. It says what the agent can see, what it can do, what it must never do, when it must stop and ask, and how we'll know it's good.
Does an AI agent still need a PRD? Yes, a shorter one. It covers the problem, the users, why now and what success looks like for the business. The agent's behaviour lives in the scope doc and the eval set.
What is an eval set? Real examples with acceptable and unacceptable answers, run before every change to the agent.
How do you know an agent spec is finished? It has an eval set, a "must never" list and the triggers for stopping to ask. Acceptance criteria alone aren't enough.
To cite this, use “Agent scope doc”, Matt Alcock, mattalcock.com/ideas/agent-scope-doc.