AI 原生软件开发工作流程
实践落地版

0SDD 是什么：一次权力倒置§

过去 30 年，代码是真理，规格是脚手架——写完就扔。SDD（Spec-Driven Development）把关系倒过来：规格是唯一真理源，代码是规格的表达式。维护软件 = 演进规格；调试 = 修复生成错误代码的规格；重构 = 为清晰度重组计划。

1环境初始化：10 分钟跑通§

前置条件：安装 uv。一条命令装 CLI，一条命令初始化项目，从此该项目的 AI 编码智能体就拥有了完整的 SDD 斜杠命令。

# 1. 安装 Specify CLI（用具体 release tag，保留前缀 v）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
# 或直接从 PyPI：uv tool install specify-cli

# 2. 初始化项目（--integration 选择你的 AI 编码智能体）
specify init my-project --integration copilot
cd my-project

# CI / 无键盘环境：加 --non-interactive，非空目录再加 --force
specify init --here --force --non-interactive --integration claude

# CLI 自管理
specify self check          # 只检查，不改任何东西
specify self upgrade --dry-run  # 预览升级动作
specify self upgrade        # 原地升级（自动识别 uv tool / pipx）

2项目宪法：一次性奠基，全程受约束§

每个项目只做一次：/speckit.constitution 生成项目级治理原则（存于 .specify/memory/constitution.md）。它像「架构 DNA」——此后每份实现计划都要通过宪法门禁（Phase -1 Gates），不通过就必须在「Complexity Tracking」里书面解释为什么。

# 一次性建立项目原则（可随时修订，但需走修订流程）
/speckit.constitution 创建聚焦代码质量、测试标准、用户体验一致性与性能要求的项目原则

3七步核心工作流：从一句话到可交付§

这是每天都会走的主干道。前四步产物全部落在 specs/<branch>/ 目录并在功能分支上版本化；implement ⇄ converge 循环直到收敛报告输出 Converged。

# ① 一次性
/speckit.constitution 项目原则：代码质量、测试标准、UX 一致性、性能

# ② 每个功能的标准节拍
/speckit.specify 构建一个照片相册应用：相册按日期分组、主页拖拽重排、
                 相册不嵌套、相册内照片以磁贴网格预览
/speckit.clarify
/speckit.plan 使用 Vite + 原生 HTML/CSS/JS，尽量少依赖库；
              照片不上传服务器，元数据存本地 SQLite
/speckit.tasks
/speckit.analyze
/speckit.implement
/speckit.converge      # 循环直至 Converged

4工件地图：specs/ 目录里到底有什么§

SDD 的全部智慧都物化在 specs/<branch>/ 里。读懂这张地图，你就能 review 别人的规格，也能诊断自己的流程卡在哪一步。

specs/003-chat-system/
├── spec.md            # 功能规格：用户故事、验收标准、[NEEDS CLARIFICATION]
├── plan.md            # 实现计划：技术决策 + 理由 + Phase -1 宪法门禁
├── research.md        # 选型调研：库对比、性能基准、安全影响
├── data-model.md      # 数据模型：实体、关系、schema
├── contracts/         # API 契约：WebSocket 事件、REST 端点（实现前先定）
├── quickstart.md      # 关键验证场景：跑通这些 = 功能成立
├── tasks.md           # 任务清单：[P] 并行标记 + 执行顺序
└── implementation-details/  # 从 plan 下沉的代码细节，保持计划可读

5质量护栏：模板如何驯服 LLM§

Spec Kit 的秘密不在命令本身，而在模板——每份模板都是一份精心设计的 prompt，用结构性约束把 LLM 从「有创意的作者」变成「有纪律的规格工程师」。理解这七道护栏，你就能举一反三地写自己的模板。

用 /speckit.checklist 生成自定义质量清单

内置清单之外，可以按领域生成专属检查表——作者称之为「给英文写的单元测试」：规格本身也是代码，也需要测试。

# 例：为安全敏感功能生成安全规格清单
/speckit.checklist 生成覆盖认证、授权、数据脱敏与审计日志的规格质量清单

6两条分支工作流：Bug 修复 与 想法评估§

主干流程之外，官方捆绑的两个可选扩展覆盖最高频的日常场景。均为 opt-in，specify extension add 后即装。

🐞 Bug 扩展：assess → fix → test

防的是「智能体从报错直接跳到补丁」：没有验证诊断、没确认修复了原始症状。bug 扩展让每次修复范围受控、基于证据、从根因到验证全程留痕。

# 一次性安装
specify extension add bug

# 三步修复一个 bug
/speckit-bug-assess "用户登录时崩溃" slug=login-crash   # 评估：定位根因
/speckit-bug-fix slug=login-crash                       # 修复：针对已评估的根因
/speckit-bug-test slug=login-crash                      # 测试：确认症状消失

💡 Assess 扩展：intake → research → define → shape → decide

好想法值得先拿证据再承诺——无论最后做不做软件。assess 扩展把一个原始想法变成有据可查的 go / needs-clarification / kill 决策。

# 一次性安装
specify extension add assess

# 五步评估一个想法
/speckit-assess-intake "离线模式" slug=offline-mode       # ① 立项登记
/speckit-assess-research slug=offline-mode               # ② 收集支持/反对证据
/speckit-assess-define slug=offline-mode                 # ③ 定义问题、目标、成功指标
/speckit-assess-shape slug=offline-mode                  # ④ 塑形候选方案与权衡
/speckit-assess-decide slug=offline-mode                 # ⑤ 裁决：做 / 澄清 / 砍掉

7团队协作落地：规格进 Git，评审进 PR§

SDD 天然支持团队流程：规格是可版本化、可分支、可合并的工件——产品经理改验收标准，实现计划自动标记受影响的技术决策；架构师发现更优模式，PRD 反向更新。

8定制体系：把 Spec Kit 变成你的流程§

四层优先级栈，运行时自顶向下解析，取第一个命中的模板——这意味着你可以不动核心、不建分支地定制任何环节。

9每日落地清单§

把流程刻进肌肉记忆。可打印贴在工位，也可作为团队 code review 的前置自查。

🚀 新项目上线前（一次性）

• uv + specify CLI 安装完成，specify self check 无更新提示
• specify init 完成，斜杠命令在智能体里可用
• /speckit.constitution 已建立，条款覆盖质量/测试/性能/安全
• 按需安装扩展（bug / assess）与团队预设

🔁 每个功能的标准节拍

• spec 只写 what/why，技术词零出现；歧义全部 [NEEDS CLARIFICATION]
• clarify 跑完，标记清零
• plan 过宪法门禁；豁免项在 Complexity Tracking 有记录
• tasks 测试任务先于实现任务；[P] 并行分组合理
• analyze 无阻断项
• implement 严格按任务序执行，先红后绿
• converge 报告 Converged 后才发起 PR

📅 每周团队例会

• 抽查一份 spec：能否独立读懂？验收标准可测吗？
• 复盘 converge 循环次数异常多的功能——是规格质量问题还是计划质量问题？
• 生产事故/指标是否回流为新的规格约束（双向反馈）？
• 宪法是否有需要走修订流程的演进项？

10常见陷阱与对策§