多步骤复杂任务：从需求分析到 PR 提交

TL;DR: 本教程深入讲解如何使用 Claude Code 处理多步骤复杂开发任务，从需求分析、任务分解、逐步执行到最终 PR 提交。你将学会利用 Claude Code 的 200K 上下文窗口和 Git 集成能力，构建端到端的开发工作流，实现从自然语言需求到生产级代码变更的完整闭环。

📋 引言：为什么需要多步骤工作流？

在 Part 3 中，我们探讨了 Claude Code 的安全沙箱和审批模式。现在，是时候将这些能力整合到一个完整的工作流中——从原始需求到最终的 Pull Request。

现实中的开发任务很少是单一步骤的“修改这个函数”那么简单。典型场景包括：

功能开发：需求分析 → 架构设计 → 实现 → 测试 → 文档 → PR
代码重构：理解现有代码 → 制定重构计划 → 逐步重构 → 验证 → PR
Bug 修复：复现问题 → 定位根因 → 修复 → 回归测试 → PR

Claude Code 的强大之处在于，它不仅能执行单个任务，还能维护整个工作流的状态，在步骤之间传递上下文。这正是 200K 上下文窗口的真正价值所在。

学习目标

完成本教程后，你将能够：

✅ 使用 Claude Code 分析复杂需求并分解为可执行步骤
✅ 构建多步骤工作流，每一步都基于前一步的结果
✅ 利用 Git 集成进行精细的变更管理
✅ 自动生成高质量的 PR 描述和变更日志
✅ 处理工作流中的异常和回滚场景

🔧 场景设定：构建一个微服务 API 网关

为了演示多步骤工作流，我们将使用一个真实的复杂场景：为一个已有的微服务架构添加 API 网关层。

项目背景

假设我们有一个由三个微服务组成的电商系统：

project/
├── services/
│   ├── user-service/       # 用户管理 (Node.js + Express)
│   ├── product-service/    # 商品管理 (Node.js + Express)  
│   └── order-service/      # 订单管理 (Node.js + Express)
├── shared/
│   ├── middleware/         # 共享中间件
│   └── types/             # TypeScript 类型定义
└── docker-compose.yml

需求：添加 API 网关，统一处理认证、限流、日志和路由转发。

为什么这个场景适合演示？

多步骤：涉及架构决策、代码生成、测试、文档
跨文件操作：需要修改多个服务
需要 Git 集成：分阶段提交，每个步骤独立 PR
需要上下文理解：必须理解现有服务结构

📝 第一步：需求分析与任务分解

启动 Claude Code 会话

cd /path/to/project
claude

输入初始需求

我需要为这个微服务项目添加一个 API 网关层。需求如下：

1. 所有外部请求通过网关进入
2. 网关负责 JWT 认证验证
3. 实现基于 IP 的速率限制
4. 统一的请求日志记录
5. 路由转发到对应的微服务

请先分析项目结构，然后给出实现方案。

Claude Code 的响应分析

Claude Code 会首先扫描项目结构：

# Claude Code 自动执行
find . -name "*.js" -o -name "*.ts" -o -name "*.json" | head -50
cat docker-compose.yml
cat services/user-service/package.json

然后输出结构化的分析结果：

📊 项目分析完成：

发现 3 个微服务，均使用 Express 框架，端口分布：
- user-service: 3001
- product-service: 3002  
- order-service: 3003

现有中间件：
- shared/middleware/auth.js (基础 JWT 验证)
- shared/middleware/logger.js (请求日志)

建议方案：
1. 使用 http-proxy-middleware 作为代理层
2. 复用现有的 auth 和 logger 中间件
3. 新增 rate-limiter-flexible 实现限流
4. 网关部署在端口 8080

任务分解（建议顺序）：
1️⃣ 创建网关项目结构和配置
2️⃣ 实现认证中间件增强版
3️⃣ 实现速率限制中间件
4️⃣ 实现路由配置和代理转发
5️⃣ 集成日志和监控
6️⃣ 更新 Docker 配置
7️⃣ 编写测试
8️⃣ 生成文档和 PR

关键技巧：需求分析的最佳实践

💡 **专家提示**：在输入需求时，遵循以下原则：

1. **提供上下文**：先让 Claude Code 扫描项目结构
2. **明确边界**：指出哪些文件不能修改（如数据库 schema）
3. **指定优先级**：标注 MUST/SHOULD/COULD 级别需求
4. **提供示例**：如果可能，给出期望的输出格式

🏗️ 第二步：构建多步骤工作流

使用会话状态管理

Claude Code 维护一个会话状态，记录所有之前的操作和决策。我们可以利用这一点构建工作流。

创建工作流指令文件

创建一个 .claude-workflow.md 文件来定义工作流：

# API Gateway 实现工作流

## 步骤 1: 创建项目结构
- 创建 `services/gateway/` 目录
- 初始化 package.json
- 安装依赖: express, http-proxy-middleware, express-rate-limit, jsonwebtoken

## 步骤 2: 实现核心中间件
- 增强 auth 中间件 (支持角色验证)
- 实现 rate-limiter 中间件
- 实现 request-logger 中间件

## 步骤 3: 实现路由配置
- 创建 routes.config.js
- 配置代理转发规则
- 实现健康检查端点

## 步骤 4: 集成与测试
- 更新 docker-compose.yml
- 编写集成测试
- 手动验证端到端流程

## 步骤 5: 文档与 PR
- 生成 API 文档
- 创建 CHANGELOG.md
- 提交 PR

执行工作流

步骤 1：创建项目结构

# 让 Claude Code 执行步骤 1
claude> 请执行工作流的步骤 1：创建网关项目结构

# Claude Code 会执行：
mkdir -p services/gateway/src/{middleware,routes,config}
cd services/gateway
npm init -y
npm install express http-proxy-middleware express-rate-limit jsonwebtoken

Claude Code 的输出：

✅ 步骤 1 完成

创建的文件：
- services/gateway/package.json
- services/gateway/src/config/index.js (占位)

依赖已安装：
- [email protected]
- [email protected]
- [email protected]
- [email protected]

步骤 2：实现核心中间件

claude> 现在执行步骤 2：实现核心中间件。请参考 shared/middleware/auth.js 的现有实现，创建增强版本。

Claude Code 会分析现有代码：

// shared/middleware/auth.js (现有代码)
const jwt = require('jsonwebtoken');

module.exports = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'No token provided' });
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid token' });
  }
};

然后生成增强版本：

// services/gateway/src/middleware/auth.js
const jwt = require('jsonwebtoken');

/**
 * 增强的认证中间件
 * 支持角色验证和令牌刷新
 */
class AuthMiddleware {
  constructor(config) {
    this.secret = config.jwtSecret;
    this.allowedRoles = config.allowedRoles || [];
    this.tokenRefreshEndpoint = config.tokenRefreshEndpoint;
  }

  validate = (req, res, next) => {
    const token = this._extractToken(req);
    if (!token) {
      return res.status(401).json({
        error: 'AUTH_REQUIRED',
        message: 'Authentication token is required'
      });
    }

    try {
      const decoded = jwt.verify(token, this.secret, {
        algorithms: ['HS256'],
        maxAge: '1h'
      });

      // 角色验证
      if (this.allowedRoles.length > 0) {
        if (!this.allowedRoles.includes(decoded.role)) {
          return res.status(403).json({
            error: 'FORBIDDEN',
            message: `Requires one of roles: ${this.allowedRoles.join(', ')}`
          });
        }
      }

      req.user = decoded;
      req.token = token;
      next();
    } catch (err) {
      if (err.name === 'TokenExpiredError') {
        return res.status(401).json({
          error: 'TOKEN_EXPIRED',
          message: 'Token has expired',
          refreshEndpoint: this.tokenRefreshEndpoint
        });
      }
      return res.status(401).json({
        error: 'INVALID_TOKEN',
        message: 'Invalid or malformed token'
      });
    }
  };

  _extractToken(req) {
    const authHeader = req.headers.authorization;
    if (!authHeader) return null;
    
    const parts = authHeader.split(' ');
    if (parts.length !== 2 || parts[0] !== 'Bearer') return null;
    
    return parts[1];
  }
}

module.exports = AuthMiddleware;

步骤 3：实现路由配置

claude> 现在执行步骤 3。请分析现有服务的路由结构，生成对应的网关路由配置。

Claude Code 会扫描现有服务：

# 自动分析路由
grep -r "router\." services/user-service/routes/
grep -r "app\.get\|app\.post\|app\.put\|app\.delete" services/*/src/

生成路由配置：

// services/gateway/src/config/routes.js
const ROUTES = {
  // 用户服务路由
  '/api/users': {
    target: 'http://user-service:3001',
    auth: true,
    rateLimit: { windowMs: 60000, max: 100 },
    methods: ['GET', 'POST', 'PUT', 'DELETE']
  },
  '/api/auth': {
    target: 'http://user-service:3001',
    auth: false,  // 登录注册不需要认证
    rateLimit: { windowMs: 60000, max: 20 },  // 更严格的限流
    methods: ['POST']
  },
  
  // 商品服务路由
  '/api/products': {
    target: 'http://product-service:3002',
    auth: false,  // 商品查询不需要认证
    rateLimit: { windowMs: 60000, max: 200 },
    methods: ['GET']
  },
  '/api/products/manage': {
    target: 'http://product-service:3002',
    auth: true,
    roles: ['admin', 'manager'],
    rateLimit: { windowMs: 60000, max: 50 },
    methods: ['POST', 'PUT', 'DELETE']
  },
  
  // 订单服务路由
  '/api/orders': {
    target: 'http://order-service:3003',
    auth: true,
    rateLimit: { windowMs: 60000, max: 60 },
    methods: ['GET', 'POST']
  }
};

module.exports = ROUTES;

🔄 第三步：Git 集成与分阶段提交

为什么需要分阶段提交？

在多步骤工作流中，每个步骤应该是一个独立的 Git 提交。这样做的好处：

可追溯：每个变更都有明确的上下文
可回滚：如果某一步出错，只需回滚该步骤
代码审查：PR 中的每个提交都有清晰的变更说明

配置 Git 工作流

# 创建功能分支
git checkout -b feature/api-gateway

# 步骤 1 提交
git add services/gateway/package.json services/gateway/src/config/
git commit -m "feat(gateway): initialize API gateway project structure

- Created gateway service directory structure
- Added express, http-proxy-middleware, express-rate-limit dependencies
- Set up base configuration files"

# 步骤 2 提交
git add services/gateway/src/middleware/
git commit -m "feat(gateway): implement enhanced auth middleware

- Added JWT validation with HS256 algorithm
- Implemented role-based access control
- Added token expiration handling with refresh endpoint
- Created rate limiter and request logger middleware"

让 Claude Code 管理 Git 操作

claude> 请为步骤 1 和步骤 2 创建 Git 提交，使用规范的 commit message 格式。

Claude Code 会执行：

git add services/gateway/
git commit -m "feat(gateway): implement core gateway components

- Add project structure and dependencies
- Implement enhanced authentication middleware with role-based access
- Add rate limiting middleware using express-rate-limit
- Create request logging middleware with structured logging
- Configure route definitions for all microservices

Closes: #42"

高级 Git 操作

交互式变基

claude> 我需要将步骤 2-4 的提交合并为一个提交，请执行交互式变基。

git rebase -i HEAD~3
# Claude Code 会自动执行 squash 操作

处理冲突

claude> 我遇到了合并冲突，请帮我分析并解决。

Claude Code 会：

分析冲突文件
显示冲突内容
提供解决方案
执行 git add 和 git commit

🧪 第四步：测试与验证

生成测试用例

claude> 请为网关生成集成测试，覆盖以下场景：
1. 正常路由转发
2. 认证失败
3. 速率限制
4. 健康检查

Claude Code 会生成：

// services/gateway/tests/integration/gateway.test.js
const request = require('supertest');
const jwt = require('jsonwebtoken');
const app = require('../src/app');

describe('API Gateway Integration Tests', () => {
  let server;
  let authToken;

  beforeAll(async () => {
    server = app.listen(8080);
    
    // 生成测试 token
    authToken = jwt.sign(
      { userId: 1, role: 'user' },
      process.env.JWT_SECRET,
      { expiresIn: '1h' }
    );
  });

  afterAll(async () => {
    await server.close();
  });

  describe('Health Check', () => {
    it('should return 200 for health endpoint', async () => {
      const response = await request(server)
        .get('/health')
        .expect(200);
      
      expect(response.body).toHaveProperty('status', 'ok');
      expect(response.body).toHaveProperty('timestamp');
    });
  });

  describe('Authentication', () => {
    it('should reject requests without token', async () => {
      await request(server)
        .get('/api/users/profile')
        .expect(401)
        .expect(res => {
          expect(res.body.error).toBe('AUTH_REQUIRED');
        });
    });

    it('should accept valid token', async () => {
      await request(server)
        .get('/api/users/profile')
        .set('Authorization', `Bearer ${authToken}`)
        .expect(200);
    });

    it('should reject expired token', async () => {
      const expiredToken = jwt.sign(
        { userId: 1 },
        process.env.JWT_SECRET,
        { expiresIn: '0s' }
      );

      await request(server)
        .get('/api/users/profile')
        .set('Authorization', `Bearer ${expiredToken}`)
        .expect(401)
        .expect(res => {
          expect(res.body.error).toBe('TOKEN_EXPIRED');
        });
    });
  });

  describe('Rate Limiting', () => {
    it('should enforce rate limits', async () => {
      const requests = Array(25).fill().map(() => 
        request(server)
          .post('/api/auth/login')
          .send({ username: 'test', password: 'test' })
      );

      const responses = await Promise.all(requests);
      const rateLimited = responses.filter(r => r.status === 429);
      
      expect(rateLimited.length).toBeGreaterThan(0);
    });
  });

  describe('Routing', () => {
    it('should proxy requests to correct service', async () => {
      const response = await request(server)
        .get('/api/products')
        .expect(200);
      
      // 验证响应来自 product-service
      expect(response.headers['x-service-name']).toBe('product-service');
    });

    it('should return 404 for unknown routes', async () => {
      await request(server)
        .get('/api/unknown')
        .expect(404);
    });
  });
});

运行测试

claude> 请运行测试并分析结果

cd services/gateway
npm test

# 输出示例
PASS  tests/integration/gateway.test.js
  ✓ Health Check (12ms)
  ✓ Authentication - reject without token (8ms)
  ✓ Authentication - accept valid token (15ms)
  ✓ Authentication - reject expired token (9ms)
  ✓ Rate Limiting - enforce limits (245ms)
  ✓ Routing - proxy to correct service (89ms)
  ✓ Routing - return 404 for unknown (5ms)

Tests: 7 passed, 7 total
Time: 1.234s

📄 第五步：文档生成与 PR 提交

自动生成 API 文档

claude> 请根据路由配置和中间件实现，生成 API 文档。

Claude Code 会生成：

# API Gateway Documentation

## Overview
API Gateway provides unified access to microservices with authentication,
rate limiting, and request logging.

## Base URL
`http://gateway:8080`

## Authentication
All protected endpoints require JWT token in Authorization header:

Authorization: Bearer


## Endpoints

### Health Check

GET /health Response: { “status”: “ok”, “timestamp”: “2026-07-15T10:30:00Z” }


### User Service
| Endpoint | Method | Auth | Rate Limit | Description |
|----------|--------|------|------------|-------------|
| /api/users | GET | Yes | 100/min | List users |
| /api/users/:id | GET | Yes | 100/min | Get user by ID |
| /api/auth/login | POST | No | 20/min | User login |
| /api/auth/register | POST | No | 20/min | User registration |

### Product Service
| Endpoint | Method | Auth | Rate Limit | Description |
|----------|--------|------|------------|-------------|
| /api/products | GET | No | 200/min | List products |
| /api/products/:id | GET | No | 200/min | Get product |
| /api/products/manage | POST | Admin | 50/min | Create product |

### Order Service
| Endpoint | Method | Auth | Rate Limit | Description |
|----------|--------|------|------------|-------------|
| /api/orders | GET | Yes | 60/min | List orders |
| /api/orders | POST | Yes | 60/min | Create order |

## Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| AUTH_REQUIRED | 401 | No authentication token |
| TOKEN_EXPIRED | 401 | Token has expired |
| FORBIDDEN | 403 | Insufficient permissions |
| RATE_LIMITED | 429 | Too many requests |

生成 CHANGELOG

claude> 请根据 Git 提交历史生成 CHANGELOG.md

# Changelog

## [1.0.0] - 2026-07-15

### Added
- API Gateway service with Express.js
- JWT authentication with role-based access control
- Rate limiting per endpoint configuration
- Structured request logging
- Route proxying to microservices
- Health check endpoint
- Docker Compose integration

### Changed
- Updated docker-compose.yml to include gateway service
- Modified service ports to internal-only access

### Security
- Enhanced JWT validation with algorithm whitelist
- Added token expiration handling
- Implemented rate limiting to prevent abuse

创建 PR

claude> 请创建 PR 描述，包括以下内容：
- 变更概述
- 架构决策记录
- 测试结果
- 部署注意事项

Claude Code 会生成完整的 PR 描述：

## 📋 Pull Request: Add API Gateway Layer

### Overview
This PR introduces an API Gateway layer that provides unified access to
our microservices architecture. All external traffic now routes through
the gateway, which handles authentication, rate limiting, and logging.

### Architecture Decision Records

**ADR-001: Gateway Technology**
- **Decision**: Express.js with http-proxy-middleware
- **Rationale**: Consistent with existing service stack, minimal learning curve
- **Alternatives considered**: Kong (overkill for current scale), Nginx (different config format)

**ADR-002: Rate Limiting Strategy**
- **Decision**: Per-endpoint rate limits with sliding window
- **Rationale**: Different endpoints have different traffic patterns
- **Implementation**: express-rate-limit with Redis store (future)

### Changes Summary

| Component | Files Changed | Lines Added | Lines Removed |
|-----------|--------------|-------------|---------------|
| Gateway Service | 12 | 845 | 0 |
| Docker Config | 1 | 15 | 3 |
| Documentation | 2 | 120 | 0 |

### Test Results

Tests: 7 passed, 7 total Coverage: 92% lines, 88% branches


### Deployment Notes
1. Add `JWT_SECRET` environment variable to gateway service
2. Update DNS records to point to gateway (port 8080)
3. Internal services should only accept traffic from gateway
4. Monitor rate limit metrics in first 24 hours

### Related Issues
Closes #42, #45, #48

🚨 常见陷阱与故障排除

陷阱 1：上下文丢失

问题：长时间会话后，Claude Code 忘记之前的上下文

解决方案：

# 保存关键决策到文件
echo "## Session Context" > .claude-context.md
echo "Decision: Use express-rate-limit over rate-limiter-flexible" >> .claude-context.md
echo "Reason: Simpler API, sufficient for current scale" >> .claude-context.md

# 在后续会话中加载
claude> 请读取 .claude-context.md 恢复上下文

陷阱 2：过度提交

问题：每个小改动都创建提交，导致 Git 历史混乱

解决方案：

claude> 请将最近 5 个提交 squash 为一个有意义的提交

陷阱 3：测试覆盖不足

问题：生成的测试只覆盖 happy path

解决方案：

claude> 请为以下边缘场景添加测试：
1. 并发请求下的竞争条件
2. 服务不可用时的优雅降级
3. 无效的 JWT 格式
4. 请求体过大

陷阱 4：依赖冲突

问题：新安装的依赖与现有版本冲突

解决方案：

claude> 请检查依赖版本兼容性，并在 package.json 中锁定版本

💡 关键要点

工作流驱动开发：使用 .claude-workflow.md 定义和执行复杂任务序列
分阶段提交：每个逻辑步骤对应一个 Git 提交，便于追踪和回滚
上下文持久化：将关键决策保存到文件中，避免会话间上下文丢失
测试先行：在实现功能前先生成测试用例，确保代码质量
PR 自动化：利用 Claude Code 生成结构化的 PR 描述和变更日志

❓ FAQ

Q1: 如何处理工作流中的错误？ A: 使用 claude> 请回滚到步骤 N 回退到特定步骤。Claude Code 会执行 git reset --hard 到对应提交。

Q2: 多个开发者如何协作同一个工作流？ A: 将 .claude-workflow.md 提交到仓库，每个开发者在自己的分支上执行工作流。使用 claude> 请同步上游变更 处理冲突。

Q3: 工作流可以嵌套吗？ A: 可以。主工作流可以包含子工作流。例如，步骤 2 “实现中间件” 可以有自己的子工作流（设计 → 实现 → 测试）。

Q4: 如何确保生成的代码符合团队规范？ A: 在 .claude-workflow.md 中添加规范要求，例如 “所有函数必须有 JSDoc 注释” 或 “使用 async/await 而非回调”。

Q5: 大型工作流（50+ 步骤）如何管理？ A: 将工作流拆分为多个阶段文件（如 workflow-phase1.md），每个阶段完成后提交并创建标签。

🔮 下一步预告

在 Part 5（本系列最后一篇）中，我们将探索 Claude Code 的高级集成与自定义工作流：

自定义 MCP 服务器：扩展 Claude Code 的能力
CI/CD 集成：在 GitHub Actions 中运行 Claude Code
多项目工作流：同时管理多个仓库的变更
性能优化：处理 500K+ 文件的大型 monorepo

本教程是 Smartotics Blog 的 “Claude Code 深度指南” 系列的第 4 部分。查看 Part 1: 入门指南、Part 2: 200K 上下文窗口和 Part 3: 安全沙箱与审批模式。

Have questions? Join our Discord community or follow us on X.

Claude Code Deep Dive — Complete Developer Guide

多步骤复杂任务：从需求分析到 PR 提交

📋 引言：为什么需要多步骤工作流？

学习目标

🔧 场景设定：构建一个微服务 API 网关

项目背景

为什么这个场景适合演示？

📝 第一步：需求分析与任务分解

启动 Claude Code 会话

输入初始需求

Claude Code 的响应分析

关键技巧：需求分析的最佳实践

🏗️ 第二步：构建多步骤工作流

使用会话状态管理

创建工作流指令文件

执行工作流

步骤 1：创建项目结构

步骤 2：实现核心中间件

步骤 3：实现路由配置

🔄 第三步：Git 集成与分阶段提交

为什么需要分阶段提交？

配置 Git 工作流

让 Claude Code 管理 Git 操作

高级 Git 操作

交互式变基

处理冲突

🧪 第四步：测试与验证

生成测试用例

运行测试

📄 第五步：文档生成与 PR 提交

自动生成 API 文档

生成 CHANGELOG

创建 PR

🚨 常见陷阱与故障排除

陷阱 1：上下文丢失

陷阱 2：过度提交

陷阱 3：测试覆盖不足

陷阱 4：依赖冲突

💡 关键要点

❓ FAQ

🔮 下一步预告