跟 Claude Cookbook 学 agent 工程:85 个 recipes 里 5 条对老程序员最有用的拆解

一、起因

7 月 23 日,HN 上 saikatsg 发了《Claude Cookbook》,80 分、30 条评论。top-1 是 killthebuddha 那条 764 字符吐槽:frontend 活儿 agent 写出来 buggy / broken / incomplete 的频率比 backend 高太多。

cookbook 主页列 85 个 recipes,前 20 条是 2026 新 Managed Agents / 异步多 agent / Memory store,后 60 多条是 2024-2025 旧 RAG / calculator tool / Wolfram Alpha。重点是 85 条里哪 5 条对写生产 agent 的老程序员真有用,哪 60 条是"喂给 AI 之前没人会真的读"的废料。

mindwok 评:几乎所有 "how to use AI" 资源都让我觉得没用,要么直接问 AI,要么这事本来就该烘到 harness 里。这话对,但 cookbook 一对一,会发现他说的"没用"指的是那 60 条旧的,新 20 条得分开看。

二、我具体做了哪些事

打开 platform.claude.com/cookbook/,curl 拿到 193 KB HTML(实测这次 platform 站点 server-side rendered,193 KB + 85 个 <p> 段,跟之前 JS 重渲染只返 9 段导航的模式不符 —— 估计 cookbook 用了静态导出),regex 提所有 85 条 recipe 标题 + 描述,按关键词(Managed Agents / subagent / Memory / MCP / async / PTC)分类,挑出前 20 条 2026 新增和后 60 条旧。5 个真可落地的:P1 / P3 / P5 / P6 / P13。

三、5 条新 wave recipes 的工程拆解

3.1 Fable 5 safety classifier 兜底(P1)

Fable 5 发布后有 safety classifier 会随机 block,Anthropic 官方解法是 server-side / SDK client-side 两套 fallback:

import anthropic
client = anthropic.Anthropic()
try:
    resp = client.messages.create(model="claude-fable-5-20260520", max_tokens=1024,
        messages=[{"role": "user", "content": prompt}])
    if resp.stop_reason == "safety_classifier_block":
        resp = client.messages.create(model="claude-opus-4-8-20260520", max_tokens=1024,
            messages=[{"role": "user", "content": prompt}])
except anthropic.APIStatusError as e:
    if e.status_code == 529 and "classifier" in str(e): pass

关键:fallback 后账单按 Opus 4.8 算,不是 Fable 5。P1 "new billing changes" 就是这个意思 —— fallback 后会多花钱。

3.2 同一 image 三档部署(P3)

Docker -> Modal -> Kubernetes 3 档共享同一 container image + 同一 HTTP interface,dev 时 POST /research 在 prod 还是同一个。cookbook 给了完整 3 段 Dockerfile,每段只有 ENV 差异。坑点:Modal 冷启动 3-5 秒,Docker 无冷启动但要自己管,K8s 链路最长。生产 K8s,开发 Docker,演示 Modal。

3.3 grade-and-revise loop with Outcomes(P5)

outcome = client.beta.messages.outcomes.define(name="citation_accuracy",
    rubric="fetch every URL; check every quote; pass if 100% resolve.")
draft = writer.run(prompt)
result = grader.evaluate(outcome=outcome, brief=draft, citations=draft.citations)
while not result.passed and draft.iteration < 5:
    feedback = result.reason
    draft = writer.run(prompt, feedback=feedback)
    result = grader.evaluate(outcome=outcome, brief=draft, citations=draft.citations)

关键:grader stateless,不带 writer 历史 —— 否则 grader 跟 writer 串通。span.outcome_evaluation_* 事件是 observability 钩子。

3.4 Memory store for Managed Agents(P6)

agent = client.beta.agents.create(name="support-bot", model="claude-opus-4-8-20260520",
    memory={"type": "managed", "scope": "user", "retention_days": 90}, tools=[])
session = client.beta.sessions.create(agent_id=agent.id, user_id="u_123")

vs pgvector:官方自动 recall(看不到向量过程),外部显式 query → embed → top-k → inject。前者 latency 高 20-50ms 但心智简单。不推荐合规审计场景。

3.5 Server-side prompt versioning(P13)

v1 = client.beta.agents.prompts.create(agent_id=agent.id, version="v1", content="...")
v2 = client.beta.agents.prompts.create(agent_id=agent.id, version="v2", content="... (revised)")
for v in ["v1", "v2"]:
    client.beta.evaluations.run(agent_version=v, test_set="support_eval_v1.jsonl",
        metrics=["resolution_rate", "csat_proxy", "latency_p95"])
client.beta.sessions.create(agent_id=agent.id, prompt_version_pin="v1")

关键:review gate 移到 prompt 层,不是 code 层。2026 agent 团队最关键的组织流程问题。

四、后 60 条旧 recipes:90% 不该再读

  • P37 "Enable parallel tool calls on Claude 3.7 Sonnet using batch tool meta-pattern" —— Claude 4.0 起原生 parallel tool calls
  • P46 "Step-by-step guide to finetuning Claude 3 Haiku on Amazon Bedrock" —— Claude 3 Haiku 已下架
  • P65 "Fetch and summarize web page content using Claude 3 Haiku via URL extraction" —— 已被 web_fetch tool 取代
  • P68 "Build chatbot RAG system with Claude and MongoDB" —— 已被 P45 + Memory store 取代
  • P83 "Legacy notebook showing iterative Wikipedia searches with Claude 2" —— Claude 2 已 EOL 18 个月

beklein 提的 OpenAI Cookbook 也有这问题。cookbook 超过 50 条后大部分成废料,新人按时间倒序读 5-10 条新 wave 就够了。cookbook 真正价值是看官方怎么想,不是按 recipe 抄。

五、目前还没完全搞清楚的几个点(局限与待验证项)

  • P3 三档部署真实生产案例(待验证) —— cookbook 给了 Dockerfile + Modal + K8s manifest,但没公开客户 case study
  • P5 grader rubric 覆盖度(不足) —— user.define_outcome 2026 Q2 才 GA,长尾 bug 还在出
  • P6 Memory store recall 精度(待验证) —— 中文 / 长尾 preference 没公开数字
  • P13 regression 来源判断(坑点) —— 跑出 regression 后,怎么知道是 prompt 改错还是 test set 跟生产分布不一致?recipe 没给
  • Fable 5 classifier block rate(待验证) —— P1 说"detect blocks",没说 block rate 多少,群里 0.3% / 1.5%
  • P5 长 brief token 成本(还在调研) —— 5 轮 grade + revise 总 token 可能是单轮 5-8 倍

六、适用场景建议

该读的:Managed Agents 集成(P3 + P6)、production prompt 管理(P13)、Fable 5 classifier block(P1)、grader / eval pipeline(P5)。不该读的:Claude 3 Haiku 教程、RAG 基础、calculator tool / Wolfram Alpha、Claude 2 资料。

对个人判断:cookbook 跟 SDLC 一样,新 release 后 2-3 条必读,旧扫一眼标题跳过。85 条全读 ROI 是 0。

七、参考链接

posted @ 2026-07-24 19:19  Ninghg  阅读(7)  评论(0)    收藏  举报