Spec-Driven Development with Coding Agents

讲师：Paul Everitt (JetBrains) · DeepLearning.AI 短课程 · 2026年4月
课程原址 →

📑 课程目录

Introduction 引言
Why Spec-Driven Development? 为什么需要SDD？
Workflow Overview 工作流概览
第4课为阅读材料（无视频）
Creating the Constitution 创建项目宪法
Feature Specification 功能规格制定
Feature Implementation 功能实现
Feature Validation 功能验证
Project Replanning 项目重新规划
The Second Feature Phase 第二个功能阶段
The MVP 最小可行产品
Legacy Support 遗留项目支持
Build Your Own Workflow 构建自己的工作流
Agent Replaceability 代理可替换性
Conclusion 结论

01 Introduction — 引言 ▼

核心内容

本课是整个课程的导入，核心目标是区分"Vibe Coding"（随性编码）和"Spec-Driven Development"（规格驱动开发，简称SDD），并阐述SDD的三大核心优势。

Vibe Coding 的问题

写一个prompt描述想要的东西，然后祈祷代理做出正确的样子
发现不对后再指出错误让代理重试，如此反复
最终产生漫长的对话历史，且不会被保存
对一个按钮还行，但无法扩展到大型持续项目
高层级prompt虽然快，但导致一次性代码和技术债务不断积累

SDD 的核心理念

SDD是对无监督AI生成混乱的专业回应
范式转变：将"规格说明"（做什么和为什么做）与"实现"（怎么做）解耦
规格不仅提供人与代理之间的契约，也是人与人之间的契约
主要任务从写代码转变为：将意图转化为清晰的规格说明

SDD 三大优势

以小控大 — 规格中几句话可能翻译成数百行CSS代码，减少认知负担
消除上下文衰减 — 规格在会话和代理之间持久存在，锚定核心上下文
提高意图保真度 — 迫使你在代理开始生成代码之前定义问题、成功标准、约束和用户流程

代理 vs 聊天机器人

聊天机器人只能谈论代码，无法访问项目代码和工具
代理接收prompt→制定计划→运用推理→访问代码库和开发工具
SDD中把代理视为高能力的结对编程伙伴，你作为高级架构师提供蓝图

"Agent是肌肉，SPEC是大脑。"

📄 显示原文字幕

When you hear agentic coding, you might think Vibe coding. Let's compare the two and see how Spec-Driven Development gives better results by bringing back engineering. Vibe coding gives quick results. You write a prompt describing what you want, like, create me a button and hope for the best. Then you look at the result. That's a big button. It's kind of close, but off on some important things. So you point out the mistakes to the agent, it tries again and so on until you are satisfied. As a result, you will end up with a long dialogue with the agent, the history of which will not even be saved. This approach works okay for a button, but it doesn't scale to a large ongoing project. While high-level prompts are fast, they lead to disposable code and mounting technical debt. We need engineering. A well-maintained specification that creates a permanent technical artifact. Spec-Driven Development is the professional response to the chaos of unsupervised AI generation. It is a paradigm shift where the Specification, explaining the what and why, is decoupled from the Implementation, the how. With specs, we get a contract between the humans, but also with the agent. Your main task as the human now shifts. Learn how to convert your intentions into clear specifications. Spec-driven development with agentic coding assistance has three main benefits. First, you're able to control large code changes with small changes to the spec. A few sentences in the spec outlining the look and feel of the app might translate to hundreds of lines of CSS. This spec-driven approach reduces the cognitive overhead needed for working with these ultra-fast coding agents. Second, specs eliminate the context decay problem that derails multi-turn agent sessions. As you work with your coding agent, its context window will fill up, often leading to more mistakes as the agent tries to cope with a full working memory. Specs persist between sessions and even agents, anchoring the agent to the core context needed to work in a code base and implement a feature. Third, specs improve intent fidelity, meaning that the agent is more likely to produce code that matches your goals. That's because specs force you to define the problem, success criteria, constraints, user flows, and so on before the agent starts generating code. Specs are a key differentiator between vibe coding, some slop, and engineering a viable software product. Whether you are starting a new project from scratch or want to implement the SDD approach into a project that has been running for years, specs help solve the drift and productivity problems. As a comparison, think of compilers, which convert understandable source code into machine code. SDD guides the agent and prompts, converting specs into source code. Even better, the specs are in a human language, making it easy for stakeholders. Spec-driven development has taken off recently as a solution to concerns about productivity. Multiple SDD projects, tools built around spec authoring, conference talks on capturing intent. This is all part of a broader push to bring engineering, lessons learned from the software development life cycle, to agentic coding. Spec-Driven Development is used with Coding Agents, not simple chatbots. A chatbot can talk about code, but the chatbot doesn't have access to your project's code nor tools you have installed. It just responds to your prompts. Agents are different. They take your prompt, make a plan, and guide themselves to a result using reasoning along the way. Importantly, agents have access to your code base and your development tools. In the SDD workflow, we treat these agents as highly capable pair programmers. They provide the technical knowledge and the speed, and you, the senior architect, provide the blueprints. As we move forward in this course, remember, the agent is the muscle, but the SPEC is the brain. With practice, you ensure that the software produced is not just functional, but is aligned with your long-term goals.

02 Why Spec-Driven Development? — 为什么需要SDD？ ▼

核心内容

深入解释为什么SDD对现代AI辅助编程至关重要，并介绍SDD工作流的总体框架。

SDD 的核心价值

先为项目做前期规划，然后为每个功能做详细规划，逐步改进
通过提供最高质量的上下文来帮助代理
关键技能：掌握合适的细节粒度——把代理当作高能力结对伙伴来找正确层级
多提供关于目标、使命、受众和约束的上下文，少操心代理可自行解决的底层决策

SDD 工作流概览

制定宪法（Constitution） — 使命(Mission)、技术栈(Tech Stack)、路线图(Roadmap)
功能开发循环 — 规划→实现→验证
重新规划阶段 — 修订宪法，更新路线图，改进流程

建筑师比喻

你是一位建筑师，给建筑工人详细的建筑图纸，然后就交给他们了。你的角色是设计、监督施工、审查和接受结果。避免告诉工人怎么做他们的工作，专注于提供他们不知道的上下文。

SDD让你从思考的起点走到交付的终点，最重要的是，它让你从那里持续改进。

📄 显示原文字幕

Spec-driven development tells the agent how to build what you want. up front for the project, then for each feature, getting better as you go. With SDD, we help the agent with the best quality context. First with decisions about the project, then with details about each feature. This spec is very detailed. One key skill in SDD is knowing the right level of detail. If you treat your agent as a highly capable pair programmer, you'll often hit the right level. Lots of context about the Goals, mission, target audience and constraints. and less about the low-level decisions the agent can figure out on its own. What does this SDD workflow look like? First, we specify the Constitution. What is the mission, the Tech stack, the Roadmap? A Constitution is just one way to formalize these project level details. Many developers use a top-level agents.md file for this purpose. But a project Constitution is agent agnostic and more structured. The Constitution captures the agreement on key decisions between the human and the agent, but also the agreement between the humans. The mission explains the why. This project's vision, audiences, scope, etc. Defining these parameters in advance is very common in software projects and helps guide ongoing decisions. The tech stack is for the engineering team, a common understanding of development and deployment technologies and constraints. The Roadmap is a living document with a sequence of phases, each implemented with their own feature spec process. Once the Constitution has been drafted, we work on each feature with a repeatable process. First, plan the feature, implement it, and finally, validate the result. In between features, it's time for the Replanning phase. Revise your Constitution, update the road map, even improve the process itself. As you heard a moment ago, one of the key skills of SDD is providing the right level of detail to create the highest quality context. In the feature phase and the replanning phases, you steer the agent. Look at it this way. Imagine that you are an architect and you give detailed drawings of a building to builders. Then it's up to them. Your role is to design, supervise the construction, then review and accept the results, or ask for changes. You'll want to avoid telling the builders how to do their jobs and focus on providing the context they don't know. Spec-Driven Development gets you from thinking at the start to delivering at the finish. Best of all, it keeps you improving from there.

03 Workflow Overview — 工作流概览 ▼

核心内容

SDD是最佳实践，不绑定任何特定IDE或编码代理
VS Code + Codex CLI、Zed编辑器 + 本地模型，都适合SDD
课程使用 WebStorm IDE + Claude Code
创建新项目"Agent Clinic"——TypeScript项目，带Git仓库追踪代码和规格版本
代理每次执行命令会请求确认（除非unsafe模式），代码的最终责任在你
Git是SDD中版本控制的关键工具

📄 显示原文字幕

Before you send your first prompt, let's talk a little bit about setting up your workspace. If you're already comfortable with setting up a coding agent like Claude Code in an IDE such as WebStorm, feel free to skip this optional video. Spec-Driven Development is a best practice that isn't tied to any specific IDE or coding agent. So, you can choose the setup you're already using or the same one you'll see in this course. VS Code with the Codex CLI, Zed editor with a local model, all great for spec-driven development. Since we are planning to develop a web application, this course will use the WebStorm IDE with Claude Code as a coding agent. Instructions on downloading and installing both have been included in the previous reading item. Let's open up WebStorm and start a brand new project named Agent Clinic. This will be a TypeScript project with a Git repository to keep close track of versioning your code and specs. Although many IDEs, including WebStorm, offer a chat panel, we know there's a lot of diversity in how you interact with your coding agents. In spec-driven development with agents, it's important to keep close track of versioning your code. Let's say we want to create an initial commit using the agent. Every time it needs to execute a command, it will ask you for the confirmation unless you start Claude Code in an unsafe mode. Pay close attention to what Claude Code asks you to do. The ultimate responsibility for the code is yours. Throughout the coming lessons, you'll see several tricks and best practices for spec-driven development with Git. Great, we've got our setup ready and you've got yours ready. Let's get started.

05 Creating the Constitution — 创建项目宪法 ▼

核心内容

SDD工作流的起点——创建项目宪法，从零开始制定项目的使命、技术栈和路线图。

制定宪法的过程

用新代理会话，告诉代理想为新项目创建宪法
代理会询问关键问题：目标受众、项目愿景、技术偏好等

三大部分

使命（Mission） — 项目是做什么的、为谁而做、范围是什么。预先定义这些参数是常见且重要的实践
技术栈（Tech Stack） — 工程团队对开发/部署技术及约束的共同理解。代理帮你确认版本选择和兼容性
路线图（Roadmap） — 活文档，包含开发阶段序列，每个阶段通过功能规格流程实现

关键实践

不必同意代理提出的所有方案，务必澄清任何让你不舒服的地方
宪法完成后，创建Git commit保存
规格文件是版本控制策略的一部分

📄 显示原文字幕

We now have a roadmap with features. But how do we build them? With specs of course, starting with the first roadmap feature. Let's take a look at the AgentClinic roadmap. Here's our phase one feature, Hello Hono. But it's too early to start coding. We need to discuss the spec and clarify all the details. A good plan outlines the approach, the sequence of work, and how to validate success. Let's start with fresh agent context. The agent can get what it needs from the official source, the constitution. We will work on this feature in a separate branch, which we will indicate to the agent. Our prompt will help start a conversation with the agent about the feature spec, a plan for tasks, collect requirements, and a scorecard for validation. The agent will ask you to make key decisions. Pay attention to potential conflicts or problems. You don't have to agree with the solutions proposed by the agent. Make sure to clarify anything that bothers you. First, regarding phase one scope, we'll keep it exactly as written. For the requirements, let's pin the Hono version and enforce strict TypeScript. For the confirmation, manual curl looks good. Then, let's submit. That was fast. Must have been a nano. Work is done and the ball is back on our side for reviewing the feature spec created by the agent. Let's review the feature plan first. It's important to get these docs right in the beginning to keep the agent on track. If you find something wrong, ask the agent to fix it, to make sure it keeps the requirements and validation in sync. For example, we would like a nice looking placeholder home page in this first feature spec. We make the change via the agent. Next, the requirements. These were also updated to reflect the homepage update. This is the right place to indicate any important technical needs or constraints. Don't speed through this, but don't state minor technical details like variable names here. We want to control the process but not oversteer the agent. Last, the validation. Make sure the agent can check that it got it right. Again, these were updated for the homepage. We're done with the feature spec. Let's create a commit in the IDE. Nice. We formulated a feature spec strategy. Made a feature branch, interviewed with the agent about what the feature should do. Put the results in markdown documents, reviewed these spec files, committed. The changes you make here in the specs will expand downstream into hundreds of lines of code. So time spent here is well spent. It's time for implementation.

06 Feature Specification — 功能规格制定 ▼

核心内容

在编码之前，如何与代理协作规划每个功能的细节。

功能规格核心流程

查看路线图 → 但还不到编码的时候 → 先讨论规格
好计划应包含：实现方法、工作顺序、如何验证成功
使用全新代理上下文，在独立分支上工作

审查功能规格文档三要素

功能计划（Plan） — 一开始就确保正确，让代理保持在轨道上。发现错误就让代理修正并保持同步
需求（Requirements） — 重要技术需求/约束的正确位置。不草草了事，也不声明变量名等次要细节。控制过程但不要过度操控代理
验证（Validation） — 确保代理能检查自己做对了没有

在规格中做出的修改会向下游扩展为数百行代码，所以这里花的时间是值得的。

📄 显示原文字幕

07 Feature Implementation — 功能实现 ▼

核心内容

基于功能规格文档，让代理执行实际代码实现。

实现流程

回顾功能规格 → 用 /clear 清除代理上下文
指示代理实现所有任务组，或一次一个任务组（小步骤更适合安全/数据库等易累积错误的领域）
观察代理进度——控制台实时显示变更
查看提交窗口——提前开始审查
查看代理总结——每个任务组的额外细节
运行应用——浏览器显示功能规格的结果

在SDD范式中，开发者的角色从"写代码"转变为"架构师/监督者"——确保代理获得清晰的契约（规格），然后让代理执行实现。

📄 显示原文字幕

We're working on the plan for the first feature in the project roadmap. We finished the feature spec. Let's do the full implementation of this feature. Just to refresh ourselves, we do a quick review of this feature specs plan. This was the first feature, hello Hono. The feature spec documents have what we need. To start your implementation, you'll want to clear out your context with a /clear command. Let's go back to the agent and enter a prompt to implement all the task groups. Sometimes you might choose to do task groups one at a time for even smaller steps and commits. This technique is especially helpful for areas where small mistakes can compound later, like in security or database management. While Claude is running, you can observe the changes it displays in the console to see its progress in real time. Afterwards, we can watch for the final changes in the commit window and visit the changes. This gives us an early jump on reviewing the work. This is the key role of the developer in such a paradigm, to act as an architect or supervisor and ensure that the agent is provided with a clear contract. We can also see the summary of what was done. As you can see, the agent provides extra details on the work performed for each of the task groups. Now, let's go to the package.json file. And in there, let's run the app. The server starts in the console. The browser shows the result of this feature spec. Not much. We said nano, but it's a good feeling to see pixels on the screen. We just implemented a feature. The agent did its validation. In the next lesson, we'll do ours.

08 Feature Validation — 功能验证 ▼

核心内容

功能开发循环最后一步——验证。重点讲解"人在回路"审查和"认知债务"处理。

验证流程

从提交视图开始审查——聚焦高层关注点（功能是否工作、是否反映规格），不纠结CSS类名等细节
发现问题后——代码问题源于规格问题："代码中的这个错误实际上源于计划中的错误——我们没有要求这个"
让代理同时修复规格和实现

人在回路 & 认知债务

代理生成 + 人类验证 = "人在回路"
代理写代码太快 → "认知债务"——跟踪代码做什么和如何演变的精神负担
为减少认知债务，变更应保持可管理

手动修改 vs 代理修改

将子组件移到各自文件——编辑器中很容易
但不要急着手动改！ 这可能导致漂移（drift）——其他制品会失去同步
让代理修复所有提及，确保不浪费后续时间

规格版本管理

宪法更新和功能在同一分支上——如果变更小可以保持
如果宪法整体更新更复杂，最好在单独分支上做
小步骤，频繁提交，保持审查不会让大脑过载

📄 显示原文字幕

It's nice to have a feature ready, but don't merge yet. In this last feature step, we collaborate with the agent to review the work. Fortunately, programmers have good tools for this validation task. After all, programmers have long spent several hours per week on code review. Start with the commit view. Let's go through the changes. Focus your review on high-level concerns like whether the features work and reflect the spec, rather than details like which CSS classes were implemented. For example, the Home.tsx is minimal. Nano really meant nano. We want a layout component with clear landmarks for header, main, and footer, but do these as sub-components. And create a CSS file. As it turns out, this mistake in the code flowed from a mistake in the plan. We didn't ask for this. Let's ask the agent to do the fix, thus correcting both spec and implementation. This process that consists of the agent generating something and us verifying it is known as the human in the loop. Because agents are so fast at writing code, software developers have lately been talking about cognitive debt, the mental load of tracking what your code is doing and how it has evolved. That is why in order for this process to be fast and easy to control, and to reduce cognitive debt, the changes should be manageable. The agent is making our changes, but also validating that these changes didn't break anything. Good news, the agent finished and gave us a quick summary. You can also see this in the editor. The feature plan was changed to add a Group 5 to list these new steps. The code now has a layout component. and a CSS file was added. It looks like the three subcomponents were just put in the same file, but that doesn't follow conventions. Let's put these in their own files using the IDE move tool. These kinds of changes are easy in editors and we've always been good at this. No need for an agent, right? Let's just do it. Not so fast. This can lead to drift where other artifacts, specs, readmes, get out of sync. Let's ask the agent to fix any mentions and to make sure this doesn't waste some time later. All changes are done. Did we break something? Tests would help, but the agent didn't install our testing package. Since this is needed for all features, we'll cover it in the next lesson. Now we're ready to mark this work as complete and merge our results. Notice that the part of the constitution was updated alongside the feature in this branch. How to handle versioning of the specs and how to associate which specs created which code changes is an evolving topic in the community. The change to the roadmap is small, just checking off a step in the roadmap. So it's okay to keep these updates on the same branch. If the overall constitution update is more complicated, it might be better to do this in a separate branch. Now we're ready to mark this work as complete and merge our results. We just used Spec-Driven Development to develop and validate our first feature. But wait, shouldn't we take another look at the project's broader scope?

09 Project Replanning — 项目重新规划 ▼

核心内容

功能之间常被忽略但至关重要的环节——重新规划。

"你必须慢下来才能跑得快"

重新规划四件事

补充测试框架到宪法 — 宪法是活文档，更新应在独立分支上。让代理更新现有功能规格和实现，编写新测试，在调试器下运行测试作为人在回路的一部分
响应产品需求变更 — 如40%用户在移动端→需要响应式设计。小改动可直接在重新规划中实现；工作量大应安排在路线图上作为独立阶段。规格要捕捉决策，不仅仅是代码
项目路线图审查 — 重新审视路线图，下一个任务是否仍合理。发现相关功能可合并步骤
改进SDD工作流本身 — Agent Skills为代理提供新能力和专业知识的指令和资源包。可用Skills自动化SDD工作流（验证步骤可打包为验证skill）

关于Skills

适合可定义、可重复的工作流
可以是项目级或全局的
很多代理有"技能技能"帮你写skill

📄 显示原文字幕

We successfully implemented the first feature. Can't wait to do it again and again. Don't rush into it. Take a step back and reflect with some replanning. You have to run slow to run fast. We have a workflow step called validation. Tests are good for validation, but we didn't give the agent all our testing preferences. Let's make a replanning branch to update the tech stack in our constitution. As you saw in the previous video, spec versioning is an evolving topic. The constitution is a living document. It's good practice to make updates to it in its own separate branch, so you can keep track of which versions of it produced which code. We'll use a prompt to state our policy. It looks like the agent updated the package.json just to have a script, no dependency. Something to note for later, when we do run tests. This change to add a testing framework applies to future code. But let's tell the agent to update existing feature specs and implementation based on this constitution change. After these two prompts, we have some good changes. The agent set up this testing change, but didn't write the tests themselves. Let's tell the agent to write some new tests. With this setup, we can run tests conveniently in our editor. Let's run under the debugger to give us a chance to step through code execution as part of the human in the loop. Looks good. We now have tests as part of validation. Let's commit. Sometimes we realize we want to do something differently in the product plan. For example, after implementing the first feature, we got an update from the product manager. Because 40% of our users are on mobile, we want to emphasize a responsive design. Let's go to the agent. Tell the agent we want responsive design and to correct the product specs and feature specs as well as any code. Since we're so early on in development, this update is a small change, so it makes sense to directly implement it during replanning. But if the new work is big, it's better to schedule it on the roadmap as its own feature phase, instead of just doing it in replanning. Use your judgment. Remember, we want the specs to capture decisions, not just the code. We want to try to keep both in sync to help team communication. The agent has implemented our responsive fix with updates not just in code, but also to the product and feature specs. Time for us to do our part and review the changes. Let's go through the diffs. This looks good. Let's do a commit. Remember, working in small steps with frequent commits keeps the review from overloading your brain. While this first part of replanning is working, let's step back and do some project housekeeping. For example, let's revisit the project roadmap and look at the next task. Does it still make sense? The roadmap shows the next feature which we cover in the next lesson. Is it still the correct one? Looking through the roadmap, it looks like features two, three, four, and five kind of hang together. Let's update the roadmap to tackle those in one step. We'll commit and start on this new feature shortly. The replanning step can be about a feature or the whole project. But replanning can also be about improving your spec-driven development workflow, across projects, across your organization. For example, maybe you have a few non-technical stakeholders that want to monitor the project's progress. You'd like it to update a changelog on each merge to main. Most AI coding agents support skills, a package of instructions and resources providing the agent new capabilities and expertise. Skills are great for definable, repeatable workflows that require context specific to your project or organization. A skill would be great for implementing a changelog update. You could write this skill by hand, but many agents actually have skills that help you write a skill. Let's use the agent to help us write and maintain a changelog skill. The agent gets to work. One thing for us to consider is this skill unique to this project? Or should it be a standard part of all projects? This is a style choice and you'll gain better understanding as you use it. You'll learn to automate your SDD workflow with skills. For example, your validation step might include updating the readme, linting, formatting, test writing, and other quality checks. You can work with your agent to package those into a validation skill. Repeatable process, less manual work. The agent is finished. We can scroll through the window to see what it created and how to use it. Note that it chose to create this in the global skills area. This skill will now be usable across all projects. Also, Claude Code used the new skill to generate a CHANGELOG in this project. CHANGELOGs are how you talk to your stakeholders, including the agent. So, let's open it and review it manually. Looks good. We are finished with this replanning work. Let's wrap up with a commit. Then merge the branch. Now that most of your work as a developer is in planning and validation, rather than implementing, make time between features to replan. In the next video, we'll work on another roadmap feature.

10 The Second Feature Phase — 第二个功能阶段 ▼

核心内容

通过开发第二个功能，重点讨论"AI疲劳"及应对策略。

对抗AI疲劳的策略

保持每个功能阶段之间的清晰分界
检查：未完成的工作？上个分支是否已合并？下个路线图项目是否正确？是否清除了代理上下文？
花时间做好开头，帮助自己完成结尾

验证——更高层级审查

坚持更高层级的需求审查，避免纠结变量名等琐碎事项
只确保代理创建了你敢以自己名字提交的代码
规格中的遗漏（如提取props类型）不是失败——你在发现新细节时演化规格，捕捉这些会带来更好的未来结果

深度验证技巧

让代理生成子代理（sub-agents）对整个项目做深度审查
子代理给代理更多空间思考变更，保护主代理上下文窗口
代理自动修复问题、运行测试

功能完成流程

使用changelog skill → 提交 → 合并分支 → 快速重新规划
功能之间的清晰中断有助于管理AI疲劳

📄 显示原文字幕

We have an improved constitution and an improved workflow. We're getting better. But before moving on to the next roadmap feature, let's tackle some strategies to deal with a common pain point. AI fatigue. Agents can generate a lot of code with a lot of changes. This massive amount of code makes the human in the loop validation exhausting. So much to review. To fight this confusion, make sure you have a clean division between each feature phase. We should start each feature in the right flow state. Do I have unfinished work? Did I merge the last feature branch to main? Is the next roadmap item the right thing to do? Did I clear the agent's context to ensure the specs capture the intent instead of memory snapshots? And to let it focus its limited context budget on the next work. Take a moment to make a good start to help yourself finish. We've done all this. Let's clear the context and start the next feature, agents and ailments. As a note, we keep typing the same thing. We'll talk about how you can streamline this repeated prompting into a custom workflow in a future lesson. As before, the agent asks good questions. The first one is about whether to keep all these features in one phase. We already decided to do this together in the previous lesson, so we'll say yes. For the migrations, we'll choose plain SQL. For validation, let's select one, two, and three. That's good. Now, let's submit. When the agent drafts the spec, we can see some of its choices. The agent's reasoning process is useful to watch. If you're using an agent with verbose mode, that could give you even more insight into its intermediate ideas. Looks good, but we want to make one small change to capture our intent. We want to use PicoCSS as our CSS framework. Next, we review the three files in the feature spec, starting with the requirements. Let's ask the agent to change the requirements to make sure any other files reflect the change. When the work is finished, let's commit the feature spec. This time, we'll let the agent come up with the message. With the spec for the second feature ready, let's go to implementation. The division between the planning phase and the feature phase helps us to not overflow context, hours and agents. If the feature seems too big to implement all at once, ask the agent to implement part of the feature plan first. This will keep the size of the changes manageable. Our agent has implemented the phase two feature. We watched the agent's progress, so we have a rough idea of what was done. But that's not enough. Slow down, do some thinking. Let's do an in-depth review of the changes. Everybody has their own style on how much to review the agent's results. To play to the agent's strengths and reduce AI fatigue, stick to higher level requirements. Avoid nitpicking stuff like variable names. Just make sure it creates code that you can commit under your name. For example, it used inline type information for the props. We'd like the prop definition in a standalone TypeScript type. Let's tell the agent to fix this everywhere in the code. You probably didn't include this decision in your spec. Remember, an omission such as extracted prop types isn't a failure. You are evolving the spec as you discover new details and capturing that leads to better future results. We're finished with our review. This is a good moment for another small step commit. Last step validation. Let's review what the agent plans to do for the validation step in this feature spec. Looks good. Let's do our validation. Remember, we want to make sure the changes are good by running the application. But we also want to prevent cognitive debt by validating that we understand these changes. Tests are a great place to work through the flow. Let's read some tests and run them under the debugger as exploration. Sometimes you need to validate that you weren't lied to. Tell the agent to spawn several sub-agents to do a deep review of the entire project with this feature change. This deep review gives the agent more space to think about the changes. And using sub-agents preserves the main agent's context window, rather than polluting it. These sub-agents will come back with a number of issues and recommendations. All these look good, so let's proceed. The agent goes off, does a bunch of fixes, runs tests, and gets our project into a good state. Keep this in your tool chest. The agent can usually find important issues during a second look. Once we are finished with our validation, our feature is complete. It's time to commit our feature. As our last step on this feature, let's use the change log skill that we made in the previous lesson. We've now documented the changes on this feature branch. One more commit, then merge the branch. In a previous lesson, we saw the replan step in between features. Let's do a quick version of this by looking at the roadmap. Does the next feature still seem right? Looks good. Our project is in good shape, ready for the next feature. This clean break between features helps manage AI fatigue. Now you can take a break for some coffee. We're starting to see a repeatable SDD process for feature development. One that captures our decisions. In the next step, let's test that hypothesis. Do we have enough to build an MVP?

11 The MVP — 最小可行产品 ▼

核心内容

用SDD工作流快速构建MVP——对宪法和已完成功能规格的极限测试。

何时可以一次实现大块功能

只有当你对宪法和规格的质量有信心时
给代理的上下文质量越高，越有信心得到与意图一致的结果
确保你能处理审查和验证

MVP流程

使用标准功能规格prompt的变体，告诉代理实现路线图剩余部分
审查规格——代理经常做出不正确假设来填补空白
让代理验证规格（而非验证代码结果）——展示MVP在规划中找到的漏洞
可与利益相关者分享此评估

重要转折

不是所有软件项目都涉及构建MVP。很多是"棕地"（Brownfield）项目——从现有代码库开始。下一课讨论如何将SDD引入遗留项目。

📄 显示原文字幕

We made a lot of progress. Two features implemented with our spec workflow. But management just asked, of course, for an MVP. Have we made enough progress to do an experiment? Let's do a variation of our standard feature spec prompt. This time we'll tell it to implement the rest of the roadmap and give some guidance about existing feature specs. In general, you should only implement such a large chunk if you feel confident in the quality of your constitution and spec. The better the context you provide your agent, the more confident you can be in getting a result aligned with your intentions. And you should be sure that you can handle review and validation. But since we've taken this risk now, let's view the MVP as an extreme test of our constitution and completed feature specs. If we now get something different from what we wanted, it means we need to very responsibly carry out another replanning phase to eliminate whatever led the agent astray. The agent asked me some questions. Again, these are good questions and recommendations. A lot of spec files start as a back and forth conversation with an agent. Finished with the interview and we selected Submit Answers. Let's write the MVP specs to disk. It's always good to review the specs. You'll often notice incorrect assumptions the agent made to fill the gaps. Let's give a quick look at the plan. the requirements and the validation. As always, we like to work in small steps with frequent commits. Let's save the planning stages feature spec. We are finished with planning. It's time for the agent to go do a big implementation step. The agent now does a lot of work. Once it's finished, it's showtime. Let's see the MVP. We'll go to our scripts to run the application. As you can see, each section now has much more driven by sample data queried from the database. At this point, usually we would validate the code results, but this is an MVP. Let's ask the agent to validate the specs. As it turns out, this was useful. The agent showed places where the MVP found holes in our planning. We can share this evaluation with the stakeholders for their MVP review, then merge or archive the branch. Our spec-driven workflow succeeded. After a constitution and two features, the MVP produced a useful demo, thanks to our guidance. Of course, not all software projects involve building an MVP. Many projects are so-called brownfield. They start from an existing code base. Next, let's see how to introduce this workflow to legacy projects.

12 Legacy Support — 遗留项目支持 ▼

核心内容

如何将SDD工作流引入已有遗留项目——SDD同样适用于现有项目。

引入流程

准备遗留项目环境——使用AgentClinic MVP代码但去掉specs文件夹模拟遗留状态
从宪法步骤开始——使用几乎相同的prompt，但告诉代理从现有制品中查找路线图项目
代理会"逆向工程"代码库中的SDD制品
宪法帮助对齐代理未来的代码变更与过去开发者已创建的内容
可以随时添加更多上下文（代码、提交、文档等使对话更丰富）

审查代理生成的宪法

使命：包含受众、项目想法和额外信息
技术栈：代理提取了项目文件结构、框架版本和澄清
路线图：工作按阶段组织，匹配TODO文件

从现在开始

工作流与之前完全相同：拿下一个功能 → 规划 → 审查规格 → 提交 → 实现 → 验证 → 提交 → 合并 → 重新规划

规格现在成为了项目的记忆，所以它不会褪色。

📄 显示原文字幕

People say spec-driven development and even AI are only good for greenfield projects. But SDD is also good for existing legacy projects. In this lesson, we'll introduce SDD to an existing project. To make it easy, we'll start with a project you already know. The AgentClinic MVP. We'll make it a legacy by starting on main without the specs folder in a new Claude Code session in a different project directory. We have some project background in the README.md file with some open work listed in TODO.md. Your legacy project might have full product plans in issue trackers, spreadsheets, Word documents, etc. Remember our workflow? We'll start with the constitution step. We'll use almost the same prompt from lesson four. This time, we'll tell it to look for roadmap items in existing artifacts. In this case, a to-do file. Remember, the agent will discover and in a sense reverse engineer the SDD artifacts from the existing code base. The constitution will help align future code changes made by the agent with what past devs have already created. You can always add more context if you have it. For example, you might have been dropped into this project in order to improve its efficiency while implementing highly requested features. The process is the same, but the conversation might be richer as the agent has more artifacts, code, commits, documents, etc. You'll see a lot of tool calls here as the agent explores the code base. Let's look at the constitution for our legacy project. In the mission, we have an audience, the project idea, and some extra information about the project. The tech stack shows that Claude extracted the project file structure, framework versions, and the clarifications we were asked. In the roadmap, we can see the work is organized in phases, matching the to-do file. Let's create a commit for the constitution files that we produced with a commit message. Remember that in SDD, specs are part of your versioning strategy. Our legacy project is now placed on an SDD foundation. From now on, the workflow is exactly the same as we discussed in previous lessons. First, we grab the next feature on the roadmap and plan it in a conversation with the agent. We'll be doing phase one feedback form. Very good. We now have a branch and specs for this feature. Let's review the feature spec. The plan, the requirements, and the validation. Then we commit the feature spec. After we have made any corrections by chatting with the agent, we proceed to implement the feature. Once the agent is finished, we do our validation. To make sure the code is good and the feature works as expected. Our feature loop is done, we can commit. And then merge the branch to main. Now it's time for replanning. Make sure you give time for this. Since you just added SDD into your project, you may find a lot of things to tune. We now have a legacy project rebased onto Spec-Driven Development without a bunch of manual work. This gives us a well-documented flow, working in steps, using engineering and staying in control. The spec is now the memory of the project, so it doesn't fade.

13 Build Your Own Workflow — 构建自己的工作流 ▼

核心内容

通过Skills、MCP、Plugins等工具自动化和定制SDD流程。

Skills 自动化

重复相同prompt → 用skill自动化，借助代理写skill
可以是项目级或全局的
显式命名skill节省思考token
趋势：从自定义/commands转向skills

MCP → Skills + CLI 趋势

Context7等MCP服务器 → 现在建议用CLI + Skills方案
CLI工具可以用更少设置和更少上下文使用量来执行操作

社区SDD框架

GitHub Spec Kit — /commands: spec-kit constitution, plan, tasks, implement
OpenSpec (Fission AI) — propose→explore→apply→archive 工作流

研究积压

功能开发中间有想法？让代理把研究写到知名位置
之后让代理安排到路线图上，链接到积压文件
可写skill自动化研究过程

SDD帮助代理按你的方式写代码。采用现有框架，然后用skills定制，以你的方式运营项目。

📄 显示原文字幕

You've now mastered an SDD workflow. Want something faster and lightweight? In this lesson, we will automate things but doing it our way with a custom process. We previously showed Agent Skills, an open standard to give agents new capabilities and expertise. For example, we repeat the same prompt when starting a feature spec. Do this, do that, write these three files. Let's automate this with a skill and with help from the agent to write it. Ask the agent to use its skill creator to talk through this with us. As a note, there are many of these skill skills in the community that you can also install and use. As the agent runs, it might ask some follow-up questions. These are usually quite good. When the interview is done, we submit the responses and the agent proceeds. While the agent is working on the skill, keep an eye on the output. Is it making the choices you wanted? Success. As you can see, the agent wrote the skill to this directory. As a note, skills can be per project or global. Skills can be invoked in several ways. In your prompt, refer to the skill before saying what to do. Also, you can ask the agent to call a skill from another skill. According to the skills open standard, agents use the skill description to decide when to call it in a process called progressive disclosure. But their judgment isn't always perfect, especially as the context window gets larger. Use the same heuristic as file tagging. If you know you want a skill used, name it. That saves you some thinking tokens. Agents have built-in / commands like /clear. Though initially popular, many agents are moving from custom/commands over to skills. Sometimes you need to give the agent more resources like access to some API, a private knowledge base, database, and so on. Until now the universal way to extend an agent has been MCP, Model Context Protocol. For example, agents need current quality context about packages. The most popular choice, Context7, an MCP that brings updated documentation of packages into your agent context. Now your agent can stay up to date with React 9.2 and higher instead of React 9.0. MCP servers are still popular, but skills that use code tools like a CLI, command line interface, often accomplish the same purpose more elegantly. Context7 now suggests this, a skill that calls a CLI tool for Context7. Let's install the Context7 package for Claude Code. During the setup, we see this immediately. A choice between MCP server and CLI + Skills. We'll use the second choice. If this is your first time, you'll need to make an account. We already did so and logged in. Once done, we can go back into Claude Code and put it to use with an example prompt that uses Context7. As the agent runs, we see it detects the need to use Context7. When it completes, the agent shows it now knows how to find out information about our tech stack. This trend from MCP servers to skills plus CLI is accelerating. People are rethinking MCP because CLI tools can take action with less setup and less context usage. As you scale your workflow implementation, skills, etc. You will want to share it with yourself, across machines, with teammates, perhaps with the outside world. Some agents such as Claude Code have plugins, a collection of agent extensions that can be installed and updated. There's a growing community of free plugins. Check them out to see if any will boost your SDD productivity. Remember, plugins are not yet a cross-agent standard. Like apps or dependencies, plugins can execute code, so make sure you trust them on install and update. GitHub's Spec Kit is one attempt at formalizing a spec-driven development workflow with agents. Installing Spec Kit for a project gives you access to / commands in your agent, similar to the workflow you used in this course. spec-kit constitution, plan, tasks, and implement. Another popular alternative is OpenSpec from Fission AI. OpenSpec follows a similar propose, explore, apply, archive workflow, where propose and explore match with the plan step, apply matches with implement, and archive matches with replanning. It also has canonical patterns for quick features. Both packages include helpful features like branch management, verification scripts, and opinionated spec document formats. I encourage you to experiment with these open source workflows to help refine your own. Sometimes in the middle of a feature, you have an idea. You want to research it with the agent, but you don't want to stop your branch work. For example, a choice of databases. But you're not yet committed to this idea, so you don't want it on the roadmap. The conversation produces some good ideas and some good questions. We accept most of the recommendations, but change our mind on one of them. You don't want to lose it. So, let's keep a backlog of research by telling the agent to write a report in a well-known location. This file is a record of your conversation and results. You can later ask the agent to schedule this research on the roadmap with a link to the backlog file. As this grows, you can write a skill to automate your research. Spec-Driven Development helps the agent write code your way. You can adopt an existing SDD framework or tool, then customize it using skills to operate your projects with your team, your way.

14 Agent Replaceability — 代理可替换性 ▼

核心内容

SDD的重要优势——代理可替换性。工作在更高层级，不绑定特定代理或IDE。

四大代理标准

MCP (Model Context Protocol) — 外部工具
AGENTS.md — 规则
Agent Skills — 可重复工作流及额外上下文
ACP (Agent Client Protocol) — 连接代理和客户端

ACP (Agent Client Protocol)

让不同编辑器搭配不同代理
ACP Registry自动化发现、安装和连接代理与客户端
协议匹配LSP（Language Server Protocol）
覆盖不仅是聊天——还包括Next Edit Suggestion和Plan Mode
可以编写自定义代理，在工具中本地安装

代理切换演示

将功能规格skill复制到Codex（OpenAI代理），迁移后运行良好
可在同一项目中来回切换代理，保持SDD工作流
JetBrains IDE中通过ACP Registry一键安装OpenCode代理

规格工作在更高层级，不绑定任何特定代理或IDE。随着更多标准出现，这种灵活性应该会增长。

📄 显示原文字幕

Spec-Driven Development moves the work from the how to the what and why. Since agents and models progress so fast, you don't want your workflow tied to just one choice. In this lesson, we see how standards let us switch agents while keeping our workflow and even our tools. These agent standards help for this goal. MCP for external tools, AGENTS.md for rules, Agent Skills for capturing repeatable workflows with extra context, and ACP for connecting agents to clients. For example, Codex is a leading AI agent from OpenAI. It runs in a desktop app and in editors as well as in a terminal. Let's see it in action. Here is our feature spec skill from lesson 12 copied into Codex, which stores them in a different path. It runs just fine once migrated. This lets you switch back and forth between agents in the same project, keeping your SDD workflow. We can also use different editors with different agents using the Agent Client Protocol standard. ACP makes it easy to connect agents and editors. If your agent and client support ACP, you have a perfect match. To make this plug and play even easier, the ACP registry automates finding, installing, and connecting agents with their clients. The ACP Registry covers the whole life cycle, making it easier to mix and match. For example, in JetBrains IDEs, the AI Chat window leads to installation from the ACP Registry. The IDE can then show a listing of compatible agents. OpenCode is a popular open source agent. The ACP registry makes it easy to add to our IDE. Clicking install automates both the installation of OpenCode itself if needed, which is nice, and integration into the IDE. Once finished, your IDE now has native integration with a new agent. You can use this new agent alongside the other agents. in your same editor as part of SDD. These new agent standards are bringing new possibilities, but how do they actually work? The ACP architecture was designed to ease plugging together agents and clients. In fact, the protocol matches what's used in LSP. ACP is more than you think. For example, it covers Next Edit Suggestion in the editor and plan mode. To go one step further with ACP, you can write your own custom agent, install it locally in your tool. Which agent to choose? The industry changes fast and benchmark sites have sprung up with leaderboards providing different evaluations. Of course, these leaderboards change fast. So make sure to keep up to date and base your decision on the criteria that matter to you. Our specs work at a higher level, not tied to any one agent or IDE. In this lesson, we prove that. We built our workflow and tools to be independent of the agent. As more standards emerge, this flexibility should grow.

15 Conclusion — 结论 ▼

核心内容

从Vibe Coding（希望代理做你想要的）走向SDD（更接近你实际需要的）
编写了宪法，通过对话规划功能，作为"人在回路"验证，用Skills和标准自动化工作流

"你今天写的规格将成为明天项目的记忆。保持它们敏锐，持续改进你的流程。最好的代码始于一个伟大的规格。"

"让我们重新带回一些工程方法。让你继续做软件的驾驶者。"

"我真心关心在所有事物中找到快乐和目标。我很兴奋看到你用这些做什么。放轻松，去做一些酷事吧。"

📄 显示原文字幕

Great work completing this course. You've seen how to go 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. You've written constitutions, planned features through conversation, validated as the human in the loop, and automated your workflow with skills and standards. The specs you write today become the memory of your projects tomorrow. Keep them sharp, keep improving your process, and remember, the best code starts with a great spec. You and many of the engineers I know may have seen the consequences of moving too fast. Let's bring back some engineering. Let's keep you as the driver of your software. I really care about finding the joy and purpose in all things. And I'm excited to see what you do with this. Take it easy. Go, do some cool stuff.

📊 课程整体总结

SDD 核心工作流

宪法 Constitution → 功能循环 → Plan → Implement → Validate → 重新规划 Replan → 下一个功能...

关键概念一览

概念	说明
宪法 Constitution	项目级文档：使命、技术栈、路线图
功能规格 Feature Spec	每个功能的计划、需求、验证标准
人在回路 Human in the Loop	代理生成，人类验证的协作模式
认知债务 Cognitive Debt	跟踪代码做什么和如何演变的精神负担
AI疲劳 AI Fatigue	代理产生大量代码导致审查疲惫
上下文衰减 Context Decay	多轮会话中上下文窗口填满导致错误增加
意图保真度 Intent Fidelity	代理产出符合你目标的代码的可能性
Skills	可重复工作流的自动化包
MCP	Model Context Protocol，外部工具集成标准
ACP	Agent Client Protocol，代理-客户端连接标准
AGENTS.md	项目规则声明文件
Spec Kit / OpenSpec	社区SDD框架工具

SDD vs Vibe Coding 对比

维度	Vibe Coding	Spec-Driven Development
指导方式	即兴prompt	结构化规格文档
结果质量	一次性代码，技术债务积累	可维护的、意图一致的产品
上下文管理	对话历史不保存，上下文衰减	规格持久存在，跨会话/跨代理
可扩展性	适合小任务	适合大型持续项目
开发者角色	代码写作者	架构师/监督者
版本控制	无	规格与代码一同版本管理