Claude Cookbooks 开发指南：基于 CLAUDE.md 的环境搭建、质量门禁与模型使用规范

本文以仓库根目录的 CLAUDE.md 为核心，完整解读 Claude Cookbooks 项目（一个由 Jupyter Notebook 与 Python 示例组成的 Claude API 实战合集）的工程化开发体系：如何快速搭建 uv 开发环境、如何使用 Makefile 与 pre-commit 双通道质量门禁、仓库对 Claude 模型命名与 API Key 管理的硬性约束，以及新增一个 Cookbook 的完整流程。读完后，你可以独立在本仓库中复现"环境安装 → 代码规范 → 质量检查 → 注册入库"的完整开发闭环。

1. CLAUDE.md 在项目中的定位

Claude Cookbooks 提供面向 Claude API 的可复制代码片段与教程（如 README.md 中介绍的 RAG、工具使用、多模态等方向）。而 CLAUDE.md 是仓库的"工程宪法"：它既是 Claude Code 在本地开发时的行为指引，也是 CI 流水线执行验证的依据。文件内容可归纳为七个部分：

1. Quick Start——环境安装与 API Key 配置；
2. Development Commands——Makefile 目标与 ruff 直调命令；
3. Code Style——行长、引号风格、Notebook 放宽规则；
4. Git Workflow——分支命名与 Conventional Commits；
5. Key Rules——API Key、依赖、模型 ID、Notebook、质量检查五条硬性规则；
6. Slash Commands——/notebook-review、/model-check、/link-review 三个 Claude Code 命令；
7. Project Structure 与 Adding a New Cookbook——目录组织与新增食谱流程。

下文将逐条展开，并用仓库中的实际配置文件（Makefile、pyproject.toml、.pre-commit-config.yaml 等）印证每条规则的真实实现。

2. 快速开始：三步搭好开发环境

CLAUDE.md 给出的 Quick Start 命令如下：

# 安装依赖
uv sync --all-extras

# 安装 pre-commit 钩子
uv run pre-commit install

# 配置 API Key
cp .env.example .env
# 编辑 .env，填入 ANTHROPIC_API_KEY

从 pyproject.toml 可以确认环境前提与依赖构成：

• Python 版本：requires-python = ">=3.11,<3.13"，即 3.11 或 3.12；
• 核心依赖：anthropic>=0.109.0、claude-agent-sdk>=0.1.50、ipykernel、jupyter、pandas、python-dotenv 等（Notebook 运行必需）；
• dev 依赖组：ruff>=0.14.2、pytest>=8.3.3、nbval>=0.11.0、pre-commit、nbconvert、tox、tox-uv、pytest-cov 等，正是质量门禁所需的全部工具链。

.env.example 定义了 .env 文件的完整模板，其中除 API Key 外还有几项对跑示例很有用的可选配置：

变量	示例值	作用
ANTHROPIC_API_KEY	sk-ant-api03-...	Claude API 密钥（必填）
CLAUDE_MODEL	claude-haiku-4-5	测试默认模型，用 Haiku 降低示例成本
TEST_MODE	true	测试模式开关
MAX_TOKENS	10	限制示例调用的 token 上限
DEBUG	false	调试详细输出

这一点也呼应了 CONTRIBUTING.md 中"Use minimal tokens for example API calls"（示例调用尽量用最小 token）的要求：.env.example 默认把 MAX_TOKENS 压到 10，就是为了控制示例脚本的真实 API 开销。

3. 开发命令与质量门禁

3.1 Makefile 目标

CLAUDE.md 定义了五个核心目标，全部通过 Makefile 落地：

make format        # ruff 格式化
make lint          # ruff 检查
make check         # format-check + lint（提交前必跑）
make fix           # 自动修复 + 格式化
make test          # 运行 pytest

从 Makefile 的源码实现看，各目标的真实语义是：

• format → uv run ruff format .；
• check 依赖两个子目标：format-check（ruff format --check .，只检查不改文件）和 lint（ruff check .）；
• fix → ruff check --fix . 之后再执行 ruff format .；
• test → uv run pytest。

仓库实际提供的 Makefile 目标比 CLAUDE.md 摘要的更多，值得补充说明：

• test-notebooks：运行 tests/notebook_tests/test_notebooks.py 的结构测试（快速、不发起 API 调用），并默认用 -m "not slow" 排除慢测试；
• test-notebooks-exec：真正执行 Notebook（慢，需要 API Key），即"Test that notebooks run top-to-bottom without errors"这条规则的自动化验证手段；
• test-notebooks-tox：在隔离的 tox 环境中跑结构测试（tox.ini 定义环境）；
• test-notebooks-quick：用 scripts/test_notebooks.py 做不依赖 pytest 的快速校验；
• 以上目标都支持 NOTEBOOK=path/to/notebook.ipynb 或 NOTEBOOK_DIR=capabilities 环境变量缩小测试范围，例如 make test-notebooks NOTEBOOK=tool_use/calculator_tool.ipynb；
• 另有 clean（清理 __pycache__、.pytest_cache、.ruff_cache、*.pyc）与 sort-authors（调用 scripts/validate_authors_sorted.py 把 authors.yaml 按字母序重排）。

3.2 pre-commit 钩子

除 Makefile 外，仓库还配置了本地提交钩子 ​.pre-commit-config.yaml，共四道检查：

1. ruff-check（带 --fix）与 ruff-format，作用域为 python / pyi / jupyter 三类文件——注意 Notebook 也被纳入 ruff 检查范围；
2. validate-notebooks：本地钩子，仅对 \.ipynb$ 变更文件执行 uv run python scripts/validate_notebooks.py，且透传文件名；
3. validate-authors-sorted：变更 authors.yaml 时自动执行 --fix 重排。

其中 scripts/validate_notebooks.py 的校验逻辑非常直接，源码中 validate_notebook() 函数只做两类检查：

• 每个 cell 的 source 不能为空（"Cell N: Empty cell found"）；
• code cell 的 outputs 中不能出现 output_type == "error"（"Cell N: Contains error output"）。

发现问题即以退出码 1 终止，从而阻断提交。这正是 CLAUDE.md 中"Notebooks must run top-to-bottom without errors"在提交前能落地为机器检查的原因。

CLAUDE.md 同时给出了不经过 Make 的 ruff 直调方式，方便按需检查：

uv run ruff format .           # 格式化
uv run ruff check .            # Lint
uv run ruff check --fix .      # 自动修复
uv run pre-commit run --all-files  # 手动对全部文件跑钩子

4. 代码风格：Ruff 的完整配置依据

CLAUDE.md 声明的风格规则只有三行，但每一条都能在 pyproject.toml 中找到对应配置：

规则	CLAUDE.md 声明	pyproject.toml 对应项
Line length	100 字符	[tool.ruff] line-length = 100
Quotes	双引号	[tool.ruff.format] quote-style = "double"
Formatter	Ruff	target-version = "py311"，且 extend-include = ["*.ipynb"] 显式把 Notebook 纳入

Lint 规则集同样有源码依据：select = ["E", "F", "I", "W", "UP", "S", "B"]（pycodestyle 错误/警告、pyflakes、isort、pyupgrade、bandit 安全、bugbear），并针对示例仓库的语境豁免了一批规则，如 S301（本地数据的 pickle 使用可接受）、S608（教学演示 SQL 字符串拼接可接受）、S101（测试中允许 assert）等。

关于 CLAUDE.md 提到的"Notebooks have relaxed rules"，[tool.ruff.lint.per-file-ignores] 中为 *.ipynb 单独放宽了四条规则：

• E402：允许文件中部导入（Notebook 按叙事顺序分段 import 是常态）；
• F811：允许重定义（迭代调试常见）；
• N803 / N806：放宽参数与函数内变量命名（API 响应字段常为驼峰）。

这说明仓库刻意区分"常规 Python 文件"与"教学 Notebook"两套规范，而不是简单地全局放宽。

5. Git 工作流

CLAUDE.md 规定的分支与提交约定：

• 分支命名：<username>/<feature-description>，例如 alice/add-rag-example；
• 提交格式（Conventional Commits）：

feat(scope): add new feature
fix(scope): fix bug
docs(scope): update documentation
style: lint/format

CONTRIBUTING.md 补充了完整的 type 集合（feat / fix / docs / style / refactor / test / chore / ci）以及配套要求：提交保持原子性（一次提交只含一个逻辑变更）、PR 标题沿用 Conventional Commit 格式、描述中写清"改了什么 / 为什么 / 如何测试 / 关联 issue"。

6. 五条 Key Rules 逐条解析

6.1 API Key：禁止提交 .env，统一走环境变量

规则原文：Never commit .env files. Use dotenv.load_dotenv() then access keys via os.environ or os.getenv()。

仓库中的标准写法（CONTRIBUTING.md 给出的示例）：

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

.env 已在 .gitignore 管理范围内，模板 .env.example 则明确提示"Copy this file to .env and add your API key"。

6.2 依赖管理：只允许通过 uv 增删

规则原文：使用 uv add <package> 或 uv add --dev <package>，Never edit pyproject.toml directly。这样做的价值在于：uv 会同步更新 uv.lock 锁定文件，避免手工编辑 pyproject.toml 造成声明与锁版本漂移；开发依赖统一落在 [dependency-groups] dev 组中，uv sync --all-extras 即可一次性还原完整环境。

6.3 模型命名：只用当前非日期别名

这是本仓库最具特色的一条规则。CLAUDE.md 规定：

• 使用当前 Claude 模型，并以官方文档为准，仓库当前约定的三个别名：
  • Sonnet：claude-sonnet-5
  • Haiku：claude-haiku-4-5
  • Opus：claude-opus-4-8
• Never use dated model IDs（如 claude-sonnet-4-6-20250514），一律使用非日期别名——别名随官方版本滚动更新，可以避免示例代码随时间腐化；
• Bedrock 模型 ID 是另一套格式，使用文档中的 base Bedrock 模型 ID：
  • Opus 4.6：anthropic.claude-opus-4-6-v1
  • Sonnet 4.5：anthropic.claude-sonnet-4-5-20250929-v1:0
  • Haiku 4.5：anthropic.claude-haiku-4-5-20251001-v1:0
  • 推荐为全局端点加前缀：global.anthropic.claude-opus-4-6-v1；
  • 注意 Opus 4.6 之前的 Bedrock 模型 ID 必须带日期后缀。

这条规则并非纯口头约定：CI 中有对应的 /model-check 命令（见第 7 节）对 PR 变更文件中的模型引用做机器校验，.env.example 也把测试默认模型固定为 claude-haiku-4-5。

6.4 Notebook 规范：保留输出、单一概念、可从头跑到尾

CLAUDE.md 对 Notebook 的三条要求：

1. Keep outputs in notebooks——输出被有意保留，用于向读者展示预期结果（CONTRIBUTING.md 明确说明这是有意为之）；
2. One concept per notebook——一个 Notebook 只讲一个概念；
3. Test that notebooks run top-to-bottom without errors——必须能从头到尾无错运行。

前一条由 pre-commit 的 validate-notebooks 钩子兜底（检查空 cell 与 error output，实现见 scripts/validate_notebooks.py）；后一条则由 make test-notebooks-exec（nbconvert/nbval 执行）和 pyproject.toml 中的 pytest 标记体系支撑：slow（需要真正执行 Notebook 的测试）、integration（依赖外部服务凭据）、mutates_state（会改动真实数据，必须在可丢弃命名空间运行）。

6.5 提交前质量检查

规则原文：Run make check before committing. Pre-commit hooks validate formatting and notebook structure. 即"提交前跑 make check（格式检查 + lint）+ 提交时钩子自动复核"的双重机制，任何一道失败都应修复后重新提交。

7. Claude Code Slash Commands：本地与 CI 同源的三个审查命令

CLAUDE.md 声明仓库内置三个 slash command，同时可用于 Claude Code 本地开发和 CI：

命令	作用
/notebook-review	Notebook 质量综合审查
/model-check	校验 Claude 模型引用是否为当前公开模型
/link-review	检查变更文件中的链接

命令定义存放在 .claude/commands/ 目录，从三份命令定义文件可以看清各自的审查协议：

• notebook-review.md：只审查 prompt 中明确列出的文件，按"✅ 做得好 / ⚠️ 建议改进 / ❌ 必须修复"三级输出，并要求以 gh pr comment $PR_NUMBER --body "..." 把结论回贴到 PR；
• model-check.md：先拉取当前公开模型清单，再核对四件事——引用是否属于当前模型、是否有已弃用模型（如旧版 Sonnet 3.5、Opus 3）、是否有内部/非公开模型名、是否建议改用 -latest 后缀别名；
• link-review.md：检查死链、过期文档、可疑站点，并给出 HTTPS 与内外部链接路径规范；对 Anthropic 内容额外要求"模型文档应指向当前模型而非弃用版本"。

此外，从目录结构看，仓库还配有 ​.claude/agents/code-reviewer.md（代码审查 agent）与 .claude/skills/cookbook-audit/（Cookbook 审计技能，内含 style_guide.md 与 validate_notebook.py），共同构成"Claude 审 Claude 示例"的自动评审层。CONTRIBUTING.md 指出这些命令与 CI 流水线"使用完全相同的验证逻辑"，因此本地执行等价于提前跑了 CI。

8. 项目结构

CLAUDE.md 给出的目录骨架如下：

capabilities/      # Core Claude capabilities (RAG, classification, etc.)
evals/             # Model evaluation patterns and benchmarks
skills/            # Advanced skill-based notebooks
tool_use/          # Tool use and integration patterns
multimodal/        # Vision and image processing
misc/              # Batch processing, caching, utilities
third_party/       # Pinecone, Voyage, Wikipedia integrations
extended_thinking/ # Extended reasoning patterns
scripts/           # Validation scripts
.claude/           # Claude Code commands and skills

对照仓库实际顶层目录，除上述目录外还存在若干同级别模块，如 managed_agents/、claude_agent_sdk/、patterns/、observability/、cost_optimization/、finetuning/、tests/ 等；CLAUDE.md 的骨架是对核心目录的概括，实际新增 Cookbook 时应按主题就近选择目录。所有 Cookbook 的"索引数据"集中在 registry.yaml 与 authors.yaml 两个文件中维护。

9. 新增一个 Cookbook：四步流程

CLAUDE.md 定义的 Adding a New Cookbook 流程为四步，结合仓库实际文件格式可展开如下：

1. 在合适的目录创建 Notebook（如 capabilities/、tool_use/、misc/），并确保它通过 make check 与 Notebook 结构校验；
2. 在 registry.yaml 添加注册条目。从现有条目看，每条记录包含 title、description、path（相对仓库根的 Notebook 路径）、authors（GitHub 用户名列表）、date 与 categories 字段，且文件头声明了 JSON Schema（# yaml-language-server: $schema=./.github/registry_schema.json），提交时可据此校验字段完整性；
3. 若贡献者为新成员，在 authors.yaml 添加作者信息。该文件将 GitHub 用户名映射为 name / website / avatar，供站点展示；pre-commit 的 validate-authors-sorted 钩子会强制其保持字母序（本地可用 make sort-authors 自动重排）；
4. 运行质量检查并提交 PR：依次执行 make check、uv run python scripts/validate_notebooks.py，并按第 5 节的 Conventional Commit 规范（如 feat(capabilities): add text-to-sql notebook）提交。

10. 小结：一套"可机检"的示例仓库规范

把 CLAUDE.md 与仓库配置文件对照后可以发现，这个项目的规范几乎条条都有对应的自动化实现：ruff 配置对应 Code Style 章节（pyproject.toml），Makefile 与 ​.pre-commit-config.yaml 对应 Development Commands 章节，scripts/validate_notebooks.py 与 pytest 标记体系对应 Notebook 规则，.claude/commands/ 中的 slash command 对应模型命名与链接质量规则，registry.yaml/authors.yaml 对应新增 Cookbook 流程。对读者而言，这意味着只要严格按照本文第 2、3、9 节的命令序列操作，就能在提交前复现 CI 的绝大部分检查，显著降低 PR 被打回的概率。