附录 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 章）

用例本身

[ ] 预期行为写得足够具体吗？
[ ] 有没有写反向用例？
[ ] 用例来源标注了吗？

打分手段

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

工程卫生

[ ] 用例之间是隔离的吗？
[ ] reset 清干净了吗？
[ ] eval 结果可复现吗？

eval-driven 实践

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

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

是不是真的不稳定？

[ ] 同一用例、同一代码版本，连跑 3 次，结果一致吗？
[ ] 如果不一致——是 Agent 行为变了，还是裁判判错了？
[ ] eval 环境是干净的吗？

应对策略

[ ] 你的 eval 是跑一次就判生死，还是跑多次看通过率？
[ ] 通过率阈值设了多少？合理吗？
[ ] 不同维度有没有区分运行次数？

裁判可靠性

[ ] 裁判和 Agent 是不是用了不同的模型？
[ ] 裁判的 prompt 有没有明确的、具体的评判标准？
[ ] 最近有没有人工抽查校准过裁判的判断？

全局

[ ] 你的项目里，哪些部分是确定性的，哪些是概率性的？
[ ] 两边都覆盖了吗？
[ ] 有没有测试盲区？

多 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 的权限是否受控？

整体

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

质量门禁检查（第 12 章）

[ ] 提交代码时，有没有自动跑测试？
[ ] 有没有自动跑 lint 和类型检查？
[ ] 测试不通过时，能不能阻止代码合并？

测试覆盖

[ ] 你的测试覆盖了哪些层？
[ ] 有没有"测了 Agent 行为但没测基础设施"的失衡？
[ ] eval 用例跑完的结果，是自动比对还是肉眼判断？

闭环

[ ] 有没有"代码写了但从没被调用"的功能？
[ ] 你的告警能真的推送到你手里吗？
[ ] 定时任务里调用的功能，都确认接通了吗？

危险信号

[ ] 你做的所有项目都没有 CI
[ ] 你的测试全集中在某个层
[ ] 你有"写了但没接通"的功能

驾驭阶段自检（第 13 章）

指令文件

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

权限

[ ] 你给 Agent 的权限是"什么都允许"还是精确到具体命令？
[ ] 你有没有回头收紧过权限？

交付方式

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

人的角色

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