规范驱动开发的定义与核心价值

本课程由 JetBrains 合作推出，旨在介绍当前构建严肃应用程序的最佳工作流：规范驱动开发（Spec-Driven Development）。在这种模式下，开发者不再逐行编写代码，而是通过 Markdown 文件或详细提示词向编程代理（Coding Agent）提供明确的构建规范。开发者的核心任务转变为补充代理已知的上下文之外的信息。正如讲师 Paul Everett 所言：“与其手动编写代码，不如专注于写下代理尚不具备的上下文。”这种方法将重点从实现细节转移到定义问题上。规范驱动开发具有三个主要优势：首先，通过微小的规范变更即可控制大规模代码修改。例如，将数据库从 SQLite 改为 MongoDB，仅需一句话的规范调整即可影响数百行代码。其次，消除会话间的上下文衰减。由于代理是无状态的，在启动时加载高质量规范能保留不可妥协的核心需求。最后，提高意图保真度。开发者定义问题、成功标准和约束条件后，代理能据此制定更完整的计划。

规范撰写的策略与工程价值

编写规范的本质是深度思考与技术决策。开发者需利用自身对权衡利弊的理解，与代理（如 Claude Code 或 Gemini）对话以确定关键架构选择，随后让代理将这些决策总结为 Markdown 文件。“编写规范需要思考，这是一项艰苦的工作。”如果没有明确的规范，开发者会将重要的产品和技术架构决策完全交给代理随机发挥。这可能导致代码可维护性差，甚至产生奇怪的产品形态。讲师分享了一个案例：某团队在没有清晰规范的情况下开发复杂软件，不同开发者指导下的代理以相互矛盾的方式快速构建功能，导致下游出现大量麻烦。规范驱动开发涉及在项目级别制定“宪法”以定义不可变标准，并通过迭代功能开发循环来隔离每个特性。这种工作流支持从零开始的新项目（Green Field）和现有代码库的改造（Brownfield），通过版本控制的小步迭代减少上下文切换带来的痛苦。

规范驱动与随意编码的对比分析

为了理解为何需要工程化的方法，课程将规范驱动开发（Spec-Driven Development）与流行的“随意编码”（Vibe Coding）进行了对比。随意编码依赖于简短的提示词，如“创建一个按钮”，然后反复修正代理的错误结果。这种方法虽然快速，但会导致代码可丢弃且技术债务累积，因为对话历史往往未被保存，无法扩展至大型持续项目。相比之下，规范驱动开发是对无监督 AI 生成混乱局面的专业回应。它实现了“是什么”和“为什么”（规范）与“怎么做”（实现）的解耦，在人类、代理和代码之间建立了契约。讲师指出：“规范驱动开发是应对无监督 AI 生成混乱局面的专业回应，它是一种范式转变。”通过强制开发者在代码生成前定义问题、成功标准和用户流程，规范显著降低了认知负荷。对于需要代理运行 20-30 分钟（相当于传统开发数小时）的复杂项目，花费几分钟编写清晰的指令远比让代理随机猜测更有效。规范是随意编码与工程化可行软件产品之间的关键区别点，它解决了项目漂移和生产力问题。

规范驱动开发（SDD）的核心定义与优势

编译器将人类可读的源代码转换为机器代码，而 规范（Specs） 则引导智能体将需求转化为源码。由于规范使用自然语言编写，利益相关者能够轻松理解项目意图。近期 SDD 的兴起旨在解决生产力担忧，多个围绕规范编写的项目、工具以及关于捕捉意图的会议演讲都证明了这一点。这是将软件工程生命周期中的经验教训引入智能体编码（Agentic Coding）的更广泛努力的一部分。

SDD 专门用于 智能体（Agents），而非简单的聊天机器人。虽然聊天机器人可以讨论代码，但它们无法访问项目源码或已安装的工具，仅对提示做出响应。相比之下，智能体会制定计划并通过推理引导自己达成结果。在 SDD 工作流中，我们将这些智能体视为 高度能力的结对程序员：它们提供技术知识和速度，而你作为高级架构师提供蓝图。正如课程所述：“智能体是肌肉，但规范是大脑”。

工作流架构：从宪法到特性迭代

SDD 告诉智能体如何构建项目，并随着每个功能的开发不断优化。我们首先提供关于项目的决策上下文，然后提供每个特性的细节。关键技能在于掌握适当的详细程度：如果将智能体视为结对程序员，应提供关于目标、使命、受众和约束的大量上下文，而减少涉及智能体可自行解决的底层决策。SDD 工作流首先制定 项目宪法（Constitution），包括使命、技术栈和路线图。许多开发者使用 top-level agents.md 文件，但项目宪法更具结构化且与智能体无关。

“The constitution captures the agreement on key decisions between the human and the agent, but also the agreement between the humans.”

宪法记录了人类与智能体之间以及人类内部关于关键决策的共识。使命解释项目的愿景和范围，技术栈明确开发约束，路线图则是包含各阶段特性规范过程的动态文档。在宪法起草后，进入可重复的特性开发流程：计划、实现、验证。特性之间设有 重新规划阶段（Replanning phase），用于修订宪法和路线图。你将智能体视为建筑师，提供详细图纸而非施工细节：“避免告诉建筑工人如何工作，专注于提供他们不知道的背景信息”。

开发环境配置与版本控制实践

在发送第一个提示之前，需进行工作区设置。SDD 是一种不绑定特定 IDE 或智能体的最佳实践，支持 VS Code、Zed 等多种组合。本课程以 WebStorm IDE 配合 Claude Code（Claw Code） 为例，开发一个名为 Agent Clinic 的 TypeScript Web 应用。虽然许多 IDE 提供聊天面板，但在 SDD 中 密切跟踪代码和规范的版本控制至关重要。

在创建初始提交时，智能体执行命令前会请求确认（除非处于不安全模式）。开发者需密切关注智能体的操作，因为 代码的最终责任在于人类。课程后续将介绍多个关于 Git 与 SDD 结合的最佳实践。设置完成后，即可开始编写宪法：明确项目的核心思想、技术栈选择及功能规划。这三项基本原则构成了指导未来特性开发的全局高层需求，帮助利益相关者理解项目形态。

建立项目宪法与人机协作基础

规范驱动开发（Spec-Driven Development）的核心在于将使命、技术栈和路线图这三根支柱文档化，这不仅是针对从零开始的新项目，同样适用于现有代码库。在课程示例“Agent Clinic”中，团队通过与人机协作的方式构建这些基础文档。这种对话能激发出架构模式、外部包选择以及速度与数据保真度等权衡方面的深刻见解。开发者首先向 AI 代理提供项目描述，并引用 readme.md 中的利益相关者输入。在提示中明确提及 Claude Code 的 ask user question 工具，虽然可选但能优化界面交互体验。要求代理与人类共同制定使命、技术栈和路线图，并将路线图分解为小步骤以支持“人在回路”的审查模式。代理随后提出关键问题，例如使命文档的语气、后端是否使用 TypeScript 以及路线图的粒度。开发者选择“ playful（有趣）”语气，确认后端技术栈为 TypeScript，并选定路线图的详细程度。在获得写入权限后，代理生成了 Mission.md、Techstack.md 和 Roadmap.mmd。> “We need to write this down for the agent, for your teammates, for the future. But we don't write it alone.”

审查与迭代项目宪法文档

生成初始文件后，进入人在回路（Human in the Loop）的审查阶段。开发者发现使命文档遗漏了目标受众，这是合理的，因为代理无法知晓业务背景。为了避免手动编辑导致的相关文档不一致，最佳实践是通过对话要求代理修改文件。例如，对于快速原型项目，开发者未明确指定数据库，但代理在推荐中建议了 SQLite 并将其纳入技术栈。经过最终审查确认无误后，提交宪法文档作为项目的“活文档”。此时，“Agent Clinic”项目拥有了指导方向的使命、路线图和技术栈。这一阶段的目标是确保在编码前将所有基础设定正确，因为后续数百行代码都将基于这些规格展开。> “It's important to get everything right up front.”

制定首个功能规格与验证标准

进入第一个特性“Hello Hano”的开发前，不能直接开始编码，而需讨论规格并澄清所有细节。良好的计划应概述方法、工作序列及成功验证方式。开发者在独立分支上启动新代理上下文，引用宪法作为权威来源。提示词旨在与代理就功能规格、任务计划、需求收集和验证记分卡展开对话。在决策环节，开发者确认保持第一阶段范围不变，锁定 HANA 版本并强制执行严格 TypeScript。对于验证方式，选择手动 curl。代理快速完成任务后，开发者需审查功能计划。> “A good plan outlines the approach, the sequence of work, and how to validate success.”

功能规格细化与实施准备

在审查中，开发者要求增加一个美观的占位符首页。通过代理更新功能规格文档中的需求和验证部分，确保技术约束与需求同步。此阶段需控制过程但不微观管理代理细节。功能规格文档的制定是投入产出比极高的环节，因为其中的变更将下游扩展为大量代码。完成规格文档后，在 IDE 中创建提交。实施阶段开始前，使用 /clear 命令清除上下文，然后提示代理实现所有任务组。这一流程确保了从规格到实现的连贯性，避免了因上下文污染或需求模糊导致的开发偏差。

任务分组执行与实时观察

在基于规范的驱动开发（Spec-Driven Development）中，将任务分解为小组并按顺序执行是确保代码质量的关键策略。这种细粒度的处理方式特别适用于安全或数据库管理等容错率极低的领域，因为微小的错误若在此类场景中累积，后期修复成本极高。在代理（Agent）运行期间，开发者可以通过控制台实时观察其进度和变更展示。提交完成后，通过查看最终差异并提交窗口中的更改摘要，开发者可以提前介入审查工作。代理会为每个任务组提供执行细节的总结，这有助于快速理解其逻辑路径。

人类在环：架构师角色与认知债务管理

在此范式下，开发者的核心角色转变为架构师或监督者，职责是确保代理获得清晰的契约。虽然代理能快速生成代码并验证功能（如启动服务器并在浏览器中显示结果），但开发者必须进行人工审查。这种“代理生成+人类验证”的流程被称为Human in the Loop（人在环路）。由于代码迭代速度极快，开发者面临巨大的“认知债务”压力——即追踪代码演变和当前状态的心理负担。为了降低这种负荷，变更必须保持可管理性。审查应聚焦于高层级问题（如功能是否符合规范），而非底层细节（如具体的 CSS 类名）。例如，若发现布局组件过于简陋且不符合规范预期，应直接要求代理修正规范和实现。

同步维护：避免工件漂移与测试集成

在重构代码结构（如将子组件分离到独立文件）时，开发者常倾向于手动操作以利用 IDE 的便捷性。然而，这种做法可能导致工件漂移（Drift），即代码、规范文档和 README 之间不同步。因此，即使是很小的结构调整，也应要求代理同步更新所有相关文档和引用，以确保一致性。此外，若代理未自动安装测试包，开发者需手动介入或在后续步骤中补充。版本控制策略在此阶段至关重要：对于较小的规范更新（如路线图打勾），可合并至同一分支；若涉及复杂的宪法级变更，则建议创建独立分支以追踪版本对应关系。最终，在标记任务完成并合并前，需确保所有变更已同步且未破坏现有功能。

重新规划：响应式设计与测试框架落地

项目初期实施首个特性后，需进行反思与重新规划（Replanning）。例如，若产品团队反馈 40% 用户来自移动端需求强调响应式设计，这一变更应被视为对产品规范和特性规范的修正。在开发早期，此类小范围调整可直接在执行重新规划时实施；若涉及大规模工作，则应将其列为独立的功能阶段。代理不仅需更新代码以实现响应式布局，还需同步修改产品规范和特性规范，确保决策被记录在案而非仅代码变更。同时，开发者应利用此机会更新“宪法”中的测试策略。通过提示代理添加测试框架并编写新测试，结合调试器逐步执行代码（Human in the Loop 的延伸），可以建立完善的验证体系。最终，通过频繁的小步提交和审查，保持团队沟通顺畅并降低认知负荷。

项目重构与技能自动化：从路线图到变更日志

在推进新功能之前，重新审视项目路线图是确保开发方向正确的关键步骤。通过回顾发现，原有的功能规划中第2、3、4和5项具有内在关联性，因此决定将它们合并为一个更大的开发阶段以提升效率。这种重规划（Replanning）不仅适用于单个功能，还可以扩展到整个组织的标准化工作流优化。例如，为了向非技术利益相关者展示进度，团队决定引入变更日志（Change Log）的自动更新机制。虽然可以手动编写此类技能，但利用AI编码代理来辅助生成和维护技能包（Skills）更为高效。这些技能本质上是包含指令和资源的软件包，旨在赋予代理特定于项目或组织的上下文能力。

"Skills are great for definable, repeatable workflows that require context specific to your project or organization."

在实施过程中，团队选择将变更日志技能创建为全局技能（Global Skills），这意味着该技能将在所有项目中可用，而不仅限于当前项目。代理成功生成了变更日志内容后，开发者需进行手动审查以确保其符合利益相关者的沟通需求。确认无误后，通过提交和合并分支来结束这一阶段的规划工作。自动化重复性工作不仅减少了手动操作，还通过标准化的技能包提升了开发流程的一致性。

应对AI疲劳：上下文管理与阶段隔离

随着代理生成大量代码，人类在环（Human in the Loop）的验证工作变得极其繁重，导致所谓的“AI疲劳”。为了缓解这种认知负荷，开发者必须在每个功能阶段之间建立清晰的界限。这意味着在开始新功能前，必须确保上一个功能的分支已合并到主分支，并清除代理的上下文（Clear Context）。这一操作至关重要，因为它能确保新的规范（Spec）捕捉的是意图而非之前的记忆快照，从而让代理有限的上下文预算专注于当前任务。

"Do I have unfinished work? Did I merge the last feature branch to main?... Did I clear the A's context..."

这种阶段隔离策略有助于开发者保持“心流”状态，避免因上下文溢出而导致的错误。此外，团队还计划在未来的课程中探讨如何将重复的提示词流转化为自定义工作流（Custom Workflow），以进一步简化操作。通过定期重规划和清理上下文，开发者能够更有效地管理代理的工作负载，确保持续的高质量输出。

规范制定与实施：从CSS框架选择到代码审查

进入第二阶段功能的实现，开发者首先通过代理起草规范。在此过程中，规范的迭代性得以体现：虽然初始草案已生成，但开发者决定将CSS框架指定为Pico CSS。这一变更通过代理同步更新到所有相关文件，展示了规范驱动开发（Spec-Driven Development）中意图捕捉的重要性。提交时，开发者允许代理自动生成提交信息（Commit Message），进一步简化了流程。

在实施阶段，代理完成了功能开发。然而，开发者并未立即合并代码，而是进行了深度审查。为了避免微观管理（如变量命名），审查重点放在满足高层级需求上。例如，发现代理使用了内联类型信息而非独立的TypeScript接口定义后，开发者指示代理在整个代码库中统一修改。这一过程表明，规范的演进是常态而非失败。通过捕获这些新发现的细节（如提取的prop类型），未来的开发结果将更加精准。最后，通过运行测试并在调试器中探索代码流，开发者验证了变更的正确性，并利用子代理（Sub-agents）对整体项目进行了深度审查，以保留主代理的上下文窗口并发现潜在问题。

特性开发闭环与标准化流程验证

在规范驱动的开发（STD）中，智能体不仅能执行代码修改，还能通过二次审查发现关键问题。当智能体完成修复并运行测试后，项目进入良好状态。特性开发的最后一步是提交变更日志，利用之前课程中创建的 changelog skill 记录分支上的所有更改。完成最后一次提交并合并分支后，开发者应回顾路线图以进行“重新规划”，确认下一个特性是否依然合理。这种在特性之间保持清晰断开的做法有助于管理 AI 疲劳。此时，项目处于良好状态，可以暂停休息。这一过程展示了一个可重复的 STD 特性开发流程，它有效地捕获了决策过程。

MVP 构建与宪法质量的极端测试

在实现两个特性后，管理层要求提供一个最小可行产品（MVP）。为了判断是否具备构建 MVP 的条件，开发者使用变体的标准特性规范提示词，指示智能体实现剩余的路线图部分。这一策略仅在开发者对宪法（Constitution）和规范质量有足够信心时采用。提供的上下文越丰富，智能体产出的结果与意图的一致性越高。此时应将 MVP 视为对宪法和规范质量的极端测试。如果产出偏离预期，则必须负责任地执行重新规划阶段以消除偏差。智能体通过问答形式协助完善规范，开发者需仔细审查生成的计划、需求和验证逻辑。在规划阶段结束后，智能体执行大规模实现步骤。

遗留项目引入 STD 工作流的策略

并非所有软件项目都涉及构建 MVP，许多项目属于“遗留”（Brownfield）性质。将 STD 引入现有代码库时，可以从已有的 README.md 和 to-do.md 等工件开始。开发者使用与绿色场项目几乎相同的提示词，但指示智能体从现有文件中提取路线图信息。这一过程本质上是逆向工程 SD 工件。宪法的作用是将未来由智能体进行的代码更改与过去开发者创建的内容对齐。通过探索代码库，智能体会发现并提取项目结构、框架版本等上下文信息。规范现在是项目的记忆，这使得在遗留项目中引入 STD 无需大量手动工作即可建立文档化、分步骤的工程流程。

MVP 验证与自动化扩展展望

MVP 实现后，虽然通常需手动验证代码结果，但在此场景下，开发者让智能体自我验证规范。这一过程揭示了规划中的漏洞，这些发现可分享给利益相关者进行评审。一旦 MVP 演示成功且分支合并或归档，便证明了规范驱动工作流的有效性。对于希望更快速、轻量级的开发者，下一步是自动化。通过之前展示的 Agent Skills（智能体技能）这一开放标准，可以为智能体赋予新的能力和专业知识。例如，通过重复使用相同的提示词来启动特性开发，可以实现定制化的自动化流程。规范驱动的开发不仅适用于绿色场项目，同样能有效提升遗留项目的工程控制力。

技能的创建、调用逻辑与管理策略

在自动化开发流程中，利用智能体（Agent）的技能创建器来编写特定任务脚本是一种高效手段。用户只需提出需求，智能体便会引导完成技能的开发。技能的存储位置分为项目级和全局级两种，这为不同粒度的工作流管理提供了灵活性。技能的调用方式多样，既可以在提示词中显式引用技能名称再执行指令，也可以让一个智能体调用另一个智能体的技能。根据开放标准中的“渐进式披露”机制，智能体会依据技能描述自动判断何时调用该技能。然而，随着上下文窗口的扩大，这种基于描述的自动化判断并不总是完美无缺。因此，如果用户明确希望使用某个技能，直接在提示词中命名它是更可靠的做法。这种显式调用虽然看似简单，但能有效节省智能体的思考Token消耗，避免其在不必要的上下文中进行冗余推理。

从MCP到CLI+Skills：工具扩展的范式转移

在需要为智能体提供额外资源（如API访问、私有知识库或数据库）时，模型上下文协议（MCP）曾是通用的扩展方式。例如，“Context 7”作为一个流行的MCP服务器，能将软件包的最新文档引入智能体上下文，使其能够获取如React 9.2等最新版本的信息。然而，行业趋势正加速从MCP服务器转向结合CLI（命令行界面）的技能方案。这种转变的核心在于，CLI工具能够以更少的配置步骤和更低的上下文占用来实现相同的功能。以Context 7为例，其官方建议现在是通过一个调用CLI工具的技能来替代传统的MCP服务器模式。在安装过程中，用户会面临选择“MCP服务器”还是“CLI+Skills”，后者因其简洁性成为更优解。这一变化反映了开发者对轻量化、低开销工具链的偏好升级。尽管MCP服务器依然流行，但基于代码执行的工具往往能更优雅地解决上下文获取问题。

跨平台工作流标准化与ACP协议的互操作性

为了实现技能和工作流的共享，智能体生态系统中出现了插件机制和标准化协议。虽然Claude Code等工具拥有独立的插件系统，但目前尚缺乏跨智能体的统一标准。相比之下，GitHub的Spec Kit和Vision AI的Open Spec等开源工作流框架提供了更结构化的规范驱动开发体验，它们包含分支管理、验证脚本和规范的文档格式。为了进一步降低工具切换的成本，代理客户端协议（ACP）成为连接智能体与编辑器的关键标准。通过ACP注册表，用户可以自动化地查找、安装和连接智能体。例如在JetBrains IDE中，用户可以直接通过ACP注册表一键集成Open Code等开源智能体。这种即插即用的体验使得在同一编辑器中并行使用多个不同来源的智能体成为可能，从而确保了工作流与特定智能体的解耦。即使将技能文件复制到不同路径或切换至OpenAI的Codeex等桌面应用，只要遵循规范驱动开发的逻辑，工作流即可无缝迁移。这种标准化不仅保护了用户的投资，还允许团队根据需求灵活组合不同的智能体和编辑器。

ACP架构：连接智能体与客户端的通用协议

ACP（Agent Communication Protocol）架构的核心设计初衷是为了简化智能体（Agents）与客户端之间的集成过程。该协议的设计逻辑高度借鉴了语言服务器协议（LSP），这种成熟的标准使得不同组件之间的对接更加顺畅和标准化。ACP的功能远不止于基础的通信，它实际上覆盖了更广泛的交互场景。它不仅支持编辑器中的下一步编辑建议（next edit suggestion），还涵盖了计划模式（plan mode）等高级功能。这种架构的通用性意味着开发者可以超越单一工具的局限，实现更灵活的工作流整合。更进一步地，ACP允许用户编写并安装自定义的智能体到本地工具中。这种可扩展性使得开发者能够根据具体需求定制专属的AI助手，而无需依赖厂商提供的黑盒方案。通过标准化的接口，ACP为构建开放、模块化的AI开发环境奠定了基础。

智能体选型：动态基准测试与独立工作流的优势

在快速迭代的行业环境中，选择合适的智能体并非易事。目前市场上涌现了大量提供排行榜的基准测试网站（benchmark sites），它们通过不同的评估维度对智能体进行排名。然而，这些排行榜的变化速度极快，依赖静态数据做决策往往具有滞后性。因此，明智的做法是保持对最新数据的关注，并基于对自己真正重要的评估标准（criteria that matter to you）来做出选择。本课程的核心理念在于，所编写的规范（specs）工作在更高层级上。这些规范和工具的设计完全独立于任何特定的智能体或集成开发环境（IDE）。这种架构上的解耦确保了工作流的灵活性，随着更多标准的出现，系统能够更轻松地适应新的智能体技术。这种独立性是应对行业快速变化的关键策略，它避免了被单一供应商锁定的风险。

从随意编码到规范驱动：回归工程本质

完成本课程意味着实现了思维模式的转变：从寄希望于智能体自动完成任务的“氛围编码”（vibe coding），转向能够更精准满足实际需求的规范驱动开发（spec-driven development）。在这一过程中，学习者掌握了编写宪法式规则、通过对话规划功能特性、作为人类在环（human in the loop）进行验证，以及利用技能和标准自动化工作流等关键技能。今天编写的规范将成为明天项目的记忆，因此必须保持规范的严谨性并持续优化流程。回顾过往，许多工程师都目睹过因追求速度过快而导致的负面后果。我们需要重新引入工程纪律（engineering），确保人类始终掌握软件开发的主动权。这一过程不仅是技术的提升，更是寻找工作乐趣与目的的过程。正如结语所言：最好的代码始于伟大的规范（The best code starts with a great spec）。

结论

规范驱动开发（SDD）通过将意图与实现解耦，有效解决了随意编码导致的技术债务累积和上下文衰减问题。其核心优势在于利用“宪法”确立不可变标准，并通过迭代特性开发隔离变更风险。实践表明，SDD 能显著降低复杂项目的认知负荷，确保代码可维护性并支持从绿色场到遗留系统的平滑迁移。然而，该模式要求开发者承担架构师职责以管理“人在回路”的审查压力及认知债务，且高度依赖高质量规范的制定。SDD 并非替代编码，而是通过标准化工作流、技能自动化及 ACP 协议等工具链扩展，实现工程纪律与 AI 效率的平衡。