Spec-Driven Development in Practice: The New AI Coding Paradigm from Andrew Ng × JetBrains

From Writing Code to Writing Specs: A New Paradigm for AI Coding

As the capabilities of Agentic Coding Assistants rapidly advance, the way developers collaborate with AI is undergoing a fundamental shift. This new course—launched through a partnership between Andrew Ng's DeepLearning.ai and JetBrains—focuses on the best workflow for building complex applications: Spec-Driven Development.

What is an Agentic Coding Assistant? The fundamental difference between an agentic coding assistant and earlier code-completion tools (such as the first generation of GitHub Copilot) lies in "agency"—the ability to autonomously plan, invoke tools, and execute multi-step tasks. Early tools could only complete a single line or function at the cursor position, whereas agentic coding assistants (like Cursor Agent, Claude Code, and Devin) can read an entire codebase, run terminal commands, call external APIs, coordinate changes across multiple files, and self-correct based on test feedback. This leap in capability stems from the expansion of LLM context windows (from 4K to 200K+ tokens), the maturation of function calling capabilities, and the practical implementation of reasoning frameworks like ReAct (Reasoning + Acting).

It's worth adding that the core idea of the ReAct framework is to have the model alternate iteratively between "reasoning" and "acting": the model first thinks about what to do next in natural language (Chain-of-Thought), then executes a concrete tool-calling action (such as reading a file or running a command), and continues reasoning based on the feedback. This "think-act-observe" loop enables the agent to handle complex tasks requiring multi-step, cross-tool collaboration, rather than merely generating text in a single pass. It is precisely this "gets things done" characteristic—rather than "only suggests"—that makes spec-driven development possible: developers don't need to implement every line themselves; they only need to clearly describe "what they want."

The course's core philosophy is straightforward: rather than writing code by hand, put your energy into "writing down the context the agent doesn't yet have." You give the coding assistant a Markdown file or a detailed prompt explaining exactly what you want to build, and the agent implements accordingly. The course is taught by Paul Everett, a JetBrains developer advocate. It's especially beginner-friendly and comes with complete sample code.

The Three Core Benefits of Spec-Driven Development

The course opens by highlighting the three immediate benefits that spec-driven development delivers, which are also key to understanding the entire methodology.

It's worth noting that spec-driven development didn't emerge from a vacuum—it deeply resonates with the long-standing software engineering tradition of "design before implementation." From the 1968 NATO Software Engineering Conference, which established the importance of requirements specifications, to user stories in Extreme Programming (XP), to the Gherkin specification language in Behavior-Driven Development (BDD), the software engineering community has always explored how to precisely express intent in human-readable language. Among these, BDD's Gherkin syntax is particularly noteworthy: it describes software behavior using a "Given (a condition) / When (an action occurs) / Then (the expected result)" structure, allowing the spec itself to drive automated tests. This is highly isomorphic to today's AI coding concept of "spec-driven code generation."

In the context of AI coding, this tradition has taken on new life: whereas the primary readers of spec files used to be human developers, today its primary "executor" has become the AI agent. This role shift brings a profound qualitative change—traditional spec files often became mere formalities because "they were written but no one strictly followed them," whereas AI agents literally "comply" with every technical decision declared in the spec. The precision and completeness of the spec directly determine the quality of the code output. The traditional predicament of "write the spec and toss it in a drawer" has been fundamentally changed—for the first time, specs have become executable documents that can be directly consumed by machines.

Controlling Large-Scale Code Changes with Tiny Spec Modifications

The first benefit is leverage. A single sentence in a spec file can often drive hundreds of lines of code. The course cites a classic example: a sentence like "use SQLite with Prisma ORM" might affect the generation of hundreds of lines of code; changing it to "MongoDB" produces the same cascading amplification effect.

There's clear technical logic behind this phenomenon: a database selection decision propagates upward to data model definitions, seeps downward into query statement styles, and radiates outward to affect connection pool configurations and environment variable management. Switching the ORM layer (such as Prisma or Mongoose) further triggers a comprehensive rewrite of schema syntax, migration scripts, and type definitions.

Take the switch between Prisma and Mongoose as an example. This isn't just an API-level replacement—Prisma uses a declarative .prisma schema file and a strongly-typed TypeScript client, while Mongoose is based on JavaScript schema objects and a callback/Promise-style query interface; the former is oriented toward the table-structure thinking of relational databases, while the latter is oriented toward the nested-structure thinking of document databases. This means that every CRUD operation, every association query, and every transaction handling in the data layer must be rewritten, and these changes further impact the business logic layer's assumptions about data structures. In traditional development, this kind of architecture-level change is often a headache-inducing refactoring project; in the spec-driven model, it only requires modifying a single technical decision declaration in the spec, and the agent automatically handles all downstream effects. This means writing specs is far more efficient than writing code by hand. A single decision you make at the spec level is faithfully amplified by the agent across the entire codebase. This "small effort, big impact" characteristic is the fundamental source of spec-driven development's efficiency advantage.

Eliminating Context Decay Between Sessions

The second benefit concerns the fundamental limitations of agents. The course emphasizes that agents are stateless—every startup is a blank slate. Therefore, loading the highest-quality context into the agent the moment it starts up is crucial.

Why are agents stateless? LLMs themselves don't store any persistent memory between sessions—each inference call is independent, and everything the model "knows" comes from the context window of the current input. For agentic systems, this means that every time a new session starts, the agent knows nothing about the project history, architectural decisions, or team conventions—unless this information is explicitly injected into the prompt.

This limitation has given rise to an active research and engineering direction: long-term memory mechanisms. Current mainstream solutions fall into three categories: first, external storage, which stores conversation history and decision records in a vector database and injects them on demand through semantic retrieval; second, structured memory files—the spec files and constitution documents discussed in this article—serving as persistent explicit context; and third, memory distillation, which periodically compresses long sessions into summaries and stores them for priority loading at the next startup. Some tools (such as Cursor's .cursorrules and Claude's CLAUDE.md) have already institutionalized the second approach, allowing developers to place persistent context files in the project root directory that are automatically loaded each time the agent starts.

From the perspective of cognitive science, the problem that spec files solve is highly similar to the knowledge management problem in human team collaboration. The concept of "tacit knowledge" proposed by management scholar Michael Polanyi—experience that is difficult to articulate and exists in expert intuition—is precisely what spec files attempt to systematically externalize. A senior developer's judgment on "why choose this architecture" and their intuition on "which boundaries absolutely cannot be crossed" will completely vanish from the agent's cognition at the start of each new session if not written into the spec. Spec files act as "memory anchors," preserving those non-negotiable core constraints, thereby avoiding context decay across multiple sessions. Without a spec, you'd have to re-explain the project background to the agent every time—inefficient and error-prone.

Improving Intent Fidelity

The third benefit is intent fidelity. The spec is defined by you and represents your true build intent; the agent then expands upon it to generate a more complete implementation plan.

Andrew Ng shared his commonly used method for writing specs: first engage in a conversation with an agent like Claude Code, Gemini, or ChatGPT Codex, use your own judgment about various trade-offs to make key architectural decisions, then have the agent organize these core decisions into a Markdown spec file.

The concept of "intent fidelity" has deep technical roots in the field of prompt engineering. Research shows that language models tend to "complete" vague or under-constrained instructions—filling in the gaps with statistical patterns from training data, patterns that may not align with the specific project's needs. This phenomenon is called specification gaming in model alignment research: the model finds shortcuts that satisfy the literal instruction but violate the true intent, especially when the instruction is ambiguous.

High-intent-fidelity specs reduce this risk by narrowing the agent's "room for improvisation": when a spec clearly specifies technical choices, boundary conditions, and acceptance criteria, the model's output distribution converges toward the developer's true intent rather than toward the statistical center of "what the average programmer would do." This is also why the more detailed the spec, the more stable the code quality tends to be—not because more constraints are always better, but because every explicit constraint compresses the agent's space of uncertainty and reduces the model's opportunity to "improvise" filling in details.

Why You Can't Leave All Decisions to the Agent

The course frankly points out that writing specs is hard work that requires deep thinking—you must decide what to build, what features it has, and what technical architecture to adopt. Without a spec, you're essentially handing these important decisions over to the coding agent to figure out at random.

Andrew Ng has a clear-eyed judgment on this: if you just want to quickly experiment and "roll the dice," this might work; but it inevitably leads to less maintainable code, and sometimes even produces rather bizarre products.

He cited a real-world example: some teams developing complex software products lacked clear specs, and as a result, multiple coding agents directed by different developers—though all making rapid progress—modified the code in contradictory ways, ultimately triggering numerous downstream problems. This is a classic cost of lacking a unified spec.

This phenomenon has a classic theoretical foundation in the software engineering field: Conway's Law states that system design tends to reflect the communication structure of the organization that created it. This law was originally proposed by Melvin Conway in 1967, and tech companies like Microsoft and Spotify later applied it in reverse—by first designing the target architecture and then adjusting the team structure to match it (i.e., the "Inverse Conway Maneuver"). In scenarios of concurrent multi-agent development, without spec files serving as "organizational memory," each agent's decisions degrade into isolated local optima, ultimately forming architectural entropy at the codebase level—system complexity grows at a superlinear rate, and maintainability declines sharply. Spec files essentially play the role of a "virtual architect," providing globally consistent decision-making grounds for concurrent agent activities without human real-time arbitration.

As a detail, Andrew Ng doesn't wholesale reject simple prompts. He explicitly states that he also supports "lazy prompting"—when a short prompt gets the job done, all the better. But for any project with a certain degree of complexity, virtually all the excellent developers he knows write detailed specs, because they possess unique context and clear build opinions, which are inevitably superior to letting an LLM lacking that context make random choices.

A succinct cost comparison: if your coding agent takes 20 to 30 minutes to write code (equivalent to several hours of work for a traditional developer), then spending three or four minutes sitting down to write clear instructions is often the more worthwhile investment.

Constitution + Feature Development Loops: A Complete Workflow Breakdown

The specific process of spec-driven development is divided into two levels.

First, at the project level, you establish a "Constitution" to define the immutable standards and constraints within the project.

Why call it a "Constitution"? The governance challenge of multi-agent collaboration Calling the project constraint file a "constitution" carries a profound engineering metaphor. In scenarios of parallel work by multiple agents or multiple developers, one of the biggest engineering risks is "locally optimal but globally contradictory"—each agent makes reasonable technical decisions within the scope of its own task, but these decisions conflict with each other, causing the overall consistency of the codebase to collapse. The project constitution provides a unified decision-making framework for all agents by explicitly specifying "inviolable principles" such as technology stack choices (e.g., "use PostgreSQL instead of SQLite"), code style conventions, module boundaries, and security constraints.

This concept has an interesting resonance with the "Constitutional AI" training methodology that Anthropic designed for the Claude series of models: Constitutional AI constrains model output behavior by having the model internalize a set of explicit principles, while the project constitution guides the agent's code generation behavior by injecting constraint rules into the context. Both embody the same idea: rather than correcting errors after the fact, set up guardrails before decisions are made. This essentially extracts the responsibility of architectural governance from the human architect's mind and transforms it into machine-readable constraint rules, enabling concurrent agent activities to maintain global consistency.

This constitution is the highest guideline for the entire project, ensuring that the behavior of all agents remains consistent. At the practical level, a well-developed project constitution typically covers the following dimensions: technical constraints (which frameworks and language versions to use, which dependencies are prohibited), architectural principles (how modules are divided, how interfaces are defined, how data flow is standardized), quality standards (test coverage requirements, performance benchmarks, security specifications), and team conventions (naming conventions, comment styles, commit message formats). Together, these four dimensions form a complete "decision space boundary," ensuring that any agent, starting at any point in time, can make consistent technical choices within the same constraint system.

Next comes the repeatedly iterated Feature Development Loops. Each feature is isolated on its own branch and goes through three steps: "Plan—Implement—Verify." This isolation mechanism gives each feature development a clean starting point, reducing interference between features and the overhead caused by context switching.

It's worth noting that this "Plan-Implement-Verify" three-step loop bears a profound structural resemblance to Test-Driven Development's (TDD) "Red-Green-Refactor" loop: both treat verification (testing/verification) as a built-in part of the development process rather than an afterthought, and both emphasize small-step iteration over large-batch delivery. The difference is that in TDD, the verification criteria (test cases) are written in advance by humans, while in spec-driven development, the verification criteria can be automatically derived from the spec file—an extension and evolution of the spirit of TDD in the AI era.

This workflow supports two types of projects simultaneously:

• Greenfield (brand-new projects): Starting from scratch, establishing the project constitution through conversation with the agent.
• Brownfield (existing codebases): Generating the project constitution based on the existing codebase.

The differentiated challenges of Greenfield and Brownfield These two terms come from the fields of real estate and urban planning, and are used in software engineering to describe the nature of a project's starting point. Greenfield projects refer to new projects starting from scratch, where developers can freely choose the technology stack and architecture; the risk lies in over-specification—writing specs too thoroughly may actually limit the space for agents to find better solutions. Brownfield projects, on the other hand, refer to continued development on an existing codebase, requiring respect for existing technical debt, dependencies, and historical decisions.

In the context of AI coding, spec formulation for brownfield projects faces an additional challenge: the existing codebase must first be "reverse-engineered"—having the agent scan the codebase, identify existing patterns and constraints, and then generate a constitution file describing the current state. This process is similar to software archaeology, requiring the design intent of years past to be "excavated" from the code itself. This is why the course clearly distinguishes between the two entry paths and specifically designs a workflow for brownfield scenarios that reverse-generates the constitution from the existing codebase.

It's worth adding that the "reverse constitution" generation process for brownfield projects is itself a valuable knowledge management behavior: it forces the team to make explicit the architectural knowledge that has long accumulated in code comments, oral tradition, and personal memory, often exposing those invisible constraints that "everyone knows but no one ever wrote down," laying a more solid cognitive foundation for subsequent human-machine collaboration. In either case, subsequent iteration is carried out through feature development loops, managing version evolution in small steps.

Course Content and Industry Outlook

Beyond the core spec-driven methodology, the course also guides you through writing your own Agent Skills, practicing them in a complete project, and ultimately building a proof of concept (PoC) to automate the entire spec-driven workflow.

From an industry perspective, this course reflects the major trend of AI coding evolving from "generating code snippets" toward "engineered collaboration." When agents can work continuously for tens of minutes and produce code equivalent to hours of human labor, the developer's core value is shifting from "writing code" to "defining intent, managing constraints, and controlling architecture."

This shift has profound implications at the level of professional roles: the excellent developers of the future will be closer to a composite "system architect + quality arbiter" role, requiring the ability to clearly express requirements (spec writing), the ability to judge output quality (code review), and the ability to design verification mechanisms (test strategy), while the actual coding execution will increasingly be handled by agents. From a more macro perspective, this shift follows the same pattern as every historical leap in programming abstraction levels (from machine code to assembly, from assembly to high-level languages, from imperative to declarative programming): each rise in abstraction level frees developers from low-level details, allowing them to focus instead on higher-level intent expression. Spec-driven development may well be the latest chapter in this historical process—establishing natural language as a new programming abstraction layer, with AI agents becoming the "compiler" that translates this layer into executable code.

Spec-driven development is precisely a systematic response to this shift. For developers who want to seriously use AI to build production-grade applications, this methodology offers a clear path to follow: think through what you want to build first, then let the agent implement it. Contributors to the production of this course also include Konstantin Czajker and Zina Smirnova from JetBrains, as well as Isabel Zarro from DeepLearning.ai, among others.

Key Takeaways