ECC 的 /prp-plan 命令解析：基于代码库感知与模式提取生成一次通过的功能实现计划

导读

本文深入剖析 ECC（agent harness performance optimization system）命令体系中的 /prp-plan 规划命令，它属于 PRP（Plan-Review-Pull）工作流系列，用于把一条功能描述或一个 PRD 阶段，转换为一篇**自包含（self-contained）**的实现计划文档——代码库模式、约定、坑点全部内嵌其中，让后续实现方无需再次搜索代码库或追问即可"一次通过（single pass）"地完成开发。读完本文，你将掌握 /prp-plan 的六阶段执行流水线（DETECT → PARSE → EXPLORE → RESEARCH → DESIGN → ARCHITECT → GENERATE）、完整的计划文档模板、输出后的自我校验清单，以及它与 /prp-implement、/prp-commit、/prp-pr 等命令如何构成闭环。

一、命令定位：PRP 工作流中的"计划生成器"

/prp-plan 的说明文档位于仓库 commands/prp-plan.md，其 front-matter 描述为：

Create comprehensive feature implementation plan with codebase analysis and pattern extraction

参数提示为 <feature description | path/to/prd.md>——即既可以直接给一段功能描述，也可以指向一个 PRD 文件的路径。该命令在仓库中具备真实的注册与分发信息：

• docs/COMMAND-REGISTRY.json 第 733-741 行登记了 prp-plan，type 为 testing，路径指向 commands/prp-plan.md；
• agent.yaml 第 230 行将 prp-plan 列入可执行命令清单；
• COMMANDS-QUICK-REF.md 第 82-90 行给出 "PRP Workflow" 一览表，完整列出了 /prp-prd → /prp-plan → /prp-implement → /prp-commit → /prp-pr 五条命令的职责。

文件开头还声明其渊源：

Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.

即本命令是从社区 PRPs-agentic-eng 思路移植而来的"深层 PRP 工作流"一环。与之相对，仓库在 commands/plan.md 第 195-197 行明确给出两者边界：ECC 自身的 /plan 是轻量会话式规划，而当需要"带 .claude/PRPs/ 制品的深度 PRP 规划"时应使用 /prp-plan，再用 /prp-implement 以严格校验循环执行这些计划。这也与 docs/PLAN-PRD-PATTERN.md 中"PRD 回答 why、plan 回答 how、两者分离"的设计判断相互印证——旧版 /prp-prd → /prp-plan 组合把 8 阶段问答与实现阶段表混入同一需求文档中，拆分后才形成如今职责清晰的命令族。

二、核心哲学与黄金法则

文档开篇即点出 /prp-plan 的存在理由，这也是理解全文的钥匙：

• 核心理念：一份好的计划应当包含实现所需的一切，实现者不需要再问任何问题。每一种模式、每一条约定、每一个陷阱——只捕获一次，全文反复引用。
• 黄金法则：如果实现过程中你将会需要去搜索代码库，那么就把这份知识现在写进计划里。

从 README.md 第 156 行可见 ECC 的总体闭环是 plan -> test -> implement -> review -> verify -> remember -> improve，而 /prp-plan 正是该闭环中"先规划再动手"的工程化载体：它把"搜索发现"的认知过程前置到计划阶段，换取实现阶段（由 /prp-implement 承接）的零查询、零打断。

三、Phase 0 — DETECT：识别输入类型

命令的第一步是判断 $ARGUMENTS 到底给了什么，文档给出如下判定表：

Input Pattern	Detection	Action
Path ending in .prd.md	File path to PRD	Parse PRD, find next pending phase
Path to .md with "Implementation Phases"	PRD-like document	Parse phases, find next pending
Path to any other file	Reference file	Read file for context, treat as free-form
Free-form text	Feature description	Proceed directly to Phase 1
Empty / blank	No input	Ask user what feature to plan

3.1 PRD 解析规则

当输入是 PRD 时，按顺序执行：

1. 用 cat "$PRD_PATH" 读取 PRD 全文；
2. 解析其中的 Implementation Phases 小节；
3. 依据状态寻找阶段：
   • 寻找状态为 pending 的阶段；
   • 检查依赖链（某阶段可能依赖前序阶段变为 complete）；
   • 选择下一个可执行的 pending 阶段；
4. 从选中阶段中提取：阶段名称与描述、验收标准（acceptance criteria）、对前序阶段的依赖、范围注释与约束；
5. 将阶段描述作为待规划的功能输入。

若已无 pending 阶段，则直接报告所有阶段均已完成。

这一判定逻辑与上游 /prp-prd 产物格式严格对齐：查看 commands/prp-prd.md 第 291-330 行可见其 PRD 模板中的 Implementation Phases 表格带 Status（pending | in-progress | complete）、Parallel、Depends 与 PRP Plan 列，而 /prp-plan 正是这些列语义的消费者——它依据 Depends 判断依赖、依据 Status 选出"下一个待办阶段"，并把计划文件路径写回 PRP Plan 列。更直接的是，/prp-prd 生成结束后的输出模板（第 392 行）就写着：

Run: /prp-plan .claude/PRPs/prds/{name}.prd.md This will automatically select the next pending phase and create an implementation plan.

可见两条命令是一对"写需求"与"拆实现"的标准上下游。

四、Phase 1 — PARSE：澄清功能需求

在进入代码库之前，先用四个问题固定功能画像，避免带着模糊认知盲目搜索：

• What —— 要构建什么（具体的可交付物）；
• Why —— 为什么重要（用户价值）；
• Who —— 谁在用（目标用户/系统）；
• Where —— 落在代码库的哪一部分。

4.1 User Story 格式

将需求规范为统一句式：

As a [type of user],
I want [capability],
So that [benefit].

4.2 复杂度评估

用粗粒度分级辅助计划篇幅与任务拆解：

Level	Indicators	Typical Scope
Small	Single file, isolated change, no new dependencies	1-3 files, <100 lines
Medium	Multiple files, follows existing patterns, minor new concepts	3-10 files, 100-500 lines
Large	Cross-cutting concerns, new patterns, external integrations	10+ files, 500+ lines
XL	Architectural changes, new subsystems, migration needed	20+ files, consider splitting

4.3 歧义闸门（Ambiguity Gate）

以下任一情形不清晰时，必须停下来向用户提问，不得继续：

• 核心交付物含糊不清；
• 成功标准未定义；
• 存在多种合理解读；
• 技术方案存在重大未知项。

文档给出明确告诫：不要猜，要问（Do NOT guess. Ask）。建立在假设之上的计划必然在实现阶段失败。

五、Phase 2 — EXPLORE：深度代码库情报收集

这是 /prp-plan 区别于"简单模板填空"的关键阶段：直接对代码库执行真实搜索，为后续计划收集证据。

5.1 八个搜索类别

对每一类使用 grep、find 与文件阅读展开检索：

1. Similar Implementations（相似实现） —— 寻找与目标功能相近的既有特性，定位相似的端点、组件或模块；
2. Naming Conventions（命名约定） —— 识别相关区域内文件、函数、变量、类与导出的命名方式；
3. Error Handling（错误处理） —— 观察相似代码路径中错误如何被捕获、传播、记录并回传给用户；
4. Logging Patterns（日志模式） —— 明确记录什么内容、用什么级别、什么格式；
5. Type Definitions（类型定义） —— 定位相关类型、接口、schema 及其组织方式；
6. Test Patterns（测试模式） —— 研究相似功能的测试写法，记录测试文件位置、命名、setup/teardown 与断言风格；
7. Configuration（配置） —— 找到相关配置文件、环境变量与特性开关；
8. Dependencies（依赖） —— 盘点相似功能所用的包、import 与内部模块。

5.2 五条调用链追踪（Codebase Analysis Traces）

仅看散点不够，还要顺着执行路径读代码，追踪五类信息：

1. Entry Points（入口） —— 请求/动作如何进入系统并抵达你将要修改的区域；
2. Data Flow（数据流） —— 数据如何在相关代码路径中流转；
3. State Changes（状态变更） —— 哪些状态被修改、在哪里被修改；
4. Contracts（契约） —— 必须遵守哪些接口、API 或协议；
5. Patterns（架构模式） —— 采用了哪些架构模式（repository、service、controller 等）。

5.3 统一发现表（Unified Discovery Table）

把所有零散发现收敛为一张"随时可查"的引用表，成为计划正文中 Patterns to Mirror 的原料：

Category	File:Lines	Pattern	Key Snippet
Naming	src/services/userService.ts:1-5	camelCase services, PascalCase types	export class UserService
Error	src/middleware/errorHandler.ts:10-25	Custom AppError class	throw new AppError(...)
...	...	...	...

这一设计的可验证价值在下游充分体现：commands/prp-implement.md 的 Phase 1 — LOAD 只做一件事：cat "$ARGUMENTS" 读取计划，然后直接抽取 Summary、Patterns to Mirror、Files to Change、Step-by-Step Tasks、Validation Commands 与 Acceptance Criteria 开干——它之所以能"无查询执行"，前提正是 Phase 2 已把 File:Lines、代码片段与模式全部写死在计划里。

六、Phase 3 — RESEARCH：外部技术调研

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

1. 搜索官方文档；
2. 寻找使用范例与最佳实践；
3. 识别版本相关的坑。

每条发现统一格式化为三段式，确保"学到的东西"能落到计划具体位置：

KEY_INSIGHT: [what you learned]
APPLIES_TO: [which part of the plan this affects]
GOTCHA: [any warnings or version-specific issues]

若功能完全依赖团队已熟悉的内部模式，可跳过本阶段并显式注明：

"No external research needed — feature uses established internal patterns."

七、Phase 4 — DESIGN：UX 前后对照

若功能涉及用户界面，用 ASCII 图画出体验改造前后的差异：

Before:

┌─────────────────────────────┐
│  [Current user experience]  │
│  Show the current flow,     │
│  what the user sees/does    │
└─────────────────────────────┘

After:

┌─────────────────────────────┐
│  [New user experience]      │
│  Show the improved flow,    │
│  what changes for the user  │
└─────────────────────────────┘

再以触点表逐一列出变更：

Touchpoint	Before	After	Notes
...	...	...	...

纯后端/内部改动则标注：Internal change — no user-facing UX transformation. 这一小节会原样继承进计划文档的 UX Design 章节，成为验收时"界面是否达标"的判据。

八、Phase 5 — ARCHITECT：战略设计

在动笔生成文档前，先定义实现策略，形成四个固定决策项：

• Approach（方案）：高层策略。示例："Add new service layer following existing repository pattern"——即复用仓库已有 repository 模式新增 service 层；
• Alternatives Considered（备选方案）：评估过哪些替代路径、为何否决；
• Scope（范围）：明确将要构建的具体边界；
• NOT Building（明确不做）：逐条列出范围之外的内容，从源头杜绝实现阶段的蔓延（scope creep）。

九、Phase 6 — GENERATE：生成计划文档

9.1 保存路径与目录初始化

完整计划写入消费者项目内的固定制品目录：

.claude/PRPs/plans/{kebab-case-feature-name}.plan.md

目录不存在时先创建：

mkdir -p .claude/PRPs/plans

注意：文件名使用 kebab-case 功能名。产物路径与 commands/pr.md 第 77-79 行所描述的 legacy PRP 制品布局（prds/、plans/、reports/）保持一致，也与 commands/prp-implement.md 执行完成后的归档动作（把计划移动到 .claude/PRPs/plans/completed/）衔接。

9.2 计划文档完整模板

下面按原样给出 /prp-plan 要求生成的计划文档模板，它是整个命令的"交付物规格"，需逐字保留后按功能填充：

# Plan: [Feature Name]

## Summary
[2-3 sentence overview]

## User Story
As a [user], I want [capability], so that [benefit].

## Problem → Solution
[Current state] → [Desired state]

## Metadata
- **Complexity**: [Small | Medium | Large | XL]
- **Source PRD**: [path or "N/A"]
- **PRD Phase**: [phase name or "N/A"]
- **Estimated Files**: [count]

---

## UX Design

### Before
[ASCII diagram or "N/A — internal change"]

### After
[ASCII diagram or "N/A — internal change"]

### Interaction Changes
| Touchpoint | Before | After | Notes |
|---|---|---|---|

---

## Mandatory Reading

Files that MUST be read before implementing:

| Priority | File | Lines | Why |
|---|---|---|---|
| P0 (critical) | `path/to/file` | 1-50 | Core pattern to follow |
| P1 (important) | `path/to/file` | 10-30 | Related types |
| P2 (reference) | `path/to/file` | all | Similar implementation |

## External Documentation

| Topic | Source | Key Takeaway |
|---|---|---|
| ... | ... | ... |

---

## Patterns to Mirror

Code patterns discovered in the codebase. Follow these exactly.

### NAMING_CONVENTION
// SOURCE: [file:lines]
[actual code snippet showing the naming pattern]

### ERROR_HANDLING
// SOURCE: [file:lines]
[actual code snippet showing error handling]

### LOGGING_PATTERN
// SOURCE: [file:lines]
[actual code snippet showing logging]

### REPOSITORY_PATTERN
// SOURCE: [file:lines]
[actual code snippet showing data access]

### SERVICE_PATTERN
// SOURCE: [file:lines]
[actual code snippet showing service layer]

### TEST_STRUCTURE
// SOURCE: [file:lines]
[actual code snippet showing test setup]

---

## Files to Change

| File | Action | Justification |
|---|---|---|
| `path/to/file.ts` | CREATE | New service for feature |
| `path/to/existing.ts` | UPDATE | Add new method |

## NOT Building

- [Explicit item 1 that is out of scope]
- [Explicit item 2 that is out of scope]

---

## Step-by-Step Tasks

### Task 1: [Name]
- **ACTION**: [What to do]
- **IMPLEMENT**: [Specific code/logic to write]
- **MIRROR**: [Pattern from Patterns to Mirror section to follow]
- **IMPORTS**: [Required imports]
- **GOTCHA**: [Known pitfall to avoid]
- **VALIDATE**: [How to verify this task is correct]

### Task 2: [Name]
- **ACTION**: ...
- **IMPLEMENT**: ...
- **MIRROR**: ...
- **IMPORTS**: ...
- **GOTCHA**: ...
- **VALIDATE**: ...

[Continue for all tasks...]

---

## Testing Strategy

### Unit Tests

| Test | Input | Expected Output | Edge Case? |
|---|---|---|---|
| ... | ... | ... | ... |

### Edge Cases Checklist
- [ ] Empty input
- [ ] Maximum size input
- [ ] Invalid types
- [ ] Concurrent access
- [ ] Network failure (if applicable)
- [ ] Permission denied

---

## Validation Commands

### Static Analysis
```bash
# Run type checker
[project-specific type check command]
```
EXPECT: Zero type errors

### Unit Tests
```bash
# Run tests for affected area
[project-specific test command]
```
EXPECT: All tests pass

### Full Test Suite
```bash
# Run complete test suite
[project-specific full test command]
```
EXPECT: No regressions

### Database Validation (if applicable)
```bash
# Verify schema/migrations
[project-specific db command]
```
EXPECT: Schema up to date

### Browser Validation (if applicable)
```bash
# Start dev server and verify
[project-specific dev server command]
```
EXPECT: Feature works as designed

### Manual Validation
- [ ] [Step-by-step manual verification checklist]

---

## Acceptance Criteria
- [ ] All tasks completed
- [ ] All validation commands pass
- [ ] Tests written and passing
- [ ] No type errors
- [ ] No lint errors
- [ ] Matches UX design (if applicable)

## Completion Checklist
- [ ] Code follows discovered patterns
- [ ] Error handling matches codebase style
- [ ] Logging follows codebase conventions
- [ ] Tests follow test patterns
- [ ] No hardcoded values
- [ ] Documentation updated (if needed)
- [ ] No unnecessary scope additions
- [ ] Self-contained — no questions needed during implementation

## Risks
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| ... | ... | ... | ... |

## Notes
[Any additional context, decisions, or observations]

9.3 模板要点逐段解读

• Mandatory Reading 用 P0/P1/P2 三级标注"实现前必读文件"：P0 是必须严格遵循的核心模式所在，P1 是相关类型，P2 是相似实现参考。它把 Phase 2 的搜索结论变成了一份按优先级排序的阅读清单。
• Patterns to Mirror 是"照抄区"，直接粘贴真实代码片段并标注 SOURCE: [file:lines]，覆盖命名、错误处理、日志、数据访问、服务层与测试六类；其自检要求是"新代码将与既有代码无法区分（indistinguishable）"。
• Step-by-Step Tasks 中的每个任务必须同时具备 ACTION / IMPLEMENT / MIRROR / IMPORTS / GOTCHA / VALIDATE 六个属性，MIRROR 反向引用 Patterns to Mirror 中的条目，从而形成"任务 → 模式"的显式依赖图。
• Validation Commands 与 Acceptance Criteria 把"什么算做完"写成可执行命令与勾选项，是 /prp-implement 落地执行时逐条对照的依据——后者在其 Success Criteria 中镜像了 TASKS_COMPLETE / TYPES_PASS / LINT_PASS / TESTS_PASS / BUILD_PASS / REPORT_CREATED / PLAN_ARCHIVED 等判定。

9.4 输出与后续动作

保存计划：写入 .claude/PRPs/plans/{kebab-case-feature-name}.plan.md。

若输入为 PRD，则回写 PRD 状态：

1. 将该阶段状态从 pending 更新为 in-progress；
2. 在阶段中把计划文件路径作为引用加入（即填回 /prp-prd 模板里预留的 PRP Plan 列）。

向用户报告，输出结构固定为：

## Plan Created

- **File**: .claude/PRPs/plans/{kebab-case-feature-name}.plan.md
- **Source PRD**: [path or "N/A"]
- **Phase**: [phase name or "standalone"]
- **Complexity**: [level]
- **Scope**: [N files, M tasks]
- **Key Patterns**: [top 3 discovered patterns]
- **External Research**: [topics researched or "none needed"]
- **Risks**: [top risk or "none identified"]
- **Confidence Score**: [1-10] — likelihood of single-pass implementation

> Next step: Run `/prp-implement .claude/PRPs/plans/{name}.plan.md` to execute this plan.

其中 Confidence Score（1-10）是对"单次通过实现成功率"的显式自评——它把不确定性量化为一个数字，供开发者在进入实现前决定是否需要补足计划。

十、成稿前验证（Verification）

文档要求生成者在最终定稿前，对照以下六组清单逐项自查。这实际上是 /prp-plan 的"质量闸门"：

Context Completeness（上下文完备性）

• [ ] All relevant files discovered and documented
• [ ] Naming conventions captured with examples
• [ ] Error handling patterns documented
• [ ] Test patterns identified
• [ ] Dependencies listed

Implementation Readiness（实现就绪度）

• [ ] Every task has ACTION, IMPLEMENT, MIRROR, and VALIDATE
• [ ] No task requires additional codebase searching
• [ ] Import paths are specified
• [ ] GOTCHAs documented where applicable

Pattern Faithfulness（模式保真度）

• [ ] Code snippets are actual codebase examples (not invented)
• [ ] SOURCE references point to real files and line numbers
• [ ] Patterns cover naming, errors, logging, data access, and tests
• [ ] New code will be indistinguishable from existing code

Validation Coverage（验证覆盖）

• [ ] Static analysis commands specified
• [ ] Test commands specified
• [ ] Build verification included

UX Clarity（UX 清晰度）

• [ ] Before/after states documented (or marked N/A)
• [ ] Interaction changes listed
• [ ] Edge cases for UX identified

No Prior Knowledge Test（零先验知识测试）——最后一条也是最苛刻的一条：一个不熟悉该代码库的开发者，应能仅凭这份计划完成实现，无需再搜索代码库或提问；若做不到，就补齐缺失的上下文。这正是第一节核心理念的验收方式：计划的完备性由一个"陌生实现者能否独立完工"来证明。

十一、Next Steps：与下游命令的闭环

文档结尾指明了三条后续路径：

• 运行 /prp-implement <plan-path> 执行本计划；
• 运行 /plan 走无需制品的轻量会话式规划；
• 运行 /prp-prd 在范围尚不清晰时先产出 PRD。

结合 commands/prp-implement.md 第 380-385 行可看到更完整的生命周期：计划执行完成后进入 /code-review 评审 → /prp-commit 提交 → /prp-pr 发起拉取请求；若 PRD 还存在后续阶段，则再次执行 /prp-plan <next-phase> 进入下一轮规划。如此，"单阶段计划"被反复迭代，最终覆盖整个 PRD 的所有实现阶段。

十二、与仓库内其他规划能力的边界

为避免混淆，仓库内对 /prp-plan 的适用场景有明确边界说明，写作/选用时可作为依据：

• 在 commands/plan.md 第 197 行中，/prp-plan 被定位为 "legacy PRP flow / deep PRP planning"，适合需要 .claude/PRPs/ 制品沉淀的深度工作流；
• docs/PLAN-PRD-PATTERN.md 第 149-154 行说明：ECC 新增的 staging-file 规划命令与既有 prp-* 命令族共存，/prp-prd、/prp-plan、/prp-implement、/prp-commit、/prp-pr 保留为 legacy/deep 工作流命令，供已有 .claude/PRPs/ 制品的用户继续使用；
• commands/epic-decompose.md 第 20-23 行将 /plan 与 /prp-plan 列为 epic 任务分解的兼容别名；
• commands/code-review.md 第 102 行与 commands/pr.md 第 77-79 行说明评审与 PR 阶段会主动识别并读取 .claude/PRPs/{prds,plans,reports,reviews}/ 下的 legacy 制品作为上下文——这意味着 /prp-plan 生成的计划不仅是"给实现者看的说明书"，也是后续评审、提 PR 时被再次消费的一等公民制品。

结语

从 commands/prp-plan.md 出发可以看到，/prp-plan 的设计本质是把"人类工程师在实现前的心智准备"编码成可复现的流程：先判输入、再澄清需求、然后用八个搜索类别与五条调用链把代码库情报榨干、必要时补外部调研、明确 UX 变化与架构边界，最后输出一份处处带 SOURCE 引用、每条任务都带 MIRROR/VALIDATE、并能通过"零先验知识测试"的自包含计划。它把昂贵的代码库检索成本一次性前置，让后续的 /prp-implement 可以像照着施工图砌墙一样只做执行与校验——这正是 ECC 所倡导的 research-first 与 plan-before-build 工程文化在单功能粒度上的具体落地。