Plan Feature

---
name: plan-feature
description: 加新功能前先扫现有代码查冲突，列出改哪建哪，写成方案文档
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, EnterPlanMode, ExitPlanMode, ToolSearch, mcp__codegraph__codegraph_explore
disable-model-invocation: true
---

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

> ⭐⭐⭐ **触发后第一动作 = call `EnterPlanMode` 工具。**
> ⚙️ 引擎分支（双端同一条规则）：无 `EnterPlanMode` 工具的引擎（如 Codex）→ 第一动作改跑 Bash `mkdir -p .cc_code/.runtime && touch .cc_code/.runtime/plan-lock` 开护栏（此后写盘被 gate.sh 拦），出关经主人确认落盘清单后 `rm .cc_code/.runtime/plan-lock`。
> 所有体检 / 侦察 / 三件套 / 交谈都在 plan 模式内做，**没有 plan 外窗口**。
> **适用场景：MVP 已交付，在既有实现上做功能迭代。** 0→1 定全量请用 `/cc-code:plan-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-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
  │   ⛔ 不读 back_up/（历史是人的，AI 判断已开发用模块清单状态列 + gates 实测）
  │
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 坐标（点名 F-n + 新断言号）
  │      → 提示走 /cc-code:agent-feature
```

---

## 二、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` 的 `~~作废~~` 断言 + `back_up/change-log.md`（顺 F 号查历次裁决记录） | 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 矩阵
      ├─ 过程产物 ──► ⛔ 不落盘（对话内裁决即用即弃），
      │              留痕 = back_up/change-log.md 追加 1 行（裁决列）
      ├─ 变更留痕 ──► back_up/change-log.md 追加 1 行（⛔ active 文件内不留台账）
      └─ 历史版本 ──► 靠 git（.cc_code 已在版本控制内，不另存快照）
```

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

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

**落盘剥残留**（落盘完必做——否则「最纯净」只有入径没有出径，残戳会随增量复利堆积）：

- 就地改写时**同步剥掉**该文件内的历史残留：章节标题 `（F-n，日期）` 戳记、行内 `★ F-n：` 标记、「触发根因 / 就地收敛说明 / 主人裁决 D-n」过程引言、文末「编号续编（F-n）」台账注释、指向 `docs/plans/` 过程文档的指针行。
- 作废规则 / 作废断言**整行删除**，编号与取代关系写进 change-log 该行「详情」列（编号永不重排，尸体不留正文）。
- 落盘后自查：`grep -nE "★ F-|（F-[0-9]|触发根因|主人裁决|编号续编" .cc_code/active/*.md`，命中即回刀剥净。

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

| 层 | 规范文件 | 唯一写者 | 本 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 小节） | 需求、线框、验收断言、**增量章节** |
| L0 | `active/status.md` | 当前角色 AI | 坐标 + 下一步（**点名 F-n + 新断言号**，agent-feature 的增量定位入口；规范协议第 4 条授权顺手写） | 里程碑（落 `back_up/milestone-log.md`，QA PASS 后才写） |
| L0 | `active/Agent.md` | **人** | ⛔ 仅代笔改「当前激活角色」一行 | 权限路由表任何一字 |
| L4 | `active/gates.md` | QA | ⛔ **绝不碰** | — |
| — | `src/` + 测试目录 | Dev | ⛔ **绝不碰** | — |

**判据速查：** 能脱离界面存在的 → L1；离开界面就没意义的 → L2；只有工程师关心的 → L3；**回答「当时怎么决定的」→ 不落盘（change-log 一行留痕）**。

**增量批次号（F-n）：** 读 `back_up/change-log.md` 已有最大 `F-n` → 本次取 `F-(n+1)`。同一需求在所有命中文件用同一个 F 号，`back_up/change-log.md` 一行即跨文件追溯链（F 号贯穿所有命中文件 + status.md 下一步指向）。

> ⚠️ **台账不是章节**：台账是 `back_up/change-log.md` 全局流水表（列结构见 `Agent.md` 归档规范），每次增量只加**一行**（F 号 / 日期 / 层 / 文件 / 模块 / 改了什么 / 裁决 / 详情链接）。它顶替旧协议里 `## 增量 F-n` 章节的追溯职能，代价从数十行降到 1 行，且不污染任何 active 文件。

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

| 三件套 | 落哪 | 说明 |
| --- | --- | --- |
| ① 逻辑图 · 业务状态机 | L1 `prd.md`（**改写**对应模块状态机段） | 业务流转 |
| ① 逻辑图 · 页面流转 | L2 `ux.md`（**改写**对应页面五态段） | 交互五态 |
| ② 原型双联 · **目标态** | L2 `ux.md`（**覆盖**原页面线框） | 只留目标态 |
| ② 原型双联 · **现状态** | ⛔ 不落盘 | 服务当轮对话裁决，裁决完即弃 |
| ③ 差异表 / 冲突收敛表 | ⛔ 不落盘 | 落盘结果已体现为 active 就地改写 + change-log 一行 |

---

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

| 门 | 判据 |
| --- | --- |
| 门 1 | 所有冲突均已拿到主人四选一裁决 |
| 门 2 | 差异表每一行都填了「落盘文件」+「权责角色」，无空格 |

> 冲突裁决与逐点交谈本身就是主人的确认——**落盘即定稿，无二次验收**。落盘后想改，直接改对应 active 小节（或再跑一次本命令）。

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

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

---

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

```
8.1 从差异表聚合批次：角色 → 待落文件（按 PM → Architect 顺序，严守串行）
8.2 for 每个批次（⭐免请示：主人对话定稿即授权，直接按序切换）：
     ├─ Edit active/Agent.md「当前激活角色」→ <角色>（只改这一行，代笔）
     ├─ 重新 Read active/Agent.md 加载新权限表
     ├─ 校验：本批文件 ⊆ 该角色【可写】域？越界即停并报错，绝不硬写
     ├─ ⭐就地收敛写入（过写入前三问）：
     │    ├─ 有对应小节 → Edit 改写该小节（原位覆盖）
     │    ├─ 无对应小节 → 在该文件**语义正确的位置**新建小节（不是文件尾巴）
     │    ├─ 新断言 → 续编进 prd.md §1.5 主表 / ux.md §2.3 U 矩阵
     │    └─ ⛔ 禁新开「## 增量 F-n」章节
     ├─ `back_up/change-log.md` 追加 1 行（F 号 / 日期 / 层 / 文件 / 模块 / 改了什么 / 裁决 / 详情）
     └─ 报本批产物清单（含「改写了哪些小节」明细，便于主人核对）
8.3 落完报「Dev / QA 域未动」，提示主人走 /cc-code:agent-feature
```

> ⭐ **就地改写 ≠ 丢历史**：`.cc_code` 在 git 内，`git log -p active/prd.md` 即完整变更史。`back_up/change-log.md` 提供语义级追溯（F 号 + 裁决摘要）。两者叠加，比堆积增量章节更完整且不污染 active。

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

---

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

| 维度 | `plan-mvp` | `plan-feature`（本 skill） |
| --- | --- | --- |
| 场景 | 0→1 定 MVP 全量 | MVP 已交付，功能迭代 |
| 基线 | 粗探项目 | 硬锁 status + gates + prd 历史 + 断言最大号 |
| 代码理解 | Glob / Grep 表层 | codegraph 四路侦察：explore/node 读现状 · impact 算传递闭包半径 · files 对账目录 · affected 算测试面（受铁律 2 约束） |
| 冲突处理 | 无（首版无历史） | 八处冲突源 + 逐条硬门控裁决 |
| 契约漂移 | 不涉及 | 撞出即停，逐条二选一 |
| 产出 | 覆写 `prd.md`（旧版归档 `backup/`） | **就地收敛改写**命中层文件对应小节 + `back_up/change-log.md` 1 行（过程不落盘） |
| 落盘层 | 仅 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 |
| 契约漂移禁沉默 | 逐条二选一 |
| ⛔ 禁批量决策清单 | 一次一个模糊点 |
| 冲突未裁决完禁出关 | 硬门控 |
| ⛔ 禁塞单一文件 | 按层路由，一层一文件一角色 |
| ⛔ 禁追加增量章节 | 就地收敛改写对应小节；过程不落盘；`back_up/change-log.md` 1 行留痕 |
| 切角色免请示 | 对话定稿即授权；`Agent.md` 只许改「当前激活角色」一行 |
| plan 内只读 | 一切写入等 ExitPlanMode 后 |
| 不找 bug | bug 是 QA 职责 |
| 不写代码 | 代码是 Dev 职责 |

---

## 十、与主线的关系

```
plan-feature（规划支线）              cc-code 主线
──────────────────────               ──────────────────────
Step0   EnterPlanMode                /cc-code:plan-mvp（0→1 规划）
Step0.5 规范体检                        /cc-code:agent-mvp（0→1 执行）
Step1-2 基线 + codegraph 侦察            ├─ Dev（编码）
Step3-4 三态判定 + 冲突裁决               └─ QA（验收 → gates.md）
Step5-6 三件套 + 逐点交谈                  → agent-whole-qa（收口全量验收）
Step7   ExitPlanMode approve
Step8   分批切角色落 L1/L2/L3 ────►  /cc-code:agent-feature（增量执行：
Step9   status.md 点名 F-n + 断言        增量定位 → Dev → QA，精准回归）
```

---

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

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

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