# 方法对照表

> 把最常见的长时 coding-agent 失败模式，对应到本仓库里最该先补的工件或规则。
> 出问题时先查这张表，对症补对应工件，不要把更多规则一股脑堆进一个超长入口文件。

## 失败模式 → 首要修复 → 工件

| 失败模式 | 实际表现 | 首要修复 | 主要工件 |
| --- | --- | --- | --- |
| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | [`current-state.md`](current-state.md) + [`tasks/`](tasks/README.md) 任务文件的执行记录 |
| 启动脆弱 | 每轮会话都要重新学怎么启动、装依赖、跑测试 | 统一启动与验证路径 | [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1) |
| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | [`tasks/README.md`](tasks/README.md) |
| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | [`tasks/README.md`](tasks/README.md)（passing 需证据）+ [`clean-state-checklist.md`](clean-state-checklist.md) |
| 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 每轮留下明确的当前快照和下一步 | [`current-state.md`](current-state.md) |
| 评审主观 | 质量判断靠个人记忆和感觉，agent 容易自我说服通过 | 用固定维度做评分 | [`evaluator-rubric.md`](evaluator-rubric.md) |
| 代码库悄悄退化 | 速度上去了，但几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | [`quality-document.md`](quality-document.md) |
| 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄 | [`00-ai-start-here.md`](00-ai-start-here.md) + 拆分到具体文档 |
| 每轮全量重读 | 多 agent 反复拉取全部文档，慢且容易混入无关上下文 | 用任务路由和提交 / 文件 SHA 增量读取 | [`agent-context.md`](agent-context.md) + [`agent-context.json`](agent-context.json) |
| 多 agent 抢改任务文件 | 多个 agent 并发时抢改同一个看板/进度文件，出现"读到旧版本"、ID 撞号、合并冲突 | 一任务一文件（默认模式已内建），执行记录进任务文件，不逐任务改共享收尾文件 | [`tasks/README.md`](tasks/README.md) |
| 多 agent 写路径碰撞 | 不同任务同时修改同一目录或共享配置，合并时才发现冲突 | 开工前声明并比较 `write_paths`，重叠时不并行；两端任务天然可拆 | [`tasks/README.md`](tasks/README.md) |

## 本项目特有的失败模式

以下四条来自前序项目 `cmroubao` / `cmpdd` 的真实教训，比通用条目更值得先防。

| 失败模式 | 实际表现 | 首要修复 | 主要工件 |
| --- | --- | --- | --- |
| 护栏被悄悄放宽 | 为了「先让流程跑通」把精确匹配改成模糊匹配、把停止改成兜底继续 | 把安全边界列成硬清单并要求逐条测试覆盖 | [`05-coding-rules.md`](05-coding-rules.md) 第 1 节 + [`04-architecture.md`](04-architecture.md) 第四节 |
| 页面判据凭推理 | 照搬旧项目常量或从文档推断页面结构，真机上判据不命中 | 先真机 dump 取证再写代码，判据记录拼多多 App 版本 | [`00-ai-start-here.md`](00-ai-start-here.md) 四条纪律 + [`tasks/README.md`](tasks/README.md) 真机证据要求 |
| 双端契约漂移 | web 与 desk 各自演进，字段或语义静默不兼容 | 契约集中在一处，改动必跑两端完整门禁 | [`api.md`](api.md) + [`03-tech-stack.md`](03-tech-stack.md) 验证矩阵 |
| 真机任务被自行标完成 | agent 用离线测试代替真机验收，把 `DONE` 建立在推断上 | `needs_device: true` 的任务只能由人验收 | [`tasks/README.md`](tasks/README.md) 硬规则 |
| 授权卡死锁任务 | 一笔永不推进的授权把任务锁在等待态，无法重来 | 围栏前允许超时 / 放弃并强制重新试选；围栏后只调和、不释放 | [`04-architecture.md`](04-architecture.md) 第 5.3 节 + T-207 / T-208 |
| 点击前后断网导致重复下单 | 客户端不知道是否取得执行权或订单是否已创建 | 点击前由服务端原子围栏；响应不明不点击；点击后保持同一提交记录人工调和 | [`04-architecture.md`](04-architecture.md) 第四节 + T-208 / T-401 |

## 使用原则

- 优先补最能直接消除当前失败模式的那**一个**工件，不要一次铺开全部。
- 工件之间用链接互相引用，让全新 agent 不问人也能从一个文件跳到相关规则。
- 同一个事实只维护一份，避免多个文件互相打架。
- 修复落地的同一轮会话里，就把对应工件更新掉。

## 评审 vs 健康度：两个不同的问题

- [`evaluator-rubric.md`](evaluator-rubric.md) 回答：**"这轮 agent 做得好不好？"**（单次输出质量）
- [`quality-document.md`](quality-document.md) 回答：**"这个项目在变强还是变弱？"**（代码库本身质量）

两者配合：rubric 守住每轮交付，quality document 守住长期趋势。