mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-05-14 10:43:20 +08:00
6556f20af7
Port the current-source-safe command documentation subset from stale PR #1687.\n\nEach copied command page maps to an English source file unchanged since the stale PR base; fastapi-review remains deferred because #1687 did not include a matching zh-CN translation.
507 lines
13 KiB
Markdown
507 lines
13 KiB
Markdown
---
|
||
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
|
||
````
|