Spec-Driven Development with Coding Agents: Write the Spec, Let the Agent Build

Andrew Ng welcomes a DeepLearning.AI course built with JetBrains. Spec-driven development, he says, is currently the best workflow for serious apps with coding agents: give the agent a markdown file or a long prompt that says exactly what to build, and it implements that spec. Your job shifts from typing code to writing down the context the agent does not already have.

The instructor is Paul Everitt, a developer advocate at JetBrains. Everitt thanks him, and they joke that Everitt is wearing spectacles he does not need—on-brand for a course about specs. Then Everitt lays out three benefits you should feel immediately.

First, small edits to the spec control large code changes. One sentence such as “use SQLite with Prisma” can move hundreds of lines; swap it for MongoDB and the same amplification runs the other way. Writing specs is far more efficient than writing that code by hand.

Second, specs fight context decay between sessions. Agents are stateless, so the highest-quality context has to be sitting there when they boot. Third, specs raise intent fidelity: you define the problem, success criteria, and constraints, and the agent can elaborate them into a fuller plan instead of guessing.

Everitt often writes a spec by talking through architectural tradeoffs with Claude Code, Gemini, or Codex, then asking the agent to summarize the decisions in markdown. That is hard work on purpose. You have to decide the product, the features, and the architecture. Skip the spec and you leave those calls to the model, which is fine if you want to roll the dice, and a good way to get unmaintainable code and weird products if you do not.

He has seen teams on a complex product with no shared spec: different developers, different agents, fast output, contradictory results. SDD starts with a project constitution of immutable standards, then feature loops. Each feature lives on its own branch with plan, implement, and verify, so you get a clean slate between features. The same loop works greenfield (draft the constitution in conversation) and brownfield (generate it from the existing tree), always versioning in small steps.

The course will also show how to write agent skills that automate the workflow. If a short prompt is enough, Everitt is happy to be lazy. For anything with real complexity, the developers he respects still write a detailed spec, because they have context and opinions the model does not. If the agent is about to code for twenty or thirty minutes—hours of old-fashioned work—three or four minutes of clear instructions is cheap.

He credits colleagues at JetBrains and Isabel Zaro at DeepLearning.AI for helping build the course. Then it is your turn: the next video is where you stop talking about specs and actually write them.

When people hear “coding with agents,” they often hear vibe coding. You prompt “create me a button,” look at a too-big result, point out mistakes, and loop until you are satisfied. The dialogue is long, and the history is not even saved. Fine for a button. Useless as a process for a large, ongoing project.

High-level prompts are fast and they produce disposable code and mounting debt. What you need is engineering: a maintained specification that is a permanent technical artifact. SDD is the professional response to unsupervised generation. The spec, the what and why, is decoupled from the implementation, the how. It is a contract among humans and with the agent. Your main job is converting intention into that spec.

The three benefits return with more texture. A few sentences about look and feel can become hundreds of lines of CSS, which cuts the cognitive overhead of watching an ultra-fast agent. Specs also kill the context-decay problem that derails multi-turn sessions: as the window fills, the agent makes more mistakes. A spec persists across sessions and even across agents, and it anchors the work to the core of the codebase.

Intent fidelity means the agent is more likely to build what you meant, because you were forced to name the problem, success criteria, constraints, and user flows before it generated code. That is the difference between vibe-coding slop and engineering a product. Specs help on a greenfield repo and on a project that has been running for years; they are how you fight drift.

Think of compilers: understandable source becomes machine code. SDD is the analog for agents—specs become source. Better still, the specs are in human language, so stakeholders can read them. The practice has taken off around productivity worries: spec-authoring tools, conference talks on capturing intent, a broader push to bring software-lifecycle lessons into agentic coding.

This is for coding agents, not chatbots. A chatbot can talk about code; it cannot see your repo or your tools. An agent takes a prompt, plans, reasons, and uses the codebase and the toolchain. In SDD you treat it as a highly capable pair programmer: it brings knowledge and speed, you bring the blueprints. The agent is the muscle. The spec is the brain.

You specify the project first, then each feature, and you get better as you go. The hard skill is the right level of detail. Treat the agent as that pair programmer and you will often hit it: lots of context on goals, mission, audience, and constraints, and less on low-level decisions it can make itself.

The workflow starts with a constitution: mission, tech stack, roadmap. Many people dump this into a top-level AGENTS.md. A constitution is more structured and agent-agnostic. It is the agreement between you and the agent, and among the humans. Mission is the why—vision, audiences, scope. Tech stack is the shared picture of development and deployment. The roadmap is a living sequence of phases, each later run through its own feature spec.

Once the constitution exists, every feature is the same loop: plan, implement, validate. Between features you replan—revise the constitution, update the roadmap, even improve the process. In those phases you steer. Imagine handing detailed drawings to builders, then supervising and accepting the result. You do not tell them how to hold the trowel. You give them the context they do not have.

That is one SDD workflow modern developers are starting to use: constitution first, then a repeatable feature loop, with you as supervisor rather than typist. Next up is the constitution itself. First, a little setup so the repo and the agent are ready.

Repo setup is in the next reading. The following video is optional: if you already run something like Claude Code in WebStorm, skip it. SDD is not tied to one IDE or one agent. VS Code with the Codex CLI, Zed with a local model—all fine. Because this course is a web app, the demos use WebStorm and Claude Code. Download instructions were in the previous reading.

Everitt opens WebStorm and starts a TypeScript project named Agent Clinic, with Git from the first commit so code and specs stay versioned. IDEs have chat panels, and people talk to agents in many ways, but the Git trail is not optional. When the agent wants to run a command, it asks unless you started it in an unsafe mode. Watch those prompts. The code is still yours.

You have to tell the agent what the project is: mission, audience, other decisions. That is the constitution, written together, not alone. For a new company web app: what is the core idea, how does it fit the house stack, what features are planned. Those three pillars become a global set of high-level requirements that later feature work has to obey, and that stakeholders can read.

Tech-stack choices are endless; you narrow them by tradeoffs and by what the company already uses, and you write that down for the agent, for teammates, and for future you. The agent will surprise you with architecture you had not considered, packages that already do the work, and questions like speed versus data fidelity. Mission, stack, and roadmap are not greenfield-only. Existing codebases have the same three pillars; brownfield comes in a later lesson.

The running example is Agent Clinic, a parody of the classic Pet Clinic: a place for AI agents to get relief from their humans. Coding agents are stressed—hallucinations, context rot, memory issues, sub-agent coordination. The clinic manages appointments, ailments like hallucination, and treatments like a context infusion. It is a full-stack web app. In the constitution conversation they will settle the actual stack; the demos land on Hono, TypeScript, and SQLite.

He pastes a project description and points the agent at README.md, where stakeholders already left notes. He mentions Claude Code’s AskUserQuestion tool—optional, but it looks good in the UI—and asks to work through mission, tech stack, and a roadmap in small steps. SDD wants a human in the loop on small diffs, not a giant unsupervised dump.

The agent asks good questions; yours will differ. First: what tone should mission.md take? Everitt picks playful. Engineers are used to TypeScript on the backend, so that becomes a requirement. For roadmap granularity he takes the first option. Submit. The agent asks for write permission, which keeps you in control. If you accept the tradeoff, you can approve a command for the rest of the session.

Three files appear under specs/: mission.md, tech-stack.md, roadmap.md. Human-in-the-loop time. The mission left out a target audience—reasonable; how would the agent know the business? Do not edit the files by hand. Ask the agent, so related documents stay consistent. They want SQLite for a quick prototype. They had not said so, but the agent had already recommended it; now it is in the stack.

One more review. Get the constitution right up front, because everything later will be generated from it, then commit it as a living document. Agent Clinic now has a mission, a stack, and a roadmap that both humans and the agent can load. Time for the first feature.

The roadmap has features. You build them with specs, starting with phase 1: Hello Hono. It is too early to code. A good plan names the approach, the sequence, and how you will know it worked. Start with fresh agent context so it loads from the constitution, and put the work on a separate branch. The prompt is a conversation about a feature spec: tasks, requirements, and a validation scorecard.

The agent will ask you to make the calls. Watch for conflicts. You do not have to take its solutions. Everitt keeps phase 1 scope as written, pins the Hono version, enforces strict TypeScript, and confirms with a manual curl. Submit. It is fast—must have been the nano. Now the ball is back on your side: review the spec the agent just wrote.

Get the docs right at the beginning or the agent will wander. If something is wrong, ask it to fix the files so requirements and validation stay in sync. They want a nicer placeholder homepage in this first spec; the agent updates the plan and the requirements. Requirements are where important constraints live. Do not skip them, and do not put variable names in them. You want control without over-steering.

Last, validation: make sure the agent can check that it got it right. Those files were updated for the homepage too. Feature spec done. Commit in the IDE. The time you spend here expands downstream into hundreds of lines of code.

Implementation. Refresh on the Hello Hono plan, then slash-clear the context so the agent is not carrying the planning chat. Prompt it to implement all the task groups. You can also do groups one at a time for smaller commits, which matters in security or database work where small mistakes compound.

While Claude runs, watch the console. Afterward, the commit window is an early look at the diff. That is the developer’s job in this paradigm: architect and supervisor, holding the agent to a clear contract. The summary lists extra detail per task group. From package.json they run the app. The server starts. The browser shows almost nothing. They said nano, but pixels on screen still feel good. The agent already did its validation; yours is next.

A feature is ready. Do not merge yet. This last step is review, and programmers already spend hours a week on code review. Start from the commit view. Focus on whether the feature works and matches the spec, not which CSS classes it used.

Home.tsx is minimal. Nano really meant nano. They want a layout with header, main, and footer as subcomponents, plus a CSS file. That miss in the code came from a miss in the plan—they never asked for it. Ask the agent to fix both spec and implementation. That generate-and-verify loop is human in the loop.

Agents write so fast that developers now talk about cognitive debt: the mental load of tracking what the code does and how it evolved. Keep changes small enough to review or the process stops being fast. The agent is also checking that the new work did not break anything. It finishes, adds a Group 5 to the feature plan, and lands a layout component and a CSS file.

The three subcomponents are still in one file, which does not match convention. Splitting them with the IDE’s move tool is the kind of thing editors have always been good at. Not so fast: that is how specs and READMEs drift. Ask the agent to fix every mention so you do not pay for it later.

Tests would help, but the agent never installed a test package. That is a constitution issue for the next lesson. Notice a bit of the constitution changed on this same branch. How to version specs against the code they produced is still an evolving community topic. Checking off a roadmap step is small enough to keep here; a bigger constitution change belongs on its own branch. Merge. First feature done. Before rushing the next one, replan.

They implemented the first feature and want to do it again. Do not rush. Run slow to run fast. Tests are good for validation, but the agent never got their testing preferences. Open a replanning branch and update the tech stack in the constitution. Spec versioning is still evolving; the constitution is a living document, and updates belong on their own branch so you can see which version produced which code.

The first prompt states the testing policy. The agent adds a script in package.json and no dependency yet—note that for later. A testing framework is for future code, but they also tell it to update existing feature specs and implementation. After two prompts the harness is there and the tests are not. A third prompt writes them. They run under the debugger as part of human-in-the-loop, then commit.

Sometimes the product plan changes. After feature one, the PM notes that 40% of users are on mobile, so responsive design is now a baseline. Tell the agent to correct product specs, feature specs, and code. This early, the change is small enough to do in replanning. If the new work is large, schedule it as its own roadmap phase. Use judgment. Specs should capture decisions, not only the code, and both should stay in sync for the team.

The agent implements the responsive fix in code and in the specs. Review the diffs, commit. Small steps and frequent commits keep review from overloading your brain. Then housekeeping: does the next roadmap item still make sense? Features two through five hang together. Collapse them into one step, commit, and take that as the next feature.

Replanning can be about a feature, the whole project, or the workflow across an organization. Non-technical stakeholders may want a changelog on every merge to main. Most coding agents now support skills: a package of instructions and resources that give the agent a new capability. Skills are for definable, repeatable, context-specific work. A changelog is a good one. You could write it by hand; many agents have a skill that writes skills.

Ask whether the skill is unique to this repo or should be standard everywhere—you will get a feel with use. You can also package validation: README updates, lint, format, tests. Repeatable process, less manual work. The agent writes the changelog skill in the global skills area, so it works across projects, then uses it to generate CHANGELOG.md here. Changelogs talk to stakeholders, including the agent. Read it. Commit, merge the branch.

Most of your work as a developer is now planning and validation, not typing the implementation. Make time between features to replan, or the constitution will rot. They just improved both the constitution and the workflow. Before the next roadmap item, a common pain point: AI fatigue from reviewing too much generated code.

Agents generate a lot of code. Reviewing it all is exhausting. Fight that with a clean division between feature phases, and start the next one in the right flow state. Unfinished work? Last branch merged to main? Next roadmap item still the right one? Agent context cleared, so the specs carry intent instead of a memory snapshot, and the limited context budget goes to the new work? Take a moment to start well so you can finish.

They clear context and start the next feature: agents and ailments. They keep typing the same prompt; a later lesson will turn that into a skill. The agent asks whether to keep these features in one phase. They already decided yes. Migrations: plain SQL. Validation: options one, two, and three. Submit. Watch the reasoning if your agent has a verbose mode; the intermediate ideas are useful.

One small intent capture: Pico CSS as the CSS framework. Review the three feature-spec files, starting with requirements, and tell the agent to update any other files that should follow. Commit the spec, this time letting the agent write the message. Then implementation. The split between planning and feature work keeps context—yours and the agent’s—from overflowing. If the feature is too big, implement part of the plan first so the diffs stay reviewable.

Phase 2 lands. You watched it, so you have a rough idea. That is not enough. Slow down. Everyone has a review style; to play to the agent’s strengths and cut fatigue, stay on higher-level requirements. Skip nitpicks like variable names. Just make sure you could commit this under your name. Here, props used inline types; they want a standalone TypeScript type, everywhere. Tell the agent to fix it.

You probably never wrote “extracted prop types” into the spec. An omission is not a failure. You are evolving the spec as you discover details, and capturing them makes later features better. Small-step commit. Last step: validation. Read what the spec said the agent would check, then run the app, and also make sure you understand the changes so cognitive debt does not pile up. Tests under the debugger are a good way to walk the flow.

Sometimes you need to check that you were not lied to. Ask the agent to spawn several sub-agents for a deep review of the whole project with this change. That gives more thinking room and keeps the main agent’s context window clean. They come back with issues and recommendations; all look good. The agent fixes, runs tests, and leaves the project in a good state. Keep that move. A second look usually finds something important.

Validation done. Commit. As a last step on the branch, run the changelog skill from the previous lesson, commit again, merge. A quick replan: is the next roadmap item still right? Yes. The project is in shape. That clean break is how you manage AI fatigue. Coffee is allowed. The process is starting to look repeatable. Next: can it carry an MVP?

Two features in, and of course management wants an MVP. Have they made enough progress to experiment? They vary the usual feature-spec prompt: implement the rest of the roadmap, with guidance about the specs already on disk. Only take a chunk this large if you trust the constitution and you can still handle review. Treat the MVP as an extreme test. If the result is not what you wanted, you owe the project a serious replan to find what led the agent astray.

The agent asks good questions again. A lot of spec files start as this back-and-forth. Submit, write the MVP specs to disk, and review them—you will often catch assumptions the agent invented to fill gaps. Glance at plan, requirements, and validation. Small steps, frequent commits: save the planning spec before the big implementation.

The agent does a lot of work. Showtime. Run the app. Each section now has much more, driven by sample data from the database: agents, therapies, a dashboard of appointments. Usually you would validate the code in depth. This is an MVP, so they also ask the agent to validate the specs. That turns out to be useful: the MVP found holes in the planning. Share that evaluation with stakeholders, then merge or archive the branch.

The workflow succeeded. After a constitution and two features, the MVP is a useful demo because of the guidance, not in spite of it. Not every project is an MVP. Many are brownfield: they start from an existing tree. Next, how to introduce SDD there.

People say SDD, and even AI, only work on greenfield. Everitt disagrees. To keep it easy, the “legacy” project is Agent Clinic’s MVP: start on main without the specs folder, in a new Claude Code session, in a different directory. Background lives in README.md; open work lives in TODO.md. A real legacy tree might have plans in an issue tracker, a spreadsheet, or a Word doc. Same workflow: constitution first, almost the same prompt as lesson four, but this time look for roadmap items in existing artifacts—here, the TODO file.

The agent discovers and, in a sense, reverse-engineers SDD artifacts from the codebase. The constitution is how future agent changes stay aligned with what past developers already built. Add more context if you have it: maybe you were dropped in to improve efficiency while shipping requested features. The conversation is richer because there is more to read—code, commits, documents. You will see a lot of tool calls while it explores.

Look at what it recovered. Mission has an audience, the project idea, and extra notes. Tech stack has the file structure, framework versions, and the clarifications they were asked. The roadmap is phased to match the TODO. Commit those constitution files. In SDD, specs are part of versioning. The legacy project now sits on an SDD foundation. From here the loop is the same as before.

Grab the next roadmap item and plan it in conversation. Phase 1 is a feedback form. They get a branch and specs, review plan, requirements, and validation, then commit. After corrections in chat, implement. When the agent finishes, validate that the code is good and the feature works. Commit, merge to main.

Then replan, and give it time. You just added SDD to a project; there will be things to tune. A legacy tree is now rebased onto spec-driven development without a pile of manual archaeology. You have a documented, stepwise, engineering-shaped flow, and you stayed in control. The spec is now the memory of the project. Do not let it fade. If you want something faster, the next lesson automates the parts you keep repeating.

They have a working SDD loop. Now automate it their way. Agent skills are an open standard for giving agents new capabilities. The feature-spec prompt is the same every time: do this, write these three files. Ask the agent to use its skill-creator skill and talk it through. There are community “skills for skills” you can install as well. Watch the output while it works. Is it making the choices you wanted?

The skill lands in a directory. Skills can be per-project or global. You invoke them by naming the skill in the prompt, or by having one skill call another. Under the skills standard, agents use the description to decide when to call a skill—progressive disclosure. Their judgment is not always perfect, especially as the window grows. Same heuristic as file tagging: if you know you want it, name it. That saves thinking tokens.

Agents still have built-in slash commands like /clear. Custom slash commands were popular; many agents are moving that energy into skills. When the agent needs an API, a private knowledge base, or a database, the universal extension has been MCP. For current package docs, the popular choice is Context7, which pulls updated documentation into context so you are not stuck on last year’s React. MCP servers are still common, but a skill that shells out to a CLI often does the same job more elegantly. Context7 now suggests that path.

They install the Context7 package for Claude Code and immediately see the choice: MCP server, or CLI plus skills. They take the second. First-timers need an account; they are already logged in. Back in Claude Code, an example prompt that needs current stack docs picks up Context7 on its own. The trend from MCP servers to skills-plus-CLI is accelerating: a CLI can act with less setup and less context.

As you scale the workflow, you will want to share it across machines, teammates, maybe the outside world. Some agents, including Claude Code, have plugins: installable bundles of extensions, with a growing set of free ones. Plugins are not yet a cross-agent standard. Like apps, they execute code, so trust them on install and on update.

GitHub’s Spec Kit is one attempt to formalize SDD with agents. Install it and you get slash commands close to this course: constitution, plan, tasks, implement. Another popular option is OpenSpec from Fission-AI. Its propose / explore / apply / archive maps onto plan, implement, and replan, with canonical patterns for quick features. Both give you branch management, verification scripts, and opinionated spec formats. Experiment, then steal what fits.

Sometimes in the middle of a feature you want to research an idea—say a database choice—without stopping the branch or putting it on the roadmap. Talk it through, accept most recommendations, change your mind on one, and do not lose it. Tell the agent to write a report in a well-known backlog location. Later you can schedule that research onto the roadmap with a link. As the pile grows, write a skill for it. SDD is how the agent writes code your way: adopt a framework, then customize it with skills so the team runs the process you actually want.

SDD moves work from the how to the what and why. Agents and models move so fast you do not want the workflow tied to one of them. Standards help you switch agents and keep the process: MCP for external tools, AGENTS.md for rules, agent skills for repeatable workflows with extra context, and ACP for connecting agents to clients.

Codex, OpenAI’s coding agent, runs in a desktop app, in editors, and in a terminal. Everitt copies the feature-spec skill from the earlier lesson into Codex’s different path. It runs. You can switch back and forth on the same project and keep the SDD workflow. Different editors can talk to different agents through the Agent Client Protocol, which is a match when both sides support it.

The ACP registry automates finding, installing, and connecting agents inside clients, covering the whole lifecycle. In JetBrains, the AI chat window leads to that registry and a list of compatible agents. OpenCode is a popular open-source agent; clicking install can fetch OpenCode itself if needed and wire it into the IDE. You then run it alongside the other agents in the same editor, on the same SDD artifacts.

How does ACP actually work? It was designed to plug agents and clients together, and the protocol matches what LSP uses. It covers more than chat: next-edit suggestions in the editor, plan mode. You can go further and write a custom agent installed locally in your tool. Which agent to pick? Leaderboards have sprung up and they change fast. Stay current, and choose on the criteria that matter to you. Specs sit at a higher level, not tied to any one agent or IDE. The lesson is that the workflow was built to be independent, and as more standards show up, that flexibility should grow.

Andrew Ng closes: you have gone from vibe coding, where you hope the agent does what you want, to spec-driven development, where you get closer to what you actually need. Constitutions, features planned in conversation, human-in-the-loop validation, skills and standards. The specs you write today become the memory of the project tomorrow. Keep them sharp. Keep improving the process. The best code starts with a great spec.

You, and many engineers Ng knows, have seen what happens when you move too fast. Bring some engineering back. Stay the driver of your software. He cares about finding joy and purpose in the work, and he wants to see what you do with this. Take it easy. Go do some cool stuff.