Spec-driven development with code agents

Introduction

#

As AI coding agents become more useful in software development, the way we describe tasks to them also becomes more important. It is no longer enough to only say “build this feature” and hope that the result matches what we had in mind. The better the instructions are, the better the agent can work.

This is where spec-driven development becomes interesting.

Spec-driven development is a workflow where the developer starts by writing a clear specification before writing or generating the code. A spec describes what the application should do, how it should behave, what the user should experience, and sometimes what technical constraints the solution should follow.

When working with AI code agents, specs can become the bridge between the human idea and the generated implementation. Instead of relying on vague prompts, the developer can give the agent a structured description of the goal.

What Is Spec-driven Development?

#

Spec-driven development means that the specification becomes the starting point for development. The spec can describe things like:

• The purpose of the application
• The main user flows
• The features that must be included
• The data the application should use
• The expected behavior in different situations
• Error handling
• Technical requirements
• What should not be included

In traditional development, a spec can help a team agree on what needs to be built before coding begins. With AI-assisted development, the spec becomes even more useful because it gives the coding agent a clearer target.

A simple prompt might be:

Build a quiz app.

A better spec-driven prompt might explain:

Build a React quiz app where users can answer one question at a time, receive feedback after each answer, save progress in local storage, review answers at the end, and reset the quiz. The app should not require login, and the questions should be stored in a separate data file.

The second version gives the code agent much more context. It reduces guesswork and makes it easier to evaluate whether the result is correct.

Why Specs Matter When Using Code Agents

#

AI code agents can generate code quickly, but they do not automatically know the full intention behind a project. If the instructions are unclear, the agent may make assumptions. Sometimes those assumptions are useful, but other times they can lead to features, structures, or design choices that do not fit the project.

Specs help because they make the task more concrete.

A good spec can answer questions such as:

• What problem is the application solving?
• Who is using it?
• What should happen first?
• What should happen after the user completes a task?
• What data should be saved?
• What should happen if something goes wrong?
• What is the minimum version that should work?

This makes it easier for the code agent to build something useful. It also makes it easier for the developer to review the result, because the finished code can be compared directly with the spec.

How I Could Use Specs With Code Agents

#

I could imagine using specs as the first step in almost every AI-assisted coding project.

Before asking a coding agent to create files or write code, I would first describe the project in a structured way. For example, if I wanted to build a small task management app, the spec could include:

• Users can create, edit, and delete tasks
• Tasks have a title, description, status, and due date
• Tasks are saved in local storage
• The app has filters for all, active, and completed tasks
• The design should be simple and mobile-friendly
• The first version should not include authentication or a backend

After writing the spec, I could ask the coding agent to create a plan before coding. This would help check whether the agent understood the task correctly.

Then the agent could generate the first version of the app based on the spec. If something is missing, I would not need to explain everything again. I could point back to the spec and say which requirement has not been fulfilled.

This makes the workflow more controlled.

Using Logs Together With Specs

#

Specs describe what should happen. Logs can show what actually happened.

That is why I think specs and logs can work very well together when using code agents. A spec gives the agent the intended behavior, while logs give the agent real information from the application or development environment.

Logs can include things like:

• Build errors
• Runtime errors
• Console output
• Test results
• API responses
• User interaction problems
• Deployment errors

When something breaks, the code agent can compare the error logs with the original spec. This gives it more context than just the error message alone.

For example, if a quiz app is supposed to save answers in local storage, but the browser console shows an error when saving, the agent can use both the spec and the log:

• The spec says answers should be saved locally
• The log shows where the save function fails
• The agent can inspect the code and suggest a fix
• The developer can test whether the behavior now matches the spec

This creates a feedback loop between intention, implementation, and real behavior.

A Possible Workflow

#

A spec-driven workflow with a code agent could look like this:

1. Write a short project idea
2. Turn the idea into a structured spec
3. Ask the code agent to review the spec and create an implementation plan
4. Let the agent build the first version
5. Run the application
6. Collect logs, errors, and test results
7. Give the logs back to the agent
8. Ask the agent to fix the implementation based on the spec
9. Review the code manually
10. Update the spec when the project changes

This workflow would make the code agent more like a development partner. Instead of only generating code from a single prompt, the agent would work with a living description of the project.

The spec would guide the direction, and the logs would help correct the implementation.

Example: Building an Application With Specs and Logs

#

Imagine I want to build a simple habit tracker.

The first spec could describe the core features:

• Users can add habits
• Users can mark habits as completed each day
• The app shows a weekly overview
• Data is stored locally in the browser
• The app works without login
• The design should be clean and easy to use on mobile

The coding agent could then build the app based on this spec.

After testing it, I might discover from the console logs that the app saves completed habits incorrectly when the date changes. Instead of just saying “fix the bug,” I could give the agent the spec and the log:

Spec requirement:
A habit should be marked as completed only for the selected day.

Observed problem:
When I mark a habit as completed today, it also appears completed for other days.

Console/log output:
[example error or state output]