企业官网建设流程全解析

Claude Cookbooks 贡献开发指南：Notebook 校验栈、Claude Code 斜杠命令与 CI 质量保障全链路

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks

本文基于 Claude Cookbooks 仓库的官方贡献文档 CONTRIBUTING.md 展开，系统讲解贡献者从开发环境搭建、Notebook 质量校验栈（nbconvert + ruff + Claude AI 评审）、Claude Code 斜杠命令，到 Git 工作流与 GitHub Actions CI 管线的完整实战路径。读完后，你可以独立完成一次合格的 Notebook 贡献：搭好本地环境、跑通全部本地检查、按规范提交 PR，并理解 CI 侧每一步校验的底层实现依据。

1. 开发环境搭建

1.1 前置条件

官方贡献文档明确列出两项前置要求：

• Python 3.11 或更高版本。仓库 pyproject.toml 中requires-python = ">=3.11,<3.13"进一步收紧了实际兼容区间，CI 工作流中也固定安装uv python install 3.11；
• uv 包管理器（推荐）或 pip。

1.2 安装 uv 并同步依赖

安装 uv 有两条路径：

# 官方安装脚本 curl -LsSf https://astral.sh/uv/install.sh | sh # 或使用 Homebrew brew install uv

克隆仓库后进入目录，创建虚拟环境并安装全部依赖：

git clone https://gitcode.com/GitHub_Trending/an/claude-cookbooks cd claude-cookbooks # 创建虚拟环境并安装依赖（含全部 extras） uv sync --all-extras # 或者使用 pip： pip install -e ".[dev]"

从 pyproject.toml 可以看到，dev依赖组实际安装了支撑整个质量体系的工具链：ruff（Lint/格式化）、pytest+nbval（Notebook 测试）、pre-commit（钩子）、nbconvert（执行）、tox+tox-uv（隔离环境）以及pytest-cov。运行中的 Cookbook 依赖则包括anthropic、claude-agent-sdk、jupyter、pandas、voyageai、pymongo等。

1.3 安装 pre-commit 钩子

uv run pre-commit install # 或：pre-commit install

1.4 配置 API Key

cp .env.example .env # 编辑 .env，填入你的 Claude API key

仓库提供了 .env.example 模板，其内容揭示了测试用的关键环境变量：

安全规范（见第 7 节）要求：.env文件永不入库，敏感数据一律走环境变量。

2. Notebook 校验栈：nbconvert + ruff + Claude AI 评审

CONTRIBUTING.md 将质量保障归纳为「The Notebook Validation Stack」，由三层组成：

• nbconvert：以真实执行 Notebook 的方式做测试；
• ruff：带原生 Jupyter 支持的高性能 Python Linter 与 Formatter；
• Claude AI Review：用 Claude 进行智能代码评审。

文档还特别说明了一条重要的仓库约定：Notebook 的输出（outputs）是刻意保留在仓库中的，因为它们向读者展示「预期结果」。这一点直接影响校验规则——保留输出的同时，输出中不允许残留 error。

2.1 ruff 配置：为什么 Notebook 有"放宽"规则

pyproject.toml 中的 ruff 配置是提交前格式检查的实际依据：

• line-length = 100、target-version = "py311"；
• lint 规则集select = ["E", "F", "I", "W", "UP", "S", "B"]，并显式忽略E501（行长）、S101（assert）、S301（本地数据的 pickle）、S608（演示用 SQL 拼接）等——注释解释了每条忽略的原因，例如 "pickle usage ok for local data in cookbooks"；
• 关键差异在per-file-ignores：*.ipynb文件额外豁免E402（文件中部 import）、F811（重定义，Notebook 中常见）、N803/N806（命名风格）。这正是 CLAUDE.md 所述 "Notebooks have relaxed rules" 的落地位置。

因此本地提交前执行：

uv run ruff check skills/ --fix uv run ruff format skills/ uv run python scripts/validate_notebooks.py

（skills/只是文档示例目录，替换为你改动的实际目录。）

2.2 结构校验脚本：查什么、怎么判定失败

scripts/validate_notebooks.py 是 pre-commit 钩子和 CI 共用的结构校验器，逻辑简洁可审计：

• 空 cell 检查：遍历nb["cells"]，任何source为空的 cell 记为Cell {i}: Empty cell found；
• 错误输出检查：任何 code cell 的outputs中出现output_type == "error"即记为Cell {i}: Contains error output；
• 存在任一个问题时打印❌ ... Found issues that must be fixed before committing并以退出码 1 终止，否则打印✅ All N notebook(s) validated successfully。

2.3 pytest 测试框架：比结构校验更深一层

tests/notebook_tests/test_notebooks.py 提供了更完整的测试脚手架，覆盖：结构合法性（JSON 可解析、cells 非空、存在 code cell、cell 类型合法、kernelspec 存在且为 Python 内核）、cell 执行顺序校验、全部 cell 已执行校验、错误输出检测、硬编码 API key 安全扫描、依赖检测，以及可选的完整执行测试。配套工具函数集中在tests/notebook_tests/utils.py。

2.4 Makefile：一条命令跑通全部检查

Makefile 将上述工具封装为可记忆的目标，与 CLAUDE.md 的 "Development Commands" 一致：

make format # uv run ruff format . make lint # uv run ruff check . make check # format-check + lint（提交前必跑） make fix # ruff check --fix + ruff format make test # uv run pytest

Notebook 专项测试支持用环境变量缩小范围，这对贡献者非常实用：

# 只测某一个 Notebook（快，不执行） make test-notebooks NOTEBOOK=tool_use/calculator_tool.ipynb # 测某个目录下的全部 Notebook make test-notebooks NOTEBOOK_DIR=capabilities # 真正执行 Notebook（慢，需要 API key） make test-notebooks-exec NOTEBOOK=capabilities/classification/guide.ipynb # 在隔离的 tox 环境中跑 make test-notebooks-tox NOTEBOOK_DIR=capabilities # 不经过 pytest 的快速结构校验 make test-notebooks-quick

此外，文档中给出的 nbconvert 手动执行方式依然可用（会实际消耗 API token，属可选项）：

uv run jupyter nbconvert --to notebook \ --execute skills/classification/guide.ipynb \ --ExecutePreprocessor.kernel_name=python3 \ --output test_output.ipynb

3. Claude Code 斜杠命令：本地与 CI 同一套校验逻辑

CONTRIBUTING.md 的一个核心设计是：本仓库内置的斜杠命令在本地 Claude Code 与 GitHub Actions CI 中复用同一套校验逻辑，让你 "push 之前就能发现 CI 会发现的问题"。命令定义存放在.claude/commands/目录。

3.1 三个核心命令

在 Claude Code 中的用法：

# 运行与 CI 完全相同的校验 /notebook-review skills/my-notebook.ipynb /model-check /link-review README.md

从命令定义文件可以看出各自的检查细则：

• /model-check（model-check.md）：先获取官方当前公开模型列表，然后核对变更文件中的模型引用——标记已弃用模型（早期 Sonnet 3.5、Opus 3 系列）、标记内部/非公开模型名，并建议改用-latest结尾的别名以保证可维护性；
• /link-review（link-review.md）：检查死链、过时链接、安全问题，并要求 HTTPS 优先、内部链接用相对路径；对 Anthropic 内容额外要求模型文档指向当前版本；
• /notebook-review（notebook-review.md）：仅评审明确列出的文件，输出"✅ 好的部分 / ⚠️ 改进建议 / ❌ 必须修复"三段式报告。

值得注意的是，.claude/commands/中还配有 review-pr.md（交互式 PR 评审）与 review-pr-ci.md（CI 自动评审）两个变体，均通过code-reviewer子代理（定义见 .claude/agents/code-reviewer.md）执行深度评审——该代理的检查清单包含 Notebook 教学结构（开篇是否从问题出发、是否列出 2–4 条学习目标）、pip install是否用-q抑制输出、是否定义顶部MODEL常量等细粒度规范。

3.2 模型命名的仓库级约定

CLAUDE.md 的 "Key Rules" 把模型引用规则写得比 CONTRIBUTING.md 更细，值得贡献者一并遵守：

• 永远不要使用带日期的模型 ID（如claude-sonnet-4-6-20250514），始终使用不带日期的别名。这是/model-check与 CI 评审共同执法的硬性规则；
• Bedrock 模型 ID 格式不同：使用文档中的基础 Bedrock ID（如anthropic.claude-opus-4-6-v1），推荐使用global.前缀走全球端点，Opus 4.6 之前的 Bedrock 模型则要求带日期 ID；
• 依赖管理同样有约定：用uv add <package>或uv add --dev <package>，不要手改 pyproject.toml。

4. Pre-commit 钩子：提交前自动拦截

安装钩子后，每次git commit都会自动运行质量检查。从 .pre-commit-config.yaml 可以看到具体挂了四道工序：

1. ruff-check（astral-sh/ruff-pre-commit，以 SHAfa1ed65...固定版本，注释标明 v0.14.6）：types_or: [python, pyi, jupyter]，即Notebook 也被 lint，且带--fix自动修复；
2. ruff-format：同样覆盖 python 与 jupyter 文件类型；
3. validate-notebooks（local hook）：entry: uv run python scripts/validate_notebooks.py，files: '\.ipynb$'触发，pass_filenames: true将变更文件列表传给脚本——这与第 2.2 节的脚本实现精确对应；
4. validate-authors-sorted（local hook）：当authors.yaml变动时运行scripts/validate_authors_sorted.py --fix，保证作者列表按字母序排列（也可手动make sort-authors）。

文档给出的处理原则很直接：如果钩子失败，修复问题后重新提交即可。CI 侧的 verify-authors.yml 工作流会在 PR 上对同一约束做二次把关。

5. Notebook 内容规范：贡献者必须遵守的最佳实践

CONTRIBUTING.md 的 "Notebook Best Practices" 四条准则，结合仓库内的执法工具，可以整理为一张可对照的清单：

1. API key 一律走环境变量：

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

   注意与.claude/agents/code-reviewer.md评审清单的配合：评审要求使用dotenv.load_dotenv()加载（而非裸os.environ读取未加载的环境），即"先 load_dotenv，再 os.environ/getenv"的组合。测试用例中硬编码密钥会被 tests/notebook_tests/test_notebooks.py 的安全检查直接判失败。

2. 使用当前 Claude 模型：可用时优先模型别名；文档给出的最新 Haiku 为claude-haiku-4-5（Haiku 4.5）。模型列表以官方文档页为准（仓库 CI 通过/model-check自动拉取核对），且Claude 会在 PR 评审中自动校验模型用法——这对应 claude-model-check.yml 工作流。

3. 一个 Notebook 只讲一个概念：解释与注释清晰；预期输出以 markdown cell 形式包含（这也是 outputs 刻意保留在仓库中的原因）。

4. 自测 Notebook：能从上到下无错跑完；示例 API 调用使用最小 token（与 .env.example 中MAX_TOKENS=10的默认值理念一致）；包含错误处理。

6. Git 工作流与 Pull Request 规范

6.1 分支与 Conventional Commits

# 1. 创建特性分支：<username>/<feature-description> git checkout -b alice/add-rag-example # 2. 使用 Conventional Commits 格式：<type>(<scope>): <subject>

文档列出的 type 全集：

文档给出的示例提交：

git commit -m "feat(skills): add text-to-sql notebook" git commit -m "fix(api): use environment variable for API key" git commit -m "docs(readme): update installation instructions"

保持 commit 原子性：一次提交只含一个逻辑变更、消息描述清晰、适用时引用 issue。

6.2 推送与 PR 要求

git push -u origin your-branch-name gh pr create # 或使用 Web 界面

PR 规范：标题沿用 conventional commit 格式；描述需说明改了什么、为什么改、如何验证、关联 issue 号；一个 PR 只做一个 feature/fix；及时响应评审意见。仓库在 .github/pull_request_template.md 提供了 PR 模板。

6.3 新增 Cookbook 的完整登记流程

CLAUDE.md 的 "Adding a New Cookbook" 补充了文档未展开的关键一步——每个 Cookbook 都要登记：

1. 在合适目录创建 Notebook；
2. 在 registry.yaml 添加条目（title、description、path、authors、categories）；
3. 新贡献者需把自己的信息加入 authors.yaml（注意保持字母序，make sort-authors可自动排序）；
4. 跑完质量检查后提交 PR。

7. 测试与 CI/CD 流水线

7.1 本地测试套件

# 校验全部 Notebook uv run python scripts/validate_notebooks.py # 对所有文件跑一遍 pre-commit uv run pre-commit run --all-files

7.2 CI 侧：五个各司其职的工作流

CONTRIBUTING.md 概括 CI 会自动"校验 Notebook 结构、ruff Lint、（维护者）测试 Notebook 执行、检查链接、Claude 评审代码与模型用法"，并明确外部贡献者的 API 测试受限以节约资源。对照 .github/workflows/ 中的实际定义，这一描述可以精确展开：

• lint-format.yml：仅针对相对 base 分支变更的.py/.ipynb文件跑ruff format --check与ruff check；发现问题时先用 Claude（claude-code-action）生成一条友好的 PR 评论（提示本地make fix/make check），再以exit 1硬性拦截。
• notebook-quality.yml：对 Notebook 跑 ruff 与scripts/validate_notebooks.py（用grep "❌"判定是否有问题）；发现问题时由 Claude 把问题分组汇总成 PR 评论（例如"7 个 Notebook 存在空 cell"）并解释修复方式。关键的差异化逻辑在这里：只有 push 到 main、或 PR 作者身份为 MEMBER/OWNER 时才会用jupyter nbconvert --execute（timeout 120s）真实执行全部 Notebook 并上传产物；外部贡献者走 mock 模式，仅用python -m nbformat.validator做结构校验——这正是文档"外部贡献者 API 测试受限"的实现。
• notebook-tests.yml：先git diff --name-only origin/$BASE_REF...HEAD取出本 PR 变更的 Notebook 列表，对每个变更文件单独跑 pytest 结构测试（-m "not slow"）；执行测试同样仅限维护者（单本timeout 300、--notebook-timeout 240），且最终状态检查特意保证"外部贡献者永远不会被 API 执行结果卡住"（无 API key 或跳过执行时不判失败）。
• links.yml：PR 场景只检查变更的.md/.ipynb（Notebook 先nbconvert --to markdown转换再抽链接），使用 lychee-action 并读取 lychee.toml 配置（30s 超时、最多 10 次重定向、3 次重试、缓存 1 天、相对链接按ipynb/md/html/py回退扩展名探测）；另有每周日 0 点的定时全量检查。
• Claude 评审系列：claude-pr-review.yml、claude-model-check.yml、claude-link-review.yml 分别驱动代码评审、模型校验与链接评审——即第 3 节斜杠命令在 CI 侧的落地。值得留意的是，从工作流注释可见 CI 中的 Claude 动作通过Workload Identity Federation（用 GitHub OIDC token 换取短期访问令牌）完成认证，而非静态 API key；而个别直接调用 API 的 Notebook 执行步骤目前仍读取静态ANTHROPIC_API_KEYsecret（工作流中的 TODO 注释已明确说明这是待迁移项）。

从这套流水线可以看出设计思路：确定性工具（ruff、nbformat、lychee、结构脚本）负责硬性拦截，Claude 负责把失败原因"翻译"成可操作的评论，而花钱的真实 API 执行只对维护者与 main 分支开放。

8. 安全、许可与求助渠道

• 安全：永不提交 API key 或任何秘密；敏感数据一律使用环境变量；安全问题应私下报告给 security@anthropic.com。
• 许可：按贡献文档，所有贡献将自动以与项目相同的MIT License（见 LICENSE）发布。
• 求助：一般问题走 GitHub Issues，社区交流走 Anthropic Discord。
• 相关配套文档：README.md 的 "Contributing" 一节建议先查已有 issues 与 PR 避免重复劳动；authors.yaml 与 registry.yaml 的格式约束分别由 .github/authors_schema.json 与 .github/registry_schema.json 校验。

小结：一次合格贡献的最小闭环

1. uv sync --all-extras+uv run pre-commit install+cp .env.example .env完成环境；
2. 写/改 Notebook：单概念、环境变量取 key、当前模型别名、顶部到尾部无错跑通、outputs 无 error；
3. 本地跑uv run ruff check <dir> --fix、uv run ruff format <dir>、uv run python scripts/validate_notebooks.py <file.ipynb>，或直接用make check与make test-notebooks NOTEBOOK=...；
4. 需要时用/notebook-review、/model-check、/link-review预演 CI；
5. 按<username>/<feature>分支 + conventional commit 推送，PR 描述写清 what/why/how-to-test/issue；新 Cookbook 记得登记registry.yaml与authors.yaml。

遵循以上闭环，你的 PR 将精确通过第 7 节所述的每一道 CI 关卡。

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks