Claude Code工程化全流程：SDLC实战方法论

flowchart LR
    subgraph 传统SDLC
        A1[需求分析] --> A2[架构设计]
        A2 --> A3[编码实现]
        A3 --> A4[测试验证]
        A4 --> A5[部署上线]
        A5 --> A6[运维监控]
    end

    subgraph Claude Code增强SDLC
        B1[CLAUDE.md项目画像] --> B2[架构决策文档]
        B2 --> B3[分阶段Agent执行]
        B3 --> B4[自动化测试流水线]
        B4 --> B5[部署配置生成]
        B5 --> B6[监控与迭代反馈]
    end

    传统SDLC -.->|AI增强| Claude Code增强SDLC

my-project/
├── CLAUDE.md              # 全局层：项目概览、技术栈、通用规则
├── src/
│   ├── CLAUDE.md          # 源码层：编码规范、目录结构说明
│   ├── api/
│   │   └── CLAUDE.md      # 模块层：API设计规范、错误处理策略
│   └── components/
│       └── CLAUDE.md      # 模块层：组件规范、样式约定
├── tests/
│   └── CLAUDE.md          # 测试层：测试策略、覆盖率要求
└── infra/
    └── CLAUDE.md          # 基础设施层：部署配置、环境变量

# Project: TaskFlow - 任务管理SaaS平台

## 技术栈
- Backend: Node.js 20 + Fastify + TypeScript
- Frontend: Next.js 14 (App Router) + Tailwind CSS
- Database: PostgreSQL 16 + Prisma ORM
- Auth: NextAuth.js v5
- Cache: Redis 7

## 项目结构
- `/src/api/` — RESTful API路由和业务逻辑
- `/src/web/` — Next.js前端应用
- `/src/shared/` — 共享类型定义和工具函数
- `/prisma/` — 数据库Schema和迁移
- `/tests/` — 测试文件（按模块镜像源码结构）

## 编码规范
- TypeScript strict mode，禁止any类型
- 函数必须有JSDoc注释（仅导出函数）
- API响应统一使用 `{ success: boolean; data?: T; error?: string }` 格式
- 组件使用函数式组件 + hooks，禁止class组件
- 提交信息遵循Conventional Commits规范

## 构建与测试命令
- `pnpm dev` — 启动开发服务器
- `pnpm build` — 生产构建
- `pnpm test` — 运行所有测试
- `pnpm test:e2e` — 端到端测试
- `pnpm lint` — 代码检查
- `pnpm db:migrate` — 执行数据库迁移

## 架构决策
- 采用Repository模式隔离数据访问层
- 使用CQRS分离读写操作（任务查询频率远高于写入）
- Redis缓存热点查询结果，TTL设置为5分钟

## 关键约束
- 所有API端点必须包含认证中间件
- 数据库查询禁止N+1问题
- 前端包体积预算：首屏JS < 100KB（gzip后）
- 禁止修改 `/prisma/migrations/` 中已执行的迁移文件

# API模块规范

## 路由定义
- 每个资源一个路由文件：`routes/users.ts`, `routes/tasks.ts`
- 路由注册在 `index.ts` 中统一管理
- 使用Fastify schema validation定义请求/响应格式

## 错误处理
- 业务错误使用自定义 `AppError` 类
- 全局错误handler统一格式化响应
- HTTP状态码规范：200成功、201创建、400参数错误、401未认证、403无权限、404不存在、500服务器错误

## 性能要求
- 列表API必须支持分页（默认每页20条）
- 所有数据库查询必须在100ms内完成（EXPLAIN ANALYZE验证）

## Feature: 任务批量导入

### 用户故事
作为项目经理，我希望通过上传CSV文件批量创建任务，
以便快速初始化新项目的任务列表。

### 验收标准
1. 支持CSV格式（UTF-8编码，最大5MB）
2. CSV列映射：标题(必填)、描述(可选)、优先级(可选：高/中/低)、截止日期(可选)
3. 导入前显示预览（前10行），用户确认后执行
4. 部分失败不影响成功记录，返回失败明细
5. 导入完成后发送通知给项目负责人

### 技术约束
- 使用流式解析避免内存溢出（文件可能包含10万+行）
- 导入操作记录审计日志
- 导入频率限制：每用户每小时不超过10次

claude "请阅读 docs/features/batch-import.md 和 CLAUDE.md，
       将这个Feature拆解为具体的开发任务列表，
       按照依赖关系排序，输出为Markdown格式的任务清单"

## 开发任务清单

### Phase 1: 数据层（预计3个任务）
- [ ] T1: Prisma Schema添加ImportJob模型（存储导入任务状态）
- [ ] T2: CSV解析服务（流式处理 + 列映射验证）
- [ ] T3: 批量导入事务处理（部分失败容忍）

### Phase 2: API层（预计2个任务）
- [ ] T4: POST /api/imports 上传接口（文件验证 + 创建ImportJob）
- [ ] T5: GET /api/imports/:id 预览接口（返回前10行解析结果 + 统计）
- [ ] T6: POST /api/imports/:id/confirm 确认执行接口

### Phase 3: 前端层（预计3个任务）
- [ ] T7: CSV上传组件（拖拽 + 进度条）
- [ ] T8: 预览表格组件（展示解析结果 + 错误高亮）
- [ ] T9: 导入结果反馈组件（成功/失败统计 + 失败明细下载）

### Phase 4: 横切关注点（预计2个任务）
- [ ] T10: 审计日志记录（导入操作追踪）
- [ ] T11: 频率限制中间件（每用户每小时10次）

<!-- docs/adr/001-repository-pattern.md -->
# ADR-001: 采用Repository模式

## 状态
已采纳

## 上下文
TaskFlow需要支持多种数据源（PostgreSQL主库 + Redis缓存）。
直接在业务逻辑中编写数据库查询会导致：
- 数据访问逻辑散布在各处
- 切换或增加数据源时改动面大
- 单元测试需要mock整个数据库

## 决策
采用Repository模式，每个聚合根对应一个Repository类。
Repository接口定义在domain层，实现在infrastructure层。

## 影响
- 新增数据表必须创建对应Repository
- 禁止在Service层直接使用Prisma Client
- 测试可通过Mock Repository隔离数据库依赖

claude "根据CLAUDE.md和docs/adr/目录中的架构决策，
       生成TaskFlow的系统架构Mermaid图，
       包含数据流方向和关键组件之间的交互"

# 错误做法：一次会话做太多事
claude "帮我实现用户注册、登录、任务创建、任务列表、批量导入这五个功能"

# 正确做法：分阶段、单任务
claude "实现用户注册API，参考 CLAUDE.md 中的API规范和 /src/api/CLAUDE.md"

# 低效：纯指令驱动
claude "写一个用户注册API"

# 高效：上下文驱动
claude "请阅读以下文件后实现用户注册API：
- CLAUDE.md（项目规范）
- src/api/CLAUDE.md（API模块规范）
- prisma/schema.prisma（数据模型）
- src/api/routes/users.ts（现有用户路由，新路由需保持一致风格）"

claude "基于CLAUDE.md和ADR-001，为任务管理模块设计：
1. TaskService接口定义
2. TaskRepository接口定义
3. API路由规范（RESTful）
输出到 docs/interfaces/task-module.ts"

# 终端1：后端实现
claude "根据 docs/interfaces/task-module.ts 的接口定义，
       在 src/api/ 下实现TaskService和TaskRepository。
       遵循 src/api/CLAUDE.md 的规范，
       参考已有的 src/api/routes/users.ts 的代码风格"

# 终端2：前端实现（独立会话）
claude "根据 docs/interfaces/task-module.ts 的接口定义，
       在 src/web/components/tasks/ 下实现任务列表和创建组件。
       遵循 src/components/CLAUDE.md 的规范，
       使用Tailwind CSS，参考现有组件风格"

# 终端3：测试编写（独立会话）
claude "根据 docs/interfaces/task-module.ts 的接口定义，
       为TaskService和TaskRepository编写单元测试。
       遵循 tests/CLAUDE.md 的测试规范，
       覆盖正常流程、边界条件和错误场景"

# 当会话变长时，执行压缩
/compact

# 每完成一个独立功能点，立即提交
claude "将刚才完成的TaskService实现提交到git，
       使用feat(task)前缀的commit message"

# 不让Claude Code自己搜索，直接指定关键文件
claude "实现任务分配功能。你需要阅读以下文件：
@src/api/services/task.service.ts — 现有任务服务
@src/api/repositories/task.repository.ts — 数据访问层
@prisma/schema.prisma — 数据模型
不要阅读其他文件，仅基于这些文件实现。"

# 第一步：定义测试
claude "根据 docs/features/batch-import.md 的验收标准，
       为CSV批量导入功能编写测试用例。
       参考 tests/CLAUDE.md 的测试规范。
       先写测试，不写实现。"

# 第二步：运行测试（应该全部失败）
claude "运行 pnpm test -- tests/services/import.test.ts，
       确认所有测试都按预期失败"

# 第三步：逐步实现
claude "运行 pnpm test -- tests/services/import.test.ts --watch，
       然后逐步实现 src/api/services/import.service.ts，
       每实现一个功能点观察测试通过情况"

        /\
       /  \
      / E2E \           ← 少量，Claude Code生成Playwright脚本
     /------\
    /集成测试 \          ← 适量，API级别测试
   /----------\
  /  单元测试   \        ← 大量，Service和Repository层测试
 /--------------\

# 测试规范

## 测试框架
- 单元测试：Vitest + Testing Library
- API集成测试：Supertest + Vitest
- E2E测试：Playwright

## 命名规范
- 测试文件：`{source-file}.test.ts`
- describe块：使用 "当...时" 格式
- it块：使用 "应该..." 格式

## 覆盖率要求
- Service层：≥ 90%
- Repository层：≥ 80%
- API路由：≥ 70%
- 总体：≥ 80%

## Mock策略
- 单元测试：Mock Repository和外部依赖
- 集成测试：使用真实数据库（Docker测试容器）
- E2E测试：完整环境

claude "根据项目结构和CLAUDE.md中的技术栈，
       创建以下环境配置模板：
1. .env.example — 所有需要的环境变量列表（含注释说明）
2. docker-compose.yml — 本地开发环境（PostgreSQL + Redis）
3. docker-compose.prod.yml — 生产环境配置
4. .github/workflows/deploy.yml — 部署工作流（参考docs/adr/中的部署决策）"

claude "对项目进行生产就绪审查，检查以下方面：
1. 所有TODO/FIXME是否已处理
2. console.log是否已清理
3. 错误处理是否完善（无unhandled rejection）
4. 环境变量是否都有fallback值
5. 数据库查询是否使用了参数化（防SQL注入）
6. API是否都有认证和频率限制
7. 前端是否有XSS防护
输出检查结果和修复建议"

# 步骤1：创建项目并初始化
mkdir taskflow && cd taskflow
git init
claude /init  # Claude Code自动分析目录并生成初始CLAUDE.md

# 步骤2：完善CLAUDE.md（参考前面章节的模板）
claude "根据我要构建的TaskFlow项目需求，
       完善CLAUDE.md文件，包含完整的技术栈说明、
       项目结构、编码规范和构建命令"

# 步骤3：生成基础设施代码
claude "基于CLAUDE.md中的技术栈，创建：
1. package.json（含所有依赖）
2. tsconfig.json（strict模式）
3. docker-compose.yml（PostgreSQL 16 + Redis 7）
4. Prisma初始Schema（User, Task, Team三个核心模型）
5. ESLint + Prettier配置"

# 步骤4：验证基础设施
docker compose up -d
pnpm install
pnpm db:migrate
pnpm dev  # 确认开发服务器正常启动

# 独立会话：专注Auth模块
claude "实现用户认证模块，包括：
1. POST /api/auth/register — 注册（邮箱+密码，密码bcrypt加密）
2. POST /api/auth/login — 登录（返回JWT）
3. GET /api/auth/me — 获取当前用户信息
4. auth中间件 — 验证JWT并注入用户信息到请求上下文

参考文件：
- CLAUDE.md（全局规范）
- src/api/CLAUDE.md（API模块规范）
- prisma/schema.prisma（User模型）
- docs/adr/001-repository-pattern.md（Repository模式）

要求：
- 使用Repository模式
- 先写测试再写实现
- 错误处理遵循API模块规范中的HTTP状态码约定"

claude "查看git diff，将当前改动拆分为逻辑清晰的多个commit。
每个commit遵循Conventional Commits：
- feat(scope): 新功能
- fix(scope): Bug修复
- refactor(scope): 重构
- test(scope): 测试
- docs(scope): 文档"

claude "总结Phase 2完成的所有工作，包括：
1. 新增的API端点列表
2. 数据模型变更
3. 待解决的技术债
4. 下一Phase的前置依赖
输出到 docs/phase-reports/phase-2.md"

## 代码风格参考
参考 src/api/routes/users.ts 的代码风格。
所有新API路由必须保持与其一致的结构：
1. 路由定义在文件顶部
2. Schema验证紧随路由定义
3. 业务逻辑调用Service方法
4. 错误处理统一使用try-catch + AppError

## 测试矩阵模板
每个API端点必须覆盖以下场景：
- 正常流程（happy path）
- 参数验证失败（缺少必填字段、类型错误、格式错误）
- 权限验证（未认证、无权限）
- 业务规则违反（重复创建、超过限制）
- 并发场景（乐观锁冲突）
- 边界值（空列表、最大值、特殊字符）