附录 C · 干货自检总清单

把全书 14 章的每章自检汇总成一份总清单。拿你自己的 agent 项目，逐条过一遍——勾不上来的，往往就是你项目的隐患所在。

一、认知层

算判分工（第 1 章）

[ ] 有没有本该用代码算、却交给了 LLM 的事？（LLM 输出里有必须确定的"计算结果"）
[ ] 有没有试图用规则穷尽、其实该交给 LLM 判的事？（if-else 越嵌越深）
[ ] LLM 的"判"有没有被确定性的"红线"约束？

四阶认知（第 2 章）

[ ] system prompt 是分区的吗（硬约束 vs 参考）？还是平铺？
[ ] agent"健忘"时，你会查"它能看到什么"，还是只改 prompt？
[ ] 写工具描述是当 API 文档写，还是当 prompt 写？
[ ] 你的循环能用一句话描述吗？

二、设计层

工具颗粒度（第 3 章）

[ ] 同类能力有没有按"单次→对比→扫描→聚合"分层？
[ ] 高密度工具是否留给决策场景？
[ ] 有没有用 eval 验证 agent 自主选对工具？

工具描述（第 4 章）

[ ] 描述里有没有"不适用场景"？
[ ] 有没有 few-shot 示例（用户怎么问→怎么调）？
[ ] 有没有踩坑后加的负面指令？
[ ] 错误返回有没有"缺什么 + 格式 + 下一步"？
[ ] 有副作用的操作收权了吗？

上下文（第 5 章）

[ ] system 里有动态信息吗？（会破坏 prompt cache）
[ ] 记忆是"按需限量"注入的吗？
[ ] 有 progressive disclosure 吗？
[ ] 有没有用 eval 发现过 context 缺口？

循环（第 6 章）

[ ] 循环体里有没有大段 if-else 替模型做流程决策？
[ ] 有迭代上限吗？触发时是硬截断还是强制收尾？
[ ] 有卡住检测吗（连续相同调用/连续失败）？
[ ] 多 tool_call 的响应每个都有结果配对吗？（W2-7 检查）
[ ] 哪些确定流程还在走自决循环？该不该编排？

三、验证层

非确定性（第 7 章）

[ ] 涉及 LLM 输出的 eval，是跑单次还是多次？
[ ] 用二元判断还是通过率阈值？
[ ] 测过用例"飘不飘"吗（跑5次看标准差）？
[ ] 运行次数是一刀切还是按可判定性分层？

eval 驱动（第 8 章）

[ ] 写功能前先写 eval 了吗？
[ ] eval 能抓退化吗？（注入错误看报不报红）
[ ] eval 测的是"代码能跑"还是"agent 行为做对"？
[ ] 有没有"隐藏队列"污染？（grep 全局可变状态）
[ ] eval 框架本身有测试吗？

打分手段（第 9 章）

[ ] 面对指标，有"该用哪种打分"的判据吗？
[ ] 能代码断言的是否优先用了代码断言？
[ ] 知道裁判在哪类输入上飘吗？
[ ] 裁判和 agent 是同一模型吗？（留意自评偏差）

四、协作层

编排 vs 自决（第 10 章）

[ ] 固定流程是编排成 pipeline，还是也让 agent 自决？
[ ] 定时任务有执行历史落盘吗？
[ ] 单步失败会不会搞崩整条流程？
[ ] 编排和自决是否共享同一套底层能力？

记忆（第 11 章）

[ ] 对话能持久化吗？有截断策略吗？
[ ] 用户观点有没有沉淀成结构化记忆？
[ ] 你以为接上的记忆/通知功能，核实过调用链闭合吗？
[ ] 注入是"按需限量"的吗？

五、工程层

错误与韧性（第 12 章）

[ ] 错误有分流吗（瞬时重试/回灌模型/找用户/上抛）？
[ ] 连续失败有熔断吗？
[ ] 熔断后上层知道怎么降级吗？
[ ] 遇到"明显的问题"，先证伪还是先动手？

工程严谨（第 13 章）

[ ] 架构有没有为未来演进留分层？
[ ] 有 CI 吗（哪怕单人）？
[ ] 代码里有 except: pass 吗？
[ ] "在跑"的功能核实过调用链吗？
[ ] 用户改的状态重启会丢吗？
[ ] 配置分层清晰吗（密钥/业务/模板）？

六、元层

驾驭曲线（第 14 章）

[ ] 你的协作，"执行"主要在谁手里？
[ ] 被坑之后画边界了，还是继续许愿？
[ ] 有没有把探索性活（跑实验/核实）交给 AI？
[ ] 你的执行比重，这半年在往 AI 迁移吗？

怎么用这份清单

不用一次全过。挑你最头疼的那一类问题，去对应章节的自检里找。勾不上来的，回那一章读 pixiu 的实证——大概率你正卡在那个坑的某个变体上。

这份清单的底层逻辑是：agent 工程的每个环节，都有"做了"和"做对"的区别。 这份清单帮你看清，自己哪些环节只是"做了"，哪些真正"做对了"。