---
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`。

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

```bash
mkdir -p .claude/PRPs/plans
```

### 计划模板

````markdown
# 计划：[功能名称]

## 摘要
[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
````
