附录 A · 自检清单合集

每章结尾都给了一份检查清单，这里汇总在一起，方便随时翻。

harness 自检（第 1 章）

遇到 Agent 表现不好时，按以下顺序排查（先别想模型的事）：

工具层面

[ ] 工具描述是否足够清晰？有没有写"什么时候用、什么时候不用"？
[ ] 工具描述里有没有具体的 usage example？
[ ] 工具失败时，返回的错误信息够不够？是泛泛的"出错了"，还是"原因 + 当前输入 + 建议修正"？
[ ] 工具返回值是否包含模型下一步决策需要的信息？

上下文层面

[ ] 模型每次决策时，能看到它需要的所有信息吗？
[ ] 上下文里有没有冗余信息，挤占了有效空间？
[ ] 过时的格式约束、冗余的 few-shot，还在 prompt 里吗？

循环层面

[ ] Agent 的最大循环次数够不够？
[ ] 循环耗尽时有没有兜底？
[ ] 触发和响应有没有混在一起？

验证层面

[ ] 你怎么知道这次输出是对的？
[ ] 工具调用的副作用，有没有被验证过安全？

认知阶位自检（第 2 章）

阶 1 Prompt

[ ] 你会不会在 system prompt 里加示例来控制输出格式？
[ ] 你能不能区分"必须遵守的规则"和"参考信息"？

阶 2 Context

[ ] 你有没有主动管理过模型的"视野"？
[ ] 当 Agent "健忘"的时候，你会不会去查"它那个瞬间到底能看到什么"？

阶 3 Harness

[ ] 你写工具描述的时候，是当成 API 文档写，还是当成 prompt 写？
[ ] 工具失败时，返回的错误信息里有没有"下一步建议"？

阶 4 Loop

[ ] 你的 Agent 执行循环，能用一句话描述吗？
[ ] 你有没有在代码里用 if-else 替模型做了它本该自己做的决定？

项目失控自检（第 3 章）

颗粒度

[ ] 我这次的交付单元是什么？能用一句话描述吗？
[ ] 这个单元需要多久能做完？超过半天的话，能不能再拆？
[ ] 我有没有写过"非目标"清单？

验证

[ ] 每个交付单元，我怎么验证它做对了？
[ ] 我的验证标准，是从"技术指标"写的，还是从"用户体验"写的？
[ ] 我能不能一句话说出"这一步成了"长什么样？

可回滚

[ ] 我有没有版本管理？
[ ] 我有没有可回滚的部署机制？
[ ] 我的提交粒度是大是小？

危险信号

[ ] 计划文档越来越长，但完成进度几乎没动
[ ] 在反复打补丁修同一个区域的问题，而不是退一步重新设计
[ ] 代码改动牵一发动全身，改一个地方冒出来好几个新问题
[ ] 错误日志在重复刷同一行，但你不知道，因为没有告警

工具设计检查（第 4 章）

描述

[ ] 描述里有没有具体的用法示例？
[ ] 描述里说清楚了"什么时候用"吗？有没有说"什么时候不用"？
[ ] 参数级别的描述够不够精确？

返回值

[ ] 返回值是给模型看的，还是给开发者看的？
[ ] 返回值里有没有模型下一步决策需要的信息？
[ ] 返回值会不会太长？太长的话有没有截断提示？

错误处理

[ ] 错误信息是不是只有一句"出错了"或"参数错误"？
[ ] 错误信息有没有"递出下一把钥匙"？
[ ] 错误信息会不会被截断逻辑砍掉？

硬编码参数

[ ] 截断阈值设了多少？为什么是这个值？
[ ] 错误信息走不走截断？
[ ] 有没有哪些值是"替模型做了决定"的？

循环设计检查（第 5 章）

循环本身

[ ] 我的核心循环能用一句话描述吗？
[ ] 我有没有在循环里塞多阶段编排？
[ ] 我有没有用 if-else 替模型做了它本该自己做的决定？

触发与响应

[ ] 触发和响应是不是绑死了？
[ ] 有没有"关注但不回复"的中间态？
[ ] 能不能通过消息格式或提示词，让模型自己区分场景？

护栏

[ ] 循环有没有次数上限？到了上限怎么办？
[ ] 有没有"回复保证"？
[ ] 有没有"卡住检测"？

该用循环还是状态机？

[ ] 这块功能的"下一步"是模型决定的，还是事先确定的？
[ ] 如果是事先确定的，我有没有为了"统一"硬套循环？

eval 设计检查（第 6 章）

用例本身

[ ] 预期行为写得足够具体吗？换一个人来看，能给出一致判断吗？
[ ] 有没有写反例（"不该怎样"）？
[ ] 用例来源标注了吗？（bug 驱动 / 场景驱动）

打分手段

[ ] 能用代码量化的指标，是不是都用了代码断言？（别什么都扔给 LLM 裁判）
[ ] 用了 LLM 裁判的地方，评判标准写得够清楚吗？
[ ] 有没有定期人工抽查校准？

工程卫生

[ ] 用例之间是隔离的吗？跑完一个用例，会不会污染下一个？
[ ] reset 清干净了吗？把模块级可变状态（单例/缓存/字典/标志位）都扫一遍，别只想着数据库
[ ] eval 结果可复现吗？（同一代码版本、同一用例，跑两次结果一致吗？）

eval-driven 实践

[ ] 新功能开发前，先写了 eval 用例吗？
[ ] eval 通过后，用例沉淀到回归基线了吗？

非确定性测试检查（第 7 章）

是不是真的不稳定？

[ ] 同一用例、同一代码版本，连跑 3 次，结果一致吗？
[ ] 如果不一致——是 Agent 行为变了，还是裁判判错了？（先排查裁判）
[ ] eval 环境是干净的吗？上一个用例的残留有没有污染？（数据库、缓存、全局状态）

应对策略

[ ] 你的 eval 是跑一次就判生死，还是跑多次看通过率？
[ ] 通过率阈值设了多少？合理吗？（太严会假阳性，太松会假阴性）
[ ] 不同维度有没有区分运行次数？（确定性维度少跑，概率性维度多跑）
[ ] 概率维度里，处在"灰色地带"的用例（裁判容易纠结的）有没有多跑几次？

裁判可靠性

[ ] 裁判和 Agent 是不是用了不同的模型？
[ ] 裁判的 prompt 有没有明确的、具体的评判标准（锚点）？
[ ] 裁判打分是单次判定，还是跑多次取通过率？
[ ] 最近有没有人工抽查校准过裁判的判断？
[ ] 你心里清楚"裁判也会判错"这件事吗？

全局

[ ] 你的项目里，哪些部分是确定性的，哪些是概率性的？
[ ] 确定性部分用传统测试，概率性部分用 eval——两边都覆盖了吗？
[ ] 有没有"确定性部分测得很好，概率性部分完全没测"的盲区？

多 Agent 决策检查（第 8 章）

先问自己三个问题

[ ] 我真的需要两种不同的专业能力吗？
[ ] 这两种能力真的没法在一个 Agent 里组合吗？
[ ] 任务的复杂度真的超过单 Agent 的上下文管理能力了吗？

如果决定拆，再问三个问题

[ ] 两个 Agent 的能力是 genuinely 互补的吗？
[ ] 任务主要是"读取"还是"写入"？
[ ] 你准备好了协调成本吗？

最危险的信号

[ ] 你想引入多 Agent 只是因为单 Agent"不稳定"
[ ] 你想让多个 Agent"讨论"来解决问题
[ ] 你觉得多 Agent"更先进"

双 Agent 协作检查（第 9 章）

异步与回调

[ ] 子 Agent 执行的时候，主流程会不会卡住？
[ ] 子 Agent 完成后，结果怎么传回主 Agent？
[ ] 主 Agent 收到结果时，上下文还在吗？

上下文传递

[ ] 你是把内容塞进 prompt，还是给文件路径让子 Agent 自己读？
[ ] 子 Agent 有没有"上次的记忆"？
[ ] 任务描述是结构化的，还是自然语言闲聊？

产出验证

[ ] 子 Agent 的产出有没有自动验证？
[ ] 验证是单层还是双层？
[ ] 验证标准写清楚了吗？

失败处理

[ ] 验证失败后会自动重试吗？
[ ] 重试带不带反馈？
[ ] 重试上限设了吗？

权限与安全

[ ] 子 Agent 的操作权限是怎么管的？
[ ] 什么操作自动批准，什么操作需要人审批？
[ ] 审批的交互在哪里完成？

三层协作自查（第 10 章）

人的角色

[ ] 人需要介入的节点定义清楚了吗？
[ ] 人的介入频率合理吗？
[ ] 人不在的时候，系统能安全运行吗？

PM Agent

[ ] PM Agent 有"能力边界意识"吗？
[ ] PM Agent 维护着项目的完整状态吗？
[ ] PM Agent 的产出验证是否可靠？

开发 Agent

[ ] 开发 Agent 是否对用户透明？
[ ] 开发 Agent 的上下文是否解耦？
[ ] 开发 Agent 的权限是否受控？

整体

[ ] 你评估过延迟吗？
[ ] 你算过可靠性吗？
[ ] 你有退出策略吗？

鲁棒性检查（第 11 章）

超时与重试

[ ] 所有的外部调用（LLM、HTTP、数据源）都配超时了吗？还是有些会无限阻塞？
[ ] 瞬时错误有没有重试？重试次数和退避策略设了吗？
[ ] 新代码会不会"绕过"已配好的默认值？（裸 new 一个客户端，而不是走带默认值的工厂）
[ ] 如果有工厂——有没有检查机制拦住"不走工厂"的写法？

熔断与降级

[ ] 连续失败时，有没有熔断？还是傻乎乎地一直重试到天亮？
[ ] 熔断放在哪一层了？检测够准、保护够广、状态能持久吗？
[ ] 熔断计数用的是单调时钟（monotonic）吗？还是会被系统时间跳变干扰？
[ ] 上层认不认识"熔断中"异常？是优雅跳过，还是当成普通失败刷日志？

强制 vs 约定

[ ] 你的鲁棒性默认值，哪些是"能强制的"（有明确禁用目标，工厂+检查能拦死）？
[ ] 哪些是"只能约定的"（如"该方法该不该重试"，检查判不了，靠纪律）？
[ ] 对只能约定的部分，至少把正确做法做得足够省力了吗？

兜底

[ ] 写数据的操作，有没有事务保证？中途断了会不会留下不一致状态？
[ ] 工具执行失败时，副作用有没有回滚或兜底？

危险信号

[ ] 有没有任何调用的地方没配超时 → 它就是下一个深夜空转的来源
[ ] 连续失败只会无限重试，没有熔断 → 服务一挂就刷一夜日志
[ ] 鲁棒性全靠"想起来才加"，没有默认机制 → 新代码永远在制造新的裸调用

质量门禁检查（第 12 章）

CI（最基本）

[ ] 提交代码时，有没有自动跑测试？
[ ] 有没有自动跑 lint 和类型检查？
[ ] 你是单人项目吗？如果是——pre-commit 配了吗？（它比云端流水线更改变你的习惯）
[ ] 测试不通过时，能不能阻止提交？

测试覆盖

[ ] 你的测试覆盖了哪些层？（算法层？HTTP 层？数据层？Agent 行为层？）
[ ] 有没有"测了好测的部分，难测的 Agent 行为层完全没测"的失衡？
[ ] eval 用例跑完的结果，接进 CI 自动比对了，还是靠肉眼判断？

闭环

[ ] 有没有"代码写了但从没被调用"的功能？（告警、日志、审计……）
[ ] 第一步：grep 每个功能的调用点，0 个的就是完全空壳
[ ] 第二步：列举每个功能"语义上该出现的所有路径"，逐一核实——抓部分接通
[ ] 你的告警能真的推送到你手里吗？还是写完了但没接通？

危险信号

[ ] 你做的所有项目都没有 CI → 你和上面那些坑之间只差一个提交
[ ] 你的测试全集中在某个层 → 未覆盖的层就是下一个 bug 的来源
[ ] 你有"写了但没接通"的功能 → 不接通等于没写
[ ] 你的项目从没跑过 lint，但配置文件里声明着 → 你以为你有 lint，其实你没有

驾驭阶段自检（第 13 章）

指令文件

[ ] 你给 Agent 的指令文件里，有没有"禁止做什么"？
[ ] 它是"系统说明书"（描述系统是什么）还是"工作指南"（告诉 Agent 怎么做）？

权限

[ ] 你给 Agent 的权限是"什么都允许"还是精确到具体命令？
[ ] 你有没有回头收紧过权限？（从粗放到精细的过程就是升级的过程）

交付方式

[ ] 你的需求是"一次大块"还是"分阶段、每阶段可验证"？
[ ] 每个交付单元有没有明确的"成了长什么样"？

人的角色

[ ] 你是在逐条指挥 Agent，还是在设计 Agent 运转的系统？
[ ] 你有没有让一个 Agent 去调用/监督另一个 Agent？

判断标准

四个都答"没有/前者" → 第一阶段（许愿式）
有边界了但还在逐条指挥 → 第二阶段（划边界）
开始约束 Agent 行为方式、权限精确化 → 第三阶段（驾驭式）
让 Agent 驾驭 Agent，人退到审批和兜底 → 第四阶段（元驾驭式）