规范驱动开发SDD的实战、原理、缺点

在传统的软件开发模式中，代码是唯一的真理。SDD（Specification-Driven Development）提出：规范才是核心资产，代码只是规范的一种翻译或实现形式。本文系统介绍使用spec-kit实现SDD的实战、原理、缺点。

1 项目实战spec-kit

从零开始创建项目，执行命令：specify init Animal_ABC_Fun --ai gemini。创建名为 Animal_ABC_Fun 的项目，使用 Gemini CLI 作为 AI 代理。

Spec Kit 的核心流程通过5个斜杠命令驱动，覆盖规范定义→计划生成→任务分解→代码实现→质量检查全链路。

1.1 制定项目宪法

作用：定义项目的最高准则（如技术栈、代码质量、性能要求），确保 AI 生成的所有内容符合团队规范；

命令：/speckit.constitution 优先使用原生 HTML5/CSS3/JavaScript（Vanilla JS），不依赖复杂的现代前端框架（如React/Vue）以保持极简。游戏必须对4岁儿童绝对安全（无广告、无外部链接、防误触）。所有静态资源（图片、音频）必须预加载。UI动画流畅，交互响应时间（包含音频播放）必须小于 50ms。

AI 在目录specify/memory/下生成.constitution.md，记录上述原则，后续所有步骤均需遵守。

AI 助手返回的系统执行报告如图。

我已根据您的具体要求成功更新了项目宪法，并同步了所有相关的依赖模板。

**变更摘要 (Summary of Changes)**
*   **宪法版本升级**：从 [模板草案] 更新至 v1.0.0。这确立了项目的基础原则。
*   **强制执行的新核心原则**：
    1.  **原生 Web 技术**：严格要求使用 HTML5、CSS3 和原生 JavaScript，明确禁止使用 React 或 Vue 等框架。
    2.  **儿童安全环境**：强制执行零广告、零外部链接政策，包括防止意外连续误触的特殊 UI 保护措施。
    3.  **资源预加载**：要求在交互游戏开始之前，必须 100% 完成图像和音频文件的预加载。
    4.  **超低延迟**：规定交互触发到音频播放的响应时间必须保持在 50 毫秒以内，且动画必须达到 60 FPS（帧/秒）。

**同步的模板 (Synchronized Templates)**
1.  **.specify/templates/plan-template.md (计划模板)**：更新了宪法检查点，以匹配上述 4 项新原则。调整了技术背景提示和项目结构布局选项，使其更符合典型的原生 JS Web 应用，而不是 Python 后端服务。
2.  **.specify/templates/spec-template.md (规范模板)**：注入了一个新的约束与合规（宪法强制要求）章节，其中包含明确可追踪的合规性指标（标记为 C-001 到 C-004）。
3.  **.specify/templates/tasks-template.md (任务模板)**：更新了阶段 2：基础任务，加入了资源预加载逻辑、Web Audio API 实现以及交互防抖（debouncing，防止孩子狂按键盘崩溃）任务。将示例代码的文件后缀从后端的 .py 修改为了前端逻辑的 .js 文件。

**手动后续操作 (Manual Follow-up)**
*   所有的占位符和标签都已自动填充完毕。现阶段不需要您进行任何手动的后续修改。您可以立即开始规范功能需求（即进行下一步）。

**建议的 Git 提交信息 (Suggested Commit Message)**
*   docs: ratify constitution to v1.0.0 with child-safe vanilla web principles
    *(翻译：文档：正式确立宪法 v1.0.0 版，采用儿童安全的纯原生 Web 原则)*

代码工程的截图

1.2 定义功能需求

作用：将模糊的用户需求转化为可测试、无歧义的功能规格，包含用户故事、功能需求、成功标准；

命令 ：/speckit.specify 构建一个适合4岁儿童玩的PC网页游戏，用于英文和动物认知学习。进入游戏需要一个开始按钮来激活浏览器音频。游戏中，孩子按下键盘上的A-Z 字母键，屏幕中央会出现对应字母开头的动物卡通图像（带有弹跳动画），同时播放英文发音（如A, Apple!..不，这里是A,Alligator!）和动物的叫声。屏幕上要显示当前按下的巨大字母和动物单词。

AI 在specs/001-animal-abc-game/目录下生成spec.md 详细功能规范。

AI 助手返回的系统执行报告如图。

已根据您的描述成功创建了动物字母乐园（Animal ABC）游戏的功能规范。

**执行摘要 (Execution Summary)**
*   **创建的分支**：001-animal-abc-game （为您在 Git 中创建了一个专属的工作分支）
*   **规范文件**：specs/001-animal-abc-game/spec.md （生成了功能需求文档）
*   **检查清单**：specs/001-animal-abc-game/checklists/requirements.md (所有检查均已通过) （验证了需求是否符合第一步制定的宪法）

**关键决策 - 无需您再做澄清 (Key Decisions)**
1.  **处理多键输入（即狂拍键盘）**：系统会立即打断当前正在播放的动画和声音，并立刻开始播放最新按下的内容。这确保了游戏对4岁儿童来说具有极高的即时响应感。
2.  **无效按键**：数字键、空格键、符号键以及修饰键（如 Ctrl/Alt）将被完全忽略，以防止孩子发生意外的交互操作（比如误触导致页面滚动或退出）。
3.  **大/小写处理**：大写锁定（Caps lock）和 Shift 键的状态不会产生影响；按下大写的 'A' 或小写的 'a' 都会同样触发Alligator（鳄鱼）的动画序列。

规范现已完成，随时可以进入**技术规划阶段**。目前不需要您再提供任何补充说明。

代码工程的截图

1.3 生成技术方案

作用：基于功能规范，AI 自动生成详细的技术实现计划，包括数据模型、接口契约、外部依赖、性能/安全要求；

命令：/speckit.plan 使用原生 Web API 构建 UI。使用 CSS Flexbox居中布局，设计一个字典对象（JSON结构）来映射26个字母到对应的图片、音频和文本数据。请给出详细的文件架构、数据模型设计和本地运行指南。

AI 更新 specs/001-animal-abc-game/目录。

AI 助手返回的系统执行报告如图。

我已完成动物字母乐园（Animal ABC Game）的技术实现规划。该设计侧重于使用原生 Web API，构建一个**超高响应速度**且**对儿童安全**的应用程序。

**生成的产物 (Generated Artifacts)**
*   **实施计划**：specs/001-animal-abc-game/plan.md （整体架构方案）
*   **研究文档**：specs/001-animal-abc-game/research.md （深入研究了 Web Audio API、资源预加载策略和 CSS 动画）
*   **数据模型**：specs/001-animal-abc-game/data-model.md （定义了 AnimalMap 字典结构和应用的状态切换逻辑）
*   **接口契约**：specs/001-animal-abc-game/contracts/asset-mapping.json.md （26个字母映射关系的 JSON 数据结构标准）
*   **快速入门**：specs/001-animal-abc-game/quickstart.md （本地开发环境和本地服务器的搭建指南）

**关键技术决策 (Key Technical Decisions)**
1.  **Web Audio API (高级音频接口)**：为了实现**低于 50 毫秒**的按键到发声超低延迟，系统会提前将音频数据解码并存入内存缓冲区（Memory Buffers），而不是使用传统的 <audio> 标签。
2.  **显式预加载 (Explicit Preloading)**：系统将设置一个自定义的加载拦截器。在所有（100%）图片和音频资源下载完成之前，开始游戏 (Start)按钮将被锁定（或隐藏），以确保游戏过程中绝对不会出现卡顿或白屏。
3.  **CSS 硬件加速 (CSS Hardware Acceleration)**：动物弹跳出场的动画将专门使用 transform 属性来实现。这能调用电脑显卡（GPU）进行渲染，确保动画永远保持丝滑的 60fps（每秒60帧）。
4.  **零框架架构 (Zero-Framework Architecture)**：已严格对照项目宪法进行审核验证（完全没有使用 React/Vue，仅使用纯正的 Vanilla JS、HTML5 和 CSS3）。

**下一步 (Next Step)**
您现在可以使用以下命令，将这份技术规划拆解为（开发人员/AI 可以直接编写的）具体执行任务：
/speckit.tasks

代码工程的截图

1.4 分解任务列表

作用：AI 将技术方案自动分解为可执行的任务单元，每个任务包含前置条件、执行步骤、依赖关系；

命令：输入 /speckit.tasks；

输出：AI 在目录specs/001-animal-abc-game/下生成tasks.md，包含分阶段任务。AI 助手返回的系统执行报告如图。

我已成功为动物字母乐园（Animal ABC Game）生成了 tasks.md（任务清单）文件。所有任务均按照用户故事进行分类，并严格遵循了检查清单的格式要求，以确保每个功能都能被独立开发和测试。

**执行摘要 (Execution Summary)**
*   **任务文件**：specs/001-animal-abc-game/tasks.md
*   **总任务数**：27 个
*   **任务分布**：
    *   **阶段 1（环境搭建）**：4 个任务（项目结构初始化）
    *   **阶段 2（基础建设）**：5 个任务（解决核心难题，如资源预加载机制和音频播放器封装）
    *   **阶段 3（用户故事 1）**：5 个任务（游戏初始化界面的渲染和浏览器音频权限的解锁）
    *   **阶段 4（用户故事 2）**：7 个任务（核心玩法：A-Z 键盘按键与画面、声音的交互循环）
    *   **阶段 5（用户故事 3）**：2 个任务（输入过滤：屏蔽无效按键，提升程序的抗破坏能力）
    *   **阶段 6（最终打磨）**：4 个任务（儿童安全限制、合规性检查以及静态资源优化）

**关键策略：MVP（最小可行性产品）优先**
建议的 MVP 范围包含用户故事1（音频解锁）和用户故事2（A-Z核心循环）。优先完成这两个部分，就能交付一个具备完整教育功能的可玩版本，并且完全符合宪法中规定的性能和安全标准。

**独立测试标准 (Independent Test Criteria)**
*   **用户故事 1**：验证Start (开始)按钮是否**只有在**资源 100% 预加载完成后才出现；验证点击该按钮是否成功激活了 Web Audio API 的发声权限。
*   **用户故事 2**：按下键盘字母 'A'，能看到鳄鱼 (Alligator)的动画和文本，并确保在 50 毫秒内听到双重音效（英语发音 + 动物叫声）。
*   **用户故事 3**：狂按非字母键（如数字、空格、F1等），系统状态没有任何改变，也不会发出任何错误提示音。

**并行开发机会 (Parallel Opportunities)**
我已经在清单中标注了几个带有 [P] 标记的并行任务（例如：编写 HTML/CSS 骨架、处理 JSON 资源映射表、编写集成测试）。这些任务互不干扰，可以同时进行，从而大幅加快初期的开发速度。

**下一步骤 (Next Step)**
任务清单现已准备就绪，可以正式进入代码编写阶段。您可以使用以下命令开始生成代码：
/speckit.implement

1.5 执行任务生成代码

作用：AI 逐一执行任务列表中的任务，自动编写代码、创建文件、运行测试，并实时报告进度；

命令：输入 /speckit.implement；

输出：AI 已经把前面的所有需求、计划和任务清单，全部转化成了实实在在的、可以运行的代码！AI 助手返回的系统执行报告如图。

✦ 动物字母乐园（Animal ABC Game）已成功开发并验证完毕。在严格遵循项目宪法要求（纯原生 JS、HTML5、CSS3 以及儿童安全设计）的前提下，实施计划中定义的所有任务均已完成。

**开发总结 (Implementation Summary)**
*   **原生 JS 架构**：游戏完全使用原生 Web API 构建（无任何第三方臃肿框架）。
*   **音频策略**：独立封装了 Web Audio API 模块（js/audio.js），实现了**低于 50 毫秒**的超低延迟，确保极速响应的教育体验。
*   **预加载引擎**：自定义了预加载器（js/preloader.js），在开始界面进行拦截，确保在孩子开始交互前，100% 的静态资源已下载完毕。
*   **儿童安全 UI**：
    *   使用正则表达式（Regex）进行了极其强大的输入过滤，直接无视所有非字母按键。
    *   **防误触保护**：加入了 100 毫秒的冷却时间（Cooldown）以及同键防抖（Debounce）机制。
    *   绝对零广告、零外部链接。
*   **视觉设计**：采用了现代的 Flexbox 弹性布局（css/main.css），以及调用显卡硬件加速的弹跳出场动画（css/animations.css）。

**已验收通过的开发阶段 (Verified Phases)**
1.  **阶段 1 & 2（环境与基建）**：目录初始化完毕，配置了 package.json，并完成了核心工具类（数据映射表、音频控制器、预加载器）的编写。
2.  **阶段 3（音频权限解锁）**：成功验证了Start (开始)按钮的工作流:从加载状态平滑过渡，并成功唤醒浏览器的音频引擎。
3.  **阶段 4 & 5（核心玩法）**：成功实现了 A-Z 的交互循环，支持双轨音频并发播放（英语人声 + 动物真实叫声），并具备强悍的输入过滤功能。
4.  **阶段 6（打磨与优化）**：加入了防抖逻辑，并通过 npx serve 命令成功验证了本地服务器部署。

**测试结果 (Testing Results)**
*   **单元测试**：5/5 全部通过（完美覆盖了数据映射逻辑和输入过滤逻辑）。
*   **集成测试**：已使用 Cypress 框架创建了自动化测试套件，用于模拟真实的初始化流程和游戏交互。

项目现已准备就绪，可以随时发布。**您现在可以在终端运行 npx serve . 命令，然后在浏览器中访问 http://localhost:8080 来在本地体验这款游戏。**

最终代码工程的截图

2 speckit命令：项目宪章

2.1 这里的宪法不是文档，是代码

在 SDD 工具链（如 speckit）中，Constitution（项目宪章） 是项目一套全局性的约束和限制。是机器可读取的元数据（Metadata）。

• 立法内容： 规定项目必须长什么样。例如：必须使用 React 18+？文件夹命名必须是 kebab-case？所有接口必须遵循 RESTful 标准？

• 地位： 它控制着所有下游环节（Plan, Spec, Tasks）。如果宪法被修改（例如从 Java 切换到 Kotlin），系统会自动更新所有的开发模板，而不需要口头通知团队成员。

3 speckit命令：需求重塑

3.1 Specify：需求的结构化翻译

这是 SDD 流水线的第一步，解决产品经理的嘴和程序员的手之间的鸿沟。

• 自动化基建： 当你输入一个自然语言描述（如做一个微信登录），工具链会自动提取关键词生成分支名（feat/wechat-login），自动创建目录结构。

• 模板填充： 利用 AI 的明智猜测能力，提取出参与者（User）、动作（Login）、数据（Token），并填入标准化的 spec.md 模板中。

• 解耦： 注意，这里只描述系统表现什么行为，绝对不涉及数据库怎么设计。这是为了解耦业务逻辑与技术实现。

3.2 Clarify：机器反向审问人类

不是人去检查文档，而是工具（AI）反过来审问开发者。

• 痛点解决： 消除模糊形容词。如果规范里写了系统需要高性能，AI 会卡住流程并提问：你指的高性能是 TPS > 1000，还是响应时间 < 50ms？

• 智能推荐： AI 不仅仅是提问，还会根据上下文给出推荐。例如：对于用户ID，建议使用 UUID（安全性高）而不是自增主键（易被遍历），你同意吗？

• 回写机制： 一旦你做出选择，系统会自动更新规范文档。这确保了在进入真正的设计阶段之前，所有的不确定性都被消灭在萌芽状态。

4 speckit命令：技术实现

4.1 Plan：从 What 到 How 的桥梁

在 SDD 模式下，严禁边写边想。在敲下第一行业务代码前，必须先生成 plan.md。

• Phase 0 - Research： 解决技术上的未知数。比如调研是选 PDFBox 还是 IText？版权是否允许？性能是否达标？这是一份可行性报告。

• Phase 1 - Design： 产出具体的施工图。Data Model是数据库表结构、字段类型、ER图。Contracts是API 接口定义。这意味着实现了契约优先开发。

4.2 宪章的安检作用

系统会自动检查你的技术方案是否违宪。

• 场景： 你在 Plan 中决定引入 jQuery，但 Constitution 规定必须用 React。

• 结果： 流程被卡断，直接报错。这保证了架构的腐化被拦截在设计阶段，而不是等代码写完了才发现不合规，避免了昂贵的返工。

5 speckit命令：原子化任务

5.1 Tasks：为 AI 准备的饲料

AI（LLM）的上下文窗口和推理能力是有限的。为了让 AI 写出完美的代码，必须将宏大的 Plan 切碎。

• 极细粒度： 这里的任务不是实现登录，而是拆解为1.建User表、2.写DTO、3.写Service接口。

• LLM Friendly： 每个任务必须足够具体，让 LLM 可以在不需要过多上下文的情况下独立完成。

• 依赖编排： 系统自动计算依赖关系。必须先有表，才能有 Repository。同时，对于互不依赖的任务（如前端样式和后端逻辑），标记为 [P] (Parallel) 以支持多 Agent 并行开发。

5.2 Analyze：起飞前的全链路对账

这是投入昂贵算力写代码前的最后一道防线。它进行三方对账：

• Spec vs Plan： 技术方案是否覆盖了所有需求？

• Spec vs Tasks： 是否有需求漏了对应的开发任务？（Coverage Verification）

• Constitution vs All： 是否有任何设计违规？

系统会生成一份带有严重性分级的体检报告。Human-in-the-loop（人在环中）体现在这里：人类指挥官看到全绿灯后，按下执行按钮。

6 speckit命令：自动化构建

6.1 Implement：工业级的软件工厂

一旦进入 Implement 阶段，这就变成了一个全自动化的流水线。

• 无需插手： 机器（AI Agent）严格按照 tasks.md 的指令一步步执行。

• 确定性： 因为前面的 Spec、Plan、Tasks 已经极其严谨，编码变成了纯粹的填空题，不需要人类再去进行复杂的逻辑判断。

6.2 TDD 与自我修正

机器写代码靠谱的秘诀在于 TDD。

• 流程： AI 先写一个必然报错的测试用例 -> 写业务代码 -> 运行测试 -> 通过 -> 下一个任务。

• 自我修正： 只要测试不通过，AI 会自动重试、修改代码，直到测试变绿。

• 结果验收： 当所有任务状态变为Completed，意味着软件不仅写完了，而且通过了所有的单元测试和集成测试。人类只需要直接拎包入住。

7 SDD的缺点

上下文失能：在遗留系统中，AI Agent 因上下文窗口限制与索引能力不足，常基于错误假设生成代码，导致幻觉或重复造轮子，彻底破坏确定性前提。

流程反敏捷：微小热修复（如变量名修正）被迫回溯修改 Spec → Plan → Tasks → 代码，形成往返跑僵局。修复简单 Bug 被要求生成 4 个用户故事+16 条验收标准，用大锤砸坚果式体验严重背离无需插手的自动化承诺。

文档负重与资源黑洞：为生成约 700 行代码需产出近 2,500 行 Markdown，开发者耗时 3.5 小时审查；每次交互注入 constitution/spec/plan 等文档导致 Token 消耗激增。

规范漂移失控：紧急场景下开发者跳过 Spec 直接改代码（现实必然），Spec 瞬间失效；系统缺乏代码→规范的反向同步能力。

遗留系统适配断层：缺乏逆向工程能力，难以将数百万行旧代码逻辑转化为可执行 Spec 与测试用例。

名修正）被迫回溯修改 Spec → Plan → Tasks → 代码，形成往返跑僵局。修复简单 Bug 被要求生成 4 个用户故事+16 条验收标准，用大锤砸坚果式体验严重背离无需插手的自动化承诺。

文档负重与资源黑洞：为生成约 700 行代码需产出近 2,500 行 Markdown，开发者耗时 3.5 小时审查；每次交互注入 constitution/spec/plan 等文档导致 Token 消耗激增。

规范漂移失控：紧急场景下开发者跳过 Spec 直接改代码（现实必然），Spec 瞬间失效；系统缺乏代码→规范的反向同步能力。

遗留系统适配断层：缺乏逆向工程能力，难以将数百万行旧代码逻辑转化为可执行 Spec 与测试用例。

文化与实践冲突：强制文档完备再编码实质是瀑布流 2.0，与敏捷边做边改直觉相悖。