规范驱动开发 · 课程笔记

Spec Driven Development 课程导论详细笔记

核心结论：Spec driven development 是与 JetBrains 合作、面向 agentic coding assistant 的工作流；把要构建的内容写成 markdown spec，让 agent 实现，从而用小型 spec 改动控制大型代码变更、减少会话间上下文衰减，并提高意图保真度。

核心要点

• 课程主题是 spec driven development：给 coding agent 一个 markdown 文件或长 prompt，准确说明要构建什么，agent 据此实现 spec。
• 开发者不再主要手写代码，而是专注于写下 agent 尚未拥有的上下文。
• 原文称 spec driven development 是当前构建严肃应用的“最佳类型工作流”（best type a workflow for building serious applications），这是课程方主张。
• 三大收益：用小型 spec 变更控制大型代码变更；消除会话之间的 context decay；提高 intent fidelity。
• 工作流核心：项目级 constitution 定义不可变标准，然后迭代 feature development loops，每个功能在独立 branch 上经过 plan、implement、verify。
• 同一工作流支持 greenfield 和 brownfield 项目。
• 课程还会展示如何编写自己的 agent skills，以自动化 spec driven workflow。
• 原文倡导：短任务可用 lazy prompting；但任何显著复杂项目，优秀开发者几乎总会写详细 spec。

课程背景与定位

• 课程名为 spec driven development，与 JetBrains 合作制作。
• 原文称其是当前用 agentic coding assistant 构建严肃应用的最佳类型工作流。
• 基本使用方式：给 coding agent 一个 markdown 文件或一个长 prompt，解释要构建什么，agent 实现该 spec。
• 重点从“手写代码”转向“写下 agent 没有的上下文”。
• 课程讲师为 Paul Everc（原文拼写；JetBrains 的 developer advocate）。开场由 Andrew 介绍，Paul 致谢；中间有关于眼镜的玩笑，属于开场互动，不影响技术内容。
• 原文提到课程贡献者包括 Constantine Chiker、Zena smoa（来自 JetBrains）以及 isaelzaro（来自 dblai）。这些名称按原文保留，疑似存在转写误差。

定义与基本工作方式

• Spec driven development 的工作对象不是逐行代码，而是 spec。
• Spec 可以是 markdown 文件，也可以是长 prompt。
• Spec 需要准确说明要构建什么，agent 据此实现。
• 开发者要提供 agent 本身不具备的上下文。
• 原文强调：写 spec 需要思考，是艰苦工作。必须决定：
• 想构建什么产品；
• 产品的功能；
• 技术架构。
• 如果没有 spec，就会把这些重要决策交给 coding agent 的“风”随机决定。原文认为，如果只想快速推进、掷骰子，这可能可以接受，但会导致可维护性更差的代码，有时还会产出奇怪的产品。

三大收益

写 spec 的方法：从对话到 markdown

原文给出一种常见写法：

1. 与 agent 对话，例如使用 cd code、Gemini 或 chagbia codex（原文拼写，疑似有转写误差）。
2. 在对话中做出关键架构选择。
3. 利用开发者自己对不同权衡的知识，决定如何 tradeoff。
4. 让 agent 把关键决策总结成一个 markdown 文件（原文为 markdown film，疑似 markdown file）。

这一方法的关键不是让 agent 替开发者思考所有事情，而是开发者先提供独特上下文和判断，再让 agent 整理成可复用的 spec。

无清晰 spec 的风险与案例

• 原文明确反对在没有 spec 的情况下把重要决策全部留给 coding agent。
• 风险包括：
• 代码可维护性下降；
• 产品可能变得很奇怪；
• 不同开发者指导不同 coding agent 时，可能快速但以矛盾方式构建。
• 原文案例：见过团队开发复杂软件产品时没有清晰 spec，结果导致许多下游头痛。不同 coding agent 在不同开发者指导下快速推进，但方式相互矛盾。
• 这说明 spec 不只是文档，而是协调多个 agent、多个开发者、多个会话的约束机制。

Spec driven development 的项目级工作流

项目级 constitution

• Spec driven development 首先涉及在项目层面开发 constitution。
• Constitution 用于定义 immutable standards，即不可变标准。
• Greenfield 项目：从头开始，通过与 agent 对话来开发 constitution。
• Brownfield 项目：基于现有代码库生成项目 constitution。
• 两种情况下，之后都会进入 feature development loops。

功能开发循环

• 每个功能被隔离在各自的 branch 上。
• 循环包含步骤：
• plan；
• implement；
• verify。
• 这些步骤在功能之间留下 clean slate，减少头痛和 context switching。
• 原文还提到在此过程中以小步骤管理 versioning。
• 这种循环结构适合减少多个功能之间的上下文污染，也适合 agent 的无状态特性。

Greenfield 与 Brownfield

• Greenfield：从零开始，constitution 通过人与 agent 的对话产生。
• Brownfield：已有代码库，constitution 基于现有代码库生成。
• 两者共同点：都要迭代 feature development loops，并小步管理版本。
• 原文强调同一工作流同时支持两类项目，这是 spec driven development 的适用范围。

Agent skills 自动化

• 课程会展示如何编写自己的 agent skills。
• 目标是用 agent skills 自动化 spec driven workflow。
• 这是课程后续内容的一部分，原文未展开具体技能格式或实现细节。

懒提示 vs 详细 spec：何时写长篇规范

• 原文作者自称是 lazy prompting 的倡导者：如果短 prompt 就能完成需要，那很好。
• 但对于任何显著复杂度的项目，原文认识的优秀开发者几乎总会写详细 spec。
• 原因：
• 他们有独特上下文；
• 他们对构建什么、如何构建有意见；
• 这比让缺少上下文的模型随机选择更优。
• 原文给出时间成本判断：如果 coding agent 要花 20 或 30 分钟写代码，这可能相当于传统开发者数小时的工作；此时通常更值得先花 3 或 4 分钟写下非常清晰的指令。

关键数字与事实

• 一句话 spec 改动可能影响数百行代码。
• Coding agent 自主写代码 20 或 30 分钟，可能相当于传统开发者数小时的工作。
• 值得花 3 或 4 分钟写清晰指令，以指导 agent 的 20 至 30 分钟工作。
• 无清晰 spec 的复杂软件项目会导致下游头痛，不同 agent 由不同开发者指导，快速但矛盾地构建。
• 三大收益：控制大型变更、消除 context decay、提高 intent fidelity。

限制条件与待确认问题

• 原文是课程导论/宣传性质，三大收益是课程方主张，未提供量化实验或对照数据。
• 多处名称和术语疑似语音转写错误，需要核对：
• Paul everc；
• cd code；
• chagbia codex；
• Constantine Chiker；
• Zena smoa；
• isaelzaro；
• dblai；
• “facts”在结尾疑似应为 “specs”。
• “sel light with prisma ormight” 一句不清晰，疑似涉及 Prisma、MongoDB 等技术选择，但具体原词无法确定。
• “with all the respect” 附近语义不清晰，结合上下文应理解为“没有 spec 时会把重要决策留给 coding agent”。
• 原文没有给出 constitution 模板、spec 文件结构、agent skills 写法、命令或代码示例。
• “best type a workflow” 是课程方观点，不是普遍证明的结论。
• Context decay、intent fidelity 等收益未给出衡量方式或指标。

行动清单

• 对显著复杂的项目，优先写详细 spec，而不是只依赖短 prompt。
• 如果短 prompt 能完成任务，可以继续使用 lazy prompting。
• 启动 coding agent 前，尽量加载最高质量的上下文。
• 先定义问题、成功标准、约束和关键架构选择。
• 在项目层面建立 constitution，定义不可变标准。
• 每个功能使用独立 branch，并按 plan、implement、verify 循环推进。
• 以小步骤管理 versioning，在功能之间留下 clean slate。
• 与 agent 对话做架构决策后，让其把关键决策总结为 markdown 文件。
• Greenfield 项目从对话生成 constitution；brownfield 项目基于现有代码库生成 constitution。
• 学习编写 agent skills，以自动化 spec driven workflow。
• 给 agent 分配 20 至 30 分钟编码任务前，先花 3 至 4 分钟写清楚指令。

总结

Spec driven development 的核心不是让 agent 替开发者思考，而是把开发者独有的上下文、约束、成功标准和架构决策写成 spec，让 agent 去实现。它通过项目级 constitution、功能级 plan/implement/verify 循环、独立 branch 和小步版本管理，试图解决 agent 无状态、上下文衰减、多人多 agent 协作矛盾等问题。原文认为其三大收益是用小 spec 改动控制大代码变更、减少 context decay、提高 intent fidelity；同时承认写 spec 需要认真思考，并不适合所有场景。短任务可以 lazy prompting，但复杂项目值得先写详细 spec。