基于Claude Code的规范驱动开发（SDD）指南

前言

传统的AI辅助开发，如同手工作坊，我们向AI描述想法，它给我们零散的部件，我们再手动打磨、组装。这个过程充满了不确定性、信息损耗和重复劳动。

本指南将尝试引领您进入软件开发的"工业时代"。在这里，"规范"就是我们的精密图纸，"Claude Code"是我们不知疲倦的自动化产线。您的角色将从一名"代码工匠"升华为一名"系统架构师"和"流程总设计师"。您的核心产出不再是代码，而是高质量的、机器可读的规范。

本指南的目标：

掌握一套完整的、端到端的、以规范为核心的开发生命周期方法论，使您能够利用Claude Code，以过去10倍以上的效率和稳定性，开发出任何复杂度的专业级软件。

核心框架：规范驱动开发的五大生命周期阶段

我们将遵循以下五个核心阶段来完成所有项目的开发、迭代与维护。

阶段	名称	核心目标	关键角色	主要产出
Phase 0	理念与架构规划	确立宏观蓝图，做出关键技术决策	人类 (战略家)	`README.md`，技术选型文档，项目结构图
Phase 1	规范定义与编写	创建项目的"法律"，定义一切行为	人类 (立法者)	`GLOBAL_SPEC.md`，`FEATURE_SPEC_xxx.md`
Phase 2	AI驱动的原子化生成	将规范精准转化为工程产物	AI (执行引擎)	`.ts`, `.py`, `.spec.ts` 等原子化代码/测试文件
Phase 3	人类集成与验证	组装组件，进行最终质量把控	人类 (总工程师)	可运行的功能模组，通过集成测试的系统
Phase 4	部署、迭代与维护	确保系统演进的健康与一致性	人机协同	部署脚本，更新后的规范与代码

Phase 0: 理念与架构规划

目标：在写下第一行规范之前，构建清晰的战略蓝图。

核心原则：人类的经验与洞察力在此阶段至关重要。AI是您的超级研究助理和决策顾问，而非最终决策者。
步骤 0.1：定义愿景与核心需求 (人类主导)
- 操作：在README.md中，用清晰的语言回答以下问题：
  1. 我们要解决什么核心问题？
  2. 我们的目标用户是谁？
  3. 成功的量化标准是什么？

提示：这是项目的"宪法"，也是您向AI解释项目背景时的重要上下文。

步骤 0.2：AI辅助技术栈研究与决策
- 操作：您根据经验提出几个备选方案，然后利用Claude Code进行深度、量化的比较，以数据驱动决策。
- 专业提示词模板：
任务：技术栈深度分析与选型推荐

作为我的资深技术顾问，请基于以下项目背景和需求，为我提供一份专业的技术栈选型分析报告。

项目背景： [在此处简述项目核心需求，例如："一个支持Markdown、多作者、高并发的智慧部落格平台后端服务。"]

候选技术栈：
1. $候选方案A，例如：Node.js + NestJS + PostgreSQL$
2. $候选方案B，例如：Python + FastAPI + PostgreSQL$
3. $可选方案C...$
分析报告必须包含以下维度，并使用表格进行对比：
- 开发效率与学习曲线：对中等水平团队而言。
- 性能表现：特别是在 [项目瓶颈场景，例如：I/O密集型] 的表现。
- 生态系统成熟度：包括社区活跃度、高质量第三方库的数量。
- 代码可维护性与工程化：类型系统、项目结构、测试支持等。
- 人才招聘难度：在当前市场上的流行度和人才储备。
最终要求：

在报告的结尾，请明确给出你的 最终推荐，并提供至少三个充分的理由来支持你的选择。
- 项目应用：
  - 智慧部落格后端：比较 NestJS vs FastAPI。
  - 即时数据仪錶盘：比较 React vs Vue vs Svelte。
  - 静态网站生成器：比较 Python (Typer) vs Go (Cobra)。

步骤 0.3：AI生成标准化项目结构

操作：一旦技术栈确定，立即让AI为您生成一个遵循社区最佳实践的、可扩展的初始项目结构。
专业提示词模板：

复制代码

# 任务：生成标准化项目目录结构

根据我们已确定的技术栈 **[在此处填写技术栈，例如：NestJS]**，为我们的项目 **[项目名称，例如："智慧部落格平台后端"]** 生成一个详细的、生产级的项目目录结构。

**结构要求：**
1.  遵循该技术栈的官方和社区最佳实践。
2.  逻辑清晰，具备良好的模块化和可扩展性。
3.  请以树状图（tree-like format）的形式展示。
4.  对每一个核心目录和配置文件，请添加一行简短的注释，说明其用途。
5.  必须预先规划出以下核心功能模块：[模块列表，例如：auth, users, posts, comments]。

提示：一个好的开始是成功的一半。标准化的结构可以极大降低团队协作的沟通成本，也便于后续的自动化生成。

Phase 1: 规范定义与编写

目标：创建项目唯一的、不容置疑的"真理之源"。这是整个流程中最关键、最有价值的一步。

核心原则："代码会说谎，规范永远真实。" (Code lies, specs are truth.) 花在编写高质量规范上的每一分钟，都会在后续阶段获得十倍的回报。

步骤 1.1：定义项目的"最高法典"：GLOBAL_SPEC.md

操作：在项目根目录创建此文件，它定义了所有代码生成时必须共同遵守的全局规则。

GLOBAL_SPEC.md 模板：

markdown 复制代码

# 全局开发规范 (GLOBAL_SPEC) - v1.0

## 1. 命名约定
- **变量/函数**: camelCase
- **类/接口/类型**: PascalCase
- **文件**: kebab-case (e.g., `user.service.ts`)
- **API Endpoints**: kebab-case (e.g., `/user-profiles`)

## 2. API设计规范
- **风格**: 严格遵循RESTful标准。
- **成功响应格式**:
  ```json
  {
    "statusCode": 200,
    "success": true,
    "data": { ... }
  }

错误响应格式 :

json 复制代码

{
  "statusCode": 400,
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input.",
    "details": [ ... ]
  }
}

3. 代码风格

Linter : 遵循项目根目录下的 .eslintrc.js 规则。
注释: 关键业务逻辑必须有JSDoc注释。

4. 测试规范

命名 : 测试文件必须以 .spec.ts 或 .test.ts 结尾。
覆盖率: 核心业务逻辑的单元测试覆盖率目标为 >90%。

步骤 1.2：为每个功能编写"原子化规范"：FEATURE_SPEC_xxx.md

操作：为项目中每一个最小的功能单元（例如，一个API端点，一个UI组件）创建一个独立的、极度详细的规范文件。

FEATURE_SPEC_xxx.md 黄金模板 (以"创建新文章"为例)：

markdown 复制代码

# 功能规范: 创建新文章 (Create New Post)

- **功能ID**: POST-001
- **版本**: 1.0.0
- **依赖全局规范**: `GLOBAL_SPEC.md` v1.0

---

### 1. 概述与业务目标
允许已通过JWT认证的用户，创建一篇新的部落格文章。文章在创建时，其初始状态必须被强制设置为"草稿(draft)"。

### 2. API接口定义 (Endpoint)
- **路径**: `POST /posts`
- **认证**: 必须提供有效的JWT Bearer Token。

### 3. 数据传输对象 (DTO)
- **名称**: `CreatePostDto`
- **字段详情**:
  | 字段名 | 类型 | 验证规则 | 备注 |
  |:---|:---|:---|:---|
  | `title` | `string` | `IsNotEmpty()`, `MinLength(5)`, `MaxLength(100)` | 文章主标题 |
  | `content` | `string` | `IsNotEmpty()`, `MinLength(50)` | Markdown格式的文章正文 |
  | `tagIds` | `number[]`| `IsOptional()`, `IsArray()`, `ArrayMaxSize(5)` | 关联的标签ID数组 |

### 4. 核心业务逻辑 (精确到步骤)
1.  **权限校验**: 从JWT Payload中解析出 `userId`。若无，则流程中止。
2.  **输入验证**: 使用DTO对请求体进行严格验证。若失败，则流程中止。
3.  **唯一标识符生成**: 基于`title`，生成一个对URL友好的`slug`。必须处理潜在的slug冲突（例如，在末尾添加唯一后缀）。
4.  **实体构建**: 创建一个新的`Post`实体，并强制设置以下字段：
    - `authorId`: 设置为从JWT中获取的`userId`。
    - `status`: 强制设置为 `'draft'`。
5.  **持久化**: 将构建好的`Post`实体存入数据库。
6.  **响应构建**: 操作成功后，构建符合 `GLOBAL_SPEC.md` 中定义的成功响应格式。`data`字段中应包含完整的新创建的文章对象。

### 5. 错误处理与状态码
| 场景 | HTTP状态码 | 错误码 (Code) | 描述 |
|:---|:---:|:---|:---|
| 未提供或JWT无效 | `401 Unauthorized` | `UNAUTHENTICATED` | 用户未登录 |
| 请求体验证失败 | `400 Bad Request` | `VALIDATION_ERROR` | 如标题过短 |
| 数据库写入异常 | `500 Internal Server Error`| `DATABASE_ERROR` | 伺服器内部错误 |

### 6. 验收标准 (测试用例)
- **用例1: 成功创建**
  - **Given**: 一个已认证的用户，提供了所有合法的字段。
  - **When**: 发送 `POST /posts` 请求。
  - **Then**: 响应码为`201 Created`，响应体包含新文章数据，且数据库中存在对应记录，其`status`为`draft`。
- **用例2: 标题不合法**
  - **Given**: 一个已认证的用户，但`title`只有3个字符。
  - **When**: 发送 `POST /posts` 请求。
  - **Then**: 响应码为`400 Bad Request`，响应体中包含指向`title`字段的验证错误信息。
- **用例3: 未认证访问**
  - **Given**: 一个未提供JWT的请求。
  - **When**: 发送 `POST /posts` 请求。
  - **Then**: 响应码为`401 Unauthorized`。

提示：这份规范就是您与AI之间唯一的、神圣的"契约"。它的精确度，直接决定了最终产出的质量。这份文件也将成为您项目中最有价值的"活文档"。

Phase 2: AI驱动的原子化生成

目标：将规范高效、可靠地转化为代码、测试、文档等工程产物。

核心原则：
1. 上下文注入(Context Injection) ：每一次请求，都必须将相关的GLOBAL_SPEC.md和FEATURE_SPEC_xxx.md作为上下文提供给AI。
2. 原子化指令(Atomic Instruction)：一次只生成一个文件或一个函数。禁止使用"生成整个模块"这样的模糊指令。原子化确保了最高质量和最强的可控性。

专业提示词黄金模板：

复制代码

# 任务: [简要说明任务, 例如：生成NestJS Service中的create方法]

作为一名顶级的、严格遵循规范的 [技术角色, 例如：NestJS后端工程师]，你的任务是根据我提供的上下文，生成指定的代码。

---
### **上下文1: 全局开发规范**
[此处完整粘贴 `GLOBAL_SPEC.md` 的内容]
---
### **上下文2: 功能规范**
[此处完整粘贴 `FEATURE_SPEC_xxx.md` 的内容]
---

### **你的具体任务与要求:**

1.  **目标文件**: [文件名, 例如：`posts.service.ts`]
2.  **目标内容**: [具体内容, 例如：实现 `create` 方法]
3.  **严格遵循**: 你必须100%遵循上述两个规范文档中的所有约定，特别是业务逻辑、数据模型、命名约定和错误处理。
4.  **依赖假设**: [说明依赖, 例如：假设已通过依赖注入获得了可用的 `PrismaService` 实例，名为 `this.prisma`]
5.  **输出格式**: 只输出纯代码。禁止包含任何解释、注释或markdown标记。

执行流程 (以FEATURE_SPEC_CreatePost.md为例)：
1. 生成DTO : 使用上述模板，要求生成 create-post.dto.ts。
2. 生成Service : 要求生成 posts.service.ts 中的 create 方法。
3. 生成Controller : 要求生成 posts.controller.ts 中的 create 端点方法。
4. 生成单元测试 : 要求为 posts.service.ts 的 create 方法生成对应的 .spec.ts 文件，并严格遵循规范中的"验收标准"。

Phase 3: 人类集成与验证

目标：将AI生成的精密零件组装成可运行的系统，并进行最终的质量把关。

核心原则：您的角色从"创作者"转变为"总工程师"和"质检员"。
步骤 3.1：规范符合性审查 (Spec-Compliance Review)
- 操作：进行Code Review。唯一的审查标准是："这段代码是否100%忠实地执行了规范？" 忽略个人风格偏好，只关注规范的实现精度。
步骤 3.2：依赖注入与模块组装
- 操作：这是少量且高度模式化的"体力活"。例如，在NestJS的posts.module.ts中，将生成的PostsController和PostsService注册到对应的数组中。
步骤 3.3：端到端(E2E)测试
- 操作：运行您的E2E测试框架（如Supertest），或者使用Postman/Insomnia，严格按照FEATURE_SPEC_xxx.md中的"验收标准"部分，对真实的API接口进行黑盒测试。
- 教练提示：如果所有原子化单元测试都通过了，但E2E测试失败，问题几乎总是出在步骤3.2的"组装"环节，而不是AI生成的业务逻辑本身。

Phase 4: 部署、迭代与维护

目标：将应用推向生产，并在未来的演进中保持其架构的健康和文档的同步。

核心原则 ：永远修改规范，而不是直接修改代码！(Always modify the spec, never the code directly!)

步骤 4.1：AI辅助生成部署配置

操作：使用类似的上下文注入方法，让AI为您生成Dockerfile, docker-compose.yml, CI/CD配置文件等。

专业提示词模板 ：

复制代码

# 任务: 生成生产环境Dockerfile

为我的 **[技术栈, 例如：NestJS]** 项目生成一个优化的、多阶段构建的 `Dockerfile`。

**要求:**
1. 使用官方的 `node:18-alpine` 作为基础镜像。
2. 严格分离开发依赖和生产依赖。
3. 最终的生产镜像应该尽可能小，只包含运行所需的必要文件。
4. 最终启动命令是 `node dist/main`。

步骤 4.2：规范驱动的迭代流程
- 当接到一个"修改需求"或"新增功能"的工单时，请严格遵循以下"黄金流程"：
1. 定位规范 : 找到或创建对应的FEATURE_SPEC_xxx.md文件。
2. 更新规范 : 修改规范文件的内容以反映新的需求。务必更新版本号，并在文件头部添加变更日志。
3. 重新生成 : 回到Phase 2，使用更新后的规范，让AI重新生成受影响的代码片段或文件。
4. 替换与验证 : 回到Phase 3，用新生成的代码替换旧代码，并运行所有相关测试。

提示：这个流程是SDD的灵魂。它强制要求您的文档、代码和测试永远保持100%的同步，彻底根除了技术债务的主要来源。

三大实战项目训练案例

现在，让我们将理论付诸实践。

案例一：后端API系统 - 「智慧部落格平台后端」 (NestJS)

完整流程演示 ：
1. Phase 0: 确定使用NestJS, PostgreSQL，并生成项目结构。
2. Phase 1 : 编写GLOBAL_SPEC.md和至少5个核心功能的FEATURE_SPEC（用户注册/登录，文章增/删/改/查）。
3. Phase 2 :
  - 从FEATURE_SPEC_UserRegister.md开始。
  - Prompt 1: 生成 register-user.dto.ts。
  - Prompt 2: 生成 auth.service.ts 中的 register 方法。
  - Prompt 3: 生成 auth.controller.ts 中的 register 端点。
  - Prompt 4: 生成 auth.service.register.spec.ts 单元测试。
  - ...对其他功能重复此过程。
4. Phase 3 : 在auth.module.ts和app.module.ts中完成组装，然后运行E2E测试，验证注册流程是否与规范完全一致。
5. Phase 4 : 接到"增加用户昵称字段"的需求后，首先修改FEATURE_SPEC_UserRegister.md，增加nickname字段及其验证规则，然后重复Phase 2和3。

案例二：前端应用 - 「即时数据仪錶盘」 (React)

规范核心展示 : 您的规范将以"组件"为核心。
- COMPONENT_SPEC_RealTimeChart.md :
  - Props定义 : dataSourceUrl: string, title: string, refreshInterval: number。
  - 内部State定义 : isLoading: boolean, error: string | null, dataPoints: DataPoint[]。
  - 行为逻辑 :
    1. useEffect on mount: 建立WebSocket连接。
    2. onmessage handler: 解析数据，更新dataPoints state。
    3. useEffect on unmount: 清理并关闭连接。
  - 渲染逻辑 :
    - isLoading为true时，显示<Spinner />。
    - error有值时，显示<ErrorMessage message={error} />。
    - 成功时，将dataPoints传递给<LineChart />子组件进行渲染。
生成流程 :
1. Prompt 1: 生成类型定义文件types.ts (e.g., DataPoint interface)。
2. Prompt 2: 基于规范生成RealTimeChart.tsx的完整组件代码。
3. Prompt 3: 基于规范中的行为逻辑，为RealTimeChart组件生成React Testing Library的测试用例。

案例三：工具链/CLI - 「Markdown静态网站生成器」 (Python)

规范核心展示 : 您的规范将以"命令"和"核心处理逻辑"为核心。
- CLI_SPEC_BuildCommand.md :
  - 命令 : builder build <source_dir>
  - 参数 : <source_dir> (必需), --output <output_dir> (可选, 默认./dist), --template <template_path> (可选, 默认内置模板)。
  - 核心处理流程 :
    1. 验证source_dir是否存在。
    2. 递归扫描source_dir下的所有.md文件。
    3. For each file :
      a. 读取文件内容。
      b. 使用python-frontmatter解析元数据(title, date)。
      c. 使用markdown-it-py将正文转换为HTML。
      d. 使用Jinja2模板引擎，将HTML内容和元数据渲染到HTML页面中。
    4. 根据所有文件的元数据，生成一个index.html导航页。
生成流程 :
1. Prompt 1: "基于核心处理流程，编写一个SiteGenerator类，实现扫描、解析、渲染的逻辑。"
2. Prompt 2: "使用Typer库，为SiteGenerator类创建一个命令行接口，实现build命令及其所有参数和选项。"

结论

规范驱动开发不仅是一种技术，更是一种思维模式的升级。它将您从繁琐、易错的编码工作中解放出来，让您能专注于最具价值的架构设计、业务抽象和流程优化。

基于Claude Code的 规范驱动开发（SDD）指南

核心框架：规范驱动开发的五大生命周期阶段

Phase 0: 理念与架构规划

任务：技术栈深度分析与选型推荐

Phase 1: 规范定义与编写

3. 代码风格

4. 测试规范

Phase 2: AI驱动的原子化生成

Phase 3: 人类集成与验证

Phase 4: 部署、迭代与维护

三大实战项目训练案例

案例一：后端API系统 - 「智慧部落格平台后端」 (NestJS)

案例二：前端应用 - 「即时数据仪錶盘」 (React)

案例三：工具链/CLI - 「Markdown静态网站生成器」 (Python)

基于Claude Code的规范驱动开发（SDD）指南