cmbuyer/docs/method-map.md

方法对照表

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

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

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

本项目特有的失败模式

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

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

使用原则

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

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

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

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