Plan Mode
Plan Mode（计划模式）是 Claude Code 的一个特殊工作模式，用于在实施复杂任务前进行规划和设计。
当遇到复杂的实现任务时，Claude Code会先进入 Plan Mode，在这个模式下，它能：
- 深入探索代码库 - 使用 Glob、Grep、Read 等工具充分理解现有架构和模式
- 设计实施方案 - 根据探索结果设计具体的实现方法
- 编写详细计划 - 创建包含实施步骤的计划文档
- 等待用户批准 - 向用户展示计划，确认方案后再开始实施
适合使用计划模式的场景：添加新功能（如"实现用户认证”）、有多种实现方案的任务（如"添加缓存机制”）、需要修改多个文件的重构、架构决策（如"添加实时更新功能”）、或者需求不明确，需要先调研的任务
不需要计划模式的场景： 简单的单行修复或小改动、 修正拼写错误、 纯粹的研究/探索任务、 用户已经给出非常详细具体的指令
Plan Mode的优势
- 避免返工 - 在写代码前确认方案，避免走错方向
- 确保对齐 - 保证实现符合用户的期望
- 提高效率 - 有计划地执行，不遗漏步骤
在Claude Code中，按Shift + 两次Tab主动进入Plan mode：
plan mode示例
例如，我们的系统原来没有登录功能，我们要给 Next.js 应用添加用户登录系统
第一步是接收任务并判断需要规划：
用户：帮我给这个项目添加用户登录系统，用户可以注册、登录、登出
Claude Code：这是一个涉及认证架构、数据库、安全等多方面的复杂功能。
让我进入计划模式来充分调研并设计方案。
✓ [使用 EnterPlanMode 工具 - 获得用户的批准后进入]
进入计划模式后，Claude Code会进行全面的代码库探索：
## 我的探索过程：
1. **查看项目结构**
[Glob 'app/**/*.tsx']
→ 发现：使用 App Router，有 app/page.tsx，app/layout.tsx
2. **检查是否有现有认证代码**
[Grep pattern="auth|login|session|token" glob="**/*.{ts,tsx}"]
→ 发现：没有任何认证相关代码
3. **检查依赖包**
[Read package.json]
→ 发现：
- 使用 Next.js 15.1.6
- 没有数据库依赖
- 没有认证库
4. **检查环境变量配置**
[Glob '.env*']
→ 发现：没有 .env 文件
5. **检查 API 路由**
[Glob 'app/api/**/*.ts']
→ 发现：没有任何 API 路由
6. **分析现有页面结构**
[Read app/page.tsx]
[Read app/layout.tsx]
→ 发现：简单的首页，没有导航，没有用户相关 UI
然后Claude Code向用户提问以明确需求：
Claude Code：我在调研代码库后发现几个需要明确的问题：
[使用 AskUserQuestion 工具]
问题1：你希望使用哪种认证方式？
选项：
- NextAuth.js (推荐) - 功能全面，支持多种登录方式，社区成熟
- 自建 JWT - 更灵活，完全控制，需要更多代码
- Clerk - 第三方托管，开箱即用，但有成本
- Supabase Auth - 如果使用 Supabase 作为数据库
问题2：需要支持哪些登录方式？
选项：
- 仅邮箱+密码
- 邮箱+密码 + Google OAuth
- 邮箱+密码 + 多个社交登录（Google、GitHub等）
问题3：数据存储方案？
选项：
- PostgreSQL (推荐用于生产)
- MongoDB
- Prisma + SQLite (适合快速开发)
- Supabase (数据库+认证一体)
Claude Code会根据用户的回答细化方案：
用户：我选择 NextAuth.js，支持邮箱密码和 Google 登录，
数据库用 PostgreSQL + Prisma
Claude Code：好的，基于你的选择，让我设计详细的实施方案...
[继续探索相关技术栈的最佳实践]
Claude Code然后编写详细的实施计划，它会创建一个详细的计划文档：
# 用户登录系统实施计划
## 技术栈决策
- **认证框架**: NextAuth.js v5 (Auth.js)
- **数据库**: PostgreSQL
- **ORM**: Prisma
- **登录方式**:
- Credentials (邮箱+密码)
- Google OAuth
- **密码加密**: bcrypt
- **Session 管理**: JWT + Database sessions
## 架构设计
### 数据模型
```prisma
model User {
id String @id @default(cuid())
name String?
email String @unique
emailVerified DateTime?
password String? // null for OAuth users
image String?
accounts Account[]
sessions Session[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
model Account { ... }
model Session { ... }
model VerificationToken { ... }
```
### API 路由结构
```
app/api/auth/[...nextauth]/
└── route.ts (NextAuth 配置)
```
### 页面结构
```
app/
├── login/
│ └── page.tsx (登录页)
├── register/
│ └── page.tsx (注册页)
├── dashboard/
│ └── page.tsx (登录后的页面，受保护)
└── profile/
└── page.tsx (用户资料页，受保护)
```
### 组件结构
```
components/
├── auth/
│ ├── login-form.tsx
│ ├── register-form.tsx
│ └── auth-provider.tsx
├── ui/
│ ├── button.tsx
│ ├── input.tsx
│ └── form.tsx
└── user-nav.tsx (显示登录状态的导航)
```
## 实施步骤（分阶段）
### 阶段 1: 基础设施搭建 (4个任务)
1. **安装依赖包**
```bash
npm install next-auth@beta @auth/prisma-adapter
npm install prisma @prisma/client
npm install bcryptjs
npm install -D @types/bcryptjs
```
2. **配置 Prisma**
- 创建 `prisma/schema.prisma`
- 定义 User, Account, Session, VerificationToken 模型
- 添加 `.env` 配置 DATABASE_URL
- 运行 `npx prisma migrate dev`
3. **配置环境变量** (.env.local)
```
DATABASE_URL="postgresql://..."
NEXTAUTH_SECRET="生成的随机密钥"
NEXTAUTH_URL="http://localhost:3000"
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
```
4. **创建 NextAuth 配置**
- 创建 `lib/auth.ts` (auth 配置)
- 配置 Credentials provider
- 配置 Google provider
- 配置 Prisma adapter
### 阶段 2: 认证 API (2个任务)
5. **创建 NextAuth API 路由**
- `app/api/auth/[...nextauth]/route.ts`
- 导出 GET, POST handlers
6. **创建注册 API**
- `app/api/register/route.ts`
- 验证邮箱格式
- 检查邮箱是否已存在
- 使用 bcrypt 加密密码
- 创建用户记录
### 阶段 3: UI 组件 (5个任务)
7. **创建基础 UI 组件**
- `components/ui/button.tsx`
- `components/ui/input.tsx`
- `components/ui/label.tsx`
- (使用 shadcn/ui 或手写简单版本)
8. **创建登录表单组件**
- `components/auth/login-form.tsx`
- 表单验证
- 调用 signIn()
- 错误处理和显示
9. **创建注册表单组件**
- `components/auth/register-form.tsx`
- 表单验证（密码强度、邮箱格式）
- 调用注册 API
- 成功后自动登录
10. **创建用户导航组件**
- `components/user-nav.tsx`
- 显示用户头像/名字
- 下拉菜单（资料、登出）
- 未登录时显示登录按钮
11. **创建 Session Provider**
- 在 `app/layout.tsx` 包裹 SessionProvider
- 确保客户端可以访问 session
### 阶段 4: 页面开发 (4个任务)
12. **创建登录页面**
- `app/login/page.tsx`
- 使用 LoginForm 组件
- 已登录用户重定向到 dashboard
- Google 登录按钮
13. **创建注册页面**
- `app/register/page.tsx`
- 使用 RegisterForm 组件
- 链接到登录页
14. **创建受保护的 Dashboard 页面**
- `app/dashboard/page.tsx`
- 使用 `auth()` 检查登录状态
- 未登录重定向到 login
15. **更新首页**
- `app/page.tsx`
- 添加 UserNav 组件到导航栏
- 显示登录/注册入口
### 阶段 5: 安全加固与优化 (3个任务)
16. **添加中间件保护路由**
- `middleware.ts`
- 保护 `/dashboard/*` 路由
- 保护 `/profile/*` 路由
17. **添加 CSRF 保护**
- NextAuth 默认已包含
- 验证配置正确
18. **添加 Rate Limiting**
- 登录接口限流
- 注册接口限流
- (可选：使用 upstash/ratelimit)
### 阶段 6: 测试与文档 (2个任务)
19. **功能测试**
- 测试注册流程
- 测试登录流程（邮箱密码）
- 测试 Google 登录
- 测试登出
- 测试路由保护
20. **更新文档**
- 在 README 添加认证系统说明
- 添加环境变量设置指南
- 添加 Google OAuth 设置步骤
## 文件清单（预计创建/修改）
### 新建文件 (~15个)
- `prisma/schema.prisma`
- `lib/auth.ts`
- `lib/db.ts`
- `app/api/auth/[...nextauth]/route.ts`
- `app/api/register/route.ts`
- `app/login/page.tsx`
- `app/register/page.tsx`
- `app/dashboard/page.tsx`
- `components/auth/login-form.tsx`
- `components/auth/register-form.tsx`
- `components/user-nav.tsx`
- `components/ui/button.tsx`
- `components/ui/input.tsx`
- `components/ui/label.tsx`
- `middleware.ts`
### 修改文件 (~4个)
- `app/layout.tsx` (添加 SessionProvider)
- `app/page.tsx` (添加导航)
- `package.json` (依赖)
- `.env.local` (新建环境变量)
- `.gitignore` (确保 .env 被忽略)
## 安全考虑
1. **密码安全**
- 使用 bcrypt (cost factor 12)
- 永不存储明文密码
- 密码最小长度 8 位
2. **Session 安全**
- NEXTAUTH_SECRET 使用强随机值
- JWT 有效期设置（7天）
- Secure cookies (生产环境)
3. **输入验证**
- 服务端验证所有输入
- 防止 SQL 注入（Prisma 自带防护）
- XSS 防护（React 自带）
4. **OAuth 安全**
- 验证 state 参数
- 使用 HTTPS（生产环境）
- 正确配置回调 URL
## 潜在问题与解决方案
1. **问题**: Google OAuth 需要公网 URL
**解决**: 开发时使用 ngrok 或等部署后配置
2. **问题**: 数据库迁移可能失败
**解决**: 提供完整的 Prisma 配置和迁移命令
3. **问题**: Session 在开发时可能不稳定
**解决**: 确保 NEXTAUTH_URL 正确设置
## 预计工作量
- 阶段 1-2 (基础设施): 奠定基础
- 阶段 3-4 (UI+页面): 主要开发工作
- 阶段 5-6 (安全+测试): 确保质量
## 依赖关系
```
阶段 1 → 阶段 2 → 阶段 3 → 阶段 4 → 阶段 5 → 阶段 6
(必须按顺序) (部分可并行) (可并行) (最后)
```
## 成功标准
✅ 用户可以使用邮箱密码注册
✅ 用户可以使用邮箱密码登录
✅ 用户可以使用 Google 账号登录
✅ 登录后可以访问受保护页面
✅ 未登录访问受保护页面时重定向到登录页
✅ 用户可以安全登出
✅ 密码加密存储
✅ Session 持久化
✅ 没有明显的安全漏洞
---
**准备就绪，等待批准开始实施** 🚀
然后Claude Code请求批准并等待反馈：
Claude Code：我已经完成了详细的实施计划，包含：
- 完整的技术架构设计
- 20 个具体的实施步骤，分为 6 个阶段
- 安全考虑和最佳实践
- 预计创建 15 个新文件，修改 4 个文件
计划已写入文件，请审阅。你可以：
1. 批准开始实施
2. 要求调整某些部分（比如不需要 Google 登录）
3. 询问任何不清楚的地方
✓ [使用 ExitPlanMode 工具]
根据用户的反应，分为几种情况：
情况A - 直接批准
用户：计划很详细，开始实施吧
Claude Code：好的！让我开始实施用户登录系统。
[创建 20 个 Todo 任务]
[标记第1个任务为 in_progress]
正在安装依赖包...
[执行 npm install...]
情况B - 要求调整
用户：看起来不错，但我不需要 Google 登录，
只要邮箱密码就行。另外能用 MongoDB 而不是 PostgreSQL 吗？
Claude Code：明白了，让我调整计划：
- 移除 Google OAuth 相关步骤（省3个任务）
- 将 Prisma + PostgreSQL 改为 Prisma + MongoDB
- 更新数据模型适配 MongoDB
[更新计划文档]
[重新使用 ExitPlanMode]
情况C - 询问细节
用户：这个方案中，用户信息会保存在哪里？Session 有效期多久？
Claude Code：好问题！
- 用户信息保存在 PostgreSQL 数据库的 User 表
- Session 默认有效期 30 天，可在 auth.ts 中配置
- JWT token 包含用户 ID，但敏感信息在服务端查询
需要调整 Session 有效期吗？
最后就是批准后的实施过程：
[TodoWrite 创建任务列表]
✓ 1. 安装依赖包 (completed)
→ 2. 配置 Prisma (in_progress)
3. 配置环境变量 (pending)
4. 创建 NextAuth 配置 (pending)
... (共20个任务)
[逐步执行，实时更新进度]
[遇到问题时及时报告]
[每完成一个阶段给你汇报]
这就是为什么复杂任务需要 Plan Mode - 它确保我们朝着正确的方向前进，而不是写完代码后才发现需求理解错了或方案不合适。