<!-- title: Claude Code规格驱动开发全实战 -->

# Claude Code规格驱动开发全实战：从PRD到交付的完整工作流

## 概述

本教程面向有一定Claude Code使用经验、希望从"对话式编码"升级到"工程化交付"的开发者。你将学会如何用**三文档工作流**（PRD → Design Spec → Task List）驱动Claude Code完成从需求分析到生产部署的完整开发周期，告别"一次生成三成成功率"的混沌状态，实现稳定、可复现的AI辅助软件开发。

**适合人群**：已使用Claude Code 1个月以上、有全栈开发基础、希望构建可规模化AI开发流程的中高级开发者。

---

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code CLI | 已安装并完成基本配置（API Key、模型选择） |
| Node.js 18+ | 运行时环境 |
| Git | 版本控制，Claude Code的变更回滚依赖Git |
| 基础全栈知识 | 了解前后端分离、REST API、数据库建模 |
| 一个待开发项目 | 建议选一个小型但完整的Web应用作为实战目标 |

---

## 第一章：为什么需要规格驱动开发

### 1.1 对话式编码的三大困境

大多数开发者使用Claude Code的方式是直接描述需求，让AI生成代码。这种"vibe coding"模式在真实项目中会遇到三个致命问题：

**困境一：上下文窗口耗尽**

Claude Code的上下文窗口约200K token。一个中等规模项目（50+文件）的全量代码就会占满窗口，导致Claude丢失关键信息、生成不一致的代码。

**困境二：一次性成功率低**

根据社区实测数据，没有规格文档时，Claude Code一次性生成正确代码的概率约为30-35%。这意味着你需要反复修正，每次修正都消耗token和时间。

**困境三：无法追踪变更意图**

当项目进行到第50次提交后，你和Claude都很难回忆"为什么要这样实现"。缺少文档化的决策记录，导致后期维护困难。

### 1.2 规格驱动开发的核心理念

Spec-Driven Development（SDD）的核心原则是：**先写规格，再写代码**。它用三个层次递进的文档替代模糊的自然语言描述：

```
┌─────────────────────────────────────────────┐
│  PRD (产品需求文档)                           │
│  → 回答"做什么"和"为什么做"                    │
├─────────────────────────────────────────────┤
│  Design Spec (设计规格)                       │
│  → 回答"怎么做"：架构、数据模型、API设计        │
├─────────────────────────────────────────────┤
│  Task List (任务清单)                         │
│  → 回答"先做什么"：可执行的实现步骤             │
└─────────────────────────────────────────────┘
```

这三层文档的本质是**将复杂的开发任务分解为Claude Code上下文窗口可以消化的粒度**。每个任务独立、完整、可验证。

### 1.3 效率对比

| 指标 | 直接对话编码 | 规格驱动开发 |
|------|-------------|-------------|
| 一次生成成功率 | ~30% | ~80% |
| 48小时原型完成度 | 40-50% | 85-95% |
| Token浪费率 | 50-60% | 15-20% |
| 后期返工量 | 高（频繁重构） | 低（架构前置） |
| 团队协作可行性 | 低（依赖个人经验） | 高（规格可共享） |

---

## 第二章：项目结构与CLAUDE.md配置

### 2.1 规格驱动项目目录结构

在开始编写规格之前，需要建立支持SDD的项目目录结构：

```
my-project/
├── CLAUDE.md                    # 项目级AI指令
├── .claude/
│   ├── settings.json            # 项目配置
│   └── specs/                   # 规格文档目录
│       ├── prd.md               # 产品需求文档
│       ├── design-spec.md       # 设计规格
│       └── tasks.md             # 任务清单
├── docs/                        # 开发文档
│   └── architecture.md          # 架构决策记录
├── src/                         # 源代码
├── tests/                       # 测试
└── package.json
```

### 2.2 编写SDD优化的CLAUDE.md

CLAUDE.md是SDD工作流的核心配置。以下是专为规格驱动开发优化的模板：

```markdown
# 项目：[项目名称]

## 开发规范

### 技术栈
- 前端：Next.js 15 + React 19 + TypeScript 5 + Tailwind CSS 4
- 后端：Next.js API Routes + Prisma ORM
- 数据库：PostgreSQL 16
- 测试：Vitest + Testing Library + Playwright

### 编码规则
- 严格TypeScript，禁止any类型
- 组件使用函数式组件 + Hooks
- API遵循RESTful设计规范
- 每个函数必须有JSDoc注释
- 测试覆盖率目标：80%以上

### 规格驱动工作流
- 所有新功能必须先在 .claude/specs/ 下创建规格文档
- 实现顺序：PRD → Design Spec → Tasks → Code
- 每完成一个Task，运行测试确认通过后再进入下一个
- 不允许跳过测试直接进入下一个Task

### Git提交规范
- feat: 新功能
- fix: 修复bug
- refactor: 重构
- test: 测试相关
- docs: 文档更新
```

### 2.3 配置项目设置

在`.claude/settings.json`中配置项目权限：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npx prisma:*)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File modified - remember to run tests'"
      }
    ]
  }
}
```

---

## 第三章：三文档工作流实战

### 3.1 第一层：编写PRD（产品需求文档）

PRD是SDD的起点。它的作用是为Claude Code提供**业务上下文**，让AI理解"为什么要开发这个功能"。

**操作步骤**：

```bash
# 启动Claude Code，进入Plan模式
claude

# 在交互界面中输入：
> 请帮我为"任务管理看板"应用创建一份PRD。
> 这个应用需要支持：
> 1. 看板视图（待办、进行中、已完成三列）
> 2. 拖拽排序
> 3. 团队协作（多人实时同步）
> 4. 标签和优先级
> 请将PRD保存到 .claude/specs/prd.md
```

**PRD模板结构**：

```markdown
# PRD：[功能名称]

## 1. 概述
一段话描述产品是什么、解决什么问题。

## 2. 目标用户
- 用户角色A：[描述]
- 用户角色B：[描述]

## 3. 功能需求
### 3.1 核心功能
- FR-001：[功能描述]
- FR-002：[功能描述]

### 3.2 辅助功能
- FR-003：[功能描述]

## 4. 非功能需求
- 性能：页面加载 < 2秒
- 安全：JWT认证 + RBAC权限
- 可用性：支持Chrome/Firefox/Safari最新两个版本

## 5. 用户故事
- 作为[角色]，我希望[行为]，以便[价值]

## 6. 约束与假设
- 技术约束：[列出]
- 业务假设：[列出]
```

**预期结果**：Claude Code会根据你的需求描述，生成一份结构化的PRD文档，保存在`.claude/specs/prd.md`。

**常见问题与解决方案**：

| 问题 | 解决方案 |
|------|---------|
| PRD过于宽泛 | 追加具体场景："请聚焦于MVP，只包含最核心的5个功能" |
| 遗漏边界条件 | 指定："请补充异常场景和错误处理需求" |
| 技术术语过多 | 要求："请用产品经理能理解的语言重写" |

### 3.2 第二层：编写Design Spec（设计规格）

Design Spec将PRD转化为**技术蓝图**。这是Claude Code生成高质量代码的关键输入。

**操作步骤**：

```bash
# 继续在Claude Code中：
> 请基于 .claude/specs/prd.md 生成设计规格文档。
> 要求包含：
> 1. 系统架构图（用Mermaid描述）
> 2. 数据库ER图
> 3. API端点设计
> 4. 前端组件树
> 5. 状态管理方案
> 请保存到 .claude/specs/design-spec.md
```

**Design Spec模板结构**：

```markdown
# Design Spec：[项目名称]

## 1. 系统架构

```mermaid
graph TB
    Client[React前端] --> API[API Routes]
    API --> Auth[认证中间件]
    API --> Service[业务逻辑层]
    Service --> DB[(PostgreSQL)]
    Service --> Cache[(Redis缓存)]
    Service --> WS[WebSocket服务]
```

## 2. 数据模型

```mermaid
erDiagram
    USER ||--o{ BOARD : owns
    USER ||--o{ TASK : created
    BOARD ||--|{ COLUMN : contains
    COLUMN ||--|{ TASK : holds
    TASK ||--o{ LABEL : tagged
```

### 2.1 数据表定义

#### users
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | PK | 用户ID |
| email |" VARCHAR(255) "| UNIQUE, NOT NULL | 登录邮箱 |
| name |" VARCHAR(100) "| NOT NULL | 用户名 |
| created_at | TIMESTAMP | DEFAULT NOW | 创建时间 |

## 3. API设计

### 3.1 端点列表
| 方法 | 路径 | 说明 | 认证 |
|------|------|------|------|
| POST | /api/auth/login | 用户登录 | 否 |
| GET | /api/boards | 获取看板列表 | 是 |
| POST | /api/boards | 创建看板 | 是 |
| GET | /api/boards/:id/tasks | 获取看板任务 | 是 |
| PATCH | /api/tasks/:id | 更新任务 | 是 |
| DELETE | /api/tasks/:id | 删除任务 | 是 |

### 3.2 请求/响应示例

#### POST /api/boards
```json
// Request
{
  "name": "Sprint 24",
  "description": "第24个迭代看板"
}
// Response 201
{
  "id": "uuid-xxx",
  "name": "Sprint 24",
  "columns": [
    {"id": "uuid-1", "title": "待办", "position": 0},
    {"id": "uuid-2", "title": "进行中", "position": 1},
    {"id": "uuid-3", "title": "已完成", "position": 2}
  ],
  "created_at": "2026-06-12T10:00:00Z"
}
```

## 4. 前端架构

### 4.1 组件树
```mermaid
graph TD
    App --> Layout
    Layout --> Sidebar
    Layout --> MainArea
    MainArea --> BoardView
    BoardView --> Column[Column x3]
    Column --> TaskCard[TaskCard x N]
    TaskCard --> LabelBadge
    TaskCard --> PriorityBadge
```

### 4.2 状态管理
- 使用 Zustand 进行全局状态管理
- 使用 React Query 处理服务端状态
- 使用 drag-over 事件处理拖拽状态

## 5. 技术决策记录
| 决策 | 选项 | 选择 | 原因 |
|------|------|------|------|
| ORM | Prisma vs Drizzle | Prisma | 成熟度高，迁移工具完善 |
| 实时同步 | WebSocket vs SSE | WebSocket | 需要双向通信 |
| 拖拽库 | dnd-kit vs react-beautiful-dnd | dnd-kit | 维护活跃，性能更好 |
```

**关键技巧**：Design Spec中一定要包含**具体的数据表字段定义**和**API请求/响应示例**。这是Claude Code生成一致代码的关键。模糊的描述会导致不同文件中的类型定义不一致。

### 3.3 第三层：生成Task List（任务清单）

Task List将Design Spec拆解为**可独立执行的实现步骤**。每个Task应该是Claude Code在单次交互中可以完成的粒度。

**操作步骤**：

```bash
> 请基于 .claude/specs/design-spec.md 生成任务清单。
> 要求：
> 1. 每个任务独立、可测试
> 2. 按依赖关系排序
> 3. 每个任务预估耗时不超过30分钟
> 4. 包含验收标准
> 请保存到 .claude/specs/tasks.md
```

**Task List示例**：

```markdown
# Task List：任务管理看板

## Phase 1：基础设施（预计2小时）

### T-001：项目初始化与数据库配置
- 创建Next.js项目
- 配置Prisma + PostgreSQL
- 创建数据库Schema（users, boards, columns, tasks, labels表）
- 运行初始迁移
- **验收**：`npx prisma migrate dev` 成功，表结构正确

### T-002：认证系统
- 实现JWT认证（登录/注册API）
- 创建认证中间件
- 前端登录/注册表单
- **验收**：可以注册、登录，受保护API返回401未授权

### T-003：基础布局与路由
- 创建应用布局（Sidebar + MainArea）
- 配置路由（/, /boards, /boards/:id）
- 响应式设计
- **验收**：所有路由可访问，布局在不同屏幕尺寸下正常

## Phase 2：核心功能（预计3小时）

### T-004：看板CRUD API
- 实现看板的增删改查API
- 自动创建默认三列
- 权限校验
- **验收**：API测试覆盖所有CRUD操作

### T-005：看板列表页面
- 展示用户所有看板
- 创建新看板的表单/模态框
- 删除看板（带确认）
- **验收**：可以创建、查看、删除看板

### T-006：看板视图 - 列与任务卡片
- 三列布局（待办/进行中/已完成）
- 任务卡片组件（标题、标签、优先级、头像）
- 新建任务功能
- **验收**：看板视图正确渲染，可以创建任务

### T-007：拖拽排序
- 集成dnd-kit
- 列内拖拽排序
- 跨列拖拽（改变状态）
- 持久化位置到数据库
- **验收**：拖拽流畅，刷新后顺序保持

## Phase 3：协作与增强（预计2小时）

### T-008：WebSocket实时同步
- 建立WebSocket连接
- 广播任务变更事件
- 冲突处理（乐观锁）
- **验收**：多用户可同时操作，变更实时同步

### T-009：标签与优先级系统
- 标签CRUD
- 任务关联标签
- 按标签/优先级筛选
- **验收**：可以创建标签、为任务添加标签、按标签筛选

### T-010：测试与优化
- 单元测试（Service层）
- 集成测试（API端点）
- E2E测试（关键用户流程）
- 性能优化（懒加载、分页）
- **验收**：测试覆盖率≥80%，Lighthouse性能分数≥90
```

---

## 第四章：逐Task实现的工作流

### 4.1 Spec → Plan → Code → Test循环

这是SDD的核心执行循环。每个Task都遵循相同的四步流程：

```mermaid
flowchart LR
    A[读取Task规格] --> B[进入Plan模式]
    B --> C[审查计划]
    C --> D[批准并实现]
    D --> E[运行测试]
    E --> F{测试通过?}
    F -->|是| G[Git提交]
    F -->|否| H[分析失败原因]
    H --> B
    G --> I[标记Task完成]
    I --> A
```

### 4.2 实战：实现T-001（项目初始化）

**Step 1：让Claude Code读取Task**

```bash
# 在Claude Code交互界面中：
> 请读取 .claude/specs/tasks.md 中的 T-001 任务，
> 并基于 .claude/specs/design-spec.md 中的数据模型设计，
> 制定实现计划。
```

**Step 2：进入Plan模式审查**

Claude Code会自动进入Plan模式，分析现有代码结构，然后输出一个实现计划。你审查计划，确认技术选型和实现路径正确后批准。

**Step 3：执行实现**

批准计划后，Claude Code开始执行。你会看到它：

1. 运行 `npx create-next-app@latest` 初始化项目
2. 安装依赖 `npm install prisma @prisma/client`
3. 创建 `prisma/schema.prisma` 并定义数据模型
4. 运行 `npx prisma migrate dev --name init`

**Step 4：验收测试**

```bash
> 运行 T-001 的验收标准：
> 1. 确认 prisma migrate dev 成功
> 2. 检查数据库表结构是否匹配 design-spec.md
> 3. 运行 npx prisma studio 验证可视化
```

**Step 5：提交**

```bash
> 请提交 T-001 的所有变更，commit message 遵循项目规范
```

### 4.3 关键执行原则

**原则一：一次一个Task**

不要让Claude Code同时实现多个Task。每个Task完成后：
1. 运行测试确认
2. Git提交
3. 再进入下一个Task

这确保了每个变更都可回滚，不会因为一次错误操作导致整个项目混乱。

**原则二：遇到问题时回到规格**

当Claude Code生成的代码不符合预期时，不要直接"修补"。而是：

```bash
> 这段实现与 design-spec.md 中的 XXX 不一致。
> 请重新读取设计规格，然后重新实现。
```

**原则三：保持规格与代码同步**

如果实现过程中发现规格需要调整：

```bash
> 在实现过程中，我发现 T-006 的验收标准遗漏了"任务编辑"功能。
> 请更新 tasks.md 和 design-spec.md，补充这个功能。
```

---

## 第五章：完整实战案例——48小时交付看板应用

### 5.1 时间规划

基于社区实战经验，一个中等复杂度的Web应用可以在48小时内从零交付：

```mermaid
gantt
    title 48小时看板应用交付计划
    dateFormat HH:mm
    axisFormat %H:%M

    section Day 1 (8h)
    编写PRD           :a1, 00:00, 60m
    编写Design Spec    :a2, after a1, 90m
    生成Task List      :a3, after a2, 30m
    T-001 项目初始化   :a4, after a3, 120m
    T-002 认证系统     :a5, after a4, 120m
    T-003 基础布局     :a6, after a5, 60m

    section Day 2 (8h)
    T-004 看板API      :b1, 00:00, 90m
    T-005 看板列表页   :b2, after b1, 60m
    T-006 看板视图     :b3, after b2, 120m
    T-007 拖拽排序     :b4, after b3, 90m
    T-008 实时同步     :b5, after b4, 60m
    T-009 标签系统     :b6, after b5, 60m
    T-010 测试优化     :b7, after b6, 90m
```

### 5.2 Day 1执行细节

**上午（0:00 - 4:00）：规格编写**

```bash
# 启动Claude Code
claude

# 第一步：生成PRD（约30分钟，含2轮迭代）
> 我要开发一个团队看板应用，类似Trello的精简版。
> 请帮我生成PRD，包含：
> - 目标用户：5-20人的敏捷团队
> - 核心功能：看板管理、任务拖拽、标签、成员协作
> - MVP范围：只做看板和任务管理，不做甘特图和报表
> 保存到 .claude/specs/prd.md

# 审查PRD后，生成Design Spec（约60分钟）
> 基于PRD生成技术设计规格。技术栈参考CLAUDE.md中的定义。
> 特别注意：数据库模型要支持拖拽排序的position字段。
> 保存到 .claude/specs/design-spec.md

# 审查Design Spec后，生成Task List（约20分钟）
> 基于Design Spec生成任务清单。
> 每个Task控制在30分钟内可完成。
> 按依赖关系排序，先基础后功能。
> 保存到 .claude/specs/tasks.md
```

**下午（4:00 - 8:00）：基础设施搭建**

逐个执行T-001到T-003。每个Task的执行模式：

```bash
# 标准执行模式
> 请执行 T-001。先读取规格文件，制定计划，等我的确认后再开始编码。

# 审查计划 → 批准 → 实现 → 测试 → 提交
# 然后进入下一个Task
> T-001 完成。请继续执行 T-002。
```

### 5.3 Day 2执行细节

**上午（0:00 - 4:00）：核心功能**

Day 2的Task更复杂（拖拽、实时同步），但因为有Day 1建立的规格基础，Claude Code的代码质量会显著提高。

关键提示词模式：

```bash
# T-006 看板视图（最复杂的Task之一）
> 请执行 T-006。注意事项：
> 1. 参考 design-spec.md 中的组件树设计
> 2. Column组件和TaskCard组件要独立可测试
> 3. 先实现静态渲染，确认UI正确后再接入API
> 4. 使用 loading skeleton 优化加载体验
```

**下午（4:00 - 8:00）：增强与测试**

```bash
# T-010 最终测试
> 请执行 T-010。要求：
> 1. 为每个Service方法编写单元测试
> 2. 为每个API端点编写集成测试
> 3. 使用Playwright编写E2E测试覆盖核心流程
> 4. 运行全部测试，确保通过率100%
> 5. 检查测试覆盖率是否达到80%
```

### 5.4 验收检查清单

项目完成后，运行最终验收：

```bash
> 请进行项目最终验收：
> 1. 逐项检查 tasks.md 中所有Task的验收标准
> 2. 运行完整测试套件
> 3. 检查 CLAUDE.md 中定义的编码规范是否全部遵守
> 4. 验证所有API端点的请求/响应符合 design-spec.md
> 5. 生成验收报告，标注通过/未通过项
```

---

## 第六章：SDD高级技巧

### 6.1 规格渐进细化（Progressive Specification）

不是所有功能都需要完整的三文档。根据复杂度选择合适的规格深度：

```mermaid
flowchart TD
    A[新功能需求] --> B{复杂度评估}
    B -->|简单: 修改按钮颜色| C[直接编码]
    B -->|中等: 新增API端点| D[只写Task]
    B -->|复杂: 新业务模块| E[三文档完整流程]
    B -->|架构级: 引入新系统| F[额外写ADR]
```

| 复杂度 | 规格要求 | 示例 |
|--------|---------|------|
| 简单（<30分钟） | 无需规格，直接编码 | 修改CSS、修bug |
| 中等（30-120分钟） | 只写Task List | 新增API端点、新页面 |
| 复杂（2-8小时） | 完整三文档流程 | 新业务模块 |
| 架构级（>1天） | 三文档 + ADR记录 | 引入消息队列、更换ORM |

### 6.2 上下文窗口管理策略

在长项目过程中，Claude Code的上下文窗口会逐渐填满。SDD通过**规格文档作为持久化上下文**来解决这个问题：

**策略一：每完成一个Phase，重新启动会话**

```bash
# Phase 1完成后
> 请总结Phase 1的所有已完成工作和关键决策，
> 保存到 docs/phase1-summary.md

# 重新启动Claude Code
claude

# 新会话开始时
> 请读取以下文件了解项目当前状态：
> 1. .claude/specs/design-spec.md（技术设计）
> 2. .claude/specs/tasks.md（检查已完成/未完成的任务）
> 3. docs/phase1-summary.md（前一阶段总结）
> 准备好后请告诉我，我们开始Phase 2。
```

**策略二：使用/spec命令快速加载上下文**

如果你的Claude Code版本支持自定义slash command，可以创建`.claude/commands/spec.md`：

```markdown
请读取项目的规格文档以了解完整上下文：
1. 读取 .claude/specs/prd.md 了解产品需求
2. 读取 .claude/specs/design-spec.md 了解技术设计
3. 读取 .claude/specs/tasks.md 检查任务进度
4. 报告当前项目状态和待完成工作

参数：$ARGUMENTS
```

使用方式：`/spec` 即可快速加载所有规格上下文。

### 6.3 多人协作的规格管理

在团队中使用SDD时，规格文档成为**团队与AI之间的契约**：

```mermaid
flowchart LR
    PM[产品经理] -->|编写PRD| PRD[prd.md]
    Arch[架构师] -->|编写Design Spec| DS[design-spec.md]
    Lead[技术负责人] -->|审核Task List| TL[tasks.md]
    PRD --> CC[Claude Code]
    DS --> CC
    TL --> CC
    CC -->|生成代码| Code[代码仓库]
    Code -->|测试验证| Review[Code Review]
    Review -->|反馈更新| DS
```

**团队规范**：

1. **PRD由产品经理维护**，技术团队不修改
2. **Design Spec由架构师维护**，开发过程中如需变更，需提交ADR（Architecture Decision Record）
3. **Task List由技术负责人维护**，每个开发者认领Task后在注释中标记`@owner`
4. **CLAUDE.md由全团队维护**，任何编码规范变更需经团队评审

### 6.4 规格与代码的双向同步

代码实现过程中发现规格需要调整时的处理流程：

```bash
# 场景：实现T-007时发现拖拽排序需要额外的position字段
> 在实现拖拽排序时，我发现需要给tasks表增加一个
> display_order字段来持久化用户自定义排序。
> 请按以下步骤处理：
> 1. 更新 design-spec.md 中的数据模型定义
> 2. 创建数据库迁移 npx prisma migrate dev
> 3. 更新受影响的API响应格式
> 4. 继续完成T-007
```

---

## 第七章：规格驱动开发的完整工作流图

```mermaid
flowchart TB
    subgraph 规格阶段
        A[需求分析] --> B[编写PRD]
        B --> C[编写Design Spec]
        C --> D[生成Task List]
    end

    subgraph 实现阶段
        D --> E{选取下一个Task}
        E --> F[Plan模式: 制定实现计划]
        F --> G[审查计划]
        G -->|拒绝| F
        G -->|批准| H[自动实现代码]
        H --> I[运行测试]
        I -->|失败| J[分析错误]
        J --> F
        I -->|通过| K[Git提交]
        K --> L{所有Task完成?}
        L -->|否| E
        L -->|是| M[集成测试]
    end

    subgraph 交付阶段
        M --> N[最终验收]
        N -->|不通过| O[修复并补充Task]
        O --> E
        N -->|通过| P[部署上线]
    end

    style 规格阶段 fill:#e1f5fe
    style 实现阶段 fill:#fff3e0
    style 交付阶段 fill:#e8f5e9
```

---

## 第八章：常见陷阱与解决方案

### 陷阱一：规格过于详细

**症状**：PRD写了50页，Design Spec包含每个函数的伪代码。

**解决**：规格应该描述"做什么"和"怎么做"的方向，而不是逐行指导实现。保持PRD在3-5页、Design Spec在5-10页。

```bash
# 如果Claude Code生成的规格过于详细：
> 这份设计规格太详细了，请精简到只包含架构决策、
> 数据模型和API设计。实现细节留给编码阶段。
```

### 陷阱二：跳过Plan模式直接编码

**症状**：读取Task后直接让Claude Code开始写代码。

**解决**：始终使用Plan模式。Plan模式让Claude Code先分析影响范围，避免盲目修改导致的连锁错误。

```bash
# 正确做法：强制进入Plan模式
> 请为T-005制定实现计划。使用Plan模式，
> 先分析需要创建/修改哪些文件，再开始实现。
```

### 陷阱三：忽视测试环节

**症状**：完成所有Task后才想起来写测试，发现大量bug。

**解决**：每个Task的验收标准中都包含测试。如果Claude Code没有主动运行测试，手动触发：

```bash
> T-004已完成。请运行相关测试确认功能正确。
> 如果没有测试，请先编写测试再继续下一个Task。
```

### 陷阱四：规格文档与代码脱节

**症状**：Design Spec写的是PostgreSQL，代码却用了SQLite。

**解决**：在每个Task开始时，让Claude Code重新确认规格：

```bash
> 请在开始T-006之前，确认以下规格要点：
> 1. 数据库使用PostgreSQL（参考design-spec.md §2）
> 2. 前端使用dnd-kit（参考design-spec.md §4.2）
> 3. API路径遵循 /api/ 前缀（参考design-spec.md §3）
```

---

## 第九章：SDD适用场景评估

### 适合SDD的项目

| 项目类型 | 适合度 | 原因 |
|---------|--------|------|
| 全栈Web应用 | ★★★★★ | 功能模块清晰，数据模型可提前定义 |
| API服务 | ★★★★☆ | 端点设计前置，减少接口不一致 |
| CLI工具 | ★★★★☆ | 命令结构可提前规划 |
| 移动应用 | ★★★☆☆ | UI层难以用规格完全描述 |
| 数据Pipeline | ★★★☆☆ | 数据流可规划，但调优需实际运行 |

### 不适合SDD的场景

- **探索性原型**：不确定技术方案时，先用对话式编码快速验证
- **一次性脚本**：不需要长期维护的自动化脚本
- **纯UI调整**：CSS微调、文案修改等简单变更

---

## 延伸阅读

- [Anthropic官方：Common Workflows](https://code.claude.com/docs/en/common-workflows) — Claude Code日常工作流官方指南
- [Anthropic官方：Best Practices](https://code.claude.com/docs/en/best-practices) — 上下文管理与提示词最佳实践
- [DataCamp：Spec-Driven Development with Claude Code](https://www.datacamp.com/tutorial/spec-driven-development-with-claude-code) — 三文档工作流完整教程
- [okhlopkov：Claude Code Workflow 2026](https://okhlopkov.com/claude-code-workflow-2026/) — 规格优先开发的实践经验
- [Brian Mena：48-Hour Sprint Tutorial](https://newsletter.brianmenagomez.com/p/claude-code-tutorial-2026-prototype) — 48小时从原型到生产的实战教程

## 参考来源

1. [Spec-Driven Development with Claude Code — DataCamp](https://www.datacamp.com/tutorial/spec-driven-development-with-claude-code) — 三文档SDD工作流的权威教程，PRD/Design Spec/Task List分层方法论
2. [Claude Code workflow: how I code with AI in 2026 — okhlopkov](https://okhlopkov.com/claude-code-workflow-2026/) — spec-first开发实践者的一手经验，含Plan模式和检查点工作流
3. [Claude Code Tutorial 2026: Prototype to Production in 48-Hour Sprints — Brian Mena](https://newsletter.brianmenagomez.com/p/claude-code-tutorial-2026-prototype) — 48小时交付框架，Agent而非Chatbot的使用哲学
4. [Claude Code in 2026: Practical End-to-End SDLC Workflow — DevelopersVoice](https://developersvoice.com/blog/ai/claude_code_2026_end_to_end_sdlc/) — 覆盖全软件开发生命周期的Claude Code集成实践
5. [Common Workflows — Claude Code Official Docs](https://code.claude.com/docs/en/common-workflows) — Anthropic官方日常工作流指南，包含代码探索、重构、测试等场景

---

> **训练营适用性评估**：本教程适合**进阶开发者训练营**（学员已具备Claude Code基础使用经验），建议教学时长**6-8小时**（含动手实践），可分为两个半天：Day 1上午讲理论与规格编写（3h），Day 1下午完成Phase 1实现（3h），课后独立完成Phase 2-3。推荐班级规模10-15人，每人独立完成一个完整项目。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)