agent-debug

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# agent-debug — 双 agent × cc-code 驱动 bug 修复执行编排器

> **纯执行器**：只修已诊断的 bug，**不诊断**。根因与方案由 `/cc-code:plan-debug` 经 qa 自动整理进 `active/bugs.md` 的 B-n 条目，**只接 状态 = 待修复 的条目**（状态定义见 `templates/bugs.md`），本命令读 B-n 直接开发，**运行中零提问**：撞上需求 / 契约冲突的 B-n 挂起、3 轮仍不过的项记账，其余 B-n 照修，结尾一次交人（唯一出处 = `../cc-code/references/dev-qa-loop.md` §九）。
> **主控是编排者，不扮演任何角色**：派哪个 agent 就是哪个角色；角色权限唯一出处 = `active/Agent.md` §三。主控的写权限见 `active/Agent.md` §一，⛔ 不写 `gates.md` / `bugs.md` / L1~L3 文件。
> **与 agent-feature 的分工**：feature 是「加一个房间」（执行 F-n 需求增量）；本命令是「修房子里的漏水点」（执行 B-n bug 修复）。执行循环、回归策略同构；结算不同——本命令由 qa 把 B-n 搬 retired。
> **初衷铁律**：完整地修复 bug —— 修复面 = B-n 用例 + affected 算出的爆炸半径，⛔ 无 agent-whole-qa、无全量回归。
> **视觉缺陷同一链路**：视觉 bug 也走本命令的既有 B 序列（不另开链路）。期望出处可以是 A/U 断言、V 规则（`../cc-code/references/ui-gates.md`）、`design.md` 数值或已冻结基线；循环唯一出处 = `../cc-code/references/dev-qa-loop.md`。⛔ 本命令不派 uiux。

## 前置检查（启动时一次性）
1. 确认项目根存在 `.cc_code/`（否则提示先 `/cc-code:init`）。
2. 确认双 agent 可用：`dev` / `qa`。
3. **增量定位（⭐第一动作，见下节）**——定位失败即拒跑，后续检查全免。
4. 确认测试基建：读 `project.md` §六「测试基建契约」（测试 / 构建 / 自检命令的唯一来源）。契约不存在或未填实 → ⛔ 不猜命令，⛔ 拒跑，按 `dev-qa-loop.md` §九 出交人报告（下一步 `/cc-code:plan-feature`，补契约归 `architect`）；契约已填实但测试基建尚未落地 → 把「按契约搭测试基建」作为 Dev 段首个任务。视觉缺陷另需 `project.md` §六 的界面驱动工具 / 视觉测试位置 / 基线目录 / 视口集合 / 亮暗模式，缺任一 → ⛔ 拒跑，同上出交人报告。
5. **索引体检（静默）**：`codegraph status --json` —— `pendingChanges` 非 0 → 静默 `codegraph sync`；`initialized:false` → 报一行（⛔ 不自动重建）。CLI 未装则静默跳过（精准回归降级为全量）。⛔ 健康时一个字都不提。
6. 执行 `/cc-code:cc-code` 完成会话开启协议，锁定当前坐标。

## ⭐ 增量定位（第一动作，纯查表，零推理）

```
 ① 读 status.md「下一步」
      └─ 期望形态：「B-n 待修复」+（bugs.md 里有对应条目，状态 = 待修复）
           ├─ 没有 B-n / 下一步是别的事
           │     → ⛔ 拒跑：「没有待修复的 bug，请先走 /cc-code:plan-debug」
           │       （本命令绝不现场诊断根因——根因唯一来源 = B-n 条目）
           └─ 拿到 B 号 + 条目内容（现象 / 复现 / 期望出处 / 根因 / 爆炸半径 / 方案）
                （期望出处可为：prd / ux 的 A、U 断言；主人原话；V 规则与 `design.md` 数值；已冻结基线）
 ② 对账（B-n 修复 PASS 时 qa 已把条目搬 retired，所以仍在 bugs.md 的就是没修好的）：
      条目已不在 bugs.md → 报「B-n 已修复，无事可做」，结束
      条目在 bugs.md，按状态分流：
        ├─ 待修复 → B-n 即本次执行范围，进 Dev 段
        ├─ 待诊断 → ⛔ 拒跑：「诊断还没做完，请先走 /cc-code:plan-debug」
        └─ 待裁决 → ⛔ 拒跑：按 §九 出交人报告（待你补答 = 条目里「待裁决」那句话，下一步 /cc-code:plan-debug）
```

## 生命周期总览

```
启动 → 增量定位 → ①Dev → 校准 → ②QA 四层（逻辑/接口/交互/视觉）→ 校准
                              │
                    ┌─────────┴──────────┐
                    ▼                    ▼
              FAIL→回Dev(≤3)         PASS→结算→结束
                    │                （⛔ 无全量清算）
            3轮仍FAIL→qa 把 B-n 状态写回「待裁决」+ 卡点→进挂起清单，其余照常结算
```

## 阶段执行规范

### ① Dev 段（agent: dev）
| 项 | 内容 |
| --- | --- |
| 范围 | bugs.md 只读本次 B-n 条目；prd / ux 只读期望出处命中的断言 / 判定项；视觉缺陷另读 `design.md` 的命中页章与数值（只读命中段，不整份改）、`project.md` §一.1 主题入口；data / api 只读命中小节（读写权限以 `Agent.md` §三 为准）；派单另列 `.cc_code/references/INDEX.md`（经验索引，命中主题才打开；规则见 `Agent.md` §四第 7 条） |
| 做 | 只按 B-n 方案修：根因处修复 + 按「爆炸半径」里的技术备注（文件清单）逐文件核对连带；遵循 project.md 约定；⛔ 不重构无关代码；实现细节缺信息可自行决定并写进报告。视觉缺陷只改实现：⛔ 不改 `design.md` 数值、⛔ 不手改主题生成物（要改生成结果 → 改生成器 / 按项目约定重新生成） |
| 挂起 | 发现 B-n 方案要动契约（data / api）、需求（prd / ux）或视觉规格（`design.md` 数值本身错 / 与已冻结基线相抵）→ 挂起该 B-n，不动，在报告「挂起」里用业务语言写（技术细节另列）；主控转 qa 把该 B-n 写成待裁决，按 `dev-qa-loop.md` §九 记进挂起清单，其余 B-n 照修，⛔ 运行中不问主人 |
| 探针 | B-n「需加探针」非「无」时：先按其加临时日志，每条带标记 `CC-PROBE-B<n>`，走 `project.md` §七 门面（DEBUG 级）→ 复现取证 → 修复 → ⛔ 交 QA 前删光（`rg CC-PROBE-B<n>` 零命中） |
| 跑 | Agent(dev) → 自检：按 `project.md` §六 测试基建契约登记的命令，依次跑代码规范检查、类型检查、单测、e2e、视觉门（有哪些跑哪些，⛔ 不自带命令；视觉门只跑不改，⛔ 不写基线） |
| 输出 | 修复代码 + 完成报告（文件清单 + 自检 pass/fail + 视觉缺陷加「受影响端 / 视口 / 亮暗」+ 「采纳经验」一行，格式见 `Agent.md` §四第 7 条） |
| ✅ 完成后 | 执行 `/cc-code:cc-code` 校准（静默） |

### ② QA 段（agent: qa，灰盒）
| 项 | 内容 |
| --- | --- |
| 范围 | bugs.md 只读本次 B-n 条目；design 只读 B-n 命中页章与数值（视觉 bug）；`src/` 只读本段改动（读写权限以 `Agent.md` §三 为准） |
| 做 | ① 按「复现」写 bug 用例（修复前应不过、修复后应通过）②⭐**落一个永久回归测试进测试根**（`project.md` §六 声明；视觉缺陷落 `project.md` §六 登记的视觉测试位置，尺子 = `ui-gates.md`）③ 完整跑一遍 B-n 用例 + 爆炸半径回归；视觉缺陷按 B-n 的端 / 屏宽 / 亮暗取证（390 必测）④ 全库搜探针标记 `CC-PROBE-` 零命中，否则不过回 Dev |
| 跑 | Agent(qa) → Dev 段改动文件的 `affected` 回归范围优先（拿不到则全量）；疑难交互用界面驱动工具探索取证；测试与视觉门命令取自 `project.md` §六；性能只在全量验收与部署用 Lighthouse 命令行 |
| 写 | `gates.md`、`bugs.md`（结算时搬条目；3 轮仍 FAIL 时把状态写回「待裁决」）——qa 是这两处的唯一写者，主控不代写；回归测试落测试根；视觉缺陷的测试与**截图基线**落 `project.md` §六 登记的视觉测试位置与基线目录（**基线 qa 独占、入 git**） |
| 输出 | QA 报告（Verdict + B-n 用例结果 + 回归范围来源标注 + 视觉缺陷的端 / 视口 / 亮暗证据） |
| ✅ 完成后 | 执行 `/cc-code:cc-code` 校准（静默） |

> **⭐ 修复 PASS 硬条件**：回归测试存在且通过才许记通过（视觉缺陷的回归测试必须是机器检查，⛔ 不拿截图目视代替）。没有测试的修复不算修完 —— 没有回归测试，gates 的 ✅ 就是假账，下次这段代码被改动没人兜底。
> **期望行为永远只来自 B-n 条目**（出处为主人原话、prd / ux 既有断言、V 规则、`design.md` 数值或已冻结基线），⛔ 不拿代码或 dev 的解释当尺子；qa 用 codegraph 的权限见 Agent.md codegraph 权限矩阵。

## qa → dev 循环（QA 段内）

> **循环协议唯一出处 = `../cc-code/references/dev-qa-loop.md`**（一轮定义、按失败项计轮、≤3 轮、升级包、任务单字段）。本命令只写差异：

1. dev 每轮只修不改方案、不改需求；修完重算 `codegraph affected <本轮修改文件>`，qa 复测范围 = B-n 用例 + affected 爆炸半径（拿不到则退回全量）+ 本轮受影响的视觉页 × 视口 × 亮暗。
2. 视觉失败项同样按失败项计轮：VH 由 qa 判、dev 修，⛔ 主控不代判、不删项、不把 VS 当阻断。
3. 每轮循环后执行 `/cc-code:cc-code` 校准（静默）；3 轮仍 FAIL → qa 把 B-n 状态写回「待裁决」并写清卡点，该项进挂起清单（§九），其余照常结算（⛔ 不回诊断、不点名去找谁）；全绿 → QA 段 PASS。
   > 修复期间 B-n 状态保持「待修复」不变：派 dev 修之前不改状态（此时 qa 尚未派出）；只有复测 PASS（条目搬 retired）或 3 轮仍 FAIL（写回待裁决）才动它。

## 修复结算（QA PASS 即结束，⛔ 无全量清算）

```
 qa 复测 PASS
    │
    ▼
 ① qa 记账 gates.md（按 B-n「期望出处」分三路）
      ├─ 出处 = 既有 A / U 断言 → 就地改写该断言行为通过（换新测试位置，不新开行）
      ├─ 出处 = V 规则 / design.md 数值 → 就地改写 §2.4 V 段对应行（同一事实只判一次）
      └─ 出处 = 主人原话        → 追溯矩阵 B 段追加一行 B-n 通过
    ▼
 ② 视觉缺陷且命中带基线的页面（组件陈列页 / 样板页）→ qa 重冻受影响页基线
      （⛔ 失败轮不冻、⛔ 不改阈值；范围外差异判回归，不顺手更新基线）
    ▼
 ③ qa 结算 bugs.md：该条目原文整段搬 backup/retired/bugs.md
      （带搬运头：日期 ｜ 来源 ｜ 退役原因「B-n 修复 PASS」），再从 active 移除
      ⛔ 不直接删——内容一个字都不许丢
    ▼
 ④ 主控追加 backup/milestone-log.md 一行
      （日期 ｜ 模块 ｜ B-n <简述> 修复 PASS ｜ 期望出处断言号 / V 规则号 / B-n）
    ▼
 ⑤ 主控更新 status.md（下一步清空 B-n 指向，或指向遗留待办）
    ▼
 ⑥ 后台派 curator（规则见 active/Agent.md §四第 7 条、§五「派 curator」；视觉段只做台账）
    ▼
 ⑦ 报告：按 dev-qa-loop.md §九 三段出（结果 = 用例通过 + 回归范围 + 回归测试位置；待你补答 = 挂起清单；
      下一步命令 + 完整 prompt），下一步同步写进 status.md
```

- **3 轮仍 FAIL 记账结算时同样后台派 `curator`**（每次结算都派，规则同上）。
- 追溯 = retired 原文 + milestone-log 一行 + 留守的回归测试。
- **不跑 agent-whole-qa、不做全量回归** —— bug 修复的验收面就是 B-n 用例 + affected 精准回归面；全量清算只属于 MVP 收口或主人显式调用 `/cc-code:agent-whole-qa`。

> ⭐ **写 active 前必过「就地更新 + 搬运归档」**（规则单一出处 = `active/Agent.md` §四第 5 条），各写者只动自己负责的文件。

## 编排器行为准则

- **你是编排器**：按阶段派对应 agent，不在主控里替角色思考，不扮演任何角色。

From weiyi88/cc-code, MIT.

More from weiyi88/cc-code