everything-claude-code/docs/zh-CN/commands/prp-plan.md

description, argument-hint

description	argument-hint
创建全面的功能实现计划，包括代码库分析和模式提取	<feature description | path/to/prd.md>

改编自 Wirasm 的 PRPs-agentic-eng。属于 PRP 工作流系列。

PRP 计划

创建一个详细、自包含的实现计划，该计划捕获所有代码库模式、约定和上下文，以便一次性实现一个功能。

核心理念：一个优秀的计划包含实现所需的一切，无需再提出其他问题。每个模式、每个约定、每个陷阱——一次性捕获，并在整个过程中引用。

黄金法则：如果在实现过程中需要搜索代码库，请立即将该知识捕获到计划中。

---

阶段 0 — 检测

根据 $ARGUMENTS 确定输入类型：

输入模式	检测	操作
以 .prd.md 结尾的路径	PRD 文件路径	解析 PRD，查找下一个待处理阶段
包含“实施阶段”的 .md 路径	类似 PRD 的文档	解析阶段，查找下一个待处理阶段
任何其他文件的路径	参考文件	读取文件以获取上下文，视为自由格式
自由格式文本	功能描述	直接进入阶段 1
空/空白	无输入	询问用户要规划什么功能

PRD 解析（当输入为 PRD 时）

1. 使用 cat "$PRD_PATH" 读取 PRD 文件
2. 解析 实施阶段 部分
3. 根据状态查找阶段：
   • 查找 pending 阶段
   • 检查依赖链（一个阶段可能依赖于先前阶段为 complete）
   • 选择 下一个符合条件的待处理阶段
4. 从所选阶段中提取：
   • 阶段名称和描述
   • 验收标准
   • 对先前阶段的依赖
   • 任何范围说明或约束
5. 将阶段描述用作要规划的功能

如果没有剩余待处理阶段，则报告所有阶段已完成。

---

阶段 1 — 解析

提取并阐明功能需求。

功能理解

从输入（PRD 阶段或自由格式描述）中，识别：

• 构建什么（具体可交付成果）
• 为什么重要（用户价值）
• 谁使用它（目标用户/系统）
• 它适合哪里（代码库的哪个部分）

用户故事

格式化为：

作为[用户类型]，
我希望[能力]，
以便[收益]。

复杂度评估

级别	指标	典型范围
小	单个文件、隔离更改、无新依赖	1-3 个文件，<100 行
中	多个文件、遵循现有模式、少量新概念	3-10 个文件，100-500 行
大	横切关注点、新模式、外部集成	10+ 个文件，500+ 行
超大	架构更改、新子系统、需要迁移	20+ 个文件，考虑拆分

歧义门控

如果以下任何一项不明确，停止并向用户提问，然后再继续：

• 核心可交付成果模糊
• 成功标准未定义
• 存在多种有效解释
• 技术方法存在重大未知数

不要猜测。要提问。基于假设的计划会在实施过程中失败。

---

阶段 2 — 探索

收集深入的代码库情报。直接针对以下每个类别搜索代码库。

代码库搜索（8 个类别）

对于每个类别，使用 grep、find 和文件读取进行搜索：

1. 类似实现 — 查找与计划功能相似的现有功能。寻找类似的模式、端点、组件或模块。

2. 命名约定 — 识别代码库相关区域中文件、函数、变量、类和导出的命名方式。

3. 错误处理 — 查找在类似代码路径中如何捕获、传播、记录错误并将其返回给用户。

4. 日志记录模式 — 识别记录什么内容、在什么级别以及以什么格式记录。

5. 类型定义 — 查找相关类型、接口、模式及其组织方式。

6. 测试模式 — 查找类似功能的测试方式。注意测试文件位置、命名、设置/拆卸模式以及断言风格。

7. 配置 — 查找相关配置文件、环境变量和功能标志。

8. 依赖项 — 识别类似功能使用的包、导入和内部模块。

代码库分析（5 个追踪）

读取相关文件以追踪：

1. 入口点 — 请求/操作如何进入系统并到达您正在修改的区域？
2. 数据流 — 数据如何在相关代码路径中移动？
3. 状态更改 — 修改了哪些状态以及在哪里修改？
4. 契约 — 必须遵守哪些接口、API 或协议？
5. 模式 — 使用了哪些架构模式（仓库、服务、控制器等）？

统一发现表

将发现结果编译到单个参考中：

类别	文件:行	模式	关键片段
命名	src/services/userService.ts:1-5	服务使用 camelCase，类型使用 PascalCase	export class UserService
错误	src/middleware/errorHandler.ts:10-25	自定义 AppError 类	throw new AppError(...)
...	...	...	...

---

阶段 3 — 研究

如果功能涉及外部库、API 或不熟悉的技术：

1. 搜索网络以获取官方文档
2. 查找使用示例和最佳实践
3. 识别特定版本的陷阱

将每个发现格式化为：

KEY_INSIGHT: [你学到的内容]
APPLIES_TO: [这影响计划的哪个部分]
GOTCHA: [任何警告或版本特定问题]

如果功能仅使用已充分理解的内部模式，则跳过此阶段并注明：“无需外部研究——功能使用已建立的内部模式。”

---

阶段 4 — 设计

用户体验转换（如果适用）

记录前后用户体验：

之前：

┌─────────────────────────────┐
│  [当前用户体验]              │
│  展示当前流程，              │
│  用户所见/所操作的内容        │
└─────────────────────────────┘

之后：

┌─────────────────────────────┐
│  [新用户体验]               │
│  展示改进后的流程，          │
│  用户会看到哪些变化          │
└─────────────────────────────┘

交互更改

接触点	之前	之后	备注
...	...	...	...

如果功能纯粹是后端/内部且没有用户体验更改，则注明：“内部更改——无面向用户的用户体验转换。”

---

阶段 5 — 架构

策略设计

定义实施方法：

• 方法：高级策略（例如，“按照现有仓库模式添加新的服务层”）
• 考虑的替代方案：评估了哪些其他方法以及为何被拒绝
• 范围：将要构建的具体边界
• 不构建：明确列出超出范围的内容（防止实施期间范围蔓延）

---

阶段 6 — 生成

使用下面的模板编写完整的计划文档。保存到 .claude/PRPs/plans/{kebab-case-feature-name}.plan.md。

如果目录不存在，则创建它：

mkdir -p .claude/PRPs/plans

计划模板

# 计划：[功能名称]

## 摘要
[2-3句概述]

## 用户故事
作为[用户]，我希望[能力]，以便[收益]。

## 问题 → 解决方案
[当前状态] → [期望状态]

## 元数据
- **复杂度**：[小 | 中 | 大 | 超大]
- **来源PRD**：[路径或“N/A”]
- **PRD阶段**：[阶段名称或“N/A”]
- **预估文件数**：[数量]

---

## UX设计

### 之前
[ASCII图表或“N/A — 内部变更”]

### 之后
[ASCII图表或“N/A — 内部变更”]

### 交互变更
| 接触点 | 之前 | 之后 | 备注 |
|---|---|---|---|

---

## 必读文件

实现前必须阅读的文件：

| 优先级 | 文件 | 行号 | 原因 |
|---|---|---|---|
| P0（关键） | `path/to/file` | 1-50 | 需遵循的核心模式 |
| P1（重要） | `path/to/file` | 10-30 | 相关类型 |
| P2（参考） | `path/to/file` | 全部 | 类似实现 |

## 外部文档

| 主题 | 来源 | 关键要点 |
|---|---|---|
| ... | ... | ... |

---

## 需镜像的模式

在代码库中发现的代码模式。请严格遵循。

### 命名约定
// 来源：[文件:行号]
[展示命名模式的实际代码片段]

### 错误处理
// 来源：[文件:行号]
[展示错误处理的实际代码片段]

### 日志记录模式
// 来源：[文件:行号]
[展示日志记录的实际代码片段]

### 仓库模式
// 来源：[文件:行号]
[展示数据访问的实际代码片段]

### 服务模式
// 来源：[文件:行号]
[展示服务层的实际代码片段]

### 测试结构
// 来源：[文件:行号]
[展示测试设置的实际代码片段]

---

## 需变更的文件

| 文件 | 操作 | 理由 |
|---|---|---|
| `path/to/file.ts` | 创建 | 功能的新服务 |
| `path/to/existing.ts` | 更新 | 添加新方法 |

## 不构建的内容

- [明确不在范围内的第1项]
- [明确不在范围内的第2项]

---

## 分步任务

### 任务1：[名称]
- **操作**：[要做什么]
- **实现**：[要编写的具体代码/逻辑]
- **镜像**：[需遵循的“需镜像的模式”部分中的模式]
- **导入**：[所需的导入]
- **陷阱**：[需避免的已知陷阱]
- **验证**：[如何验证此任务正确]

### 任务2：[名称]
- **操作**：...
- **实现**：...
- **镜像**：...
- **导入**：...
- **陷阱**：...
- **验证**：...

[继续所有任务...]

---

## 测试策略

### 单元测试

| 测试 | 输入 | 预期输出 | 边界情况？ |
|---|---|---|---|
| ... | ... | ... | ... |

### 边界情况检查清单
- [ ] 空输入
- [ ] 最大尺寸输入
- [ ] 无效类型
- [ ] 并发访问
- [ ] 网络故障（如适用）
- [ ] 权限被拒绝

---

## 验证命令

### 静态分析
```bash
# Run type checker
[project-specific type check command]
```
预期：零类型错误

### 单元测试
```bash
# Run tests for affected area
[project-specific test command]
```
预期：所有测试通过

### 完整测试套件
```bash
# Run complete test suite
[project-specific full test command]
```
预期：无回归

### 数据库验证（如适用）
```bash
# Verify schema/migrations
[project-specific db command]
```
预期：Schema 为最新

### 浏览器验证（如适用）
```bash
# Start dev server and verify
[project-specific dev server command]
```
预期：功能按设计工作

### 手动验证
- [ ] [逐步手动验证检查清单]

---

## 验收标准
- [ ] 所有任务完成
- [ ] 所有验证命令通过
- [ ] 测试已编写并通过
- [ ] 无类型错误
- [ ] 无 lint 错误
- [ ] 符合 UX 设计（如适用）

## 完成检查清单
- [ ] 代码遵循发现的模式
- [ ] 错误处理符合代码库风格
- [ ] 日志记录遵循代码库约定
- [ ] 测试遵循测试模式
- [ ] 无硬编码值
- [ ] 文档已更新（如需要）
- [ ] 无不必要的范围扩展
- [ ] 自包含 — 实现期间无需提问

## 风险
| 风险 | 可能性 | 影响 | 缓解措施 |
|---|---|---|---|
| ... | ... | ... | ... |

## 备注
[任何额外的上下文、决策或观察]
```

---

## Output

### Save the Plan

Write the generated plan to:
```
.claude/PRPs/plans/{kebab-case-feature-name}.plan.md
```

### Update PRD (if input was a PRD)

If this plan was generated from a PRD phase:
1. Update the phase status from `pending` to `in-progress`
2. Add the plan file path as a reference in the phase

### Report to User

```
## 计划已创建

- **文件**：.claude/PRPs/plans/{kebab-case-feature-name}.plan.md
- **来源PRD**：[路径或“N/A”]
- **阶段**：[阶段名称或“独立”]
- **复杂度**：[级别]
- **范围**：[N个文件，M个任务]
- **关键模式**：[前3个发现的模式]
- **外部研究**：[研究的主题或“无需”]
- **风险**：[主要风险或“未识别”]
- **置信度评分**：[1-10] — 单次实现成功的可能性

> 下一步：运行 `/prp-implement .claude/PRPs/plans/{name}.plan.md` 来执行此计划。
```

---

## 验证

在最终确定之前，请根据以下检查清单验证计划：

### 上下文完整性
- [ ] 所有相关文件已发现并记录
- [ ] 命名约定已通过示例捕获
- [ ] 错误处理模式已记录
- [ ] 测试模式已识别
- [ ] 依赖项已列出

### 实现就绪性
- [ ] 每个任务都有操作、实现、镜像和验证
- [ ] 没有任务需要额外的代码库搜索
- [ ] 导入路径已指定
- [ ] 陷阱已在适用处记录

### 模式忠实度
- [ ] 代码片段是实际的代码库示例（非虚构）
- [ ] 来源引用指向真实文件和行号
- [ ] 模式涵盖命名、错误、日志记录、数据访问和测试
- [ ] 新代码将与现有代码无法区分

### 验证覆盖范围
- [ ] 静态分析命令已指定
- [ ] 测试命令已指定
- [ ] 构建验证已包含

### UX清晰度
- [ ] 之前/之后的状态已记录（或标记为N/A）
- [ ] 交互变更已列出
- [ ] UX的边界情况已识别

### 无先验知识测试
不熟悉此代码库的开发人员应能仅使用此计划实现该功能，无需搜索代码库或提问。如果不能，请添加缺失的上下文。

---

## 后续步骤

- 运行 `/prp-implement <plan-path>` 来执行此计划
- 运行 `/plan` 进行快速对话式规划（无需产物）
- 如果范围不明确，运行 `/prp-prd` 先创建PRD