Spec-Driven Development for AI

Getting started with spec-driven development for AI coding agents. Compare vibe coding with spec-driven development for Claude Code and Codex.

Spec-driven development is for work that takes more than one conversation with an AI agent to complete. Most people use AI the way they use a search engine or a chatbot. They ask, read the answer and ask again, and for a series of questions that works. But prompting your way through a series of tasks can easily devolve into a mess. It might look finished, but it will be difficult to continue in a new session.

The reason is AI's missing memory. An AI agent remembers almost nothing from one session to the next, and on a long task its working memory (its context) fills up and it loses track of earlier decisions. For complex, multi-stage projects, agents do best with explicit, unambiguous instructions, so we set up project files that describe what we want (specifications) and how to do it (a plan, or playbook), as well as files that record progress (work history), such as a changelog or a work ledger. With files for instructions, a plan and notes on what was accomplished, any new session, or a different agent, can pick up where the last one stopped, with a continuity of memory that otherwise is lost.

Spec-driven development is a standard practice in software engineering, and it can be used for many other AI-assisted workflows that require reading and writing files, where the practice is less well known. I'll describe spec-driven development for a software project here.

Personally, as a former software engineering manager, director of engineering, and CTO, who now works exclusively with AI agents, I've found that applying these principles lets me launch the kind of robust, reliable software products in a matter of weeks that used to require teams of three to fifteen engineers, plus a product manager and UX designer, on software projects that once required a year or more of teamwork.

In this article I explain how the method works, how it differs from vibe coding, and how to use it with Claude Code and Codex with nothing more than Markdown files. I also describe special-purpose tools built for spec-driven development, and the criticism of the method, because it doesn't suit every job.

You should read Developer Setup for Starter Projects first, to learn where to put a project folder and how to open it in your agent.

Spec-driven development is one way to work once your Mac is set up for coding. See how to set up a Mac for development for a broader overview.

Before you get started

I recommend using our free app to install Claude Code and Codex if you will try spec-driven development. It is a FREE Mac app that installs the developer tools and AI coding agents you need, sets up an example starter project (organized for spec-driven development if you have coding experience), and verifies your setup is working. Here are all the details about the app before you download. Then download it:

Download the app "Set Up Your Mac for Coding"

How spec-driven development works

Spec-driven development gives an AI agent a set of planning documents that guide its work, and sets up rules to record progress, so any new session can follow the plan and determine what needs to be done next.

A spec - what to build and why, written as what a user will see and how you'll know it works. It leaves out how to build it.
A plan (or playbook) - how to build it, step by step, once the design choices, such as the language and the libraries, are made.
Tasks - the plan broken into small pieces of work, each one you can check, often as a checklist in a plan or playbook.
Software code or Work deliverables - the result after the agent works through the tasks, and you review each change.

The spec stays in the project as the record of what was agreed, and a measure of how well the agent has delivered the requirements. You're never locked into the original specification. It is natural to discover new requirements during work on a project. The agent can handle it. If you decide you need something different, or you want to improve what you've built, go back and revise the original specification, then ask for changes.

Vibe coding, vibe engineering and spec-driven development

Andrej Karpathy coined the term "vibe coding" in February 2025, to describe a working style that accepts whatever an AI writes without reading it. He described it as good enough for throwaway weekend projects. A prompt can produce a working app quickly, but the assumptions behind it and the decisions made along the way are never written down, so the app requires more and more attention in the final stages. And it becomes difficult to maintain with bug fixes and new features.

Simon Willison, a software developer who writes widely about AI coding tools, proposed the term "vibe engineering" in October 2025, in a blog post of that name (Vibe engineering). He wanted a name for the other end of the range from vibe coding, where experienced developers use coding agents to work faster but stay accountable for the software they ship. He chose the name half in jest, and in February 2026 he added that "agentic engineering" was becoming the more common name for the same idea.

Willison's point is that coding agents reward the habits and practices good software engineers already use. He lists automated tests, a plan before you code, good documentation, version control, automatic checks on every change, code review, careful manual testing, and research into the options before you choose one. An agent that can run tests can check its own work, and an agent that can read a plan and documentation doesn't have to guess.

Here's how the three terms differ:

Vibe coding - you describe what you want and accept whatever the agent writes, if it seems to work, without reading the code.
Vibe engineering - you stay responsible for the code. You plan, test, review and keep records, and the agent writes more of the code. It is a way of working, with no fixed set of documents.
Spec-driven development - a method for one part of vibe engineering, the plan. You write down what to build before the agent writes code, and keep that document as the record. Willison's list includes writing specifications and defining what success looks like, so spec-driven development fits inside vibe engineering, as one of its habits.

Developers who use specs say they pay off when a project is bigger than one session, when other people or other agents will work on it, and when you need to know later why the code does what it does.

Three levels of spec-driven development

Birgitta Böckeler, an engineer at Thoughtworks, sorts the method into three levels, in Understanding Spec-Driven-Development (October 2025):

Spec-first - you write a spec for the task at hand, and the agent builds from it.
Spec-anchored - you keep the spec after the task is done, and update it as features change.
Spec-as-source - the spec is the only file people edit, and the code is generated from it.

Every specialized spec tool she tried worked at the first level, and only one, Tessl, was aiming at the other two. She also separates a spec, written for one feature, from the files an agent reads in every session, such as AGENTS.md and overviews of the product. She calls those a "memory bank". We could refer to both as "AI project management."

Spec-driven development with Claude Code and Codex

You don't need a special-purpose tool, though several exist (described later). Claude Code and Codex can follow the method with plain Markdown files in your project folder:

Ask the agent to interview you about the feature, then to write a spec to a Markdown file such as specs/greeting.md, saying what the feature should do, what it leaves out, and how you'll check that it is done. Anthropic's best practices for Claude Code suggest this interview.
Read the spec, and revise it until it says what you want.
Ask the agent for a plan and a task list (a playbook) based on the spec, saved in a file, with no code yet.
Start a fresh session, so the agent has a clean context, and ask it to build from the playbook, one task at a time.
Turn the spec's "done when" list into checks the agent can run, such as tests, so it can confirm its own work. When it is done, ask the agent to check the code against the spec.

Add a line to AGENTS.md that says where the specs are, and tells the agent to read the relevant one before it starts work, so every session finds them. The next sections name the kinds of documents involved and show how to lay out a project folder for them, first a simple layout and then the one I use for my own projects.

Specs, designs, plans and playbooks

Spec-driven projects use several kinds of documents, and tools and teams give them different names. Each kind has its own place in the folder layouts below:

Spec - what to build and why, and how you'll know it is done, without saying how. Also called requirements, or a PRD (product requirements document). It goes in 3-specifications/.
Design - how the pieces fit, such as the language, the libraries and the structure, and why you chose them. Record it as a decision in 2-decisions/. Specialized tools may use different names: Spec Kit writes its design to a file named plan.md, and Kiro to design.md.
Plan and tasks - the ordered steps for a piece of work, broken into small items the agent checks off. Also called an implementation plan or an execution plan (OpenAI's "ExecPlan"), and the tasks can be listed in a checklist (tasks.md in Spec Kit and Kiro). Where it goes depends on its scope: a roadmap or plan for the whole project in 0-project-management/, a plan that settles an approach in 2-decisions/, or a handoff to the session that will build it in 4-playbooks/.
Playbook - step-by-step instructions an agent follows. In my projects it is often a one-time handoff from a spec to an implementation session, and it can also be a procedure you repeat, such as a release, which operations teams call a runbook. Both go in 4-playbooks/.

Human teams that follow Agile methods usually work from a sprint backlog of tickets, each with a user story and acceptance criteria, and figure out the implementation steps as they work. An AI agent doesn't think with the imaginative back-and-forth, try-and-retry habits of the human mind, comfortable with gaps and conjecture, so the plan or playbook you prepare for it has to be complete on its own. OpenAI's guidance for its execution plans says a newcomer, or a fresh session, should be able to finish the work from the plan alone.

Folder structure for a simple spec-driven project

The coding starter project in my "Set Up Your Mac" apps, AI-Coding-Project, is a small spec-driven project built with plain Markdown files and no special tool. See Developer Setup for Starter Projects for how to get it. Here is its layout:

AI-Coding-Project/
├── AGENTS.md              instructions the agent reads first
├── CLAUDE.md              containing a single line @AGENTS.md
├── README.md              "Start here", for you or an agent
├── CHANGELOG.md           what changed, newest first
├── 0-project-management/
│   ├── overview.md        what the project is, its roadmap and status
│   └── work-ledger/       handoff notes between sessions
├── 1-research/            what you learned before deciding
├── 2-decisions/           each choice and the reasons for it
├── 3-specifications/      one spec per feature, and a template
├── 4-playbooks/           task lists or procedures to implement the code
├── source/                the code
├── .claude/  .agents/     skills for Claude Code and Codex
└── .gitignore             files Git leaves out, such as .env

Here's what goes in each part, and how it guides the agent:

AGENTS.md - the agent reads it at the start of every session. It says the documents in the folder are the project's memory, tells the agent to read the relevant ones before it acts, and says not to write code without an agreed spec. If a spec turns out to be wrong, the agent fixes the spec and checks with you before it changes the code. CLAUDE.md holds the single line @AGENTS.md, so Claude Code reads the same instructions.
0-project-management/ - overview.md says what the project is for, what comes next and where things stand, so a new session can find its bearings. The work-ledger/ folder holds a short handoff note for each finished piece of work, with an index, newest first.
1-research/ - notes on what you learned before a decision, such as the options you compared. A decision cites them as its evidence.
2-decisions/ - one short record for each real choice, such as a language or a library, with the reasons and the alternatives you turned down. The agent reads them so it doesn't reopen a question you already settled.
3-specifications/ - one spec per feature, started from a template with a goal, the reasons, the behavior, a "done when" checklist and what is out of scope. The agent builds from the spec and checks its work against the checklist.
4-playbooks/ - tasks to execute for each work sprint, or step-by-step procedures you repeat, such as running or testing the program, so the agent follows the same steps every time and corrects the playbook when a step changes.
source/ - the code, kept apart from the documents that explain it.
CHANGELOG.md - a dated list of what changed, which the agent updates when it finishes a piece of work.

A research note leads to a decision, the decision to a spec, and the spec to a playbook for implementing it, followed by a changelog entry and a handoff note. Each document in the numbered folders starts with a short header that gives its version and date and names the documents it depends on, so you and the agent can follow the trail from the code back to the reasons for it. The project's skills help the agent write each kind of document the same way every time.

Folder structure for an advanced spec-driven project

I use a larger version of the same layout for my own projects, including my apps. It adds folders for every phase of a project's life, from research to measuring the results, and a few rules that keep many sessions and several agents consistent over months. Here's the layout for a project that ships an app:

my-app/
├── AGENTS.md              instructions, project facts, what not to do
├── CLAUDE.md              the single line @AGENTS.md
├── README.md              what the project is, for people or agents
├── CHANGELOG.md           notable changes, dated, newest first
├── work-ledger/           handoff notes: an index and one entry per piece of work
├── 0-project-management/  goals, roadmap, status, and a queue of bugs and ideas
├── 1-research/            what was learned before deciding
├── 2-decisions/           decision records (EDR-001, EDR-002 and so on)
├── 3-specifications/      specifications (SPEC-001 and so on)
├── 4-playbooks/           implementation tasks for the agent (PB-001 and so on)
├── 5-assets/              images, media and other files staged before use
├── 6-outreach/            announcements, campaigns and emails
├── 7-performance/         analytics and other measurements
├── 8-archive/             closed and superseded documents
├── source/                the code
└── scripts/               build and release scripts

Here's how it guides the agent, beyond what the simple layout does:

The numbers give a reading order. The folders follow the phases of the work: orient yourself, then research, make decisions, plan what to build and how to implement it, record what was made, and measure how well it meets goals. An agent new to the project reads them from low to high to catch up. Every project has all nine numbered folders, even when some are empty, so the order is the same in every project and the agent never has to learn a new layout.
Documents cite each other by ID. A file in the decision, specification, playbook or project-management folder gets a date and a permanent ID in its name, such as 2026-06-02-EDR-001-database-choice.md. A spec can say "as decided in EDR-001", and the agent can find that decision even if its file is later renamed.
Every document names its inputs. The header at the top of each Markdown document gives its version, date and author, and the documents it depends on, so the agent knows which version is current and what to recheck when an input changes.
AGENTS.md holds facts as well as rules. Facts that are easy to get wrong from memory, such as a version number or a key date, are listed with the date each was checked and a pointer to the evidence, so the agent looks them up instead of guessing. A "what not to do" list covers the actions that are costly to undo, such as publishing the site without my permission.
Each piece of work is recorded once, at four lengths. The Git commit message tells the full story. The changelog gets one to three sentences on what changed, the work ledger's index gets one line, and the ledger entry holds the decisions, the paths not taken, the evidence and the next steps. A new session reads the short versions first and the long ones only when it needs them.
Problems found along the way go in a queue. When the agent notices a bug or an idea outside its current task, it adds an item to a queue in 0-project-management/, with an ID and a severity, and doesn't fix it in passing. The current task stays focused, and nothing noticed is lost.

This layout takes more effort than the simple one, and the agent reads more before each task.

You'll see a similar structure in well-managed AI coding projects, though the structure and file names vary with each workplace and project leader. Software engineering managers may quibble over details of the structure but it follows generally-recognized practices for software engineering, adapted to an AI-native approach.

Spec-driven development tools

Several tools add commands to your AI agent that run the method for you, with a template for each document. These three come up most often in tutorials and discussions (so far, in October 2026).

GitHub Spec Kit

Spec Kit is GitHub's free, open-source toolkit. You install a command-line tool, specify, which sets up a project with templates and adds Spec Kit's commands to your agent. It works with more than 40 AI coding tools, including Claude Code and Codex.

Spec Kit needs uv (a Python package manager) and Python 3.11 or later. A new Mac has no Python, and the old system Python that comes with the Xcode Command Line Tools, version 3.9.6, is too old for Spec Kit. You don't need to install a newer Python yourself, because uv downloads one when it is needed. Install uv as shown in uv for Python on Mac, then install Spec Kit and create a project for Claude Code:

$ uv tool install specify-cli
$ specify init my-project --integration claude

For Codex, use --integration codex. The new folder looks empty in the Finder, because Spec Kit's files are in hidden folders (.specify, and .claude or .agents). Start your agent in the folder and run Spec Kit's commands in the agent's chat, one at a time, reviewing each result. You write a constitution (the project's principles) once, then for each feature a spec, a plan, tasks, the code, and a final check of the code against the spec. In Claude Code you type /speckit-constitution, /speckit-specify and so on, and in Codex $speckit-specify. Spec Kit reached version 1.0 in August 2026 and renamed its commands, so older tutorials show different names.

Kiro

Kiro, from Amazon Web Services (AWS), is its own app, a code editor based on VS Code, with a command-line version and a web version. For each feature or bug fix, Kiro writes three Markdown files, requirements.md (or bugfix.md for a bug), design.md and tasks.md, and waits for your approval at each stage. Each requirement follows a fixed pattern, "WHEN [something happens] THE SYSTEM SHALL [do something]", so it can be tested. Guidance for the whole project goes in "steering" files in a .kiro/steering folder, and Kiro also reads AGENTS.md. Kiro has a free plan with 50 credits, and paid plans from $20 a month (October 2026). Download it from kiro.dev.

OpenSpec

OpenSpec is a free, open-source tool from Fission AI, which its makers describe as lighter than Spec Kit. It needs Node.js, which Homebrew installs as a dependency:

$ brew install openspec

Move into your project folder and run openspec init, which asks which AI agents you use and adds OpenSpec's commands to them. Each change you propose gets its own folder in an openspec folder, with a proposal, specs, a design and a task list. In Claude Code you type /opsx:propose and a description of what you want, /opsx:apply to build it, and /opsx:archive when it is done. Codex spells the commands differently, such as $openspec-propose. OpenSpec sends anonymous usage statistics (command names and its version) unless you turn them off with openspec config set telemetry.enabled false.

Criticism of spec-driven development

You'll see criticism of spec-driven development, so consider critical perspectives before you adopt the method.

Too heavy for small jobs. Böckeler found that Kiro turned one small bug into four user stories with 16 acceptance criteria. Anthropic's own advice is to skip planning for a change you can describe in one sentence.
Too much to read. The tools write many long Markdown files, and you have to review them as well as the code.
Agents still drift. An agent can ignore a spec, follow it too literally, or report a task done when it isn't.
Some decisions appear only while you build. Critics call the method a return to "waterfall" planning, where everything is decided up front. In January 2026, leading practitioner Martin Fowler passed on Kent Beck's objection that descriptions of spec-driven development assume you learn nothing while you build. With an AI agent, I think you've got flexibility to adapt as you progress, because you can revise the spec as you learn, so I disagree.
Built-in planning may be enough. Claude Code and Codex both have a plan mode, and some developers find that a short plan, saved in the project, does the same job without a tool. Boris Cherny, who came up with Claude Code's plan mode, wrote in September 2026 that he no longer uses even that, because the newest models plan as they work.

Opinion is divided. In Hacker News discussions from July 2025 to August 2026, slightly more developers favored writing some kind of spec than opposed it, and most of those in favor keep light, homemade Markdown files in the project rather than use a special-purpose tool.

Where to start

Start with one small feature: a project folder, an AGENTS.md, and one spec with a "done when" list. That is the method in a nutshell, with the plan, the code and their history in one folder you control, and an agent that reads them. Most of your work with an AI can stay as quick as a chat. Write a spec when the job is bigger than one session, and look at the tools above if you want commands that run the method for you.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.