Spec-Driven Development: Andrew Ng Teaches You to Master AI Coding Agents Efficiently

Article Body

In an era where AI coding assistants grow ever more powerful, a new challenge has emerged for professional developers: how to truly harness these agents that can work continuously for 20 to 30 minutes—equivalent to hours of human effort. The latest course launched by Andrew Ng in collaboration with JetBrains, Spec-Driven Development with Coding Agents, offers a clear answer: Spec-Driven Development.

What Is Spec-Driven Development

The course is presented by Paul Everett, a Developer Advocate at JetBrains. Its core philosophy is straightforward: rather than writing code line by line, put your energy into writing the context that the agent doesn't yet possess. You give the coding agent a Markdown file or a detailed prompt clearly specifying what to build, and the agent implements the entire spec accordingly.

Andrew Ng points out that Spec-Driven Development is currently the best workflow for building serious applications with intelligent coding assistants. This differs fundamentally from the old practice of dashing off a few lines of prompt and letting the model improvise freely—it transforms the developer's role from "coder" to "architectural decision-maker."

Intellectual Origins: Spec-Driven Development did not emerge from nowhere. Intellectually, it inherits decades of tradition in software engineering's "Design by Contract"—proposed by Bertrand Meyer in 1986 alongside the Eiffel language—which emphasizes clearly defining preconditions, postconditions, and invariants before writing code. A "precondition" is an input constraint the caller must satisfy, a "postcondition" is the output guarantee the implementer promises, and an "invariant" is a system state that remains true throughout the entire lifecycle—together, these three form a machine-verifiable behavioral contract. The Eiffel language embedded these contracts directly as syntactic keywords (require/ensure/invariant), allowing contract violations to be caught instantly at runtime. This design influenced later languages such as D, Kotlin protocols, and Python's typing module. It's just that in the age of AI programming, the audience for the "contract" has shifted from the compiler to the large language model.

More broadly, it also echoes the "Spec First" API design culture, such as the OpenAPI/Swagger specification, which forces developers to define the interface contract before implementing the interface—API consumers can even generate mock services based on the spec file for parallel development before the server-side implementation is complete. OpenAPI (originally Swagger) was initiated by Tony Tam at Wordnik in 2010, donated to the Linux Foundation and renamed in 2016, and has since become the industry standard for describing REST APIs, natively supported by mainstream cloud platforms like AWS API Gateway, Azure API Management, and Google Cloud Endpoints. Its core contribution lies in solidifying an API's input/output structures, authentication methods, error codes, and other behavioral conventions into machine-readable YAML/JSON format, enabling code generation, documentation generation, and test stub generation to be automated. This concept of "specification as executable documentation" has evolved, in the context of AI coding agents, into the idea that a high-quality Markdown spec is itself a "soft program" that can be parsed and executed by an agent.

This chain of thought illustrates a truth: formalizing intent before coding has always been a core habit of high-quality software engineering. AI has merely amplified the returns of adhering to this habit several times over.

How Coding Agents Work

The "coding agents" repeatedly mentioned in the course are, technically speaking, autonomous agent systems based on large language models. Unlike single-turn Q&A-style code completion (such as early GitHub Copilot), coding agents possess a "perceive—plan—act" loop capability: they can read and write files, execute terminal commands, invoke test suites, search codebases, and perform multiple rounds of self-correction based on execution results.

Typical implementations include Claude Code (Anthropic), Gemini CLI (Google), Codex CLI (OpenAI), and JetBrains' own Junie. Such agents typically adopt the ReAct (Reasoning + Acting) framework—jointly proposed by Princeton University and Google Brain in 2022, published in the paper ReAct: Synergizing Reasoning and Acting in Language Models. Its core idea is to alternate between "reasoning traces" and "actions": at each step, the model first explicitly reasons in natural language about what to do next, then invokes a tool to execute it, and the tool's return result (called an Observation) is injected into the next round of reasoning, forming a "Thought→Action→Observation" triadic closed loop. This design makes the reasoning process fully recordable and auditable, forming an important technical foundation for the interpretability of today's mainstream AI agents.

Unlike pure Chain-of-Thought prompting, ReAct's reasoning steps not only serve the final answer but also constitute a decision-making process that adjusts plans in real time after dynamically observing external environment feedback—this allows the agent, when faced with unpredictable tool execution results (such as test failures, missing files, or compilation errors), to adjust its strategy based on actual observations rather than preset assumptions. It's worth noting that the ReAct framework resonates deeply with the concept of "System 2 Thinking" in cognitive science: in Daniel Kahneman's dual-process theory, System 1 is a fast, automatic, intuition-driven cognitive mode, while System 2 represents a slow, conscious, step-by-step reasoning mode. By forcing the model to make each reasoning step explicit, ReAct pulls the LLM away from fast pattern matching (System 1-like) toward more deliberate step-by-step decision-making (System 2-like), thereby maintaining higher planning coherence in long tasks and enabling the agent to sustain tool-invocation chains of dozens of steps without deviating from the goal. This mechanism also explains why, in complex programming tasks, a ReAct agent equipped with robust tool-invocation capabilities often significantly outperforms a purely generative model relying solely on pretrained knowledge.

It is precisely this ability to "run autonomously for 20-30 minutes" that multiplies the impact of upstream spec quality on the final output—the more autonomous the agent, the higher the cost of any deviation in the initial instructions.

Three Core Benefits

The course emphasizes three immediate benefits of Spec-Driven Development.

Leveraging Small Changes to Drive Large Ones

The first benefit is the leverage effect. A one-sentence change to the spec can affect hundreds of lines of code. For example, writing a single line like "use SQLite with Prisma ORM" can automatically generate large amounts of corresponding code; changing it to "MongoDB" triggers the same downstream amplification effect to regenerate the entire implementation.

Technical Background: SQLite is an embedded relational database created by D. Richard Hipp in 2000. Data is stored in a single file with no separate server process required, making it one of the world's most widely deployed database engines (estimated to run on over a trillion devices, including built into iOS and Android). It suits local prototypes, mobile applications, or lightweight backends. MongoDB is a document-oriented NoSQL database that stores JSON-like documents in BSON (Binary JSON) format, excelling at handling unstructured or frequently changing data models and naturally fitting horizontal scaling scenarios; it is a standard data-layer component of the "MEAN/MERN stack." The architectural differences between the two are vast: query paradigms (SQL declarative syntax vs. MongoDB Query Language, MQL), transaction models (SQLite supports full ACID transactions, while MongoDB only introduced multi-document transactions in version 4.0, having long been criticized for lacking transaction support before that), indexing strategies, and deployment methods are all completely different. Migration costs in traditional development are extremely high, typically requiring a complete rewrite of the entire data access layer.

Prisma ORM, as a type-safe database toolchain for Node.js/TypeScript, gained widespread adoption after Prisma Data Inc. (formerly Graphcool) released version 2.0 in 2019. One of its core designs is precisely to abstract underlying database differences through the schema.prisma configuration file—developers describe data models using a unified Prisma Schema Language (PSL), a declarative domain-specific language that lets developers define entity relationships from the perspective of "what the model is" rather than "how to operate the database." Prisma Client generates type-safe query code for the corresponding database (TypeScript type definitions update automatically with the model, eliminating at the root the "impedance mismatch" problem where the ORM and type system become disconnected), and Prisma Migrate generates DDL migration scripts in the corresponding database dialect. This "one model definition, multiple database implementations" architecture is itself an engineering embodiment of the "spec-driven" philosophy: first define the model contract, then let tools generate the implementation. In Prisma, switching database providers theoretically only requires modifying the provider field of the datasource block, with the ORM layer responsible for generating the corresponding query adapter. Once a coding agent understands this specification, a single spec change can trigger a code refactoring across the entire data access layer—this is the most intuitive manifestation of "spec leverage."

This means writing specs is far more efficient than hand-writing code—you make decisions at the spec level and let the agent handle the heavy lifting of implementation.

Eliminating Context Decay Between Sessions

The second benefit is combating context decay. Agents are essentially stateless—each launch starts from a "blank slate." Therefore, at the moment of launch, it is crucial to "fill" the agent with high-quality context. The spec file serves as a memory carrier across sessions, solidifying those non-negotiables and avoiding the information loss that comes from re-communicating every time.

Deeper Reasons: "Context decay" involves the underlying architectural characteristics of large language models (LLMs). Existing Transformer architecture models are essentially stateless functions: each inference is an independent forward pass, model weights do not update during inference (this is fundamentally different from the backpropagation training process of human learning), nor is any session memory persisted. The so-called "memory" relies entirely on the token sequence within the context window explicitly passed in with each call—information outside the window is, as far as the model is concerned, as if it never existed.

It's worth noting that even within the same context window, Stanford University researchers in 2023 discovered the "Lost in the Middle" phenomenon—the model's attention weights for content at the beginning and end of the window are significantly higher than for the middle portion, a phenomenon related to the positional encoding design of the Transformer's self-attention mechanism. This means that even if the spec file is included in the window, its positioning within the window will affect the agent's actual adherence. This finding has direct guidance for spec-writing practice: key constraints should be placed at the beginning or end of the spec file, not buried in lengthy middle paragraphs. Even though the context windows of today's mainstream models have expanded to hundreds of thousands or even millions of tokens (e.g., Gemini 1.5 Pro supports 1 million tokens, and the Claude 3 series supports 200,000 tokens), memory fractures across sessions remain a structural issue—once a session ends and the window is cleared, the next conversation returns to zero, and all project decisions and constraints the agent learned in the previous session vanish.

Academia and industry have explored various "external memory" solutions, including vector databases (Vector DBs such as Pinecone, Weaviate, pgvector) that store conversation summaries and recall them on demand via semantic search, memory distillation that compresses long conversations into structured summaries, and agent frameworks specifically designed for long-term memory management such as MemGPT—but these solutions come at considerable cost in engineering complexity and recall accuracy. The role of the spec file is precisely to serve as an "external memory substrate" at the lowest cost—at the start of each session, systematically re-injecting key architectural decisions, technical constraints, and project context back into the model's context, mechanistically combating this structural defect without requiring any additional infrastructure.

Improving Intent Fidelity

The third benefit is intent fidelity. When you clearly define elements such as the problem, success criteria, and constraints in the spec, the agent can build upon them to generate a more complete plan.

Andrew Ng shared his own frequently-used method for writing specs: first converse with agents like Claude Code, Gemini, or ChatGPT Codex, make key architectural choices based on his own judgment of different trade-offs, and then have the agent organize these decisions into a Markdown file.

The Cost of No Spec

The course also candidly points out the risks of lacking a spec. Writing a spec requires serious thought—you must decide what product to build and consider key decisions such as technical architecture in advance, which is itself an arduous mental effort.

Without a spec, you are entirely handing over these important decisions to the coding agent to improvise. This may be workable in scenarios that pursue extreme speed and are willing to "roll the dice," but it often leads to less maintainable code and sometimes even produces a fairly chaotic product.

Andrew Ng cited a real case: he has seen teams developing complex software without a clear spec, where different developers each direct the coding agent, all building quickly but in mutually contradictory directions, ultimately planting numerous downstream hazards. This phenomenon has a classic counterpart in software engineering: Fred Brooks pointed out long ago in The Mythical Man-Month (1975) that when multiple people develop in parallel without a unified architectural blueprint, communication costs grow with the square of the number of people—a rule known as "Brooks's Law." Brooks wrote this book based on his own management experience developing the IBM System/360 operating system, and his insight that "adding manpower to a late software project makes it later" is still revered today as a fundamental law of software project management. The deeper logic of Brooks's Law comes from Conway's Law: system architecture inevitably mirrors the organization's communication structure, and a team lacking a unified spec will inevitably present a fragmented architectural state in its codebase.

Conway's Law was first proposed by computer scientist Melvin Conway in 1967, originally stated as "organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations." This law regained widespread attention after the rise of microservices architecture, giving rise to the "Inverse Conway Maneuver": instead of passively accepting that organizational structure determines architecture, proactively design the organizational structure to drive the desired architectural form. Amazon's "two-pizza team" principle (team size capped at what two pizzas can feed, about 6-8 people) and Spotify's four-tier "Squad/Tribe/Chapter/Guild" organizational model can both be seen as engineering practices that consciously leverage Conway's Law to reverse-design organizational structures to drive architectural evolution. In the context of AI agent collaboration, Conway's Law takes on a new dimension: each agent instance's "communication boundary" is determined by its context window, and when a shared spec is lacking, multi-agent parallel development multiplies the intensity of architectural fragmentation—different agents may produce entirely different data model abstractions for the same business concept, forming hard-to-merge "architectural dialects"—which can be understood as a new form of Conway's Law in human-machine hybrid teams.

Workflow: From Project Constitution to Feature Development Loops

The specific workflow of Spec-Driven Development is divided into two levels.

At the project level, you need to establish a "constitution" that defines the immutable standards for the entire project, drawing a baseline for all subsequent development. This "project constitution" typically includes: technology stack choices (language, framework, database), code style conventions, directory structure specifications, security and compliance requirements, and explicitly prohibited patterns or dependencies. Its essence is to make implicit team consensus explicit, ensuring that every agent launched in a new session works under the same set of constraints. In practice, this constitution file is usually placed at the root of the code repository with a fixed filename such as AGENTS.md, CLAUDE.md, or SPEC.md, and some coding agents (like Claude Code) have built-in support for automatically reading specific filenames, automatically injecting them into the context at the initialization of each session.

At the feature level, progress is made through iterative feature development loops. Each feature is isolated on its own branch, following the three steps of "plan—implement—verify." This isolation keeps each feature at a clean starting point, reducing the chaos caused by context switching.

Mapping to Git Workflows: This "feature development loop" is not a new invention but a reinterpretation of mature Git workflows for the AI era. In the traditional GitHub Flow, each feature is likewise isolated on its own feature branch, merged into the mainline after development, code review, and CI/CD verification; GitLab Flow builds on this by adding environment branches (such as staging, production) to support continuous delivery scenarios. Spec-Driven Development extends this process upstream: before creating a branch, first generate the feature's Markdown spec document, letting the coding agent use it as a blueprint to autonomously complete the implementation in an isolated environment.

The "verify" step usually corresponds to running unit tests, integration tests, or having the agent self-review whether the code meets the success criteria defined in the spec—which aligns closely with the approach of Test-Driven Development (TDD): first define "what constitutes success," then drive the implementation. It's worth noting that the "success criteria" in specs differ in level from test cases in TDD: the former are business acceptance criteria described in natural language, while the latter are executable technical assertions—an ideal spec-driven process guides the agent to automatically convert the former into the latter, forming a complete conversion chain of "spec→test→implementation." This conversion chain shares a common approach with the Gherkin language of Behavior-Driven Development (BDD): BDD describes acceptance criteria in structured natural language with a "Given (precondition) / When (triggering event) / Then (expected result)" structure, then binds them to executable test code via tools (such as Cucumber, Behave, pytest-bdd)—the role the agent plays in Spec-Driven Development is precisely the automated replacement for this "binding layer," and it can handle freer and more complex natural-language spec descriptions than Gherkin syntax.

The "branch as sandbox" design both prevents code from different features from contaminating each other and provides the agent with clean operational boundaries—reducing the probability of it producing unexpected side effects in the global codebase, while also naturally supporting manual review through Pull Requests, maintaining reasonable tension between automation and human oversight. This "Human-in-the-Loop" design principle also aligns closely with current AI governance requirements for regulating high-risk automated systems.

The same workflow supports both project development and feature development. Developers manage version iteration in small steps through these loops. The course also teaches you to write your own agent skills to automate the entire spec-driven process.

When to Write a Spec: Not Every Scenario Needs One

You may not have noticed, but Andrew Ng does not blindly advocate for specs. He explicitly states that he is a proponent of "lazy prompting"—if a short prompt can get the job done, that's of course best.

But he emphasizes that the excellent developers he knows almost always write detailed specs when facing any project of a certain complexity. The reason is that they possess unique context and clear judgment about "what to build and how to build it," which far surpasses letting a context-less large model make random decisions.

He offered a very compelling cost calculation: if the coding agent takes 20 to 30 minutes to write code (equivalent to hours of work for a traditional developer), then spending three or four minutes upfront writing clear instructions is often the more worthwhile investment. This logic corresponds economically to the "leverage of upfront planning"—the higher the downstream execution cost of a task, the higher the marginal return on upstream planning.

Software engineering has a widely cited piece of empirical data from Barry Boehm's COCOMO model research: the cost of fixing a defect at the requirements stage is 5-10 times that of the coding stage and 10-100 times that of the testing stage. COCOMO (Constructive Cost Model) was a cost estimation model established by Boehm in 1981 based on statistical analysis of data from thousands of real software projects, one of the few quantitative models in software engineering based on large-scale empirical data (rather than pure theoretical derivation). The subsequent COCOMO II (1995) further incorporated correction factors for modern development modes such as object-oriented development and commercial off-the-shelf software (COTS) reuse. One of COCOMO's core findings is precisely that "the earlier a defect is found and fixed, the lower the total cost"—this rule of "exponentially growing defect-fixing costs" has been repeatedly verified in numerous independent studies over the following decades, becoming one of the few quantitative laws in software engineering that stands the test of time. It's worth adding that the IBM Systems Sciences Institute gave even more extreme figures in its research reports: the cost of fixing a defect in a production environment can be 100 times that of the requirements stage; and in safety-critical systems (such as aviation and medical device software), this multiplier is further amplified by factors like recalls and regulatory penalties. This magnitude of cost difference constitutes the most powerful economic argument for "spec first." The essence of Spec-Driven Development is precisely migrating this ancient rule of thumb to the new scenario of human-machine collaboration: investing minutes at the spec level to avoid hours of agent rework—and as the trend of ever-increasing agent autonomy continues, this leverage effect will only keep expanding.

Conclusion

This course is essentially a redefinition of the "division of labor in human-machine collaboration": in an era where agents can autonomously complete large amounts of coding work, the greatest value of human developers lies not in typing at the keyboard but in making high-quality decisions and clearly expressing intent. What Spec-Driven Development provides is precisely the methodology to systematize and engineer this value.

The course was jointly created by JetBrains' Constantine Chiker and Zina Smirnova, along with DeepLearning.AI's Isabel Zaro and others. It is well worth in-depth study for developers hoping to build serious applications with AI agents.

Key Takeaways