A spec is a contract between you and the AI agent — it states what should be built, what should not be built, and how the work will be verified. Agents are eager builders; given a vague spec they invent assumptions and race down the wrong path. The fix is to make intent explicit up front, break complex work into small verifiable tasks, keep the spec concise and living, and reserve specs for work important enough that alignment actually matters.
Good software engineering has always required writing specs, but the audience has changed: now we write them for AI. With features like Claude Code's plan mode, everyone is writing specs for their agents — yet many people write the same PRDs and design docs they always have and wonder why their agents still produce undesirable outcomes. A spec, in this framing, is a contract between you and the AI agent. It defines what should be built, what should not be built, and how the work will be verified, and it is a living document that constantly gets updated as work progresses and requirements change.
A good spec covers what outcomes should be true when the work is done, what is in scope and what is explicitly out of scope, what constraints or assumptions apply, what decisions have already been made, how the work should be broken into tasks, and what checks should be run to prove the work is correct.
"A spec is a contract between you and the AI agent. It defines what should be built, what should not be built, and how the work will be verified."
Agents are very eager to build things. If they don't have a spec, or the spec is vague, they will make up assumptions and do guesswork for your engineering and product decisions — which means they can head down the wrong path quickly. This gets worse across long tasks, multiple sessions, and complex work. And one of the biggest AI failure modes is asking for too much in one shot: agents will happily generate a huge amount of code, but that pushes the review burden downstream and won't hold the same quality and verification as doing one small thing at a time.
A better pattern is to break a complex task into smaller, achievable tasks where singular agents work on each task individually and verify the work as they go. Even better, add an adversarial agent to check their work. This gives greater results, more control over correctness, and makes parallel agent workflows safer and easier to manage.
"One of the biggest AI failure modes is asking for too much in one shot."
The demo walks through Augment's Intent product. The presenter starts with a high-level intent — "add authentication to my app" — deliberately vague. A good agent responds by interviewing you, asking clarifying questions to make sure you're thinking about the right requirements and scope and to clear out assumptions. The finished spec shows a high-level goal, a breakdown of tasks each with their own individual spec, acceptance criteria, known goals, assumptions, a verification plan, and a rollback plan.
The advice is to actually review this spec rather than just clicking accept — the real value comes from the review, where you might find assumptions to clear up or change. At the same time, avoid over-specifying the implementation; keep it concise enough that you have a good understanding of what to expect. Once kicked off, a coordinator agent delegates tasks to run in parallel with individual sub-agents, and the spec stays living: it constantly gets updated by the sub-agents. Where old-world PRDs rarely got updated as things changed, here you can message the coordinator agent to add, say, two-factor authentication, or update the spec manually yourself — Intent treats the spec as a first-class primitive.
Not every task needs a detailed spec. Specs are more useful for non-trivial work; if something is quick, exploratory, or experimental, you're probably better off giving one prompt to one agent for faster results and quicker iteration. On dedicated frameworks like SpecKit and OpenSpec, the presenter's personal take is that they're a bit overkill — they generate many docs, making it harder to keep track and maintain. The general advice is to keep specs somewhat simple and easy for you to understand, since ultimately the spec is a contract between you and the AI agent.
"Spec-driven development is not about adding more paperwork. It's about making intent explicit before cheap generation turns ambiguity into expensive mistakes."
The closing guidance: if you're building with AI today, you're probably already doing some form of this. Remember the spec is a contract between you and the agent — keep it concise, review it carefully, keep it up to date, and use it when the work is important enough that alignment actually matters.
"A spec is a contract between you and the AI agent."
"One of the biggest AI failure modes is asking for too much in one shot."
"Spec-driven development is not about adding more paperwork. It's about making intent explicit before cheap generation turns ambiguity into expensive mistakes."
"Keep it concise, review it carefully, keep it up to date, and use it when the work is important enough that alignment actually matters."
| Approx. Time | Topic |
|---|---|
| 0:00 | Why specs changed once the audience became AI |
| 0:29 | What a spec is — a contract; what a good spec covers |
| 1:00 | Why it matters: eager agents, guesswork, and one-shot failure |
| 1:37 | Breaking work into small verifiable tasks and adversarial checks |
| 1:58 | Intent demo — high-level intent and the clarifying interview |
| 2:20 | Reviewing the generated spec; avoid over-specifying |
| 2:50 | Parallel sub-agents and the living spec (adding 2FA) |
| 3:25 | When you don't need a spec; frameworks (SpecKit, OpenSpec) |
| 4:04 | Wrap-up — making intent explicit before expensive mistakes |