Spec-Driven Development：用 Claude Skill 实现 AI 编码的多工具规约管理

当团队使用多个 AI 编码工具时（Claude Code、Cursor、Copilot、Windsurf），一个常见的问题开始浮现：你让 Claude Code 构建了一个功能，一小时后它做出了一个技术上令人印象深刻但不太符合预期的东西。你让 Cursor 去修复它，结果 Cursor 推翻了 Claude Code 的做法。你再让 Copilot 清理，它创造了第三种解释。

根因始终是同一个：AI Agent 之间没有共享的事实来源。每个工具都用自己的假设填补空白，导致输出互相矛盾。

FredAntB/Spec-Driven-Development 是一个 Claude Skill，通过在编写代码之前生成三个规约文件（requirements.md、design.md、tasks.md）来解决这个问题，并为所有主流 AI 编码工具生成匹配的配置文件。

核心问题：AI 工具的”各自为政”

AI 编码工具的普及带来了新的协作难题。每个工具都有自己的上下文窗口和假设空间，当它们处理同一个项目时，缺乏统一的规约基础会导致：

SDD（Spec-Driven Development）的核心思想是：在 AI Agent 接触代码之前，先建立一份所有工具都同意且必须遵守的规约。

安装 SDD Skill

这个 Skill 通过三种方式安装，覆盖不同的使用场景：

Claude.ai / Claude 桌面应用（Chat 标签）：

从 releases 页面 下载 spec-driven-development-v1.0.skill 文件，然后在 Claude 设置 → Skills → Install from file 中导入。

或者通过 CLI 安装：

claude plugin install FredAntB/spec-driven-development

Claude Code（Code 标签）：

git clone https://github.com/FredAntB/Spec-Driven-Development

在 Code 标签中打开项目文件夹，自动读取 CLAUDE.md 文件，在会话启动时引导 Skill。

安装完成后，可以用以下短语启动：

• “I want to start a new project”
• “my AI keeps going off script, help”
• “I already have a codebase, no specs yet”
• “set up cursor and claude code for my team project”

三大规约文件

Skill 会在对话中通过 4 个简短问题了解你的需求，然后生成三个文件：

your-project/
├── requirements.md      ← 系统必须做什么
├── design.md            ← 系统如何构建
├── tasks.md             ← 按顺序的实施步骤
└── CLAUDE.md            ← Claude Code 自动读取

requirements.md — 需求规约

每个需求使用 shall 语言和 REQ-xxx ID，确保可追溯性和可测试性：

## Functional Requirements

### Tasks
- **REQ-001**: Users shall create tasks with a title, description,
  due date, and assignee.
  - _Acceptance_: POST /tasks returns 201 with the created task object

- **REQ-002**: Users shall update only tasks they created or are
  assigned to.
  - _Acceptance_: PATCH /tasks/:id returns 403 for unauthorized users

每个需求都附带明确的验收标准（Acceptance），AI Agent 在实现后可以用这个标准自我验证。

design.md — 设计规约

描述系统的架构结构、数据模型和组件关系。AI Agent 必须严格遵循设计规约来生成代码。

tasks.md — 任务规约

每个任务链接回对应的需求，按阶段和优先级排序：

## Phase 2: Core endpoints

- [ ] **TASK-007** [REQ-001]: Implement POST /tasks with validation
  - _Output_: Route handler + request schema validation
  - _Verify_: POST /tasks returns 201 with all fields present

任务规约确保不同的 AI Agent 不会重复实施同一个功能，也不会遗漏关键步骤。

Universal Instruction Block：多工具协同的核心

SDD Skill 最巧妙的设计是 Universal Instruction Block（通用指令块）。它为每个 AI 工具生成匹配的配置文件：

每个配置文件包含相同的指令块，只有项目名称和规约版本号不同：

═══════════════════════════════════════════════════════════
SPEC DRIVEN DEVELOPMENT — PROJECT CONSTITUTION
Project: Your Project Name
Version: 1.0
═══════════════════════════════════════════════════════════

This project uses Spec Driven Development. All work is
governed by three source-of-truth files:

  requirements.md  — What the system must do
  design.md        — What the system is structured
  tasks.md         — The ordered implementation plan

MANDATORY BEFORE ANY ACTION:
  1. Read requirements.md in full
  2. Read design.md in full
  3. Read tasks.md — identify the next incomplete [ ] task

HARD CONSTRAINTS:
  ✗ Never implement requirements not in requirements.md
  ✗ Never alter the data model without updating design.md first
  ✗ Never create files not listed or implied in design.md
  ✗ Never mark a task [x] without verifying its acceptance criterion
  ✗ Never guess when a requirement is ambiguous — ask instead

这个硬约束块确保每个 AI Agent 在行动之前先阅读规约、引用规约、遵守规约。如果实施必须偏离设计规约，Agent 必须立即暂停、描述冲突、等待用户批准、在写代码前更新设计规约。

三个实战场景

场景一：新项目（Greenfield）

最适合 SDD 的场景。Claude 通过 4 个简短对话式问题完成需求访谈，自动生成完整的规约文件。适合想用 AI 编码但又不想让它”自由发挥”的开发者。

场景二：现有代码库改造（Retrofit）

对于已有代码的项目，Skill 会通过对话反向工程出现有的需求规约。所有推断出的字段都会标记 [TO VERIFY]，第一个实施阶段是规约验证而不是新代码。

your-project/
├── requirements.md      ← v0-retrofit: discovered from existing code
├── design.md            ← with [TO VERIFY] on every inferred field
└── tasks.md             ← Phase 1 is spec verification, not new code

场景三：多工具团队（Cross-AI Teams）

当团队使用多种 AI 编码工具时，每个工具读取相同的规约文件、相同的指令块。差距只体现在工具特定的配置差异上，核心规约完全一致。

内置测试套件与 CI 集成

这个 Skill 自带完整的测试套件——135 项断言分布在三个阶段：

GitHub Actions 工作流在每次 push 和 PR 时自动运行可自动化的检查。all-checks 作为分支保护规则中的单一状态检查，一条规则覆盖所有自动化阶段。

本地运行测试：

python3 phase2a/run_assertions.py

python3 phase2c/check_outputs.py

防反模式设计

Skill 内置了硬性检查：听到 “just start coding” 时会拒绝执行并要求先写规约；无规约上下文的 Feature Request 会先检查 requirements.md；AI 猜测模糊需求时会要求澄清而非虚构。这些保护机制让规约体系得以维持，不会因为效率焦虑而被跳过。

总结

SDD Skill 解决的是越来越多团队正在面临的现实问题：AI 编码工具越来越多，但缺少统一的事实来源。通过 requirements.md、design.md 和 tasks.md 三个文件 + Universal Instruction Block，它建立了一个所有 Agent 都同意并遵守的规约体系。

对于已经使用多个 AI 编码工具、或者团队中不同成员偏好不同工具的开发者来说，这是一个值得尝试的工作流改进。当前处于公开测试阶段（1.0-beta），已经通过了 135 项自动化断言和 3 个端到端生成流测试，等待更多来自实际使用场景的反馈。

项目地址：github.com/FredAntB/Spec-Driven-Development

许可证：MIT