SDD 在各 AI 工具中的落地实践

一句话：在各工具里落地 SDD，关键不是找「哪个工具内置了 SPEC」，而是分清三件事——工具官方内置了什么、你必须自己定义什么、规范放在哪里能让所有工具读到。

说明：产品迭代很快，本文写于 2026-10。内置机制、目录名和配置项以各工具官方文档为准；本文只描述「怎么接」，不把用户自定义的 Skill、个人脚本或第三方插件写成官方能力。

为什么需要

工具宣传最容易制造三种误解：

把用户自定义能力当成内置。 例如某个仓库里的 /spec 工作流、spec-* Agent，可能是本地 Skill 或第三方插件，不是工具自带。
把「能读取某个文件」说成「内置 SDD」。 能读 CLAUDE.md 不等于内置了规范、任务、测试的完整流程。
把某个团队的项目约定当成产品功能。 specs/ 目录、EARS 格式、审核门，都是约定，不是某个工具的专属。

误解的代价是：换版本或换工具后流程失效，团队却以为是「工具不支持 SDD」。

核心机制

三层区分

层	定义	例子	谁负责
内置	官方提供、开箱即用	规则文件、hooks、plan mode	工具厂商
可配置	官方提供扩展点，内容由你写	自定义命令、Skill、workflow	你的团队
约定	工具不认，但人和 Agent 都遵守	`specs/` 目录、验收标准格式	你的团队

SDD 的稳定性来自第三层。 第一、二层只负责让 Agent 读到约定；约定本身必须与工具解耦，否则换工具就要重写。

各工具能力盘点

工具	官方内置（写作时）	需要你定义	规范怎么接
Claude Code	`CLAUDE.md`、hooks、subagents、Skills、自定义 slash commands、MCP	规范模板、阶段命令、审核门	`CLAUDE.md` 指向 `specs/`；hook 在写入前检查
Cursor	`.cursor/rules/*.mdc`、`.cursor/commands/`、Plan mode、Agent mode	规范模板、命令内容	rule 写明「先读 `specs/`，确认后再改代码」
GitHub Copilot	`.github/copilot-instructions.md`、prompt files、coding agent、code review	规范模板、prompt	instructions 指向 `specs/`
Windsurf	rules、workflows、Cascade	规范模板、workflow 步骤	rule/workflow 中加入 spec 阶段
Aider	`CONVENTIONS.md`、`--read`、`--architect`、自动 lint/test	规范模板、启动参数	启动时 `--read specs/<feature>/spec.md`
Cline	Plan/Act 模式、`.clinerules`、MCP、逐步审批	规范模板、规则	rules 指向 `specs/`，审批卡住实现

三个必须说清的点：

Claude Code 的 /spec 不是官方内置命令。 本仓库里的 spec-* Agent 属于本地配置；Superpowers 是第三方开源插件。两者都要在文档里注明来源。
GitHub Spec Kit 是独立开源工具包，不是 Copilot 内置。 它通过 CLI 生成命令，让 Agent 执行。
Windsurf 早期用 .windsurfrules，新版本改为 .windsurf/rules/ 目录；以官方文档为准。

通用落地结构

text

repo/
├── specs/<feature>/spec.md          # 唯一权威，进 git
├── AGENTS.md                        # 通用约束；支持的工具会自动读
├── CLAUDE.md                        # Claude Code
├── .cursor/rules/sdd.mdc            # Cursor
├── .github/copilot-instructions.md  # Copilot
├── .windsurf/rules/sdd.md           # Windsurf
├── CONVENTIONS.md                   # Aider
└── .clinerules/sdd.md               # Cline

每个工具文件只放指针和硬约束，不要复制规范正文：

markdown

## SDD 规则
1. 改代码前先读 specs/<feature>/spec.md；没有 spec 先补。
2. 未确认 spec 前不要修改业务代码。
3. 验收标准必须可执行；实现后逐条对照。

复制正文会导致六个地方不一致；指针只有一个来源。

最小上手

建 specs/login/spec.md，写目标、范围、约束、验收四块。
在每个工具的规则文件里加同样三条指针（参见上节）。
给一个需求，观察 Agent 是否先读 spec、是否在写代码前复述理解。
加一个 warning 模式的 pre-commit，验证「只改代码不改规范」时能提示。

#!/bin/sh
# .githooks/pre-commit —— 先 warning，不阻塞
changed=$(git diff --cached --name-only)
code=$(printf '%s\n' "$changed" | grep -E '^(src|app)/' || true)
spec=$(printf '%s\n' "$changed" | grep -E '^specs/' || true)
if [ -n "$code" ] && [ -z "$spec" ]; then
  echo "WARN: source changed without specs/ change" >&2
fi
exit 0

启用：

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

跑通的标志：改一个 src/ 文件并提交，能看到警告；同时改 specs/ 后警告消失。

生产动作

规则文件只放指针和硬约束，规范正文只放 specs/。 同一规则不要抄六份。
Hook 先 warning 后 blocking。 直接阻塞容易被 --no-verify 绕过，也会引起团队反弹；先让误报可见，再收紧。
工具升级后重跑盘点。 内置机制可能改名或迁移，旧配置会静默失效。
多工具团队指定唯一权威目录。 其他工具的配置只做引用；冲突时以仓库规范为准。
让「是否读了 spec」可观察。 要求 Agent 在回复里引用 spec 路径和验收条目，而不是只说「已按规范实现」。
不在工具配置里写业务规则。 业务规则属于规范；工具配置只回答「怎么读、何时读」。

边界

不要把本地 Skill、个人脚本、第三方插件写成官方能力。 文档中注明来源、维护者和版本。
不同工具对同一文件的读取优先级不同。 冲突时以仓库权威规范为准，工具配置让位。
内置 Plan mode 不等于 SDD。 它只做计划，不保证验收标准、测试和规范落盘。
规则文件写太多会被忽略。 超过一屏的规则，Agent 的遵循度会下降（经验判断，非实测）。
Hooks 是提醒，不是强制。 有 --no-verify、有直接改文件、有 CI 之外的路径；真正的门在 CI 和 Review。

讲清楚

在各工具里落地 SDD，关键不是找内置功能，而是分层：工具内置的规则、hooks、plan mode 只负责让 Agent 读到约束；真正的规范放在仓库的 specs/ 里，作为唯一权威；各工具的配置文件只做薄指针。Claude Code 的 /spec、Superpowers 都不是官方内置，前者可能是本地 Skill，后者是第三方插件，写文档时必须区分。跨工具复用的做法是规范与工具解耦：换工具只改指针文件，不改规范。最后用 hook 或 CI 做一致性提醒，先从 warning 模式开始。

初稿 2026-07 | 最后修订 2026-10 | 事实核查：移除未核实的内置能力与付费信息；区分内置/自定义/约定

SDD 在各 AI 工具中的落地实践 ​

为什么需要 ​

核心机制 ​

三层区分 ​

各工具能力盘点 ​

通用落地结构 ​

最小上手 ​

生产动作 ​

边界 ​

讲清楚 ​