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

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

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

# 项目：[项目名称]

## 开发规范

### 技术栈
- 前端：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: 文档更新

{
  "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'"
      }
    ]
  }
}

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

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

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

# Design Spec：[项目名称]

## 1. 系统架构

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

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

// 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"
}

graph TD
    App --> Layout
    Layout --> Sidebar
    Layout --> MainArea
    MainArea --> BoardView
    BoardView --> Column[Column x3]
    Column --> TaskCard[TaskCard x N]
    TaskCard --> LabelBadge
    TaskCard --> PriorityBadge

**关键技巧**：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：任务管理看板

## 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

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

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

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

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

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

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

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

# 启动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

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

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

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

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

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

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

# 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。

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

参数：$ARGUMENTS

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

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

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

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

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

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

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