Claude Cookbook 的价值在于示例可以运行，这也容易让人高估它证明了什么。一个 Notebook 可以展示某个模型如何调用工具、使用缓存、记忆或 Managed Agents，但无法说明更换模型、修改工具 schema、依赖变慢或权限变化后，原有行为是否仍然成立。
正确的晋升路径不是从示例直接进入生产，而是把示例变成测试夹具，再形成回归套件，最后接入发布门禁。
Cookbook recipe 是可执行假设
Claude Cookbook 已覆盖 Responses、工具、Agent patterns、Managed Agents、Evals、Observability、Skills 和集成。部分 recipe 已提供测试所需的组件：Building evals 把评估拆成 input、output、golden answer 和 score；Tool evaluation 记录工具调用次数与耗时；Managed Agents 示例还涉及 prompt 版本与回滚。
这些内容仍然是教学材料。官方示例也可能为了讲清概念而简化实现。Tool evaluation 页面就明确提示，示例中的动态 eval() 调度只用于演示，生产环境应使用更安全的函数映射。
这不代表上游仓库没有测试。它使用 uv.lock 固定依赖，执行 lint 和 Notebook 结构检查，维护者工作流还可以运行发生变化的 Notebook。这些控制保护 recipe 自身，却不知道你的退款权限、数据范围、服务目标和可接受失败率。
可以把每个 recipe 改写成一条假设：
在这个模型、prompt、工具契约、环境和输入下，Agent 应得到指定结果，同时不违反这些约束。
回归测试要让句子里的每个名词都可以追踪。
先建立有版本的测试 manifest
把 Notebook 原样塞进 CI 并不够。Notebook 存在隐式状态，cell 可以乱序执行，模型别名和依赖也可能移动。每个生产场景都应由机器可读的 manifest 描述。
id: invoice_lookup_unauthorized_account
suite: billing_agent_regression
model: claude-sonnet-5
api_version: 2023-06-01
prompt_version: billing-v17
tool_schema_sha256: 8d4e...
environment_image: billing-eval@sha256:31af...
trials: 8
max_tokens_per_trial: 12000
max_cost_usd_p95: 0.18
max_latency_ms_p95: 14000
required_graders:
- no_unauthorized_tool_call
- refusal_is_specific
- no_secret_in_output
release_policy: all_hard_checks_and_7_of_8_quality_pass
除了模型 ID，还要记录 API version header、SDK 与依赖锁文件、system prompt、工具定义、检索快照、环境镜像、feature flag 和 grader 版本。Anthropic 会在一个 API 版本内保留现有输入输出参数，但仍可能增加可选输入、输出值或错误变体，解析器需要为这些允许的变化准备回归测试。
把一个预期答案拆成四层契约
Agent 可以用不可接受的路径得到看起来正确的答案，因此需要分别验收四层。
第一层：准入
以下条件应 fail closed：
- 只调用获准工具和网络目的地；
- 工具参数符合授权与数据边界；
- transcript 和输出没有 Secret 或受保护记录；
- schema、文件类型和资源限制有效；
- 不可逆动作经过规定的人工确认。
权限违规不能与文字质量取平均分。硬条件失败就应阻止候选发布。
第二层：结果
Anthropic 的 Agent eval 指南区分 transcript 和 outcome。订票 Agent 可以说“已经完成”，但数据库里可能没有订单。应该检查环境终态，例如数据库记录、生成文件、工单状态、提交的 patch 或外部系统事件。
能用确定性 grader 时优先使用。精确比较、schema 校验、单元测试、静态分析、数据库查询和 allowlist 比模型 judge 更快、更便宜，也更容易复现。
第三层：行为
当执行路径具有安全含义时，需要检查 trace：
- 是否调用必要工具；
- 是否避开禁用工具；
- 参数和顺序是否合法；
- 重试是否在上限停止；
- 不确定性达到阈值后是否升级给人；
- 中间文件与状态变化是否留在 Sandbox 内。
除非顺序本身就是安全要求，否则不要锁死唯一工具序列。更强模型可能找到更短的合法路径，却被脆弱断言误判。
第四层：运行
记录 token、成本、延迟、重试、工具错误和完成方差。模型升级即使保持质量，若 p95 延迟翻倍，对同步产品仍然是回归。平均成本下降也可能掩盖昂贵的失败尾部。
把能力评估与回归评估分开
Anthropic 给出了一条重要区分：capability eval 问 Agent 还能学会什么，应该包含当前成功率不高的难题；regression eval 问已经会做的任务是否退化，目标应接近 100% 通过。
混在一个平均分里会产生错觉。新难题上的进步，可能掩盖密码重置、退款授权或引用核验已经坏掉。
可以按目的和风险组织套件：
| 套件 | 目的 | 常见触发 |
|---|---|---|
| Smoke | API、prompt 与工具接线 | 每次提交 |
| Regression | 保留已知行为 | 每次相关变更 |
| Safety | 权限、Secret、副作用 | 必须全部通过 |
| Capability | 探索困难新任务 | 提供信息或人工审查 |
| Migration | 比较当前与候选模型 | 模型切换前 |
| Production replay | 覆盖真实边缘案例 | 定时和发布前 |
当一个能力任务变得稳定且重要后，可以晋升到回归套件。
重复运行，并做配对比较
一次成功不能证明稳定。Anthropic 把同一个 task 的每次尝试称为 trial，因为模型输出存在方差。运行次数应足以暴露当前决策关心的失败率。
升级时，让当前配置和候选配置在相同 task、环境和 grader 上执行，并保留配对结果：
- baseline 通过而 candidate 失败；
- 两者都通过，但成本或延迟恶化；
- candidate 使用了风险更高的路径；
- 模型 judge 与确定性终态检查冲突。
发布决策要关注任务级退化和不确定区间，而不是只看聚合均值。高风险任务可以要求每次 trial 都通过，低风险质量项则可以设阈值。
最后才使用模型 judge
语气、完整性和解释质量等开放维度可能需要模型评分。给 judge 明确 rubric、约束输出 schema 和边界案例，并用领域专家标注校准。更换 judge 模型或 rubric 后需要重新检查一致性。
不要让一个模糊 judge 同时决定权限、环境事实和写作质量。事实与硬约束交给确定性检查，代码无法表达的维度再交给模型判断。
只触发最小相关套件
如果每次修改都运行全部任务，回归系统会慢到被绕开。应把变更映射到影响面：
| 变更 | 最小测试范围 |
|---|---|
| Prompt 或 Skill | 任务回归、安全、行为 |
| 模型 ID 或 thinking 参数 | 完整迁移、成本、延迟、安全 |
| 工具描述或 schema | 工具契约、授权、负例 |
| 检索源 | 引用、新鲜度、数据边界 |
| SDK 或 API version | 协议 smoke、解析、错误处理 |
| Sandbox 镜像 | 工具执行、文件、网络、资源限制 |
每次提交运行小型确定性集合，合并前运行更广的重复 trial，切换模型前再执行完整迁移和安全套件。
补上生产反馈环
离线夹具会老化。对脱敏生产 trace 采样，聚类新失败，在受控环境中复现，并把代表案例加入套件。同时保留 prompt 作者和优化 Agent 看不到的封存测试集。
离线门禁通过后，先走 shadow 或受限 canary。监测与评估阶段相同的 outcome、安全、成本和延迟指标，并保留上一版 prompt 与模型，让回滚成为操作而不是重建工程。
这正是 GEPA 把评估器视为接口带来的实际提醒：评估器遗漏的要求都会成为优化捷径。回归套件既是质量系统，也是对 Agent 允许变成什么的精确定义。
最小落地顺序
- 选择一个接近真实工作流的 Cookbook recipe。
- 固定模型、prompt、工具、环境和依赖。
- 用真实正例、负例和边界案例替换演示输入。
- 加入权限与副作用硬断言。
- 检查环境终态，而不只检查最终文字。
- 记录 trace、token、成本、延迟和重试。
- 重复运行并建立当前 baseline。
- 按风险规则把套件接入 CI。
- 回灌生产失败，并维护封存测试集。
- 通过 canary 发布，并固定回滚目标。
Cookbook 继续负责提供可运行模式，回归套件则负责提供发布证据。
常见问题
可以直接把 Cookbook Notebook 当测试吗？
可以把它作为起点，但应把配置、输入、断言和依赖迁移到有版本的文件。Notebook 隐式状态会让失败难以复现。
每个任务都需要 golden answer 吗？
不需要。有些任务适合精确答案，有些应检查环境终态、不变量或 rubric。成功条件需要对应真实产品结果。
多少次 trial 才够？
取决于可接受失败率和后果。非确定性或高风险任务需要更多 trial，并应报告不确定性，不能把一次通过当成确定性。
可以让 LLM 给自己的 Agent 打分吗？
经过校准后可以评分主观维度，但不应成为权限、工具副作用、数据库状态和安全边界的唯一 judge。