claude code 规划模式（Plan Mode）完整指南

📋 规划模式（Plan Mode）完整指南

本指南详细介绍Claude Code中规划模式的工作原理、使用方法和最佳实践

🎯 概述

规划模式（EnterPlanMode）是Claude Code中用于复杂实现任务的结构化工作流程。它在编写代码之前创建一个强制性的设计阶段，确保实现方案经过深思熟虑并与用户期望对齐。

核心目的

减少返工 - 通过前期设计避免实现阶段的重大修改
确保质量 - 遵循现有架构模式和编码约定
增进理解 - 与用户确认实现方案后再动手
管理复杂性 - 将大型任务分解为可控步骤

📊 何时使用规划模式

必须使用的场景（CLAUDE.md规定）

场景类型	具体示例	是否需要规划
新功能实现	添加用户认证、缓存系统、搜索功能	✅ 必须
多种解决方案	Redis vs 内存缓存、WebSocket vs SSE	✅ 必须
代码修改	重构登录流程、更新错误处理	✅ 必须
架构决策	状态管理方案、服务层设计	✅ 必须
多文件变更	涉及3+个文件的修改	✅ 必须
需求不明确	需要探索才能理解完整范围	✅ 必须
用户偏好相关	实现可能有多种合理方式	✅ 必须

不需要使用的场景

场景类型	具体示例	推荐做法
简单修复	修复拼写错误、明显bug	❌ 直接修复
单行修改	添加console.log、小调整	❌ 直接修改
明确指令	用户给出详细具体说明	❌ 按说明执行
纯研究任务	查找信息、理解代码	❌ 使用Agent探索

🔄 工作流程

完整流程图

复制代码

用户提出任务请求
    │
    ▼
[进入规划模式]
    │  使用 EnterPlanMode 工具
    │
    ▼
[探索代码库]
    │  ├─ Glob：查找相关文件
    │  ├─ Grep：搜索相关内容
    │  └─ Read：读取关键文件
    │
    ▼
[理解架构]
    │  ├─ 现有模式分析
    │  ├─ 编码约定检查
    │  └─ 依赖关系梳理
    │
    ▼
[设计方案]
    │  ├─ 方案A评估
    │  ├─ 方案B评估
    │  └─ 选择最优方案
    │
    ▼
[编写计划]
    │  ├─ 实现步骤
    │  ├─ 文件修改列表
    │  ├─ 设计决策说明
    │  └─ 风险评估
    │
    ▼
[请求批准]
    │  使用 ExitPlanMode 工具
    │
    ▼
    ├─ 用户批准 ──────────→ 开始实施
    │
    ├─ 用户要求修改 ──────→ 重新规划
    │
    └─ 用户拒绝 ──────────→ 重新理解需求

🛠️ 工具使用指南

✅ 规划模式下可用的工具

1. Glob - 文件模式匹配

复制代码

用途：查找符合模式的文件

示例：
- Glob(pattern="src/tools/**/*.ts")    # 查找所有工具文件
- Glob(pattern="**/*.test.ts")         # 查找测试文件
- Glob(pattern="src/services/*")       # 查找services目录文件

2. Grep - 内容搜索

复制代码

用途：在文件内容中搜索模式

示例：
- Grep(pattern="auth", type="ts")              # 搜索TypeScript文件中的auth
- Grep(pattern="export.*function", glob="*.ts") # 搜索导出的函数
- Grep(pattern="component", output_mode="content") # 显示匹配行内容

3. Read - 文件读取

复制代码

用途：读取文件内容

示例：
- Read(file_path="src/main.tsx")           # 读取主入口文件
- Read(file_path="src/CLAUDE.md")          # 读取项目配置

4. TaskCreate - 任务列表

复制代码

用途：创建结构化任务列表

示例：
- TaskCreate(subject="分析现有认证模式", 
              description="探索src/services/oauth/目录")

5. AskUserQuestion - 需求澄清

复制代码

用途：在规划阶段澄清模糊需求

注意：不要用于询问"计划好吗？"这类问题
      这是ExitPlanMode的工作

❌ 规划模式下不可用的操作

操作	工具	原因
编辑文件	Edit	会直接修改代码
创建文件	Write	会直接写入文件
执行命令	Bash	可能修改系统状态
提交代码	Bash+git	会创建提交

⚠️ 退出规划模式的唯一方式

复制代码

ExitPlanMode()

重要规则：

❌ 不要用 AskUserQuestion 问"计划好吗？"
❌ 不要自己决定是否实施
✅ 必须使用 ExitPlanMode 让用户审查

📝 计划文档结构

🔍 本项目特殊考虑

项目架构特点（基于CLAUDE.md）

1. 模块化工具系统

复制代码

src/tools/
├── tool-name/
│   ├── ToolName.ts      # 工具实现
│   └── index.ts         # 导出
├── shared/              # 共享工具库
├── tools.ts             # 工具注册表
└── bundled/             # 内置技能

规划建议：

新工具应放在独立目录
使用现有的工具注册模式
考虑共享工具库的复用

2. 服务层架构

复制代码

src/services/
├── mcp/          # MCP服务器集成
├── oauth/        # 认证服务
├── plugins/      # 插件系统
└── ...

规划建议：

新服务应遵循现有模式
注意ANT-only工具的条件加载
考虑feature flag的使用

3. 组件系统

复制代码

src/components/    # React组件
src/ink/          # Ink终端UI组件

规划建议：

遵循Ink组件最佳实践
维护UI一致性
考虑终端环境的限制

4. 特殊系统

隐蔽模式 ：src/utils/undercover.ts
KAIROS/ULTRAPLAN：主动助手系统
条件加载：基于USER_TYPE和feature flag

规划建议：

理解这些系统的存在
不要破坏现有机制
必要时进行集成

技术栈要求

技术	版本/要求	注意事项
TypeScript	18+	严格类型检查
React + Ink	最新	终端UI渲染
Bun/Node.js	18+	运行时环境
无测试框架	-	npm test不可用

编码约定

文件组织：
- 每个工具独立目录
- 清晰的导出结构
- README文档（可选）
代码质量：
- 无console.log
- 完整的类型定义
- 错误处理完善
安全考虑：
- 避免命令注入
- 输入验证
- 权限控制

🚀 实施阶段转换

从规划到实施的步骤

第1步：获得批准

复制代码

用户审查计划文档
    │
    ▼
用户给出反馈
    ├─ "批准，按计划实施" → 进入实施
    ├─ "需要修改" → 返回规划阶段
    └─ "重新考虑" → 重新理解需求

第2步：准备工作

复制代码

# 创建任务列表
TaskCreate(subject="实施<功能名称>", 
            description="按照批准的计划执行")

# 检查git状态
Bash(command="git status")
Bash(command="git diff")

第3步：按计划实施

复制代码

按照"实现步骤"逐一执行
    │
    ▼
每个步骤完成后验证
    │
    ▼
记录进度

第4步：完成和验证

复制代码

# 运行构建
Bash(command="npm run build")

# 测试功能
# （根据项目情况手动测试）

# 创建提交
# （需要时询问用户）

⚡ 工具命令速查

EnterPlanMode

复制代码

EnterPlanMode()

何时使用：开始复杂任务前
效果：进入规划模式
限制：不能直接修改代码

ExitPlanMode

复制代码

ExitPlanMode({
  allowedPrompts: [
    {tool: "Bash", prompt: "run tests"},
    {tool: "Bash", prompt: "install dependencies"}
  ]
})

何时使用：规划完成后
效果：显示计划，请求批准
参数：列出实施时需要的操作权限

常用工具组合

探索代码库

复制代码

// 查找文件
Glob({pattern: "src/**/*.ts"})

// 搜索内容
Grep({pattern: "authentication", type: "ts"})

// 读取文件
Read({file_path: "src/main.tsx"})

创建任务

复制代码

TaskCreate({
  subject: "分析现有代码",
  description: "探索相关模块"
})

🎓 最佳实践

1. 充分探索，不要假设

复制代码

错误做法：
- 基于项目名称猜测结构
- 假设使用某种模式
- 不查看现有代码就开始设计

正确做法：
- 实际查看项目结构
- 搜索相关实现
- 理解既有模式

2. 保持计划具体且可操作

复制代码

较差计划：
"我会添加认证功能"

优秀计划：
"步骤1：分析现有oauth服务
 步骤2：设计新的认证流程
 步骤3：实现认证组件
 ..."

3. 遵循项目约定

复制代码

- 使用现有的工具注册模式
- 遵循TypeScript类型定义
- 维护UI组件一致性
- 遵守安全规范

4. 考虑边界情况

复制代码

- 空数据
- 错误输入
- 并发操作
- 性能影响
- 回滚方案

5. 与用户对齐

复制代码

- 用计划文档确认理解
- 讨论设计决策
- 明确验收标准
- 约定实施范围

⚠️ 常见错误

错误类型	示例	正确做法
计划太粗略	"实现搜索功能"	详细列出每个步骤
计划太详细	包含每行代码	关注步骤和设计决策
忽略现有模式	重新发明轮子	遵循项目约定
不探索就设计	基于假设	先查看现有代码
忘记边界情况	只考虑正常流程	列出异常处理
不请求批准	直接实施	使用ExitPlanMode

📚 参考资源

官方文档

<CLAUDE.md> - 项目特定指导
系统提醒中的技能列表
工具使用说明

📦 附录：工具参考

EnterPlanMode

签名：EnterPlanMode()

描述：进入规划模式，允许探索但不允许直接修改代码

使用时机：

复杂实现任务开始前
需要设计方案时
涉及架构决策时

ExitPlanMode

签名：ExitPlanMode({ allowedPrompts?: Array<{tool: string, prompt: string}> })

描述：退出规划模式，显示计划文档，请求用户批准

参数：

allowedPrompts：实施阶段允许的操作权限列表

使用时机：

规划文档完成时
准备请求用户批准时

🏁 总结

规划模式是Claude Code中最重要的工作流程之一。通过强制性的设计阶段，它：

✅ 降低风险 - 提前发现问题
✅ 提高质量 - 遵循最佳实践
✅ 节省时间 - 减少返工
✅ 增强协作 - 与用户对齐期望

记住：好的规划是成功实施的一半。在面对复杂任务时，总是先规划，后实施。

📝 附录A：文档完善技巧与提示词

A.1 文档完善的核心原则

1. 结构化思维

复制代码

优秀文档特征：
- 清晰的层级结构（H1→H2→H3）
- 逻辑连贯的内容流
- 重点突出的关键信息
- 易于查找的索引和目录

2. 读者导向

复制代码

考虑读者需求：
- 新手需要什么基础信息？
- 专家需要什么深度细节？
- 实施者需要什么操作步骤？
- 维护者需要什么注意事项？

3. 可操作性

复制代码

确保文档实用：
- 提供具体示例和代码片段
- 包含可复制的命令
- 明确成功标准和验收条件
- 给出常见问题和解决方案

A.2 提示词工程（Prompt Engineering）技巧

1. 明确目标

复制代码

❌ 不好的提示词：
"写一下这个功能"

✅ 好的提示词：
"为[功能名称]创建技术文档，包含：
- 功能概述（1-2句话）
- 架构设计图（文字描述）
- API接口说明
- 使用示例
- 注意事项和限制"

2. 提供上下文

复制代码

❌ 缺乏上下文的提示词：
"帮我写个用户认证模块"

✅ 完整上下文的提示词：
"基于以下信息设计用户认证模块：
- 项目：Claude Code CLI
- 技术栈：TypeScript + React/Ink
- 现有服务：src/services/oauth/
- 需求：支持多平台认证，JWT令牌
- 约束：无测试框架，需手动测试

请提供完整的实现方案"

3. 分步细化

复制代码

❌ 一次性复杂要求：
"把这个系统重构了"

✅ 分步迭代提示词：
"步骤1：分析现有系统的架构
步骤2：识别需要重构的模块
步骤3：设计新的架构方案
步骤4：制定迁移计划

请从步骤1开始"

4. 使用模板

复制代码

通用文档提示词模板：

"请创建一份关于[主题]的文档，包含以下部分：

## 概述
- 简述[主题]的目的和价值

## 核心概念
- 列出关键术语和定义
- 解释工作原理

## 架构设计
- 系统组件和关系
- 数据流向

## 实现细节
- 技术选型理由
- 关键代码示例
- 配置说明

## 使用指南
- 快速开始步骤
- 常见操作示例

## 故障排查
- 常见问题
- 解决方案

## 参考资料
- 相关文档链接
- 最佳实践"

A.3 文档完善的工作流程

复制代码

草稿阶段 → 审查阶段 → 完善阶段 → 发布阶段
    ↓           ↓           ↓           ↓
收集信息    内容审查    格式优化    最终确认
    ↓           ↓           ↓           ↓
头脑风暴    准确性检查  可读性提升  发布更新
    ↓           ↓           ↓           ↓
初稿完成    结构调整    链接检查    版本记录

A.4 具体的提示词示例

4.1 文档结构生成提示词

复制代码

"请为以下内容创建清晰的文档结构：

主题：[输入主题]
目标读者：[技术人员/新手/混合]
文档类型：[教程/参考/指南]

要求：
1. 创建层次化的大纲
2. 每个部分标注预计内容长度
3. 识别需要图表或示例的部分
4. 列出需要确认的关键点"

4.2 内容扩展提示词

复制代码

"基于以下要点，扩展成详细的技术文档：

要点：
- [要点1]
- [要点2]
- [要点3]

扩展要求：
1. 每个要点写100-200字
2. 包含具体的代码示例
3. 说明实际应用场景
4. 指出可能的陷阱和解决方案"

4.3 示例代码生成提示词

复制代码

"为[功能/模块]创建示例代码：

技术要求：
- 语言：[TypeScript/JavaScript/Python]
- 框架：[React/Express/其他]
- 风格：[函数式/面向对象]

示例场景：
1. 基础用法
2. 高级用法
3. 错误处理
4. 性能优化

代码要求：
- 包含完整的类型定义
- 添加详细的注释
- 遵循项目的编码规范
- 展示最佳实践"

4.4 文档审查提示词

复制代码

"请审查以下文档的质量：

[文档内容]

审查维度：
1. 准确性：技术细节是否正确
2. 完整性：是否覆盖所有重要方面
3. 清晰性：语言是否易懂
4. 一致性：格式和风格是否统一
5. 实用性：是否包含可操作的信息

请提供具体的改进建议"

A.5 文档维护的最佳实践

1. 版本控制

复制代码

文档版本记录模板：

| 版本 | 日期 | 作者 | 更新内容 |
|------|------|------|----------|
| 1.0  | 2026-05-06 | AI | 初稿创建 |
| 1.1  | 2026-05-10 | AI | 补充示例代码 |
| 2.0  | 2026-05-15 | 人工 | 重大重构 |

2. 定期审查

复制代码

审查清单：
- [ ] 技术细节是否仍然准确
- [ ] 链接是否仍然有效
- [ ] 示例代码是否可用
- [ ] 是否需要更新依赖版本
- [ ] 读者反馈是否需要整合

3. 反馈收集

复制代码

收集反馈的方法：
1. 在文档中添加评论链接
2. 创建GitHub Issue跟踪建议
3. 定期查看使用统计
4. 进行用户调查
5. 监控常见问题

A.6 本项目文档规范

1. 文件命名约定

复制代码

- 功能文档：FEATURE_NAME_GUIDE.md
- API文档：api-REFERENCE.md
- 教程文档：tutorial-STEP-BY-STEP.md
- 快速参考：quick-REFERENCE.md

2. 内容格式要求

复制代码

- 使用中文撰写
- 技术术语保持英文
- 代码块标注语言类型
- 重要的警告使用⚠️符号
- 成功的示例使用✅符号
- 错误的示例使用❌符号

3. 质量检查清单

复制代码

文档发布前检查：
- [ ] 标题清晰表达了内容
- [ ] 目录链接正常工作
- [ ] 代码可复制运行
- [ ] 图片和图表清晰
- [ ] 无拼写和语法错误
- [ ] 链接引用正确
- [ ] 版本信息准确

🎯 如何工作的总结

提示词的工作原理

模式识别：AI通过大量训练数据学习文档结构和写作模式
上下文理解：基于提供的上下文生成相关内容
模板匹配：将输入映射到已知的文档模板
逐步生成：按照逻辑顺序逐段生成内容

文档完善的流程

收集需求 - 明确文档目标和读者
创建大纲 - 规划文档结构
填充内容 - 使用提示词生成各部分内容
审查优化 - 检查准确性、清晰性和完整性
格式美化 - 优化排版和视觉效果
测试验证 - 确保示例和说明可行
发布维护 - 版本控制和定期更新

关键成功因素

清晰的提示词 - 具体、详细、有上下文的提示
迭代优化 - 多次审查和修改
读者思维 - 始终考虑读者的需求
实践验证 - 确保内容可操作和准确

📊 文档质量评估标准

评估维度	优秀标准	合格标准	需要改进
准确性	所有技术细节100%正确	主要内容正确	存在事实错误
完整性	覆盖所有关键方面	覆盖主要方面	重要内容缺失
清晰性	表达通俗易懂	基本可理解	难以理解
实用性	可直接指导实践	提供参考价值	理论性太强
美观性	格式精美专业	格式规范	格式混乱
维护性	易于更新维护	可维护	难以维护

最后更新：2026/05/06 依据CLAUDE.md项目规范编写 文档版本：2.0

claude code 规划模式（Plan Mode）完整指南

📋 规划模式（Plan Mode）完整指南

🎯 概述

核心目的

📊 何时使用规划模式

必须使用的场景（CLAUDE.md规定）

不需要使用的场景

🔄 工作流程

完整流程图

🛠️ 工具使用指南

✅ 规划模式下可用的工具

1. Glob - 文件模式匹配

2. Grep - 内容搜索

3. Read - 文件读取

4. TaskCreate - 任务列表

5. AskUserQuestion - 需求澄清

❌ 规划模式下不可用的操作

⚠️ 退出规划模式的唯一方式

📝 计划文档结构

推荐模板

🔍 本项目特殊考虑

项目架构特点（基于CLAUDE.md）

1. 模块化工具系统

2. 服务层架构

3. 组件系统

4. 特殊系统

技术栈要求

编码约定

🚀 实施阶段转换

从规划到实施的步骤

第1步：获得批准

第2步：准备工作

第3步：按计划实施

第4步：完成和验证

⚡ 工具命令速查

EnterPlanMode

ExitPlanMode

常用工具组合

探索代码库

创建任务

🎓 最佳实践

1. 充分探索，不要假设

2. 保持计划具体且可操作

3. 遵循项目约定

4. 考虑边界情况

5. 与用户对齐

⚠️ 常见错误

📚 参考资源

官方文档

相关文件

📦 附录：工具参考

EnterPlanMode

ExitPlanMode

🏁 总结

📝 附录A：文档完善技巧与提示词

A.1 文档完善的核心原则

1. 结构化思维

2. 读者导向

3. 可操作性

A.2 提示词工程（Prompt Engineering）技巧

1. 明确目标

2. 提供上下文

3. 分步细化

4. 使用模板

A.3 文档完善的工作流程

A.4 具体的提示词示例

4.1 文档结构生成提示词

4.2 内容扩展提示词

4.3 示例代码生成提示词

4.4 文档审查提示词

A.5 文档维护的最佳实践

1. 版本控制

2. 定期审查

3. 反馈收集

A.6 本项目文档规范

1. 文件命名约定

2. 内容格式要求

3. 质量检查清单

🎯 如何工作的总结

提示词的工作原理