01-为什么AI写代码总跑偏

SDD 规范驱动开发实操手册 · 第 1 篇 / 共 8 篇

全系列按「说明 → 介绍 → 使用 → 实操 → 排障 → 收益」推进，每篇都可独立阅读，收藏专栏后按序看不会断。

这一篇说明手册解决什么问题、四类读者各自该读到哪，并给出一条「只有 30 分钟」也能走完的最小闭环。如果你现在就想在项目里试一次，直接跳到 1.6 节。

第一章 说明：这本手册怎么用

1.1 这本手册要解决的具体问题

先说结论：大多数人听说 SDD（Spec-Driven Development，规范驱动开发）之后，卡住的不是"不懂概念"，而是三个非常具体的问题——

第一，不知道第一个文件该写什么。看了一堆"规范即真源"的宣言，打开编辑器，光标在空白文件里闪了十分钟，最后还是回去跟 AI 聊天了。

第二，不知道写多细才算够。写少了 AI 自由发挥，写多了变成八股文，团队三天就放弃。

第三，不知道怎么塞进现有流程。需求在 Jira、设计在 Confluence、代码在 GitLab、评审在 PR 里，SDD 好像要在旁边再开一套体系，谁来维护？

这本手册就是按这三个问题组织的。全书有一条主线：一个真实需求，从一句话变成上线代码，中间每一步都留下可复制的文件、命令和判断标准。 读完第四章，你手上会有一份能直接搬进自己项目的完整素材。

1.2 谁该读，读到什么程度

1.3 三条阅读路径

路径 A｜30 分钟决策（管理者）：1.4 → 2.1-2.4 → 2.8 → 6.2-6.4 → 6.6。目的是判断"我们团队要不要上、上多重的版本"。

路径 B｜3 小时跟练（开发者）：1.6 → 第三章全部 → 第四章 Step 0-8。跟着敲一遍，你会得到一个跑通的示例功能。

路径 C｜两周落地（推动者）：第三章 → 第五章全部 → 6.6 的 30/60/90 天路线图。按图施工，两周内团队能形成习惯。

1.4 全书约定

• 工具基线：GitHub Spec Kit（CLI 名为 specify）、Amazon Kiro、OpenSpec 三类主流实现。三者理念一致、产物都是纯 Markdown，命令有差异。书中以 Spec Kit 为主线演示，关键处标注 Kiro / OpenSpec 的对应做法。
• 两条命令通道，先分清再动手：全书只有两类命令，运行位置完全不同，混用一定报错。
  • 终端命令（代码块里以 $ 开头的那行）：在项目根目录打开终端执行。Windows 用 PowerShell（在开始菜单搜 "PowerShell"，普通权限即可，不需要管理员），不要用 CMD——|| 在 CMD 里不可用、curl 是系统自带的另一个程序，行为完全不同；macOS / Linux 用 Terminal。凡安装类命令 Windows 与 macOS 写法不同，书中分两套给出。
  • 斜杠命令（/speckit.specify 这类）：在 AI 编程助手的对话窗口里输入，不是在终端里敲，也不写进任何代码文件。助手必须在项目根目录启动（cd 到项目后再启动），否则它读不到 .specify/ 目录，斜杠命令会提示不存在。
  • $ 是提示符、# 是注释，复制时都不要带上。
  • 判断标准一句话：要你按回车的、在终端；要 AI 干的、在对话框。
• 版本提醒：SDD 工具迭代很快，斜杠命令的命名空间和 init 参数在不同版本间改过（--ai 与 --integration 都出现过）。凡命令报错，先跑 specify --help / specify init --help / specify integration list，以你本地实际安装的版本为准。 这不是手册的问题，是这个领域当下的常态。
• 示例项目：一个 6 人团队的电商后台，Spring Boot 3.2 + MySQL 8.0 + Redis 7 + Vue 3，需求是"优惠券领取与核销"。选它的原因是：业务人人能懂，边界条件足够多（库存、限领、叠加、并发、过期、退款回滚），最能暴露"不写规范会漏什么"。
• 代码片段：只保留说明问题的最小片段，标注文件路径；完整模板在附录 A。

1.5 一个必须先接受的判断

SDD 不是"写更多文档"。它是把决策从聊天记录里搬到仓库里。

区别在于：文档是给人看的旁证，规范是给人和 AI 共同执行的输入。判断你写的东西是文档还是规范，只有一个标准——它能不能被验证成"是/否"。"系统应尽量快速响应"是文档；"当库存大于 0 时，系统应在 300 毫秒内返回券码"是规范。后者可以写测试，前者只能吵架。

1.6 如果只有 30 分钟：最小闭环五步

不想读完整本手册，就做这五步。任何项目、任何语言都能跑。

先明确在哪儿敲。 第 0～2 步是终端命令，不是在你平时写代码的编辑器里敲，也不是在 AI 对话框里敲：

• Windows：开始菜单搜 PowerShell，打开蓝色窗口，粘贴命令后回车。不要用 CMD（curl 是另一个程序、|| 不可用，会直接报错）。
• macOS：打开「终端」（Terminal，按 Command+空格 搜 terminal）。
• Linux：任意终端模拟器均可。

下面的命令逐行复制、逐行回车；# 开头是注释，不用输进去（本书后面有些代码块用 $ 表示提示符，同样不要复制）。按你的系统选一块：

▍Windows（PowerShell）

# 第 0 步：确认环境（Python 3.11+ / Git）
python --version
git --version

# uv 是包管理器；已装会打印版本号，报"无法识别"再执行下面这行
uv --version
irm https://astral.sh/uv/install.ps1 | iex

# 第 1 步：重新打开PowerShell，安装 SDD 命令行工具（全局装一次，之后所有项目通用）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 第 2 步：进入你的项目根目录，再就地初始化（--here = 不动现有目录结构）
cd C:\path\to\your-project
specify init --here

▍macOS / Linux（Terminal）

# 第 0 步：确认环境（Python 3.11+ / Git）
python3 --version
git --version

# uv 未安装时执行下面这行
uv --version
curl -LsSf https://astral.sh/uv/install.sh | sh

# 第 1 步：安装 SDD 命令行工具（全局装一次）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 第 2 步：进入你的项目根目录，再就地初始化
cd /path/to/your-project
specify init --here

装完先验证再往下走：specify --version 能打印版本号，才说明第 1 步成功。若提示 command not found，多半是 PATH 没刷新——把终端窗口关掉重开一次再试。

初始化完成后，项目里会多出 .specify/（模板、脚本、宪法）和 specs/（每个功能一个目录）。接下来换成 AI 编程助手的对话窗口（不是在终端里敲），确认它已在项目根目录启动，按顺序输入五条：

/speckit.constitution 建立本项目的基本法：代码质量标准、测试要求、错误处理约定、性能底线

/speckit.specify 我要给订单列表加"按交付日期筛选"。用户可以选择起止日期，
只填一端时按开区间处理，清空则恢复全量。筛选状态要能分享给同事（URL 带参数）。

/speckit.plan 后端 Spring Boot 3.2，前端 Vue 3，日期参数用 ISO-8601，走现有 /api/orders 接口增加查询参数

/speckit.tasks

/speckit.implement

验收标准：specs/ 下出现一个以功能命名的目录，里面有 spec.md、plan.md、tasks.md。打开 spec.md，如果你能指着某一条说"这条可以写成一个测试"，最小闭环就成了。

⚠️ 注意：如果 specify init 报参数错误，去掉 --here 看帮助，或改用 specify init my-project 新建目录。参数在不同版本间变过，以 --help 为准。

下一篇：SDD 到底是什么？它和瀑布、敏捷、TDD 的差别在哪，为什么「写清楚需求」这句话在 AI 时代突然变得可执行。

系列目录见专栏。如果这篇对你有用，点个赞让更多被 AI 写崩过项目的人看到