Before an agent implements a complicated feature, we need to agree on what that feature should do and how it fits the project. A written specification gives us something to discuss and revise together. In this video, we will look at when that agreement is worth writing down, at the discussion itself, the implementation and review that follow, and the more extreme option of regenerating code from a revised spec.
For a small program, a script, or a quick experiment, you can simply describe what you want, let the agent build it, and check the result. If the result is wrong, you fix it, or you throw it away and try again. Software like this does not need a specification. Writing one first would cost more than it saves.
Software grows, and so do the teams that build it. A larger system has many components, several people working on it, and several agents working alongside those people. Every change now involves decisions that interact with decisions made by other people and other agents. Before anyone builds, the team needs a way to agree on what the change should do and how the work should flow.
Spec-driven development is one practice for handling that complexity. The people and the agents involved agree on the intended behavior and the important decisions in a written document, and the implementation follows from it.
One way to work is to describe a feature, let the agent implement it, and review the code and behavior. You explain what needs changing and repeat. This is a legitimate way to develop software. But when the feature involves several interacting decisions, you can end up discovering what you wanted only after the agent has built something else.
Spec-driven development adds an earlier round of iteration. You draft the spec, discuss the decisions, and revise the document before asking for implementation. You still review and improve the code afterward. The advantage is that you have already worked through important questions about what to build.
Implementation also teaches us things. A constraint we missed or a requirement we reconsidered sends us back to the spec. These are connected cycles of work, and discoveries in the code can improve the next version of the specification.
A specification records what we intend to build, its scope and constraints, and the design decisions that matter. Writing requirements before implementation has a long history in software development. Coding agents give us another way to use that document: the agent can read it alongside the project and work on the implementation it describes.
The spec gives you, your teammates, and the agent a shared basis for the work. People can challenge a decision without first reconstructing it from code. It also helps to record why an important decision was made, because that explanation is exactly what someone needs when they later propose changing it.
Because the code is built from the spec, the spec defines the intended behavior. If the implementation disagrees with a requirement that still holds, the implementation is wrong. Documentation written after the fact describes what was built. When nobody maintains it, it drifts, and an agent reading it can work toward behavior the program no longer has. A spec also needs maintenance when requirements change. Its authority comes from defining the intended behavior, not simply from being a document.
A spec can describe a feature in a few hundred lines while its implementation runs to thousands or tens of thousands of lines. The requirements are concentrated in one place, while the implementation distributes those decisions across functions, files, and tests. That makes the spec a useful place to review the intended behavior together.
Generating code can be quick. Understanding it, checking it, integrating it, and changing it again take work. When we settle an important decision in the spec, we avoid building and then revising all the code that depends on the wrong decision. This is the reason to invest in the discussion before a complicated implementation.
In a large system, the spec normally describes a feature or a bounded change. You do not need to specify the entire system before working on it, and implementing the feature does not mean regenerating everything around it. The existing project is the starting point.
Features interact with other parts of the software. The spec discussion needs to cover interfaces, shared data, and existing behavior that must keep working. That means reading the relevant code, and involving the people responsible for the affected components. This is where a team discovers conflicting assumptions, and agrees on how the feature belongs in the system.
A short request leaves decisions unstated. As you describe the feature more carefully, you have to think about failure behavior, compatibility, and the responsibilities of different components. Writing the spec makes those questions visible. Answering one question can reveal another that you had not considered.
If you ask an agent to build while these questions are unresolved, it will sometimes ask you and sometimes continue with its own assumptions. So the important decisions are worth making explicit before you ask for the code. You can also leave a decision for later. In that case it helps to record it as open, along with which part of the work depends on resolving it.
One easy way to start is to ask the agent to read the relevant project context and help you draft the specification, and to raise the decisions it finds unresolved before anything is implemented. Then you discuss those questions at a pace that lets you think the answers through. When the decisions need careful attention, you can ask for one question at a time.
As the discussion develops, you keep going back to the written draft. The agent explains its interpretation and the consequences of the proposed choices, and you correct anything that does not match your intent. It is worth updating the document during this exchange rather than at the end, because reading the spec itself is one of the ways you discover the next question.
The milestone is a shared understanding of what will be built next. You understand the agent's proposal, its written description matches what you intend, and your teammates agree on the behavior, constraints, and checks for the next increment. An agent saying that it has no more questions is not enough on its own. The agreement comes from reviewing its explanation and the spec yourself.
What goes into the spec? There is no fixed list, so take what follows as a suggestion. A natural place to start is the goal and the scope: what changes, and what is outside this piece of work. Next comes the behavior that people or other software will observe, including normal use, failures, and the important edge cases. This is what gives the reader a clear account of what the feature is meant to do.
The spec also records how the feature connects to the existing project, and which constraints it must respect. An implementation decision belongs here when other work depends on it, or when leaving it open would lead to an unsuitable design. The reasons behind the important choices belong here too, without describing every line of code.
Acceptance criteria describe how to check that the required behavior is present, and they belong in the spec as well. The decisions that are still open stay visible too, together with when they need an answer. These sections are a starting point rather than a template. The right amount of detail is whatever lets people understand and review the decisions this change needs.
The spec is worth keeping in version control, like the code. Then each revision is a diff, and you can see exactly which decisions changed. That matters because a short change in requirements can affect several parts of the implementation. Once you agree on the intended change, it becomes the guide for reviewing the code.
Once the spec is agreed, the agent gets the document and access to the relevant repository, and you ask it to implement the feature within the existing project. Starting this in a fresh session is a useful test of the document. The new session still receives the project context and the applicable instructions, but it does not have the design conversation to fill in the decisions you forgot to write down.
What comes back is reviewed against the requirements, with the agreed checks run against it. It also has to fit the project and preserve the behavior that was already there. When something does not match, the fix depends on why. An implementation that got a clear requirement wrong is what gets fixed, and rewriting the spec to match that mistake would only hide the problem.
After revising the spec, you can ask the agent to change the current implementation. This preserves useful working code and applies the new decisions to it. It is a sensible starting point when the implementation still fits the design and the changes are localized.
You can also discard the feature's implementation and ask the agent to generate a fresh one from the revised spec. This makes sense when the first attempt was organized around assumptions that you have now changed, and repairing it would mean working against that structure.
Two implementations can satisfy the same spec and still have different internal designs. That is fine, and it tells you what to pin down: a design choice goes into the spec when it affects the requirements, the integration, or an important constraint. The other choices can stay open. A fresh implementation can also introduce different mistakes, though, so both paths need review and testing.
So far, the spec has guided ordinary development. You agree on the requirements in the document, and then you implement and edit the code as usual.
Some proponents of spec-driven development take the idea further. The spec becomes the maintained source, and the implementation is generated from it. When they want a change, they change the spec and regenerate the code from scratch. In this extreme, manual fixes to generated code aren't the durable way to record a change, because the next generation can replace them.
This is a stronger commitment than writing and reviewing a feature spec. It requires preserving the decisions and checks needed to generate an acceptable implementation again. It can apply to a feature or component without applying to the whole system. You can use spec-driven development without adopting this extreme.
There is a lot more to say about specs, and how far to take them is still argued about. What we hope you take from this video is simpler. A spec is a useful working tool for agreeing on what to build before the agent builds it, and we hope you try it in your own work.