Claude Code

Appearance

规划师 (Planner) ​

规划师是 Claude Code 的战略规划专家，专门负责功能规划、需求分析、技术设计和开发任务分解。在任何新功能开发之前，规划师都是您的第一站。

核心职责 ​

主要能力 ​

  • 需求分析: 深入理解用户需求，转化为技术规格
  • 功能设计: 创建详细的功能设计文档和用户故事
  • 技术设计: 制定技术架构和实现方案
  • 任务分解: 将复杂功能拆分为可执行的开发任务

专业领域 ​

  • 产品功能规划
  • 用户体验设计
  • 技术架构决策
  • 项目任务管理

使用场景 ​

何时使用规划师 ​

适合的场景 ​

bash
# 新功能规划
"我需要添加用户认证功能"

# 需求分析
"我想设计一个电商购物车系统"

# 技术方案选择
"如何实现一个高性能的消息推送系统？"

# 项目任务分解
"将这个复杂功能拆分成具体的开发任务"

不适合的场景 ​

bash
# 代码实现 (应使用执行器)
"实现这个登录API接口"

# 代码调试 (应使用调试器)  
"修复这个数据库连接错误"

# 代码审查 (应使用审查员)
"检查这段代码的性能问题"

工作流程 ​

规划师采用严格的三阶段交互式流程，每个阶段都需要用户明确确认才能进入下一阶段。

阶段 0: 功能类型确定 ​

新功能流程 ​

bash
用户: "我需要添加用户认证功能"
规划师: "我将为'用户认证'功能创建规划。请提供一个kebab-case格式的功能名称"
用户: "user-authentication"
规划师: "好的，我将创建 specs/user-authentication/ 目录并开始需求分析"

现有功能流程 ​

bash
用户: "我想优化之前规划的用户认证功能"
规划师: "我找到了现有的 user-authentication 规格，您想要优化哪个阶段？"
- 需求定义 (requirements.md)
- 技术设计 (design.md)  
- 任务分解 (tasks.md)

阶段 1: 需求定义 ​

生成需求文档 ​

规划师会创建符合 EARS 语法的需求文档：

markdown
# 用户认证功能需求

## 用户故事

### 用户注册
**作为** 新用户  
**我想要** 使用邮箱和密码注册账户  
**以便** 我可以访问应用的个性化功能

**验收标准:**
- **Given** 用户在注册页面 **When** 输入有效邮箱和密码 **Then** 系统应该创建新账户
- **Given** 用户输入重复邮箱 **When** 尝试注册 **Then** 系统应该显示"邮箱已存在"错误
- **Given** 用户输入弱密码 **When** 尝试注册 **Then** 系统应该显示密码强度要求

### 用户登录
**作为** 注册用户  
**我想要** 使用邮箱和密码登录  
**以便** 我可以访问我的个人账户

**验收标准:**
- **Given** 用户输入正确凭据 **When** 点击登录 **Then** 系统应该验证并登录用户
- **Given** 用户输入错误密码 **When** 尝试登录 **Then** 系统应该显示"凭据无效"错误
- **Given** 用户连续3次登录失败 **When** 再次尝试 **Then** 系统应该暂时锁定账户

## 功能需求

### FR-1: 用户注册
系统应该允许用户使用邮箱地址和密码创建新账户。

### FR-2: 用户登录
系统应该验证用户凭据并建立安全会话。

### FR-3: 密码重置
系统应该提供通过邮箱重置密码的机制。

## 非功能需求

### NFR-1: 安全性
- 密码必须使用BCrypt或Argon2进行哈希存储
- 会话令牌应该有合理的过期时间
- 支持HTTPS传输加密

### NFR-2: 性能
- 登录请求应该在2秒内响应
- 支持并发1000个用户登录
- 数据库查询应该有适当的索引优化

### NFR-3: 可用性
- 登录界面应该简洁直观
- 错误信息应该清晰明确
- 支持"记住我"功能

交互式优化过程 ​

bash
规划师: "我已经生成了初步的需求文档。让我重点询问几个关键问题：

1. 除了邮箱密码登录，是否需要支持第三方登录（如Google、Facebook）？
2. 密码复杂度要求是什么？（最小长度、特殊字符等）
3. 用户会话应该保持多长时间？
4. 是否需要双因素认证（2FA）？
5. 用户角色权限是否有不同级别？"

用户: "需要支持Google登录，密码至少8位包含数字，会话保持7天，暂不需要2FA"

规划师: "好的，我将更新需求文档包含这些信息。还有其他需要补充的吗？"

阶段 2: 技术设计 ​

确认需求后，规划师进入技术设计阶段：

markdown
# 用户认证技术设计

## 系统架构

### 组件概览
```mermaid
graph TB
    A[前端应用] --> B[认证服务]
    B --> C[用户数据库]
    B --> D[会话存储Redis]
    B --> E[邮件服务]
    B --> F[Google OAuth API]

数据模型 ​

User 表 ​

sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255),
  display_name VARCHAR(100),
  avatar_url TEXT,
  email_verified BOOLEAN DEFAULT FALSE,
  google_id VARCHAR(255) UNIQUE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Session 表 ​

sql
CREATE TABLE user_sessions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  token_hash VARCHAR(255) NOT NULL,
  expires_at TIMESTAMP NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

API 设计 ​

认证端点 ​

POST /api/auth/register ​

请求体:

json
{
  "email": "user@example.com",
  "password": "securePassword123",
  "displayName": "John Doe"
}

响应:

json
{
  "success": true,
  "user": {
    "id": "uuid",
    "email": "user@example.com", 
    "displayName": "John Doe"
  },
  "token": "jwt-token"
}

POST /api/auth/login ​

请求体:

json
{
  "email": "user@example.com",
  "password": "securePassword123",
  "rememberMe": true
}

响应:

json
{
  "success": true,
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "displayName": "John Doe"
  },
  "token": "jwt-token",
  "expiresAt": "2024-01-01T00:00:00Z"
}

GET /api/auth/google ​

重定向到Google OAuth授权页面

GET /api/auth/google/callback ​

处理Google OAuth回调并创建用户会话

前端组件设计 ​

组件层次结构 ​

text
AuthProvider
├── LoginPage
│   ├── LoginForm
│   ├── GoogleLoginButton
│   └── ResetPasswordLink
├── RegisterPage
│   ├── RegisterForm
│   └── PasswordStrengthIndicator
└── AuthGuard (路由保护)

状态管理 ​

typescript
interface AuthState {
  user: User | null;
  token: string | null;
  isLoading: boolean;
  error: string | null;
}

interface AuthActions {
  login: (email: string, password: string) => Promise<void>;
  register: (userData: RegisterData) => Promise<void>;
  logout: () => void;
  loginWithGoogle: () => Promise<void>;
  resetPassword: (email: string) => Promise<void>;
}

安全考虑 ​

密码安全 ​

  • 使用 BCrypt 哈希，工作因子至少为12
  • 实施密码强度验证
  • 防止密码重用（存储历史哈希）

会话管理 ​

  • JWT令牌包含最小必要信息
  • 实施令牌刷新机制
  • 支持令牌撤销

攻击防护 ​

  • 实施登录速率限制
  • CSRF保护
  • SQL注入防护
  • XSS防护

技术决策讨论 ​

bash
规划师: "在技术设计中，我需要您确认几个关键决策：

1. **数据库选择**: 我建议使用PostgreSQL，您是否同意？
2. **会话存储**: 建议使用Redis存储会话，提高性能
3. **JWT vs Session**: 我建议使用JWT令牌，便于无状态扩展
4. **前端状态管理**: 建议使用Context API + useReducer

您对这些技术选择有什么看法吗？"

用户: "PostgreSQL和Redis都可以，但前端我们使用的是Zustand状态管理"

规划师: "好的，我将更新设计文档，使用Zustand进行前端状态管理"

阶段 3: 任务分解 ​

最后阶段是将设计转化为具体的开发任务：

markdown
# 用户认证功能开发任务

## 任务概览
总估时：约 3-4 周  
优先级：P0 (最高)  
依赖：数据库设计、API规范

## 后端任务

### 1. 数据库设计和迁移
- [ ] 1.1 设计用户表结构
  - [ ] 1.1.1 创建users表迁移文件
  - [ ] 1.1.2 创建user_sessions表迁移文件
  - [ ] 1.1.3 添加必要的索引和约束
- [ ] 1.2 运行数据库迁移
- [ ] 1.3 编写数据库种子文件（测试数据）

### 2. 用户模型和数据访问层
- [ ] 2.1 创建User实体类
  - [ ] 2.1.1 定义用户属性和验证规则
  - [ ] 2.1.2 实现密码哈希方法
  - [ ] 2.1.3 添加邮箱验证逻辑
- [ ] 2.2 创建UserRepository
  - [ ] 2.2.1 实现用户CRUD操作
  - [ ] 2.2.2 实现按邮箱查找用户
  - [ ] 2.2.3 实现Google用户关联查找
- [ ] 2.3 创建SessionRepository
  - [ ] 2.3.1 实现会话创建和验证
  - [ ] 2.3.2 实现会话过期清理
  - [ ] 2.3.3 实现会话撤销功能

### 3. 认证服务层
- [ ] 3.1 创建AuthService
  - [ ] 3.1.1 实现用户注册逻辑
  - [ ] 3.1.2 实现用户登录验证
  - [ ] 3.1.3 实现密码重置功能
- [ ] 3.2 创建JWTService
  - [ ] 3.2.1 实现JWT令牌生成
  - [ ] 3.2.2 实现JWT令牌验证
  - [ ] 3.2.3 实现令牌刷新机制
- [ ] 3.3 创建GoogleOAuthService
  - [ ] 3.3.1 配置Google OAuth客户端
  - [ ] 3.3.2 实现OAuth回调处理
  - [ ] 3.3.3 实现用户信息获取和关联

### 4. API控制器
- [ ] 4.1 创建AuthController
  - [ ] 4.1.1 实现注册端点 POST /api/auth/register
  - [ ] 4.1.2 实现登录端点 POST /api/auth/login
  - [ ] 4.1.3 实现登出端点 POST /api/auth/logout
  - [ ] 4.1.4 实现用户信息端点 GET /api/auth/me
- [ ] 4.2 实现Google OAuth端点
  - [ ] 4.2.1 实现OAuth重定向 GET /api/auth/google
  - [ ] 4.2.2 实现OAuth回调 GET /api/auth/google/callback
- [ ] 4.3 实现密码重置端点
  - [ ] 4.3.1 发送重置邮件 POST /api/auth/reset-password
  - [ ] 4.3.2 确认重置密码 POST /api/auth/confirm-reset

### 5. 中间件和安全
- [ ] 5.1 创建认证中间件
  - [ ] 5.1.1 JWT令牌验证中间件
  - [ ] 5.1.2 用户权限检查中间件
- [ ] 5.2 实现安全措施
  - [ ] 5.2.1 登录速率限制
  - [ ] 5.2.2 CSRF保护
  - [ ] 5.2.3 输入验证和清理

## 前端任务

### 6. 状态管理设置
- [ ] 6.1 配置Zustand存储
  - [ ] 6.1.1 创建认证状态store
  - [ ] 6.1.2 定义用户状态类型
  - [ ] 6.1.3 实现状态持久化
- [ ] 6.2 创建认证actions
  - [ ] 6.2.1 实现登录action
  - [ ] 6.2.2 实现注册action
  - [ ] 6.2.3 实现登出action

### 7. API集成层
- [ ] 7.1 创建认证API客户端
  - [ ] 7.1.1 配置HTTP客户端（Axios/Fetch）
  - [ ] 7.1.2 实现请求拦截器（自动添加token）
  - [ ] 7.1.3 实现响应拦截器（处理认证错误）
- [ ] 7.2 实现API方法
  - [ ] 7.2.1 登录API调用
  - [ ] 7.2.2 注册API调用
  - [ ] 7.2.3 Google登录API调用
  - [ ] 7.2.4 密码重置API调用

### 8. UI组件开发
- [ ] 8.1 创建认证表单组件
  - [ ] 8.1.1 LoginForm组件
    - [ ] 8.1.1.1 邮箱密码输入字段
    - [ ] 8.1.1.2 表单验证逻辑
    - [ ] 8.1.1.3 错误状态显示
  - [ ] 8.1.2 RegisterForm组件
    - [ ] 8.1.2.1 注册字段设计
    - [ ] 8.1.2.2 密码强度指示器
    - [ ] 8.1.2.3 条款同意选择
- [ ] 8.2 创建第三方登录组件
  - [ ] 8.2.1 GoogleLoginButton组件
  - [ ] 8.2.2 处理OAuth回调页面
- [ ] 8.3 创建密码重置组件
  - [ ] 8.3.1 ResetPasswordForm组件
  - [ ] 8.3.2 重置确认页面

### 9. 页面和路由
- [ ] 9.1 创建认证页面
  - [ ] 9.1.1 登录页面 /login
  - [ ] 9.1.2 注册页面 /register
  - [ ] 9.1.3 密码重置页面 /reset-password
- [ ] 9.2 实现路由保护
  - [ ] 9.2.1 AuthGuard组件（保护需要登录的路由）
  - [ ] 9.2.2 GuestGuard组件（登录用户重定向）
- [ ] 9.3 实现自动重定向逻辑

### 10. 用户体验优化
- [ ] 10.1 加载状态管理
  - [ ] 10.1.1 登录/注册按钮loading状态
  - [ ] 10.1.2 页面级loading指示器
- [ ] 10.2 错误处理和提示
  - [ ] 10.2.1 表单验证错误显示
  - [ ] 10.2.2 网络错误处理
  - [ ] 10.2.3 成功消息提示
- [ ] 10.3 用户反馈优化
  - [ ] 10.3.1 邮箱验证提醒
  - [ ] 10.3.2 密码重置成功提示

## 测试任务

### 11. 后端测试
- [ ] 11.1 单元测试
  - [ ] 11.1.1 AuthService测试
  - [ ] 11.1.2 UserRepository测试
  - [ ] 11.1.3 JWTService测试
- [ ] 11.2 集成测试
  - [ ] 11.2.1 认证API端点测试
  - [ ] 11.2.2 数据库集成测试
- [ ] 11.3 安全测试
  - [ ] 11.3.1 SQL注入测试
  - [ ] 11.3.2 认证绕过测试

### 12. 前端测试
- [ ] 12.1 组件测试
  - [ ] 12.1.1 LoginForm组件测试
  - [ ] 12.1.2 RegisterForm组件测试
- [ ] 12.2 集成测试
  - [ ] 12.2.1 登录流程端到端测试
  - [ ] 12.2.2 注册流程端到端测试
- [ ] 12.3 用户体验测试
  - [ ] 12.3.1 表单验证测试
  - [ ] 12.3.2 错误处理测试

## 部署和配置

### 13. 环境配置
- [ ] 13.1 开发环境配置
  - [ ] 13.1.1 数据库连接配置
  - [ ] 13.1.2 Google OAuth应用设置
  - [ ] 13.1.3 邮件服务配置
- [ ] 13.2 生产环境准备
  - [ ] 13.2.1 环境变量配置
  - [ ] 13.2.2 SSL证书配置
  - [ ] 13.2.3 Redis集群配置

### 14. 监控和日志
- [ ] 14.1 实现认证日志
  - [ ] 14.1.1 登录尝试日志
  - [ ] 14.1.2 安全事件日志
- [ ] 14.2 设置监控指标
  - [ ] 14.2.1 登录成功率监控
  - [ ] 14.2.2 API响应时间监控

## 验收标准

### 功能验收
- [ ] 用户可以使用邮箱密码成功注册和登录
- [ ] Google登录功能正常工作
- [ ] 密码重置流程完整可用
- [ ] 会话管理正确（过期、刷新、撤销）
- [ ] 错误处理用户友好

### 性能验收
- [ ] 登录响应时间 < 2秒
- [ ] 支持1000并发用户
- [ ] 数据库查询优化（索引使用）

### 安全验收
- [ ] 密码正确哈希存储
- [ ] JWT令牌安全实现
- [ ] 防护常见攻击（SQL注入、XSS、CSRF）
- [ ] 通过安全审计

## 发布计划

### 第一阶段 (Week 1-2): 核心功能
- 完成任务 1-7: 后端基础和API
- 完成任务 8-9: 前端基础UI

### 第二阶段 (Week 2-3): 增强功能  
- 完成任务 10: 用户体验优化
- 完成任务 11-12: 测试覆盖

### 第三阶段 (Week 3-4): 部署上线
- 完成任务 13-14: 部署和监控
- 完成全部验收标准
- 生产环境发布

使用技巧 ​

1. 明确需求表达 ​

bash
# 模糊的需求
"我需要一个登录功能"

# 具体的需求  
"我需要为电商应用添加用户认证功能，支持邮箱密码登录和Google第三方登录，包含注册、密码重置功能"

2. 分阶段确认 ​

规划师严格按阶段工作，每个阶段都需要您的确认：

bash
规划师: "需求分析完成，请确认是否可以进入技术设计阶段？"
用户: "确认，可以进入下一阶段"
规划师: "好的，开始技术设计..."

3. 迭代优化 ​

每个阶段都支持反复优化：

bash
用户: "需求文档中缺少邮箱验证功能"
规划师: "好的，我将在需求文档中添加邮箱验证相关的用户故事和验收标准"

4. 利用项目上下文 ​

确保规划师了解您的项目背景：

bash
# 提供项目信息
"这是一个Flutter移动应用，后端使用Node.js和PostgreSQL"

# 引用现有文档
"请参考 @.ai-rules/tech.md 了解我们的技术栈"

高级功能 ​

1. 需求模板 ​

规划师支持不同类型的需求模板：

bash
# 使用特定模板
claude --agent=planner --template=ecommerce "设计商品管理功能"

# 自定义模板
claude --agent=planner --template=custom "使用我们的企业级需求模板"

2. 需求复用 ​

对于相似功能可以复用已有需求：

bash
# 基于现有功能扩展
claude --agent=planner "基于user-authentication功能，设计admin-authentication"

# 需求对比分析
claude --agent=planner "对比分析当前需求与industry best practices"

3. 多角色视角 ​

规划师可以从不同角色角度分析需求：

bash
# 多角色分析
claude --agent=planner "从用户、开发者、运维三个角度分析这个功能"

# 利益相关者分析
claude --agent=planner "分析这个功能对产品经理、开发团队、最终用户的影响"

质量保证 ​

EARS 语法标准 ​

规划师严格使用 EARS (Easy Approach to Requirements Syntax) 语法：

markdown
# 正确的EARS格式
**Given** 用户在登录页面
**When** 输入正确的邮箱和密码  
**Then** 系统应该验证凭据并重定向到仪表板

# 系统需求格式
系统应该在用户连续3次登录失败后暂时锁定账户15分钟

任务依赖管理 ​

任务分解严格按照依赖关系排序：

markdown
# 正确的依赖顺序
- [ ] 1. 数据库设计 (无依赖)
- [ ] 2. 用户模型 (依赖: 数据库设计)  
- [ ] 3. 认证服务 (依赖: 用户模型)
- [ ] 4. API控制器 (依赖: 认证服务)

常见问题 ​

Q: 规划师生成的任务太详细了，可以简化吗？ ​

A: 可以要求规划师调整粒度：

bash
"请将任务粒度调整为更高层次，每个任务大约半天到一天的工作量"

Q: 如何处理需求变更？ ​

A: 规划师支持需求迭代：

bash
"需求有变更，请更新 user-authentication 功能的需求文档，增加双因素认证"

Q: 可以同时规划多个功能吗？ ​

A: 建议一次专注一个功能，但可以分析功能间依赖：

bash
"先完成用户认证功能规划，然后分析它与订单管理功能的依赖关系"

最佳实践 ​

1. 需求收集准备 ​

  • 明确业务目标
  • 了解用户场景
  • 准备技术约束信息
  • 收集类似功能参考

2. 有效沟通 ​

  • 使用具体的业务术语
  • 提供充分的上下文
  • 及时反馈和确认
  • 积极参与讨论

3. 质量控制 ​

  • 仔细审查每个阶段的输出
  • 确保需求完备性
  • 验证技术方案可行性
  • 检查任务分解合理性

4. 文档管理 ​

  • 将规格文件纳入版本控制
  • 定期更新需求文档
  • 与团队共享规划结果
  • 建立需求追溯体系

相关资源 ​

规划师 - 好的开始是成功的一半

Claude Code 使用指南

Copyright © 2025