Spec-kit 开发流程

制定宪法

包含：

1. 技术栈（如 React+TS）、代码风格（如类名必须用小驼峰）、设计原则（如必须支持多语言）；

2. 业务原则、架构约束、名词解释等；

需求规格化

1. 创建分支，例如分支名为：001-user-management

2. 执行 /speckit.specify <用户管理相关需求>，/speckit-specify 命令会自动在 specs 目录下创建以分支命名的规格目录

specs/  
├── 001-user-management/  
│   ├── spec.md          # 用户注册、登录、个人信息  
│   ├── plan.md  
│   └── tasks.md  
├── 002-role-management/  
│   ├── spec.md          # 角色定义、分配  
│   ├── plan.md  
│   └── tasks.md  
└── 003-permission-system/  
    ├── spec.md          # 权限控制、访问管理  
    ├── plan.md  
    └── tasks.md

3. 编写和完善规格（这是主要工作的地方）

具体见官方规格模板：https://github.com/github/spec-kit/blob/main/templates/spec-template.md

一致性分析与精确执行

/speckit.analyze 是只读操作，不会修改任何文件；(spec是驱动开发的真实源、是人与AI交互的入口，因此必须是人类深思熟虑后的内容)

/speckit.analyze 会分析当前 feature 的三个核心文件（spec.md、plan.md、tasks.md），来验证一致性、术语漂移、冲突需求等问题。

当新开发功能或需求调整时，始终遵循的是：更新spec -> plan -> tasks -> analayze(验证一致性) -> implement实施；

在执行 spec -> plan -> tasks 时，spec-kit 会自动判断任务是否已执行，从而避免 tasks 中的任务被重复执行。但如果 spec 改动比较大，例如基础架构或核心数据模型被改，则可能需要手动重置任务状态；tasks 中的任务通常包含以下信息：

Checkbox: 必须以 - [ ] 开始，表示此任务是否已执行；
Task ID: 连续编号（T001, T002, T003...）
[P] 标记: 仅在任务可并行时包含
[Story] 标签: 必须映射到 spec.md 中的用户故事
描述: 必须包含确切的文件路径

当发现 BUG 时，应该先判断是否 spec 需求不完整；如果需求完整，是实现层面的 BUG ，则写测试再验证并完成功能，而非直接以聊天对话的方式让 AI 修复BUG。

新增功能：/speckit.specify <需求内容> 此命令始终自动创建新分支、新目录和新的spec，因此更新需求时不要执行此命令；

更新需求：/speckit.clarify <需求内容> 此命令更新需求后，可能还会列出其它澄清项，可以选择性忽略；

更新宪法：/speckit.constitution <宪法内容>

修改BUG：/speckit.implement <修复 [具体文件] 中的 [具体 BUG 描述]>

质量验证：/speckit.verify 此命令识别代码中可能存在的“幻觉”或遗漏，检查代码是否满足了 specs/ 目录中定义的所有业务功能和技术约束

注：修BUG时，尽量使用 /speckit.implement 命令；因为此命令会强制读取宪法、spec.md、plan.md、tasks.md 等文件，从而更全面的了解整体业务和逻辑，并优先遵守文档中的定义，防止修复了 A 却破坏了 B（符合规范）,最终还会在 tasks.md 中生成BUG修改记录。如果不使用 /speckit.implement 命令修改BUG，AI 就只能看当前代码和报错信息，修改BUG时，就极易可能违反 spec.md 设计的方案。

但如果 BUG 只是低级语法错误或类型报错，也可以直接用聊天对话的方式修改，因为它并不会影响其它地方；使用 /speckit.implement 命令时加载了太多东西，不仅费token，也很耗时。

注：/speckit.specify 是创建新的 spec，因此更新需求时不要执行此命令；/speckit.specify 命令会检查当前分支下有没有对应的 spec.md ，如果没有就会在当前分支下创建分支对应的目录及 spec.md；否则就会直接创建新分支，并自动切换到新分支，然后在新分支中创建分支对应的目录及 spec.md；（新分支是基于当前分支创建）

/speckit.specify 默认是依据规格自动命令分支名称，可执行 git branch -m <旧名称> <新名称> 命令为分支重命名；

spec-kit 常用命令都所加载的文件：

@speckit.plan：加载宪法 + spec.md。它需要根据需求和全局规则来制定技术路线。

@speckit.tasks：加载宪法 + spec.md + plan.md。它必须确保拆解的任务既符合需求，又遵循计划。

@speckit.implement：加载全部（宪法 + spec.md + plan.md + tasks.md + 当前代码）。

@speckit.clarify：主要加载 spec.md

强关联业务处理

要在 spec.md 中声明关联业务，要在 plan 中声明关联的外部接口；重新生成 plan.md 时，外部接口不会重置；

总之，spec-kit的理念：显式优于隐式：确保可追踪和可维护；例如，在 spec.md 中声明前置条件或外部依赖，如下：

写法：明确指出“该功能需调用 UserModule 的 getUserInfo 接口获取数据”。
目的：让 AI 在理解需求阶段就意识到这不是一个孤立的功能

实践经验

将“澄清记录”合入“功能定义”：避免 AI 不停地在琐碎的问题记录中“寻找”规则，导致核心业务逻辑的注意力被稀释；

增加“核心流程伪代码”或“状态图”：增加实现的可控性和可靠性；要描述清楚前后端、各模块之间如何传参，以及数据结构等；

在 spec 中直接给出关键的数据库模型或接口定义。

功能分块实施：分步实施可降低实现难度；以极高的上下文纯度提高实现的可靠性，从而实现故障隔离与快速验证、降低“幻觉”概率；

单体全量实施 vs 分模块实施：

单体全量实施时，初期极快，但后期会陷入 Debug 泥潭。分模块实现：稳扎稳打，后期整合快，单元质量高，结构清晰；AI 压力极小（因为专注度高）；

一般建议按功能分步实施。如果分步实施太粗（例如按子系统实施），会导致 AI 会因为逻辑过于复杂而产生幻觉。如果分步实施太细（例如按函数或类实施），会导致程序员沦为“伪代码翻译员”，写 Spec 的时间比自己写代码还长。

分步实施时，AI 不需要知道项目整体业务，让 AI 知道项目整体业务本身也不现实（会导致注意力分散、能力下降）。分布实施时，AI 只需要了解每个功能，且多个功能完成可以并发执行。

SDD 开发时，强烈建议采用前后端分离。契约化 AI 的指南针，后端 AI 负责实现契约，前端 AI 负责调用契约；

前后端分离开发时，两者互不干扰，并行效率更高；同时可降低上下文复杂度；

前后端分离的最佳实践：先写一个定义 API 结构的 spec，生成一份符合 OpenAPI 3.0 标准的 YAML 文件，将 openapi.yaml 导入 Swagger UI 或 Postman，即可直接阅读和调试。甚至前端可以直接根据这个 YAML 生成 Mock 数据和 Typscript 类型，在后端接口没有提供的情况下完成功能开发。

SDD 开发并非所有代码都是 AI 来写；当发生“幻觉”死循环、复杂业务逻辑等 AI 无法解决的问题时，仍然需要人工写代码来补足。

推荐在已有的代码框架上进行开发，让 AI 搭建代码是一个非常繁琐的事情，因为代码框架本身的细节非常多。

注：如果代码已存在，则重新执行 /spec.implement 时，代码会增量更新修复，可能并不会重新生成代码。

注：在需求不确定的情况下，SDD 要求的前置思考时间变成了“无效成本”。

注：

目前公认最高效的开发方式是灰盒开发”（也叫人机协作/Copilot模式）。

而黑盒开发仅适合Demo级项目开发，因为 AI 黑盒开发存在幻觉积累、架构崩塌等问题；如果人不干预，AI 往往会选择最简单的路径；细微的逻辑错误会随着代码量增加而指数级累积，最终导致系统“不可调试”

生成UI图

产品经理给出原型图，再由 AI 根据原型图渲染出UI图，AI 通过 MCP 引用 UI 图，并按 UI 图生成软件界面，这是最佳实践。千万不要让 AI 根据需求来“盲猜”生成原型或UI图；但 AI 可辅助生成原型或中低保真的原型/UI图，以供参考。

生成项目

我准备使用 spec-kit + claude code + glm-4.7 管理项目需求、计划等，然后将打磨好的需求给 Galileo AI、v0.dev、Figma AI (Figma Make) 、Google Labs Stitch、Uizard (Autodesigner) 这类UI生成工具进行打磨，UI 打磨好以后，让 spec-kit + claude code + glm-4.7 项目通过 MCP 依照 UI 生成软件。这是最佳实践吗？有什么更好的方式？

最佳实现

everything-claude-code (ECC) 与 spec-kit 是 AI 驱动开发中的“黄金搭档”。规范驱动的 spec-kit 通过 spec.md、plan.md、tasks.md 等文件维护“真理源”文档，ECC 自动读取这些文档，并调用内置的各种 Agent（如架构师、测试员）去精准执行这些计划。

spec-kit 是通用的：它本质上是文档驱动，无论用 Cursor、Windsurf 、VS Code + Copilot 等，只要能读取 spec.md 和 plan.md，这套工作流就依然有效。

everything-claude-code (ECC) 是深度绑定在 Claude Code (命令行工具) 之上的插件系统；它利用了 Claude Code 特有的 MCP 接口、内部插件加载机制以及特定的 .claude/rules/ 架构；如果更换 AI 客户端工具，ECC中的指令集和专家 Agent 调度将失效，但其 System Prompts (系统提示词) 和 Rules 文件可以通用，也非常值得参考。

Agent 调度失效原因：ECC 后台自动切换“架构师”、“安全专家”等角色的逻辑是基于 Claude Code 的运行环境编写的，Cursor 等工具并没有开放这种深度的脚本控制权限。