Spec-Driven Development With AI: How to Start With Your Team

Spec-Driven Development With AI: How to Start With Your Team

Spec-driven development with AI is the practice of writing a clear, reviewable specification before asking an assistant for code, then using that text as the reference for generating, testing and reviewing. Instead of fixing vague results afterward, the team discusses intent, limits and acceptance criteria before the first line is written. The working hypothesis is simple: a misunderstanding shows up in the text, where it is cheap to fix, and not in code that already exists.

Key takeaways

• The spec becomes the contract between people and the assistant: what must happen, what must not happen, and how you know it is done.
• Coding assistants fill gaps with assumptions. The more gaps in the instruction, the more rework in review.
• A good spec is short, verifiable and versioned alongside the code, not a long document nobody updates.
• The spec's acceptance criteria are the natural basis for tests, which makes it easier to validate what the AI delivered.
• The safest way to start is a pilot on one real, small feature, with human review and a success criterion agreed in advance.

What is spec-driven development with AI?

It is a way of organizing work with assistants such as Claude Code, Copilot or Cursor. First the team writes, in plain language, what the change needs to do. Then the assistant proposes a plan, the team reviews the plan, and only then is code generated. The spec stays alive: when the behavior changes, the text changes first.

The idea itself is not new. Teams that already wrote requirements, user stories or design documents know the principle. What assistants change is speed. Generating code has become cheap, so the bottleneck shifts to deciding well what to generate. An ambiguous instruction produces a lot of plausible, wrong code, and reading that code costs the time of experienced people.

It helps to separate three things. What the official tool documentation describes is how to give instructions and context to the model. What comes from implementation experience is that teams tend to gain clarity when they discuss the text before the code. And what is still a hypothesis, to be tested in your own setting, is how much rework each team actually avoids.

Why does asking for code without a spec create rework?

When someone writes only "build the rescheduling screen," the assistant has to decide many things on its own: who can reschedule, until when, what happens to billing, what message appears when something fails. Every decision made silently is a possible divergence from what the business wanted.

Rework usually shows up in four forms:

• Business rules invented by the model that look reasonable but contradict how the operation works.
• Code that works on the happy path and ignores edge cases, such as missing data or a user without permission.
• Changes that touch too many files, because the scope boundary was never stated.
• Long reviews in which the reviewer has to reconstruct the intent from the code.

The spec moves that conversation earlier. The discussion happens over a paragraph, not over a set of changes already spread across the repository.

What does a good spec contain?

It does not need to be long. It needs to be verifiable. A lean structure that works for most tasks:

• Goal: the change in one or two sentences, tied to the business problem.
• Context: where this lives in the system, and which modules and integrations are affected.
• Expected behavior: rules written as situations and outcomes (when X happens, the system does Y).
• Out of scope: what the assistant must not touch or decide.
• Data and permissions: which personal data is involved, who can run the action, and what must be logged.
• Acceptance criteria: objective conditions the team can check, preferably converted into tests.
• Open questions: doubts that need a human answer before implementation.

The open questions item is the most underrated. Asking the assistant to list its doubts before planning stops it from filling gaps on its own.

How to start: a step-by-step plan

For a team that has not yet adopted the practice, the suggestion is a short, controlled pilot:

• Choose a real, small, low-risk feature, with a business owner available to answer questions.
• Define the success criterion before you begin, for example: fewer correction rounds in review and a clear understanding of what was delivered. Record how you will observe it.
• Write the spec as a plain text file in the repository itself, so it is versioned and reviewable like any other artifact.
• Ask the assistant to read the spec and return questions and an implementation plan, without writing code yet.
• Review the plan with a human. Fix the spec, not just the assistant's answer.
• Generate code in small steps, each tied to one acceptance criterion, and run the tests at each step.
• Do the code review by comparing the result with the spec, not only with the reviewer's opinion.
• At the end, record what the spec was missing and adjust the document template for the next task.
• Decide based on what you observed: expand to other tasks, adjust the format, or stop.

That last point matters. If the format did not help for that type of work, stopping is a legitimate outcome of the pilot.

Illustrative scenario: rescheduling rule for a technical visit

Imagine, as an example, a service company that wants customers to reschedule a technical visit through the internal system. Without a spec, the request to the assistant would be "allow visits to be rescheduled." The likely result is a button that changes the date, without checking whether the technician is available and without notifying anyone.

With a spec, the text would say something like this: the customer can only reschedule visits that have not started; the new date must respect the technician's calendar; if there is no slot, the system offers a list of free dates and changes nothing; every change creates a record of who asked and when; customer messages use the templates already approved; billing changes are out of scope. Under open questions, the team notes: is there a minimum notice period before the visit to allow a change?

The answer to that question comes from the operations owner in minutes, before any code. Without that step, the rule would probably be discovered in production. This is a constructed example to illustrate the mechanism, not a customer result.

How does the spec connect to tests, context and skills?

Acceptance criteria are the link to quality. Each verifiable criterion can become a test, which lowers the risk of accepting tests that merely confirm what the code already does. It is worth reading the article on AI-generated tests and how to validate them to build that step carefully. Anthropic's engineering guidance on evaluating agents follows the same logic: define up front what counts as success and measure against it.

There is also the matter of context. A spec that is too long takes up space the model could use for the relevant code. Anthropic's guidance on context engineering for agents points toward providing enough information, kept lean, without excess. If the topic is new to you, the article on the context window in AI explains why this matters.

Finally, whatever repeats should become a standard. Spec templates, project conventions and review checklists can be packaged as Claude Code skills, so the whole team starts from the same format. As a general principle, Anthropic's material on building effective agents recommends starting simple and adding complexity only when it is justified, which applies to the process as well.

What mistakes should you avoid, and how do you know it is working?

The most common problems are predictable:

• Writing the spec after the code, just to document it. That does not reduce rework, it only creates paperwork.
• Over-detailing. A huge text that describes the implementation removes room for good plans and goes stale quickly.
• Forgetting to say what is out of scope.
• Treating the assistant's plan as approved without a human reading it.
• Putting real customer personal data in the spec or the prompts without need. If personal data is involved, the team should align with internal policy and with LGPD requirements, and use fictional examples whenever possible.

On measuring, the care is not to turn the pilot into individual surveillance. Watch process signals: how often a delivery comes back for correction, how many doubts surfaced only in review, whether the reviewer understood the intent without asking. The article on how to measure AI productivity without surveillance covers this approach in detail.

The method we use in AI projects applies here directly. Map: understand how the team specifies and reviews today, and where rework concentrates. Limit: define which tasks, data and permissions the assistant can touch. Pilot: apply the format to a real workflow, with records and an agreed success criterion. Transfer: hand the spec template and the review process to the team, and decide together whether to expand, adjust or stop.

Frequently asked questions

Does spec-driven development with AI work for small teams? Yes, as long as the format stays light. For a small team, a spec of a few paragraphs in the repository is enough to build the habit of deciding before generating. The risk is bureaucracy, so start with one task and adjust as you use it.

Do I need a specific tool to practice it? Not necessarily. The core of the practice is a reviewable text file, an assistant that can read it, and a review process that compares the result against it. Some tools structure this flow, but you can start with what the team already uses.

Does the spec replace the prompt? No, it organizes it. The prompt points to the spec and asks for clear steps, such as listing doubts, proposing a plan and implementing one criterion at a time. The spec stays in the repository and also serves whoever arrives later, while the prompt is disposable.

How do I know whether the practice is reducing rework? Agree before the pilot on what you will observe, such as the number of correction rounds per delivery and the doubts that only surfaced in review, and compare with the previous flow without turning it into a ranking of people. If the gain is not noticeable for that type of task, adjust the format or stop. The decision should come from what was recorded, not from expectation.

Sources

• Anthropic: Effective context engineering for AI agents
• Anthropic: Demystifying evals for AI agents
• Anthropic: Building effective agents