Spec-Driven Development: Bringing Engineering Discipline Back to AI Coding Agents

When you hear "agentic coding," you might picture "vibe coding" — typing "give me a button" and hoping the model delivers something useful. This course, co-produced by DeepLearning.ai and JetBrains with JetBrains Developer Advocate Paul Everett as instructor and Andrew Ng as co-host, offers a more rigorous alternative: Spec-Driven Development (SDD).

The core idea is simple: instead of writing code by hand, write down the context the agent doesn't have. You give the agent a Markdown file or a detailed prompt describing what to build, and let it figure out how to build it.

Why Specs Beat Vibe Coding

Vibe coding produces quick results, but the output tends to be throwaway code with accumulating technical debt. Your conversation history with the agent isn't even saved. It works fine for a button — but it falls apart the moment you try to scale to a large, continuously evolving project.

The course frames SDD as a professional response to "unsupervised AI-generated chaos" — a paradigm shift that decouples specs (which explain what and why) from implementation (which explains how). The spec becomes a contract between humans and agents, and between humans and other humans.

Andrew Ng offers a pragmatic benchmark: if a short prompt gets the job done, great — he's a self-described fan of "lazy prompting." But once a project has any real complexity, good developers almost always write detailed specs. The reason is that developers bring unique context and strong opinions about how to build things — far better than letting an LLM without that context make arbitrary choices. He makes a compelling time argument: if the agent is going to spend 20–30 minutes writing code (the equivalent of hours of traditional development), spending 3–4 minutes writing clear instructions usually pays off.

Three Key Benefits of SDD

The course repeatedly distills SDD's value into three points:

Small changes drive large outcomes. A single line in a spec — say, "use SQLite with Prisma ORM" — can map to hundreds of lines of code. Changing it to MongoDB triggers equally amplified downstream changes. Writing specs is therefore far more leveraged than writing code.

Eliminates context decay. Agents are stateless. As multi-turn sessions accumulate, the context window fills up and the agent becomes increasingly error-prone. Specs persist across sessions and across different agents, anchoring the agent to the essential context it needs to implement a feature.

Improves intent fidelity. Specs force you to define the problem, success criteria, constraints, and user flows before the agent starts working — making the resulting code far more aligned with your actual goals. This is precisely the dividing line between "vibe coding into a mess" and "engineering something that works."

The course offers an apt analogy: just as a compiler transforms readable source code into machine code, SDD guides an agent to transform specs into source code — except specs are written in human language, making them far easier to understand.

The Constitution and the Feature Development Loop

SDD's workflow operates at two levels. First is the project-level Constitution — a document defining immutable standards, built on three pillars:

• Mission: Explains the why — project vision, target audience, scope.
• Tech Stack: The team's agreed-upon technologies, tools, and constraints.
• Roadmap: A living document that breaks work into a series of phases.

The Constitution serves a similar purpose to the top-level agents.md file many developers already use, but it's agent-agnostic and more structured. For greenfield projects (starting from scratch), the Constitution is written through a conversation with the agent, which surfaces architectural questions you hadn't considered. For brownfield projects (existing codebases), the agent reads the existing code and reverse-engineers the Constitution from it.

The second level is the repeatable feature development loop: Plan → Implement → Validate. Each feature is isolated on its own branch. Between features, there's a "re-planning" phase — revising the Constitution, updating the Roadmap, and even improving the process itself. Maintaining clean boundaries between features dramatically reduces context-switching headaches.

The course positions the developer's new role using the architect analogy: you hand detailed blueprints to the builders and step back. You design, supervise, review, and accept the work — you avoid telling the builders how to do their job, and instead focus on providing the context they don't have. In short: the agent is the muscle; the spec is the brain.

Greenfield vs. Brownfield are common software engineering terms for describing where a project starts. Greenfield refers to a brand-new project with no legacy constraints — teams are free to choose any architecture or tech stack. Brownfield refers to development on top of an existing codebase or system, requiring compatibility with prior decisions, technical debt, and team conventions. This distinction matters greatly in the SDD context: greenfield projects can "define from scratch" through a conversation with the agent, while brownfield projects require the agent to first understand the implicit rules embedded in existing code and reverse-engineer the Constitution from them — a process that both tests the agent's comprehension and makes tacit knowledge explicit.

Agent Clinic in Practice: From Constitution to MVP

The course uses a running example project called Agent Clinic — a clinic where AI agents go to get "treated" for ailments like hallucinations, context rot, and memory issues. It's a playful riff on the classic Pet Clinic learning project. The tech stack is Next.js backend with a React frontend, developed in WebStorm IDE paired with the Claude Code agent.

The hands-on flow is genuinely instructive. Writing the Constitution isn't done in isolation — it's a dialogue with the agent, which raises architectural questions you hadn't thought of, suggests existing packages with ready-made solutions, and surfaces tradeoffs like speed versus data fidelity. Developers are repeatedly reminded: keep a human in the loop to review small changes, and don't edit files manually — let the agent make the changes so that specs, code, README, and all other artifacts stay in sync and avoid "drift."

The first feature, "Hello Hono," walks through the complete spec-plan-implement-validate cycle. One detail the course highlights: during review, focus on high-level concerns like "does this feature match the spec?" rather than nitpicking CSS class names or variable choices. When you spot a problem in the code that turns out to stem from a gap in the plan, the right move is to have the agent fix both the spec and the implementation — not just patch the code.

As the project progresses, the course demonstrates several advanced techniques: spawning sub-agents to perform deep reviews, giving the agent more room to think while protecting the main agent's context window from pollution; and using judgment when a product manager drops a "40% of users are on mobile, we need responsive design" change request — deciding whether to implement it immediately during re-planning (small change) or add it to the roadmap as a separate phase (large change). Ultimately, the team boldly implements the remaining roadmap all at once after completing two features, treating the MVP as an ultimate stress test of the Constitution and specs.

Engineering the Workflow with Skills and Standards

The second half of the course turns to automation and portability. Repeatedly typing the same feature spec prompt gets tedious — you can use the agent's "skill creator" to package it as an Agent Skill (an open standard that gives agents new capabilities and dedicated context). Skills can be project-level or global, and quality checks like updating the README, linting, formatting, and running tests can all be bundled into a "validation skill."

One noteworthy industry trend: the dominant way to extend agents used to be MCP (Model Context Protocol) — for example, the popular Context7, which injects up-to-date package documentation into the agent's context so it knows about React 9.2 rather than 9.0. But the course notes that in a growing number of scenarios, a skill that calls a CLI tool can accomplish the same thing with less setup and less context consumption. Context7 itself now recommends the "skill calling CLI" approach. The shift from MCP servers toward "skills + CLI" is accelerating.

The open-source ecosystem also offers ready-made solutions: GitHub's SpecKit and Fission AI's Open Spec are both working to formalize SDD workflows. Open Spec's "Propose-Explore-Apply-Archive" flow maps directly onto the course's Plan-Implement-Re-plan cycle.

On portability, the course emphasizes making your workflow independent of any single agent or IDE. Through MCP (external tools), agents.md (rules), Agent Skills (reusable workflows), and ACP (Agent Communication Protocol), you can switch freely between Claude Code, OpenAI Codex, OpenCode, and other agents while preserving your workflow. ACP's architecture draws inspiration from LSP — its registry handles automatic agent discovery, installation, and integration within clients like JetBrains IDEs.

MCP (Model Context Protocol) is an open standard proposed by Anthropic in late 2024, designed to let AI agents connect to external tools, data sources, and services in a unified way. It works like a USB interface: once a tool implements an MCP server, any agent with an MCP client can call it directly — no per-agent adaptation required. Context7 is one of the more prominent implementations, using MCP to inject up-to-date third-party library documentation into the agent's context in real time, solving the problem of LLMs having a training data cutoff and being unaware of the latest API changes. However, MCP servers require a separate running process, consume additional context quota, and add configuration complexity. The "skill calling a CLI tool" approach reuses locally installed command-line programs and carries lower overhead in many lightweight scenarios — which is the underlying reason for the migration trend mentioned in the article.

ACP (Agent Communication Protocol) is another emerging standard, drawing design inspiration from LSP (Language Server Protocol), which is widely used in editor tooling. LSP decouples "language analysis capability" from "editor," allowing the same language server to be reused by VS Code, Vim, JetBrains, and any other editor. ACP does the same for agents and client IDEs — through a registry mechanism, it enables automatic agent discovery and integration, so developers don't have to reconfigure their entire workflow when switching agents.

Closing Thoughts

Spec-Driven Development shifts the center of gravity from how to what and why. Because models and agents are evolving at a breakneck pace, you shouldn't lock your workflow to any single tool — standardization is the key defense against that kind of lock-in.

To borrow the course's closing words: the specs you write today become your project's memory tomorrow. In an era where agents can produce in minutes what traditionally took hours to code, keeping the human as the architect holding the blueprints may be exactly what "bringing engineering back" actually means.