> For the complete documentation index, see [llms.txt](https://cc-code.rongyeliu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cc-code.rongyeliu.com/skills/plan-prd-feature/skill.md).

# /cc-code:plan-prd-feature — 增量需求规划器（第一动作即 plan 模式）

> ⭐⭐⭐ **触发后第一动作 = call `EnterPlanMode` 工具。** 所有体检 / 侦察 / 三件套 / 交谈都在 plan 模式内做，**没有 plan 外窗口**。 **适用场景：MVP 已交付，在既有实现上做功能迭代。** 0→1 定全量请用 `/cc-code:plan-prd-mvp`。

## ⛔ 六条铁律（违反任一即本次规划无效）

### 铁律 1：第一动作 call EnterPlanMode

触发后，在 call `EnterPlanMode` 之前，**不许做任何动作**：

* ❌ 不许先 Read `Agent.md` / `status.md`
* ❌ 不许先 codegraph 探测
* ❌ 不许先输出三件套
* ❌ 不许先输出「请主人审阅决策清单」
* ✅ 唯一允许的第一动作：call `EnterPlanMode` 工具

### 铁律 2：codegraph 只准校准 L3，永不许生成 L1 / L2 / L4

这是插件信息流铁律，本 skill 最易踩的坑 —— **迭代场景下代码已存在，AI 会本能地"读代码推需求"，那是需求层被实现层反向污染**。

```
codegraph 的产出只许流向三处：
  ✅ 判定「已实现 / 未实现」            —— 纯事实陈述
  ✅ 算改动爆炸半径（impact / callers）  —— 纯事实陈述
  ✅ 校准 L3 契约的实现状态标记          —— Architect 契约纪律授权

  ⛔ 绝不许反推「所以需求应该是 X」      —— L1 唯一来源 = 主人的话
  ⛔ 绝不许反推「所以断言应该是 Y」      —— L1 / L4 禁生成
  ⛔ 绝不许反推「所以界面应该长 Z」      —— L2 唯一来源 = 主人的话

新需求的逻辑与原型只能从【与主人的对话】长出来。
codegraph 只提供「现状那一半」，用于双联对比与冲突取证。
```

### 铁律 3：契约漂移禁沉默

codegraph 撞出「代码 ≠ `active/api.md` / `active/data.md` 契约」时，**立即停下逐条请主人二选一**：改代码回归契约 / 修契约并记录。禁止默默按代码算、也禁止默默按契约算。

### 铁律 4：禁批量决策清单

⛔ 禁止「全量输出决策清单，可全量接受 / 逐项修订 / 否决某项」。 必须逐点提问：一次只问一个模糊点或一条冲突，等主人答，再问下一个。

### 铁律 5：禁塞单一文件

⛔ 禁止把所有产出一股脑写进 `active/prd.md`。必须按内容性质路由到对应层的文件，**一层一文件一角色**（见「五、落盘路由表」）。

### 铁律 6：越权红线

```
⛔ active/gates.md         —— QA 唯一域，本 skill 绝不写
⛔ src/ 与测试目录          —— Dev 唯一域，本 skill 绝不写
⛔ active/Agent.md 权限路由表 —— 人的域，一个字不许动
✅ active/Agent.md「当前激活角色」一行 —— 仅在主人当场确认后代笔改
```

***

## 一、生命周期总览

```
触发 /cc-code:plan-prd-feature "<新需求>"
  │
Step0 ⭐ call EnterPlanMode（第一动作，Write/Edit 当场锁死）
  │ ══════════════ 以下全程 plan 模式内（只读 + 文字输出）══════════════
Step0.5 规范体检门
  │   项目 active/Agent.md ⟷ 插件规范比对
  │     宪法比规范薄 → ⚠️提醒升级，不阻断，按插件规范推进
  │     目录形态偏离 → ⛔停手，要求先跑 /cc-code:init
  │
Step1 基线锁定（只读，守上下文最小化）
  │   Agent.md   → 锁角色权限路由表
  │   status.md  → 里程碑=已开发 · 下一步=已规划未开发 · Blockers
  │   prd.md     → 章节标题 + 模块清单 + 断言最大编号 + Out of Scope
  │   gates.md   → 已 PASS / FAIL / UNVERIFIABLE / ESCALATE
  │
Step2 codegraph 侦察（受铁律 2 约束，只取事实）
  │   ⓪ 新鲜度保险 → status --json：pendingChanges 非 0 则先 sync
  │   ① explore(需求原话) → query(实体名) → node(读符号)
  │   ② impact(核心符号) → 传递闭包真半径（比 callers 一层准）
  │   ③ files → 目录树现状 ⟷ project.md §三 目录规约 对账
  │   ④ affected(涉及文件) → 测试影响面，写进差异表
  │   顺手撞契约漂移 → 触发铁律 3
  │
Step3 需求逐点三态判定（禁悬空，每点必须落格）
  │   ✅已实现 / ⚪未实现无冲突 / ⛔未实现有冲突
  │
Step4 冲突逐条硬门控（一次一条，四选一，未裁决完禁 ExitPlanMode）
  │
Step5 输出三件套（ascii）
  │   ① 逻辑图  ② 原型双联  ③ 差异表（带落盘路由列）
  │
Step6 逐点循环至通顺（⛔禁批量决策清单）
  │     否 → 问下一个 → 回 Step5 刷新
  │
Step7 三门齐开才 call ExitPlanMode
  │ ══════════════ 退出 plan 模式 ══════════════
Step8 按层分批切角色落盘（PM 批 → Architect 批）
  │
Step9 顺手更新 status.md 坐标 → 提示走 /cc-code:agent-to-mvp
```

***

## 二、Step0.5 规范体检门

以**插件规范为唯一标尺**，项目 `.cc_code/` 的形态不作为依据。

| 体检项            | 规范态（`templates/Agent.md`）            | 缺失时的动作                     |
| -------------- | ------------------------------------ | -------------------------- |
| 文件分层表          | L0\~L4 五层 + 唯一写者                     | ⚠️提醒升级，缺的按规范当默认生效          |
| 信息流铁律          | L1→L2→L3→代码，L4 只拿 L1/L2 当尺子          | ⚠️同上                       |
| codegraph 纪律   | 只准校准 L3，永不生成 L1/L2/L4                | ⚠️同上（**本 skill 无论如何强制生效**） |
| PM 两产物边界       | `prd.md` 规则 / `ux.md` 界面；断言 A 序列永久稳定 | ⚠️同上                       |
| Architect 契约纪律 | 契约漂移禁沉默                              | ⚠️同上                       |
| QA 灰盒定义        | 需求只来自 L1/L2/api，代码永不重定义需求            | ⚠️同上                       |

提醒话术（命中任一即报，只报一次，不啰嗦）：

```
⚠️ 本项目 .cc_code 为旧版形态，缺 <项>。
   建议：/plugin update cc-code  →  重跑 /cc-code:init 升级
   本次规划仍按插件规范推进。
```

**目录形态偏离 → 停手**（防写坏文件）：

```
规范路径缺失（如无 active/ux.md、prd.md 不在 active/ 下、L3 三件缺项）
  ⛔ 停：「规范路径 <X> 不存在，请先跑 /cc-code:init 归正目录形态，
          否则增量章节会落错文件造成版本冲突。」
  → 仅当主人明示「就落 <实际文件>」才落，落完再提醒一次升级
```

***

## 二·五、Step2 codegraph 侦察规格（0.10.0 扩容）

> 受铁律 2 约束：本步只取**事实**，一个字都不许流向 L1 / L2 / L4。 CLI 未装 → 全步降级为 Glob / Grep 表层扫描，并在三件套里标注「半径为估算」。

### ⓪ 新鲜度保险（必做第一件事）

```
codegraph status --json
  pendingChanges 非 0  → 先跑一次 codegraph sync 再侦察
  为什么: daemon 空闲 5min 自杀, 期间的改动无人追写。
          catch-up 只在 daemon 复活时跑, 存在「拿到旧数据」的竞态窗口。
          规划阶段读到旧索引 → 半径算错 → 冲突漏判, 代价最大。
  initialized:false → 报一行, 本次降级为表层扫描（⛔ 不自动重建）
```

### ①\~④ 四路侦察（各有分工，不可互相替代）

| 序 | 能力                           | 回答什么             | 产出流向                               |
| - | ---------------------------- | ---------------- | ---------------------------------- |
| ① | `explore` → `query` → `node` | 「这块现在怎么实现的」      | Step3 三态判定的「已实现」判据 + 原型双联的「现状」那一半  |
| ② | `impact <核心符号>`              | 「改它会炸到哪」**传递闭包** | 差异表「爆炸半径」列                         |
| ③ | `files`                      | 「目录树现状」          | 与 `project.md` §三 目录规约对账，偏离即触发铁律 3 |
| ④ | `affected <涉及文件>`            | 「该补/该跑哪些测试」      | 差异表「测试影响」列，供 Dev 段落地               |

**② 为什么必须用 `impact` 而非只用 `callers`**：

```
callers  只回答「谁直接调它」        —— 一层
impact   回答「改它的传递影响面」    —— 闭包（depth 默认 2，可调）

  一层视野会把跨层级的连带改动漏掉 → 半径估小 → 规划时以为「改一处」
  实际动到五处 → Dev 段爆炸 → 返工。两者并用: impact 定面, callers 定点。
```

**④ `affected` 返回空的处置**（报一行，不做前置检测）： ① 测试代码是否被 `.gitignore` 屏蔽（被 ignore 则不进索引）② 测试是否 `import` 被测源码（纯 HTTP 型无 import 边）③ 命名是否需 `--filter "<project.md §六 登记的 glob>"`。

***

## 三、Step3 三态判定与冲突源

每个需求点必须落进一格，**禁悬空、禁一点跨两格**（跨了就是需求点没拆够，先拆）。

```
┌──────────────┬─────────────────────────────────────────────┐
│ ✅ 已实现     │ codegraph 找到等价实现                        │
│              │ → 报「已有，位置 <file:line>」，问主人是否改口径│
├──────────────┼─────────────────────────────────────────────┤
│ ⚪ 未实现无冲突│ 不与任何已 PASS 断言 / 规则 / Out of Scope 抵触│
│              │ → 直接进新增逻辑                             │
├──────────────┼─────────────────────────────────────────────┤
│ ⛔ 未实现有冲突│ 与下表任一冲突源抵触 → 押进 Step4             │
└──────────────┴─────────────────────────────────────────────┘
```

冲突源必扫八处，一处不许跳：

| # | 冲突源         | 在哪查                                                                               | 层  |
| - | ----------- | --------------------------------------------------------------------------------- | -- |
| 1 | 已 PASS 验收断言 | `active/gates.md` 实测结果                                                            | L4 |
| 2 | 模块核心规则 R    | `active/prd.md` 逐模块规格                                                             | L1 |
| 3 | 全局规则 G      | `active/prd.md` 全局规则                                                              | L1 |
| 4 | 明确不做        | `active/prd.md` Out of Scope                                                      | L1 |
| 5 | 已作废/已删功能    | `active/prd.md` 的 `~~作废~~` 断言 + 各文件**文末变更台账**（顺台账链翻 `docs/plans/F-n-*.md` 的冲突收敛表） | L1 |
| 6 | 交互五态        | `active/ux.md` 五态矩阵                                                               | L2 |
| 7 | 数据契约        | `active/data.md` interface ↔ DB 列                                                 | L3 |
| 8 | 接口契约 + 架构决策 | `active/api.md` / `active/project.md` Needs Decision                              | L3 |

***

## 四、Step4 冲突硬门控

一次只摆一条，四选一，**未拿到裁决禁止进 Step5**：

```
⛔ 冲突 n/N 待裁决
   旧：<来源文件 §章节> <旧值原文>
   新：<需求点>
   四选一：
    [1] 覆盖旧值 → 旧断言号加 ~~删除线~~ + 注明被谁取代，绝不重排绝不复用
    [2] 新旧共存 → 必须给出可判真假的分支判据，模糊判据不算裁决
    [3] 放弃新需求 → 本条移出范围，写进 prd.md Out of Scope
    [4] 延后       → 写进 prd.md 待澄清，不进本次断言
```

***

## 五、落盘路由表（唯一权责边界）

### ⛔ 落盘第一纪律：就地收敛，禁追加章节

```
   active = 最新 + 最完整 + 最纯净

   ❌ 旧协议(0.8.0 及以前): 各层文件尾部新开「## 增量 F-n」章节
      → N 次增量后, 同一个 interface / path / 规则 散成 N 段补丁
      → Dev 得读 N 处自行拼接才知道「现在长什么样」
      → active 行数随迭代线性膨胀, 且无收敛出口

   ✅ 新协议(0.9.0 起): 就地改写 + 台账留痕 + 过程外置
      ├─ 变更内容 ──► 直接改写 active 里对应小节（原位覆盖）
      ├─ 新断言   ──► 续编进 prd.md §1.5 主表 / ux.md §2.3 矩阵
      ├─ 过程产物 ──► docs/plans/F-n-<需求名>.md
      ├─ 变更留痕 ──► 各文件文末「变更台账」追加 1 行
      └─ 历史版本 ──► 靠 git（.cc_code 已在版本控制内，不另存快照）
```

**写入前三问**（任一不通过即停手重判）：

| # | 自查               | 不通过怎么办                          |
| - | ---------------- | ------------------------------- |
| 1 | active 里已有对应小节吗？ | 有 → **就地改写**，⛔ 禁新开章节            |
| 2 | 这段在回答「现在是什么」吗？   | 不是（是「当时怎么决定的」）→ 落 `docs/plans/` |
| 3 | 别的层已经有了吗？        | 有 → 不写，只留指针（跨层唯一源）              |

### 落哪个文件、写什么

| 层      | 规范文件                      | 唯一写者      | 本 skill 落什么（**就地改写**）                                              | 绝不写                   |
| ------ | ------------------------- | --------- | ------------------------------------------------------------------ | --------------------- |
| **L1** | `active/prd.md`           | PM        | 模块规则（改写对应模块小节）· 验收断言 **A 序列续编进 §1.5 主表** · 业务状态机                   | 线框、字段类型、接口参数、**增量章节** |
| **L2** | `active/ux.md`            | PM        | 视觉规格（改写对应页面小节，只留**目标态**）· 交互五态矩阵 **U 序列续编** · 组件清单                 | 业务规则、字段类型、**增量章节**    |
| **L3** | `active/project.md`       | Architect | 架构决策 · 技术选型 · 目录（改写对应章节）                                           | 需求、线框、**增量章节**        |
| **L3** | `active/data.md`          | Architect | 数据契约（改写该 interface / 该表小节）                                         | 需求、线框、**增量章节**        |
| **L3** | `active/api.md`           | Architect | method / path / 入参 / 出参 / 错误码（改写该 path 小节）                         | 需求、线框、验收断言、**增量章节**   |
| —      | `docs/plans/F-n-<需求名>.md` | 本 skill   | ⭐**过程产物集中地**：需求清单 R · 冲突收敛表 · 裁决记录 · 契约漂移登记 · 迁移检查清单 · 现状态原型 · 待澄清 | 当前态规格（那些进 active）     |
| L0     | `active/status.md`        | 当前角色 AI   | 坐标 + 下一步（规范协议第 4 条授权顺手写）                                           | 里程碑（QA PASS 后才写）      |
| L0     | `active/Agent.md`         | **人**     | ⛔ 仅代笔改「当前激活角色」一行                                                   | 权限路由表任何一字             |
| L4     | `active/gates.md`         | QA        | ⛔ **绝不碰**                                                          | —                     |
| —      | `src/` + 测试目录             | Dev       | ⛔ **绝不碰**                                                          | —                     |

**判据速查：** 能脱离界面存在的 → L1；离开界面就没意义的 → L2；只有工程师关心的 → L3；**回答「当时怎么决定的」→ `docs/plans/`**。

**增量批次号（F-n）：** 读各层文件\*\*文末「变更台账」\*\*已有最大 `F-n` → 本次取 `F-(n+1)`。同一需求在所有命中文件用同一个 F 号，台账行 + `docs/plans/F-n-*.md` 共同构成跨文件追溯链。

> ⚠️ **台账不是章节**：台账是文末一张表，每次增量只加**一行**（F 号 / 日期 / 改了什么一句 / 冲突裁决 / 详情链接）。它顶替旧协议里 `## 增量 F-n` 章节的追溯职能，代价从数十行降到 1 行。

**三件套的落盘去向（避免重复，守 DRY）：**

| 三件套              | 落哪                          | 说明                              |
| ---------------- | --------------------------- | ------------------------------- |
| ① 逻辑图 · 业务状态机    | L1 `prd.md`（**改写**对应模块状态机段） | 业务流转                            |
| ① 逻辑图 · 页面流转     | L2 `ux.md`（**改写**对应页面五态段）   | 交互五态                            |
| ② 原型双联 · **目标态** | L2 `ux.md`（**覆盖**原页面线框）     | 只留目标态                           |
| ② 原型双联 · **现状态** | `docs/plans/F-n-*.md`       | 服务裁决留档，不进 active                |
| ③ 差异表 / 冲突收敛表    | `docs/plans/F-n-*.md`       | ⭐改动点：不再进 `prd.md`，避免 active 堆历史 |

***

## 六、Step7 出关三门（缺一不许 ExitPlanMode）

| 门   | 判据                                 |
| --- | ---------------------------------- |
| 门 1 | 所有冲突均已拿到主人四选一裁决                    |
| 门 2 | 三件套已输出，且主人**明确说**验收通过（沉默 / "嗯" 不算） |
| 门 3 | 差异表每一行都填了「落盘文件」+「权责角色」，无空格         |

**通顺三判据**（Step6 循环的收敛条件）：

1. **逻辑通顺** —— 每条流转有明确触发与结果，无悬空分支、无孤儿状态
2. **配置通顺** —— 新增配置项有默认值 / 取值范围 / 生效时机
3. **断言可判真假** —— 禁「优化 / 友好 / 更好 / 提升体验」等无法判真假的词

***

## 七、Step8 分批切角色落盘

```
8.1 从差异表聚合批次：角色 → 待落文件（按 PM → Architect 顺序，严守串行）
8.2 ⭐先落过程产物（无需切角色，docs/ 不属任何角色专属域）：
     └─ 写 docs/plans/F-n-<需求名>.md：需求清单 R · 冲突收敛表 · 裁决记录
        · 契约漂移登记 · 迁移检查清单 · 现状态原型 · 待澄清
8.3 for 每个批次：
     ├─ 报本批：角色 / 文件清单 / 每文件**要改写哪个小节**
     ├─ 请示主人：「确认切到 <角色>？」   ⛔ 未确认不许动任何文件
     ├─ 主人确认 → Edit active/Agent.md「当前激活角色」→ <角色>（只改这一行）
     ├─ 重新 Read active/Agent.md 加载新权限表
     ├─ 校验：本批文件 ⊆ 该角色【可写】域？越界即停并报错，绝不硬写
     ├─ ⭐就地收敛写入（过写入前三问）：
     │    ├─ 有对应小节 → Edit 改写该小节（原位覆盖）
     │    ├─ 无对应小节 → 在该文件**语义正确的位置**新建小节（不是文件尾巴）
     │    ├─ 新断言 → 续编进 prd.md §1.5 主表 / ux.md §2.3 U 矩阵
     │    └─ ⛔ 禁新开「## 增量 F-n」章节
     ├─ 文末「变更台账」追加 1 行（F 号 / 日期 / 改了什么 / 裁决 / docs/plans 链接）
     └─ 报本批产物清单（含「改写了哪些小节」明细，便于主人核对）
8.4 落完报「Dev / QA 域未动」，提示主人走 /cc-code:agent-to-mvp
```

> ⭐ **就地改写 ≠ 丢历史**：`.cc_code` 在 git 内，`git log -p active/prd.md` 即完整变更史。台账行 + `docs/plans/F-n-*.md` 提供语义级追溯。三者叠加，比堆积增量章节更完整且不污染 active。

⚠️ 切角色前严禁预读下一角色的禁读文件 —— 侦察阶段（Step1/Step2）的全域只读是**具名例外**，落盘阶段必须回到严格角色权限。

***

## 八、与 `plan-prd-mvp` 的分工

| 维度   | `plan-prd-mvp`              | `plan-prd-feature`（本 skill）                                                             |
| ---- | --------------------------- | --------------------------------------------------------------------------------------- |
| 场景   | 0→1 定 MVP 全量                | MVP 已交付，功能迭代                                                                            |
| 基线   | 粗探项目                        | 硬锁 status + gates + prd 历史 + 断言最大号                                                      |
| 代码理解 | Glob / Grep 表层              | codegraph 四路侦察：explore/node 读现状 · impact 算传递闭包半径 · files 对账目录 · affected 算测试面（受铁律 2 约束） |
| 冲突处理 | 无（首版无历史）                    | 八处冲突源 + 逐条硬门控裁决                                                                         |
| 契约漂移 | 不涉及                         | 撞出即停，逐条二选一                                                                              |
| 产出   | 覆写 `prd.md`（旧版归档 `backup/`） | **就地收敛改写**命中层文件对应小节 + 台账 1 行 + 过程落 `docs/plans/`                                        |
| 落盘层  | 仅 L1                        | L1 + L2 + L3 动态命中                                                                       |
| 角色   | 单一 PM 域                     | PM 批 → Architect 批，逐批请示切换                                                               |
| 断言   | A1..An 全新                   | A 序列**续编进 §1.5 主表**，作废加删除线；UI 侧 U 序列续编进 `ux.md` §2.3                                    |
| 出关   | 逻辑+配置通顺                     | 通顺 **且** 冲突全裁决 **且** 主人明确验收                                                             |

***

## 九、关键约束速查

| 约束                        | 说明                                                |
| ------------------------- | ------------------------------------------------- |
| ⭐ 第一动作 call EnterPlanMode | 触发后不许先做别的                                         |
| 无 plan 外窗口                | 体检/侦察/三件套/交谈全在 plan 内                             |
| 规范唯一源 = 插件                | 项目 `.cc_code` 形态不作依据；落后即提醒升级 + 重跑 `/cc-code:init` |
| codegraph 只校准 L3          | 永不生成 L1/L2/L4                                     |
| 契约漂移禁沉默                   | 逐条二选一                                             |
| ⛔ 禁批量决策清单                 | 一次一个模糊点                                           |
| 冲突未裁决完禁出关                 | 硬门控                                               |
| ⛔ 禁塞单一文件                  | 按层路由，一层一文件一角色                                     |
| ⛔ 禁追加增量章节                 | 就地收敛改写对应小节；过程落 `docs/plans/`；台账 1 行留痕             |
| 切角色须请示                    | `Agent.md` 只许改「当前激活角色」一行                          |
| plan 内只读                  | 一切写入等 ExitPlanMode 后                              |
| 不找 bug                    | bug 是 QA 职责                                       |
| 不写代码                      | 代码是 Dev 职责                                        |

***

## 十、与主线的关系

```
plan-prd-feature（支线）              cc-code 主线
──────────────────────               ──────────────────────
Step0   EnterPlanMode                /cc-code:agent-to-mvp
Step0.5 规范体检                      ├─ PM（细化 L1/L2）
Step1-2 基线 + codegraph 侦察          ├─ Architect（补齐 L3）
Step3-4 三态判定 + 冲突裁决             ├─ Dev（编码）
Step5-6 三件套 + 逐点交谈              └─ QA（验收 → gates.md）
Step7   ExitPlanMode approve
Step8   分批切角色落 L1/L2/L3 ────►  /cc-code:whole-qa（收口全量验收）
Step9   status.md 坐标 + 提示下一步
```

***

## 十一、触发后首步动作

⭐ **第一个动作：call `EnterPlanMode` 工具。不许先做任何其他事。**

进入 plan 模式后，按 Step0.5 → Step9 执行。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cc-code.rongyeliu.com/skills/plan-prd-feature/skill.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.