4.5 KiB
4.5 KiB
方法对照表
把最常见的长时 coding-agent 失败模式，对应到本仓库里最该先补的工件或规则。 出问题时先查这张表，对症补对应工件，不要把更多规则一股脑堆进一个超长入口文件。
失败模式 → 首要修复 → 工件
| 失败模式 | 实际表现 | 首要修复 | 主要工件 |
|---|---|---|---|
| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | current-state.md + tasks/ 任务文件的执行记录 |
| 启动脆弱 | 每轮会话都要重新学怎么启动、装依赖、跑测试 | 统一启动与验证路径 | ../init.sh / ../init.ps1 |
| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | tasks/README.md |
| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | tasks/README.md（passing 需证据）+ clean-state-checklist.md |
| 自写自审偏差 | 写入 Agent 只复述自己的实现，自测缺口和安全 / 架构风险被合理化 | 保留唯一写入者，按风险增加只读测试与安全 / 架构评审，并针对固定 SHA 复审 | tasks/README.md + gitea-collaboration.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 重复领取 | 两个 agent 同时把同一 Issue 改为 doing，读回后都以为成功 | 由 dispatcher 串行分配，claim 分支只作防御性标记，标签只展示状态 | gitea-collaboration.md |
| 多 agent 写路径碰撞 | 不同任务同时修改同一目录或共享配置，合并时才发现冲突 | dispatcher 串行声明 / 比较 write_paths，worker 使用独立 worktree |
gitea-collaboration.md + tasks/README.md |
| claim 长期占用 | Issue 仍 doing，但 agent 已退出或分支无活动，后续任务无法分配 | 只读审计 lease_until，人工核实后回收，不自动抢占 |
gitea-collaboration.md + ../scripts/audit_gitea_coordination.py |
| 规则悄悄漂移 | 导航、任务元数据、模板或敏感配置在多轮提交后不一致 | 用同一离线治理命令在本地和 Actions 检查 | ../scripts/validate_harness_governance.py |
使用原则
- 优先补最能直接消除当前失败模式的那一个工件，不要一次铺开全部。
- 工件之间用链接互相引用，让全新 agent 不问人也能从一个文件跳到相关规则。
- 同一个事实只维护一份，避免多个文件互相打架。
- 修复落地的同一轮会话里，就把对应工件更新掉。
评审 vs 健康度：两个不同的问题
evaluator-rubric.md回答："这轮 agent 做得好不好？"（单次输出质量）quality-document.md回答："这个项目在变强还是变弱？"（代码库本身质量）
两者配合：rubric 守住每轮交付，quality document 守住长期趋势。