Spec-Driven Development 实战：让 Claude、Cursor 和 Copilot 共用一份代码规范

你用 Claude Code 写了一个功能。一小时后它输出了一堆看起来不错但不完全是你想要的东西。你让 Cursor 来修复，它和 Claude 做的矛盾了。你叫 Copilot 做清理，它凭空创造了第三种解释。

这个问题正在折磨每个深度使用 AI 编码工具的团队：AI Agent 没有统一的真相来源（source of truth）。每个工具在缺少明确规范时，都会用自己的假设填补空白。

Spec-Driven Development（SDD）解决的就是这个问题——在写任何代码之前，先创建一份共享的规范文件，让所有 AI 工具都基于同样的蓝图工作。

三步工作流

SDD 不是一个复杂的框架，而是一个简单的流程：

第一步：生成规范。与 Claude 对话式沟通 4 个问题（逐一提问），系统自动生成三个文件：

your-project/
├── requirements.md    ← 系统必须做什么
├── design.md          ← 如何实现
├── tasks.md           ← 按顺序实现的任务清单
└── CLAUDE.md          ← Claude Code 自动读取的上下文

第二步：AI 按规范实现。每个 AI 工具（Claude Code、Cursor、Copilot）在读取 spec 文件后才开始编码，确保不产生矛盾。

第三步：验证一致性。任务完成后，对照 requirements.md 逐条验证——每一条需求都 traceable。

requirements.md 的写法

这是 SDD 的核心文件。每一条需求都有独立编号、shall 语句和验收标准：

## 功能性需求

- **REQ-001**: 用户应能针对客户项目记录工时条目。
  - _验收_: POST /entries 返回 201，包含 entry_id、duration 和 project_id
- **REQ-002**: 用户应能从已记录的工时生成月度发票。
  - _验收_: GET /invoices/:month 返回 PDF，明细项之和等于总金额
- **REQ-003**: 系统应防止同一时段重复记录。
  - _验收_: 同一 user_id + project_id + date 的第二条 POST /entries 返回 409

## 非功能性需求

- **REQ-101**: 页面加载时间应小于 2 秒（Lighthouse Mobile）。
- **REQ-102**: 系统应在 99.9% 的时间内可用。

关键原则：每条需求都是可测试的。验收标准（Acceptance）不是一个模糊的描述，而是一个具体的 API 行为或界面状态。这样 AI 生成代码时就知道什么时候算”做完了”。

design.md 的架构级指导

design.md 不是需求列表的重复，而是架构决策的记录。这里写：

## 技术栈

- 后端：Go 1.24 + Chi Router
- 数据库：PostgreSQL 16 + pgx v5
- 认证：JWT (HS256)，token 有效期 24h

## 数据模型

- `users (id, email, name, created_at)`
- `projects (id, name, client_id, hourly_rate)`
- `entries (id, user_id, project_id, duration_minutes, date, description)`

## 关键决策记录

- ADR-001：不使用 ORM，使用 pgx 原生 SQL — 保持对查询的完全控制
- ADR-002：工时精确到分钟而非秒 — 减少 UI 复杂性，满足业务需求即可

这份文件的读者是人类的你和AI Agent。写清楚为什么选某个方案，比只写方案本身更重要——因为 AI Agent 需要理解上下文才能做后续决策。

tasks.md 的任务分解

tasks.md 将需求分解为可按顺序执行的独立任务，每条链接回对应的需求：

- [ ] **TASK-001** [REQ-001]: 创建 users 和 projects 表迁移脚本
  - _输出_: `migrations/001_create_users_projects.sql`
  - _验证_: `migrate -path migrations up` 执行成功

- [ ] **TASK-002** [REQ-001]: 实现 POST /entries 端点
  - _输出_: routes handler + duration schema 验证
  - _验证_: POST /entries 返回 201，含所有必填字段

- [ ] **TASK-003** [REQ-001: 添加并发的工时验证
  - _输出_: 数据库唯一约束 + 应用层冲突检测
  - _验证_: 重复 POST 返回 409

- [ ] **TASK-004** [REQ-002]: 实现 GET /invoices/:month 端点
  - _输出_: PDF 生成 + 条目汇总
  - _验证_: GET /invoices/2026-06 返回有效 PDF

任务的粒度很重要：每个任务应在单个会话中完成。如果某个任务需要超过 30 分钟的 AI 编码时间，就拆分成更小的子任务。这样即使会话中断，你也知道从哪里继续。

实战：多个 AI 工具共用规范

SDD 最实用的场景是同一项目多个 AI 工具协同。团队里有人用 Cursor、有人用 Claude Code、有人用 VS Code Copilot——SDD 通过三件事确保一致性：

1. 规范文件作为唯一真相来源。所有工具在编码前读取 requirements.md 和 design.md，而不是各自的 prompt 历史。

2. 按任务分派。在 tasks.md 里用 [assigned-to: cursor] 标记分派：

- [ ] TASK-002 [assigned-to: cursor] 实现 POST /entries
- [ ] TASK-003 [assigned-to: claude-code] 添加并发验证

3. CLAUDE.md 自动引导。SDD 的安装过程会生成 CLAUDE.md 文件，Claude Code 启动时自动读取。这意味着每次打开新会话时，AI 都知道”先读 requirements.md，读完再写代码”。

什么时候不适合 SDD？

SDD 不是万能的。以下场景不建议使用：

• 原型验证：快速试错的阶段，写规范的成本高于收益
• 一次性脚本：用完即弃的代码不需要持久化规范
• 纯展示页：没有复杂业务逻辑的页面改版，规范和直接改代码耗时差不多
• 单人小项目：如果你只有一个 Agent、一个文件、做完就部署，SDD 过度工程了

总结

SDD 把 AI 编码从”猜你想要的”变成了”按规范交付”——不是通过更长的 prompt，而是通过结构化的、可追溯的、多工具共享的规范文件。

GitHub: github.com/FredAntB/Spec-Driven-Development（MIT 协议） 安装：claude plugin install FredAntB/spec-driven-development 或克隆仓库，在 Code Tab 中打开即可自动激活