CCPM Plan 阶段实战：从头脑风暴到 PRD，再到可分解的技术 Epic-二趣网

CCPM Plan 阶段实战：从头脑风暴到 PRD，再到可分解的技术 Epic

【免费下载链接】ccpmProject management skill system for Agents that uses GitHub Issues and Git worktrees for parallel agent execution.项目地址: https://gitcode.com/GitHub_Trending/ccpm/ccpm

Plan（规划）是 CCPM（Claude Code Project Manager）五阶段规范驱动开发流程的第一环，其核心任务是把一个模糊的"想法"固化为结构化的 PRD（产品需求文档），再进一步解析为面向技术实现的技术 Epic。本文以 CCPM 技能包中的 plan.md 为骨架，完整讲解 PRD 的编写规范、PRD 到 Epic 的解析流程、质量门槛与编辑守则，并结合仓库中的 conventions.md 与配套脚本给出可复制的操作细节。读完本文，你将掌握如何在任意 Agent 工作区中产出符合 CCPM 文件约定的 PRD 与 Epic，为后续任务分解、GitHub 同步和并行执行铺平道路。

CCPM 中的 Plan 阶段定位

CCPM 把软件交付生命周期划分为五个阶段：Plan（捕获需求）→ Structure（分解任务）→ Sync（同步 GitHub）→ Execute（并行执行）→ Track（状态跟踪）。正如 SKILL.md 所描述，其核心哲学是"需求存在于文件中，而不是头脑中"（Requirements live in files, not heads）：每个功能先从 PRD 开始，变成技术 Epic，再分解为 GitHub Issues，最终由并行 Agent 执行并保持全程可追溯。

Plan 阶段覆盖两件事：

编写 PRD：通过引导式头脑风暴，把用户想法沉淀为带 frontmatter 的PRD: <name>文档；
解析 PRD：把现有 PRD 转换为技术 Epic，即.claude/epics/<name>/epic.md。

整个阶段产生的所有文件都遵循统一的目录约定（见 conventions.md 的 Directory Structure）：

.claude/ ├── prds/ │ └── <feature-name>.md # 产品需求文档 └── epics/ ├── <feature-name>/ │ └── epic.md # 技术 Epic

所有跨阶段文件操作（frontmatter 结构、日期格式、命名规则）都必须先查阅 conventions.md，这些约定对 Plan 阶段同样生效。

编写 PRD

触发条件与预检查

触发条件：用户想要规划一个新功能、产品需求或工作领域。典型口语触发包括"我想构建 X"、"为 X 写一个 PRD"、"帮我把这个范围定一下"。

动笔之前必须完成三项预检查（Preflight）：

查重：检查.claude/prds/<name>.md是否已存在——如果存在，必须先与用户确认是否覆盖，不能静默覆盖已有文档；
建目录：确保.claude/prds/目录存在，不存在则创建；
校验命名：功能名必须为 kebab-case（小写、仅字母/数字/连字符、以字母开头）。不符合时输出固定错误提示：
```
❌ Feature name must be kebab-case. Example: user-auth, payment-v2
```
这一命名规则在 conventions.md 的 Naming Conventions 一节中也被强制约定：功能名必须小写 kebab-case、与文件名一致。例如user-auth、payment-v2合法，而UserAuth、payment_v2、2fa都不合法。

头脑风暴先行

plan.md 明确要求：在写任何内容之前，先进行一次真正的头脑风暴（Conduct a genuine brainstorming session），而不是直接套模板。向用户提出以下五个问题：

这个功能解决什么问题？（What problem does this solve?）
受影响的用户是谁？（Who are the users affected?）
成功长什么样？（What does success look like?）
明确排除在范围之外的是什么？（What's explicitly out of scope?）
有哪些约束——技术、时间、资源？（What are the constraints?）

这五个问题分别对应 PRD 模板中的 Problem Statement、User Stories、Success Criteria、Out of Scope、Constraints & Assumptions，确保后续文档不是空泛套话，而是有真实决策依据。这一"先思考再落盘"的流程，正是 README.md 强调的No Vibe Coding原则在需求阶段的体现。

PRD 文件结构与 frontmatter

头脑风暴完成后，写入.claude/prds/<name>.md。文件必须包含 frontmatter 与固定章节结构，完整模板如下（plan.md）：

--- name: <feature-name> description: <one-line summary> status: backlog created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ"> --- # PRD: <feature-name> ## Executive Summary ## Problem Statement ## User Stories ## Functional Requirements ## Non-Functional Requirements ## Success Criteria ## Constraints & Assumptions ## Out of Scope ## Dependencies

逐字段说明：

name：kebab-case 功能名，与文件名一致；
description：一句话摘要，prd-list.sh 与 prd-status.sh 会把它直接展示在列表里，因此要写得足够自解释；
status：取值backlog、active或completed（conventions.md 的 PRD Frontmatter Schema）。plan.md 中新建 PRD 默认backlog；
created：必须取系统真实当前时间，禁止占位文本。统一使用命令date -u +"%Y-%m-%dT%H:%M:%SZ"生成 ISO 8601 格式（UTC），这也是 conventions.md 的 Datetime Rule。

说明：<run: ...>是 CCPM 文档中的约定写法，表示该字段由 Agent 在运行时执行命令生成，而不是字面写入的字符串。

正文九个章节中，## Executive Summary（执行摘要）应给出一段凝练的全局说明，## Problem Statement对齐头脑风暴第一个问题，## User Stories用用户故事句式（"作为…我希望…以便…"）描述需求，## Functional Requirements与## Non-Functional Requirements分别列功能性与非功能性需求，## Success Criteria定义可衡量的验收指标，## Constraints & Assumptions记录约束与假设，## Out of Scope显式列出不做的事，## Dependencies记录对现有模块、外部服务或依赖项的依赖关系。

保存前的质量门槛

plan.md 定义了四条硬性质量门槛（Quality gates），未通过不得保存：

任何章节都不允许有占位文本（No placeholder text in any section）；
用户故事必须包含验收标准（User stories include acceptance criteria）；
成功标准必须可衡量（Success criteria are measurable）；
范围外内容必须显式列出（Out of scope is explicitly listed）。

这四条门槛把"文档写完了"与"文档写对了"区分开，是后续解析为 Epic 时不再返工的前提。

创建完成后的确认

保存成功后，向用户输出确认信息，并主动给出下一步动作建议：

✅ PRD created: `.claude/prds/<name>.md` Ready to create technical epic? Say: parse the <name> PRD

这样把 Plan 阶段的两个子流程自然地衔接起来。

将 PRD 解析为技术 Epic

触发条件与预检查

触发条件：用户希望把现有 PRD 转换为技术实施计划。典型触发语："解析 X 的 PRD"、"为 X 创建 Epic"。

预检查包含两项：

验证 PRD 存在且 frontmatter 合法：.claude/prds/<name>.md必须存在，且 frontmatter 包含name、description、status、created四个字段（与 conventions.md 的 PRD Schema 一致）；
Epic 查重：检查.claude/epics/<name>/epic.md是否已存在，存在则先与用户确认是否覆盖。

Epic 文件结构与 frontmatter

完整阅读 PRD 后，产出.claude/epics/<name>/epic.md，模板如下（plan.md）：

--- name: <feature-name> status: backlog created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ"> progress: 0% prd: .claude/prds/<name>.md github: (will be set on sync) --- # Epic: <feature-name> ## Overview ## Architecture Decisions ## Technical Approach ### Frontend Components ### Backend Services ### Infrastructure ## Implementation Strategy ## Task Breakdown Preview ## Dependencies ## Success Criteria (Technical) ## Estimated Effort

与 PRD 相比，Epic 的 frontmatter 新增了几个关键字段（对照 conventions.md 的 Epic Frontmatter Schema）：

progress：进度百分比，新建时为0%，后续在任务关闭时按closed / total重新计算；
prd：指向来源 PRD 的路径，形成 PRD → Epic 的可追溯链；
github：同步到 GitHub 后填入 Epic Issue 的 URL（占位说明(will be set on sync)表示该字段在 Sync 阶段由同步脚本写入，见 sync.md）；
updated：Epic 每次被编辑时更新的时间戳（plan.md 的 Editing 一节要求维护此字段）。

正文章节则从"产品视角"切换到"技术视角"：## Architecture Decisions记录关键架构决策与取舍，## Technical Approach分 Frontend Components、Backend Services、Infrastructure 三个子层描述技术方案，## Implementation Strategy给出实施策略，## Task Breakdown Preview是后续 Structure 阶段任务分解的预览，## Success Criteria (Technical)定义技术验收标准，## Estimated Effort给出工作量估算。

三条关键约束

plan.md 为 Epic 解析定义了三条约束，直接决定后续任务分解的形态：

任务总量 ≤ 10 个：优先简单而非"完备"（prefer simplicity over completeness）。这一约束与 structure.md 中"小 Epic（<5 任务）顺序创建、中等 Epic（5–10 任务）分批并行"的策略相呼应——超过 10 个任务的 Epic 会显著增加并行协调成本；
优先复用已有功能：在写新代码之前，先寻找可复用的现有能力（leverage existing functionality），避免重复造轮子；
在任务分解预览中识别并行化机会：提前标注哪些任务可以并行，为 Structure 阶段设置parallel: true/depends_on/conflicts_with元数据做准备。

创建完成后的确认

✅ Epic created: `.claude/epics/<name>/epic.md` Ready to decompose into tasks? Say: decompose the <name> epic

至此，Plan 阶段闭环：想法 → 头脑风暴 → PRD → Epic，并自然导向下一阶段 Structure（任务分解）。

编辑 PRD 或 Epic

plan.md 最后给出编辑守则：先读文件，再做定向编辑，保留所有 frontmatter，并更新updated字段为当前时间。

结合 conventions.md 的 Frontmatter Update Pattern，单字段更新推荐用sed原地替换：

sed -i.bak "/^<field>:/c\\<field>: <value>" <file> rm <file>.bak

例如把某个 Epic 的status改为active：

sed -i.bak "/^status:/c\\status: active" .claude/epics/<name>/epic.md rm .claude/epics/<name>/epic.md.bak

注意事项：

切勿整体重写文件或删掉 frontmatter 字段——prd、github、progress等字段是后续阶段脚本（如 epic-status.sh）读取元数据的依据；
编辑后同步更新updated（Epic/Task 必含该字段；PRD 若需要记录修改时间也应维护它）；
需要把 frontmatter 剥离出来给 GitHub 用（Sync 阶段场景）时，使用 conventions.md 提供的双段剥离命令：
```
sed '1,/^---$/d; 1,/^---$/d' <file> > /tmp/body.md
```

Plan 阶段的配套脚本佐证

Plan 阶段产出的 PRD 与 Epic，会在后续 Track 阶段由确定性 bash 脚本读取和展示，这也反向约束了本阶段的文件格式必须严格合规。从源码可以看到这些脚本对 frontmatter 字段的依赖：

prd-list.sh 按status字段把 PRD 分组为 Backlog / In-Progress / Implemented，并读取name、description展示——因此新建 PRD 时status: backlog与可读的description缺一不可；
prd-status.sh 统计各状态 PRD 数量并绘制条形图，还会依据状态给出下一步建议（如backlog数量 > 0 时建议"Parse backlog PRDs to epics"），恰好衔接 Plan → Structure；
epic-list.sh 读取epic.md的name、status、progress、github字段并按状态分组展示，同时统计 Epic 目录下的任务文件数量——可见 Epic 解析时把progress: 0%写好、把任务目录结构留好，后续统计才能正确工作；
epic-status.sh 解析epic.md的status/progress/github，遍历[0-9]*.md任务文件统计 total / closed / open / blocked 并渲染进度条；
validate.sh 会校验所有 PRD/Epic 文件是否包含 frontmatter、是否有孤儿任务文件、depends_on引用的任务是否存在——这再次印证 Plan 阶段留下的每一个字段、每一条依赖都会被机器化校验，格式即契约。

此外，若项目尚未初始化（.claude/不存在），track.md 要求先运行 init.sh，它会创建prds/、epics/等目录结构并检查 gh CLI 与认证，确保 Plan 阶段的目录约定就绪。

小结：Plan 阶段的最佳实践清单

先头脑风暴，后写文档——五个引导问题全部对齐后再落盘；
命名严守 kebab-case，否则直接报错拒绝；
PRD 与 Epic 的 frontmatter 严格遵循 conventions.md 的 Schema，时间用date -u +"%Y-%m-%dT%H:%M:%SZ"生成；
过质量门槛再保存：无占位文本、用户故事带验收标准、成功标准可衡量、Out of Scope 显式列出；
Epic 控制在 ≤10 个任务、优先复用、预判并行化；
编辑走定向 sed 更新，保留 frontmatter 并维护updated字段；
把"确认 + 下一步建议"输出给用户，引导进入decompose the <name> epic的 Structure 阶段。

Plan 阶段产出的.claude/prds/<name>.md与.claude/epics/<name>/epic.md，将作为后续任务分解（structure.md）、GitHub 同步（sync.md）、并行执行（execute.md）与状态跟踪（track.md）的唯一事实来源——写好这一份文档，等于为整条规范驱动交付流水线打下了可追溯的地基。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析