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.11uv 包管理器推荐或 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依赖组实际安装了支撑整个质量体系的工具链ruffLint/格式化、pytestnbvalNotebook 测试、pre-commit钩子、nbconvert执行、toxtox-uv隔离环境以及pytest-cov。运行中的 Cookbook 依赖则包括anthropic、claude-agent-sdk、jupyter、pandas、voyageai、pymongo等。1.3 安装 pre-commit 钩子uv run pre-commit install # 或pre-commit install1.4 配置 API Keycp .env.example .env # 编辑 .env填入你的 Claude API key仓库提供了 .env.example 模板其内容揭示了测试用的关键环境变量变量说明ANTHROPIC_API_KEYClaude API 密钥必填CLAUDE_MODEL测试默认模型模板值为claude-haiku-4-5选便宜模型节省成本TEST_MODE/MAX_TOKENS/DEBUG测试模式开关、单调用 token 上限模板为 10、调试输出安全规范见第 7 节要求.env文件永不入库敏感数据一律走环境变量。2. Notebook 校验栈nbconvert ruff Claude AI 评审CONTRIBUTING.md 将质量保障归纳为「The Notebook Validation Stack」由三层组成nbconvert以真实执行 Notebook 的方式做测试ruff带原生 Jupyter 支持的高性能 Python Linter 与 FormatterClaude AI Review用 Claude 进行智能代码评审。文档还特别说明了一条重要的仓库约定Notebook 的输出outputs是刻意保留在仓库中的因为它们向读者展示「预期结果」。这一点直接影响校验规则——保留输出的同时输出中不允许残留 error。2.1 ruff 配置为什么 Notebook 有放宽规则pyproject.toml 中的 ruff 配置是提交前格式检查的实际依据line-length 100、target-version py311lint 规则集select [E, F, I, W, UP, S, B]并显式忽略E501行长、S101assert、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.pyskills/只是文档示例目录替换为你改动的实际目录。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 pytestNotebook 专项测试支持用环境变量缩小范围这对贡献者非常实用# 只测某一个 Notebook快不执行 make test-notebooks NOTEBOOKtool_use/calculator_tool.ipynb # 测某个目录下的全部 Notebook make test-notebooks NOTEBOOK_DIRcapabilities # 真正执行 Notebook慢需要 API key make test-notebooks-exec NOTEBOOKcapabilities/classification/guide.ipynb # 在隔离的 tox 环境中跑 make test-notebooks-tox NOTEBOOK_DIRcapabilities # 不经过 pytest 的快速结构校验 make test-notebooks-quick此外文档中给出的 nbconvert 手动执行方式依然可用会实际消耗 API token属可选项uv run jupyter nbconvert --to notebook \ --execute skills/classification/guide.ipynb \ --ExecutePreprocessor.kernel_namepython3 \ --output test_output.ipynb3. Claude Code 斜杠命令本地与 CI 同一套校验逻辑CONTRIBUTING.md 的一个核心设计是本仓库内置的斜杠命令在本地 Claude Code 与 GitHub Actions CI 中复用同一套校验逻辑让你 push 之前就能发现 CI 会发现的问题。命令定义存放在.claude/commands/目录。3.1 三个核心命令命令作用命令定义/link-review校验 markdown 与 Notebook 中的链接.claude/commands/link-review.md/model-check校验 Claude 模型引用是否为当前公开模型.claude/commands/model-check.md/notebook-review综合 Notebook 质量检查.claude/commands/notebook-review.md在 Claude Code 中的用法# 运行与 CI 完全相同的校验 /notebook-review skills/my-notebook.ipynb /model-check /link-review README.md从命令定义文件可以看出各自的检查细则/model-checkmodel-check.md先获取官方当前公开模型列表然后核对变更文件中的模型引用——标记已弃用模型早期 Sonnet 3.5、Opus 3 系列、标记内部/非公开模型名并建议改用-latest结尾的别名以保证可维护性/link-reviewlink-review.md检查死链、过时链接、安全问题并要求 HTTPS 优先、内部链接用相对路径对 Anthropic 内容额外要求模型文档指向当前版本/notebook-reviewnotebook-review.md仅评审明确列出的文件输出✅ 好的部分 / ⚠️ 改进建议 / ❌ 必须修复三段式报告。值得注意的是.claude/commands/中还配有 review-pr.md交互式 PR 评审与 review-pr-ci.mdCI 自动评审两个变体均通过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 可以看到具体挂了四道工序ruff-checkastral-sh/ruff-pre-commit以 SHAfa1ed65...固定版本注释标明 v0.14.6types_or: [python, pyi, jupyter]即Notebook 也被 lint且带--fix自动修复ruff-format同样覆盖 python 与 jupyter 文件类型validate-notebookslocal hookentry: uv run python scripts/validate_notebooks.pyfiles: \.ipynb$触发pass_filenames: true将变更文件列表传给脚本——这与第 2.2 节的脚本实现精确对应validate-authors-sortedlocal hook当authors.yaml变动时运行scripts/validate_authors_sorted.py --fix保证作者列表按字母序排列也可手动make sort-authors。文档给出的处理原则很直接如果钩子失败修复问题后重新提交即可。CI 侧的 verify-authors.yml 工作流会在 PR 上对同一约束做二次把关。5. Notebook 内容规范贡献者必须遵守的最佳实践CONTRIBUTING.md 的 Notebook Best Practices 四条准则结合仓库内的执法工具可以整理为一张可对照的清单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 的安全检查直接判失败。使用当前 Claude 模型可用时优先模型别名文档给出的最新 Haiku 为claude-haiku-4-5Haiku 4.5。模型列表以官方文档页为准仓库 CI 通过/model-check自动拉取核对且Claude 会在 PR 评审中自动校验模型用法——这对应 claude-model-check.yml 工作流。一个 Notebook 只讲一个概念解释与注释清晰预期输出以 markdown cell 形式包含这也是 outputs 刻意保留在仓库中的原因。自测 Notebook能从上到下无错跑完示例 API 调用使用最小 token与 .env.example 中MAX_TOKENS10的默认值理念一致包含错误处理。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 全集type用途feat新功能fixBug 修复docs文档style格式化refactor代码重构test测试chore维护性事务ciCI/CD 变更文档给出的示例提交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 都要登记在合适目录创建 Notebook在 registry.yaml 添加条目title、description、path、authors、categories新贡献者需把自己的信息加入 authors.yaml注意保持字母序make sort-authors可自动排序跑完质量检查后提交 PR。7. 测试与 CI/CD 流水线7.1 本地测试套件# 校验全部 Notebook uv run python scripts/validate_notebooks.py # 对所有文件跑一遍 pre-commit uv run pre-commit run --all-files7.2 CI 侧五个各司其职的工作流CONTRIBUTING.md 概括 CI 会自动校验 Notebook 结构、ruff Lint、维护者测试 Notebook 执行、检查链接、Claude 评审代码与模型用法并明确外部贡献者的 API 测试受限以节约资源。对照 .github/workflows/ 中的实际定义这一描述可以精确展开lint-format.yml仅针对相对 base 分支变更的.py/.ipynb文件跑ruff format --check与ruff check发现问题时先用 Claudeclaude-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 --executetimeout 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.ymlPR 场景只检查变更的.md/.ipynbNotebook 先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 或任何秘密敏感数据一律使用环境变量安全问题应私下报告给 securityanthropic.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 校验。小结一次合格贡献的最小闭环uv sync --all-extrasuv run pre-commit installcp .env.example .env完成环境写/改 Notebook单概念、环境变量取 key、当前模型别名、顶部到尾部无错跑通、outputs 无 error本地跑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...需要时用/notebook-review、/model-check、/link-review预演 CI按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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
