Spec-Driven Development: Using Specs to Keep AI Coding Assistants Under Control

When you let a coding assistant run for twenty or thirty minutes generating code, it's far better to spend three or four minutes upfront writing clear instructions than to spend hours cleaning up the mess afterward. That's the central argument of the Spec-Driven Development (SDD) course produced by DeepLearning.AI in collaboration with JetBrains. Taught by JetBrains developer advocate Paul Everitt and introduced by Andrew Ng, the course systematically explains how to use a single Markdown specification file to govern the behavior of AI coding assistants.

From Vibe Coding to Engineering

The classic vibe coding scenario goes like this: you type "give me a button," watch the result, notice it's too big or the wrong color, point out the problem, ask the agent to retry, and repeat. For a single button, that's fine — but it falls apart on large projects. High-level prompts are fast, but they produce throwaway code and accumulating technical debt, and that long conversation history doesn't even get saved.

The course defines SDD as "a professional response to the chaos that comes from unsupervised AI generation." At its core, it's a paradigm shift: decoupling the specification — which describes what to build and why — from the implementation, which describes how to build it. The spec becomes a contract between humans and agents. A developer's primary job shifts from writing code by hand to translating intent into clear specifications.

The course uses a helpful analogy: a compiler transforms human-readable source code into machine code, while SDD uses agents and prompts to transform specs into source code — except specs are written in human language, making them understandable to all stakeholders.

The context window is the maximum amount of text a large language model can process in a single inference pass — currently ranging from roughly 100,000 to 2 million tokens across mainstream models. As conversation history grows longer, early instructions and agreed-upon conventions get pushed out of the model's effective attention range. The model begins to "forget" project rules, and output quality degrades — this is the underlying mechanism behind what the course calls context decay. Being stateless means that in each new session, an agent starts from scratch with no memory of previous interactions, unless the developer actively brings the necessary context into the new session. SDD addresses this inherent limitation by using persistent specification documents as external memory.

Three Core Benefits of Specs

The course repeatedly emphasizes three key advantages of SDD. First: controlling large changes with small edits. A single line in a spec — "use SQLite with Prisma ORM" — can influence hundreds of lines of code. Changing it to "switch to MongoDB" is just one sentence. This makes writing specs far more efficient than writing code by hand, and dramatically reduces the cognitive load of collaborating with a fast-moving coding agent.

Second: eliminating context decay. Agents are stateless. As a conversation progresses and the context window fills up, agents start making frequent mistakes. Specs persist across sessions and even across different agents, anchoring them to the core context the codebase requires.

Third: improving intent fidelity. Specs force you to define the problem, success criteria, constraints, and user flows before the agent starts generating code. Because developers bring unique background knowledge and judgment that LLMs lack, explicitly writing down those decisions produces far better outcomes than letting the model make arbitrary choices.

The Constitution and the Feature Development Loop

The SDD workflow begins with a project-level document called the Constitution. The constitution defines three pillars: the mission (explaining the project's vision, audience, and scope), the tech stack (the team's shared understanding of the technologies, deployment choices, and constraints), and the roadmap (a dynamic, phase-ordered document). The course notes that many developers use a top-level agents.md file for similar purposes, but the project constitution is more structured — and not tied to any specific agent.

Once the constitution is in place, every feature follows a repeatable loop: plan → implement → validate. Each feature is developed on its own branch, keeping a clean starting point between features and reducing context-switching friction. Between features, there's a replanning step — revising the constitution, updating the roadmap, and even improving the process itself. The course describes this as "slowing down to go fast."

The recommended approach to writing a constitution is through dialogue with an agent. The course demonstrates this with a sample project called Agent Clinic — a clinic for treating sick AI agents, playfully referencing how agents themselves suffer from hallucinations, context rot, and memory issues. The developer feeds the agent a project description and a stakeholder-written readme, then asks it to probe the mission, tech stack, and roadmap. Agents often surface architectural patterns and trade-off questions developers hadn't considered — such as "speed vs. data fidelity."

The Developer's Evolving Role

The course compares developers to architects: you hand detailed blueprints to a construction crew, then supervise the work, review the results, and request revisions — rather than telling workers how to swing a hammer. "The agent is the muscle; the spec is the brain."

Because agents write code so fast, developers are starting to talk about cognitive debt — the mental load required to track what the code is doing and how it's evolving. The antidote is keeping change sets manageable and committing frequently in small increments. During review, focus on high-level concerns (does the feature work? does it match the spec?) rather than minutiae like CSS class names. The course also demonstrates an effective technique: having the agent spawn multiple sub-agents to perform a deep review of the entire project. This gives the agent more room to think while using sub-agent isolation to protect the main agent's context window from pollution.

One memorable insight: discovering gaps in the spec during implementation — like forgetting to specify how to extract prop types — isn't a failure. It's the spec evolving through exploration. Document the new discovery so future runs produce even better results.

Brownfield Projects and Workflow Automation

Many people assume SDD and AI are only suited to brand-new greenfield projects. The course directly pushes back on this. For existing legacy (brownfield) projects, agents can reverse-engineer the SDD artifacts by exploring the existing codebase, commit history, and documentation — generating a constitution to align future code changes. The workflow is identical to a greenfield project.

The second half of the course covers how to use agent skills to automate repetitive workflows. For example, if you type the same prompts every time you start a feature spec, you can package that into a skill. The validation step — updating the readme, linting, formatting, running tests — can also be encapsulated into a validation skill. Skills can be scoped to a project or defined globally.

An important trend the course highlights is the shift from MCP toward "skills + CLI." The previously dominant way to extend agents was through MCP (Model Context Protocol) — Context7, for instance, is a popular MCP service that gives agents access to up-to-date package documentation. But Context7 itself is now recommending CLI-based skills over MCP servers, because CLI tools accomplish the same work with less setup and lower context consumption. The course sees this trend accelerating.

MCP (Model Context Protocol) is an open protocol proposed by Anthropic in late 2024, designed to standardize how AI models connect to external data sources and tools — essentially a "USB interface" for the agent world. Through MCP servers, agents can make real-time calls to search engines, databases, code repositories, and other external capabilities without hardcoding those capabilities into the model itself. Context7 is one of the more prominent MCP services, providing agents with up-to-date official documentation for various open-source libraries — solving the problem of models citing outdated APIs due to training data lag. The trend the course identifies — moving from MCP to CLI-based skills — reflects a practical discovery: the configuration complexity and extra context overhead of MCP servers sometimes outweighs their convenience, and directly invoking mature command-line tools is often lighter-weight and more reliable.

Keeping Workflows Tool-Agnostic

The course closes by emphasizing that, given how fast models and agents are evolving, you shouldn't lock your workflow to a single toolchain. It introduces a set of emerging standards: agents.md for rules, agent skills for encapsulating repeatable workflows, MCP for external tools, and ACP (Agent Client Protocol) for connecting agents to clients. ACP's architecture mirrors LSP — paired with an ACP registry, it enables agents like OpenCode to be automatically discovered, installed, and connected inside an IDE.

On the open-source tooling side, the course mentions GitHub's SpecKit (offering slash commands for constitution, plan, tasks, and implement) and FissionAI's OpenSpec (following a propose → explore → apply → archive workflow), both of which include branch management, validation scripts, and spec document formats. The course demonstrates the same feature-spec skill migrating seamlessly from Claude Code to OpenAI Codex, proving the portability of the workflow.

As the course concludes: "The spec you write today becomes your project's memory tomorrow." SDD's value lies in shifting the center of gravity from how to build, toward what to build and why — putting developers back in the driver's seat rather than leaving them to gamble on whatever the agent outputs next.

LSP (Language Server Protocol) is a protocol Microsoft proposed for VS Code in 2016 that has since been widely adopted. It decouples language intelligence features — code completion, go-to-definition, error diagnostics — from the editor itself, so any language only needs to implement one language server to work with any LSP-compatible editor. ACP (Agent Client Protocol) borrows the same decoupling philosophy, aiming to establish a standardized interface between agent capabilities and IDE clients: agents implement the ACP server side, IDEs implement the ACP client side, and the two communicate through the protocol. This allows the same agent to work seamlessly across different development environments, so developers don't have to reconfigure their entire agent toolchain just because they switched editors.