Claude Cookbooks 实践指南：配方地图、环境搭建与 Notebook 校验体系

Claude Cookbooks 是 Anthropic 官方的 Claude 开发配方仓库，提供可直接复制到生产代码中使用的 Jupyter Notebook 示例与配套代码。本文以仓库根目录的 README.md 为核心脉络，完整梳理其配方（recipe）分类地图、运行前提与环境搭建命令，并结合 pyproject.toml、Makefile、registry.yaml 等仓库文件深入讲解该项目的发现机制与质量保障体系，读完你可以独立完成环境初始化、按主题定位所需示例，并理解每个配方的注册与校验方式。

项目定位与阅读前提

README 对项目的定义非常明确：Claude Cookbooks 提供代码与指南，帮助开发者构建基于 Claude 的应用，核心交付物是可复制的代码片段（copy-able code snippets），你可以直接将其集成到自己的项目中。

README 在 "Prerequisites" 一节给出的前提如下：

1. 需要一个 Claude API Key：这是运行绝大多数 Notebook 的前提；
2. 示例以 Python 为主：代码示例主要用 Python 编写，但其中的概念可以迁移到任何能与 Claude API 交互的编程语言；
3. API 基础建议：如果你是第一次接触 Claude API，README 建议先完成官方的 "Claude API Fundamentals" 课程再进入这些 Notebook，以获得扎实的基础。

此外 README 在 "Explore Further" 一节指出，除了仓库本身，还可以配合 Anthropic 开发者文档、支持文档以及 Anthropic Discord 社区来扩展学习（这些为外部资源，此处不重复罗列链接）。

环境搭建：从依赖安装到 API Key 配置

仓库的 CLAUDE.md 给出了 Quick Start，与 README 的前提说明相互印证，完整流程如下：

# 1. 安装依赖（项目使用 uv 作为包管理器）
uv sync --all-extras

# 2. 安装 pre-commit 钩子（提交时自动做格式与结构校验）
uv run pre-commit install

# 3. 配置 API Key
cp .env.example .env
# 编辑 .env，写入你的 ANTHROPIC_API_KEY

CONTRIBUTING.md 进一步补充了 uv 的安装方式（curl 脚本或 Homebrew）以及 pip 的替代方案 pip install -e ".[dev]"，并强调 Notebook 中的 API Key 应始终通过环境变量读取：

import os
api_key = os.environ.get("ANTHROPIC_API_KEY")

CLAUDE.md 的 "Key Rules" 也重申了同一条安全规则：永远不要提交 .env 文件，使用 dotenv.load_dotenv() 加载后通过 os.environ / os.getenv() 访问密钥。

依赖清单：一个配方仓库需要哪些依赖

从 pyproject.toml 可以看到，项目声明 requires-python = ">=3.11,<3.13"，核心依赖与配方的主题高度对应：

依赖	服务方向
anthropic>=0.109.0	所有配方调用的 API SDK
claude-agent-sdk>=0.1.50	claude_agent_sdk/ 与 managed_agents/ 中的 Agent 类配方
jupyter / notebook / ipykernel	Notebook 运行环境
numpy / pandas / matplotlib / networkx	数据处理、图表与知识图谱配方（如 capabilities/knowledge_graph/）
voyageai	第三方 embedding 集成（third_party/VoyageAI/）
pymongo	MongoDB Atlas 集成（managed_agents/mongodb_on_cma/）
python-dotenv	上述的 .env 密钥管理
requests / rich / pyjwt	HTTP 调用、终端展示与 token 处理

dev 依赖组则对应下文的质量校验体系：ruff（格式化与 lint）、pytest + nbval（Notebook 结构/执行测试）、pre-commit、nbconvert、tox + tox-uv。

代码风格约定

CLAUDE.md 的 "Code Style" 与 pyproject.toml 中 [tool.ruff] 配置一致：

• 行宽 100 字符，双引号，格式化器为 Ruff；
• Notebook 享有更宽松的规则：允许文件中段导入（E402）、重复定义（F811）以及变量命名放宽（N803/N806），这在 pyproject.toml 的 per-file-ignores 中逐条落实；
• 日常开发命令：make format、make lint、make check（format-check + lint）、make fix、make test，全部封装在 Makefile 中。

CLAUDE.md 还特别约定了模型命名规范：使用当前模型的无日期别名（如 claude-sonnet-5、claude-haiku-4-5、claude-opus-4-8），禁止在示例中使用带日期的模型 ID；Bedrock 场景则使用 anthropic.claude-*-v1 形式的模型 ID，并推荐加 global. 前缀指向全球端点。这一规则保证了示例代码在模型迭代时尽可能少地腐化。

配方地图：README 的完整 Table of recipes

README 的 "Table of recipes" 按主题将配方分为五大类。下面完整继承该表，并将原文指向外部仓库的链接全部转换为以本仓库根目录为起点的相对路径，可直接在仓库内跳转：

Capabilities（核心能力）

配方	说明（README 原文意译）	仓库路径
分类（Classification）	使用 Claude 做文本与数据分类的技术	capabilities/classification
检索增强生成（RAG）	用外部知识增强 Claude 的回答	capabilities/retrieval_augmented_generation
摘要（Summarization）	高效的文本摘要技术	capabilities/summarization

Tool Use and Integration（工具使用与集成）

配方	说明	仓库路径
Tool use 目录	让 Claude 调用外部工具与函数，扩展其能力边界	tool_use
客服 Agent	工具调用驱动的典型客服场景	tool_use/customer_service_agent.ipynb
计算器集成	最小化的函数调用示例	tool_use/calculator_tool.ipynb
SQL 查询	用 Claude 生成并执行 SQL	misc/how_to_make_sql_queries.ipynb

Third-Party Integrations（第三方集成）

配方	说明	仓库路径
第三方集成目录	用外部数据源补充 Claude 的知识	third_party
Pinecone 向量库 RAG	基于 Pinecone 的检索增强	third_party/Pinecone/rag_using_pinecone.ipynb
Wikipedia 搜索	结合维基检索的问答	third_party/Wikipedia/wikipedia-search-cookbook.ipynb
网页阅读	用 Haiku 读取并处理网页	misc/read_web_pages_with_haiku.ipynb
Voyage AI Embeddings	创建 embedding 的方法	third_party/VoyageAI/how_to_create_embeddings.md

Multimodal Capabilities（多模态能力）

配方	说明	仓库路径
Vision 目录	视觉能力总入口	multimodal
图像入门	图像输入基础	multimodal/getting_started_with_vision.ipynb
Vision 最佳实践	图像任务的最佳实践	multimodal/best_practices_for_vision.ipynb
图表解读	解读图表与 PPT	multimodal/reading_charts_graphs_powerpoints.ipynb
表单/文本转录	从表单中提取内容	multimodal/how_to_transcribe_text.ipynb

Advanced Techniques（进阶技术）

配方	说明	仓库路径
子 Agent	用 Haiku 作为子 Agent 配合 Opus 工作	multimodal/using_sub_agents.ipynb
PDF 上传	解析 PDF 并以文本形式传给 Claude	misc/pdf_upload_summarization.ipynb
自动化评估	用 Claude 自动化 prompt 评估流程	misc/building_evals.ipynb
JSON 模式	保证一致的 JSON 输出	misc/how_to_enable_json_mode.ipynb
内容审核过滤器	为应用构建内容审核过滤器	misc/building_moderation_filter.ipynb
Prompt Caching	高效的提示缓存技术	misc/prompt_caching.ipynb
成本优化	在 Agent 上执行成本优化清单，度量任务通过率与单任务成本，寻找帕累托最优配置	cost_optimization/cost_optimization.ipynb

注意：README 的这张表是经典入门配方清单，而非仓库全部内容的枚举。当前仓库的目录实际已扩展到 README 表格之外，例如 capabilities/knowledge_graph、capabilities/contextual-embeddings、capabilities/text_to_sql、tool_use/programmatic_tool_calling_ptc.ipynb、tool_use/memory_cookbook.ipynb、managed_agents、claude_agent_sdk、skills、extended_thinking、evals 等。完整的权威清单见下文的 registry.yaml。

配方发现机制：registry.yaml 与 authors.yaml

从源码结构看，README 表格的"升级版"是仓库根目录的 registry.yaml——一份机器可读的配方注册表。它当前登记了 93 条配方（每条含 title、description、path、authors、date、categories 六个字段），是浏览、检索和统计全部配方的唯一权威来源。一条典型记录长这样：

- title: Programmatic tool calling (PTC)
  description: Reduce latency and token consumption by letting Claude write code that
    calls tools programmatically in the code execution environment.
  path: tool_use/programmatic_tool_calling_ptc.ipynb
  authors:
  - PedramNavid
  date: '2025-11-24'
  categories:
  - Tools

其中 categories 采用标签体系（如 Claude Managed Agents、RAG & Retrieval、Multimodal、Tools、Evals 等），path 字段同样是以仓库根目录为起点的相对路径。文件头部的 $schema=./.github/registry_schema.json 注释表明该文件受 JSON Schema 约束，保证结构一致性。

配套的 authors.yaml 维护"GitHub 用户名 → 作者详情（姓名、网站、头像）"的映射，供网站展示使用；新增贡献者时需在此补充其信息。

从 CLAUDE.md 的 "Adding a New Cookbook" 一节可以看到，registry.yaml 在贡献流程中的地位：新建 Notebook 后必须在 registry.yaml 中登记 title、description、path、authors、categories，新作者还需加入 authors.yaml，然后跑质量检查再提交 PR。

质量保障：Makefile、tox 与 Notebook 校验栈

README 强调本项目"thrives on the contributions of the developer community"，而仓库用一套自动化工具链来守护这种协作的质量。CONTRIBUTING.md 将其概括为 Notebook 校验栈：nbconvert（Notebook 执行测试）+ ruff（带原生 Jupyter 支持的 lint/格式化）+ Claude AI Review（CI 中的智能代码审查），并特别说明：Notebook 输出（outputs）是被刻意保留在仓库中的，因为它们向使用者展示了预期结果。

Makefile 目标一览

Makefile 提供了分层清晰的命令入口，make help 会打印全部目标：

# 代码质量
make format              # ruff 格式化
make lint                 # ruff lint 检查
make check                # format-check + lint（提交前必跑）
make fix                  # ruff 自动修复 + 格式化

# 测试
make test                # 运行 pytest 全量测试
make test-notebooks      # Notebook 结构测试（快，无 API 调用）
make test-notebooks-exec # Notebook 执行测试（慢，需要 API Key）
make test-notebooks-tox  # 在隔离的 tox 环境中跑结构测试
make test-notebooks-quick  # 不经过 pytest 的快速校验

# 按 Notebook / 目录过滤（环境变量）
make test-notebooks NOTEBOOK=tool_use/calculator_tool.ipynb
make test-notebooks-tox NOTEBOOK_DIR=capabilities

结构测试与执行测试的分层是刻意设计：test-notebooks 使用 pytest 的 -m "not slow" 标记排除慢测试，无需 API Key 即可完成；test-notebooks-exec 追加 --execute-notebooks 参数真正运行 Notebook，适合本地有密钥时验证"自上而下可运行"。

tox 隔离环境：六个预设 testenv

tox.ini 进一步把测试切成六个可组合的环境，配合 tox-uv 快速建环境：

环境	用途
structure	快速结构校验，不执行、不调 API
structure-single	只测单个 Notebook 的结构
execution	完整执行测试（需要 ANTHROPIC_API_KEY，超时 300 秒/Notebook）
execution-single	执行单个 Notebook
registry	只测 registry.yaml 中登记过的 Notebook（--registry-only）
third-party	专项跑 third_party/ 目录，透传 Voyage/Pinecone/MongoDB 等第三方密钥
lint / format	ruff 检查与格式化

值得注意的细节：execution 与 third-party 环境在 passenv 中显式透传了 ANTHROPIC_API_KEY、OPENAI_API_KEY、VOYAGE_API_KEY、PINECONE_API_KEY、MONGODB_URI 乃至 DEEPGRAM_API_KEY、ELEVENLABS_API_KEY、WOLFRAM_APP_ID——这与 third_party/ 下 Deepgram、ElevenLabs、WolframAlpha 等音频与搜索集成配方一一对应。测试代码主体位于 tests/notebook_tests/test_notebooks.py，配套 conftest 在 tests/conftest.py；另有独立脚本 scripts/validate_notebooks.py、scripts/validate_all_notebooks.py、scripts/validate_authors_sorted.py（后者由 make sort-authors 调用，保证 authors.yaml 按字母序排列）。

pytest 的标记体系定义在 pyproject.toml 中：slow（需要执行 Notebook）、integration（需要外部服务凭据，缺凭据自动跳过）、mutates_state（会改动真实数据，必须在可丢弃命名空间内运行并自带 teardown）。

贡献流程要点

README 的 "Contributing" 一节强调：贡献可以是一个想法、一个错别字修复、一个新指南或对既有指南的改进；为避免重复劳动，提交前应先查阅已有 issues 与 PR，新示例/指南的想法应先在 issues 页提出。

结合 CONTRIBUTING.md 与 CLAUDE.md，完整的贡献流程可以归纳为：

1. 分支与提交规范：分支命名 <username>/<feature-description>；提交遵循 conventional commits（feat(scope): ... / fix(scope): ... / docs(scope): ... 等）；保持提交原子化；
2. Notebook 编写准则：一个 Notebook 聚焦一个概念；解释清晰；API 调用用最小 token；包含错误处理；确保自上而下可运行且输出保留；
3. 提交前检查：uv run ruff check . --fix + uv run ruff format .，再跑 uv run python scripts/validate_notebooks.py；需要时用 jupyter nbconvert --to notebook --execute ... 本地执行验证；
4. pre-commit 钩子：每次提交自动执行 ruff 格式化与 Notebook 结构校验，失败则修复后重提；
5. CI 自动化：GitHub Actions 会自动校验 Notebook 结构、ruff lint、Notebook 执行测试（维护者）、链接检查，并由 Claude 审查代码与模型引用。仓库还内置了三个 Claude Code slash command——/notebook-review、/model-check、/link-review——复用与 CI 完全相同的校验逻辑，让你在 push 之前就能发现同类问题。

延伸资源与下一步

README 的 "Additional Resources" 提到两个方向：使用 Claude on AWS 的官方样例集合，以及可改造后配合 Claude 使用的 AWS 代码样例（部分样例需要修改才能与 Claude 最佳配合）。作为读者，建议的进入路径是：

• 先读 README.md 上文的配方表锁定主题域，再到 registry.yaml 按 categories 标签检索同主题的全部 93 条配方；
• 环境上按 Quick Start 完成 uv sync --all-extras 与 .env 配置，用 make check 保证本地代码风格与仓库一致；
• 深入某个能力域（如 capabilities 下的 RAG、tool_use 下的工具调用、managed_agents 下的托管 Agent）后，可用 make test-notebooks NOTEBOOK=<路径> 对单个 Notebook 做结构级验证。

整体上，Claude Cookbooks 的价值不仅在于"示例多"，而在于它用 registry.yaml 把配方资产化、用 ruff + pre-commit + tox 把质量流程化、用保留输出的 Notebook 把"预期结果"文档化——这三者共同构成了一份可持续演进的官方配方库的工程底座。