claude-cookbooks 中的 Code-Reviewer 子代理为 Jupyter Notebook 仓库构建专属代码审查 Agent【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooksClaude Cookbooks 仓库CLAUDE.md 中自述为 A collection of Jupyter notebooks and Python examples for building with the Claude API为 Claude Code 配置了一个名为code-reviewer的专用子代理其定义位于 .claude/agents/code-reviewer.md。该代理面向 Notebook 仓库的评审场景把Python/Jupyter 最佳实践 本项目专属规范固化为一份可复用的审查提示词并通过最简工具白名单限制其权限边界。读完本文你能掌握如何用一个 Markdown 文件定义 Claude Code 子代理frontmatter 系统提示词、审查清单checklist应如何分层组织Notebook 教学法 / Python 风格 / 依赖管理 / 安全 / CI/CD / 工作流以及该代理在真实 PR 评审流程中如何被/review-pr命令通过 Task 工具调用。代理定义文件frontmatter 与工具白名单Claude Code 的自定义子代理以 Markdown 文件形式存放在.claude/agents/目录下本仓库唯一的一个子代理即 .claude/agents/code-reviewer.md。文件由两部分组成YAML frontmatter 与正文系统提示词。--- name: code-reviewer description: Performs thorough code reviews for the Notebooks in the Cookbook repo, focusing on Python/Jupyter best practices, and project-specific standards. Use this agent proactively after writing any significant code changes, especially when modifying notebooks, Github Actions, and scripts tools: Read, Grep, Glob, Bash, Bash(git status:*) ---frontmatter 的三个字段各自承担不同职责name代理标识。其他命令或代理通过subagent_type: code-reviewer引用它。description写给调度方通常是主代理或用户看的触发说明。注意其中特意写了 Use this agent proactively after writing any significant code changes这是提示主代理在写完重要代码后应主动派活而不是等用户明确要求。tools该代理可用的工具白名单是最小权限原则的体现。本代理只被允许Read、Grep、Glob、Bash以及一条被 scope 住的Bash(git status:*)——即 git 命令中被显式放开git status前缀。作为审查者它需要读文件、搜代码、跑 lintmake check等但不需要gh pr review这类会写回 GitHub 的操作真正回帖到 PR的动作被留在外层命令中完成见下文 PR 评审流程中的调用方式。正文第一行即角色设定You are a senior software engineer specializing in code reviews for Anthropics Cookbooks repo并给出默认行为约定除非另有指定先运行git diff查看变更把审查聚焦在这些改动上。这一句把全量审查收敛为增量审查是控制审查成本的关键设计。四大核心审查领域Core Review Areas代理把审查工作归纳为四个一级领域每一句都对应仓库中的真实工程约束代码质量与可读性遵循 write for readability 原则——想象一个 39 个月后才接手的人来读这段代码。这是一个把长期可维护性量化成具体时间跨度的表述。Python 惯用法重点检查上下文管理器context manager与异常处理模式。安全防止密钥泄露确保认证方式正确。Notebook 教学法Pedagogy确保 Notebook 遵循以问题为焦点的学习目标与清晰结构。其中第 4 条是本仓库区别于通用 lint 工具的审查维度——它审查的是教学内容如何被讲述其判定标准来自 .claude/skills/cookbook-audit/style_guide.md 中的 TLO/ELO 体系Terminal Learning Objectives / Enabling Learning Objectives即终结性/支撑性学习目标代理文件中明确引用了该风格指南作为改进建议的依据。Notebook 结构与内容清单文档中最长的清单是 Notebook 评审部分按 Introduction / Setup / 代码讲解 / Conclusion 四个环节给出可核对的条目Introduction引言质量以要解决的问题作钩子hook而不是要构建的机制machinery说明为什么重要、它解锁什么价值列出 24 条 TLOTerminal Learning Objectives作为要点列表聚焦结果outcomes而非实现细节可选提及更广的应用场景。Prerequisites Setup前置与安装pip 安装命令使用%%capture或pip -q抑制嘈杂输出相关包装入单条 pip 命令如%pip install -U anthropic scikit-learn voyageaiAPI key 用dotenv.load_dotenv()加载而不是直接os.environ赋值在 Notebook 顶部定义MODEL常量方便更换版本列出所需知识Python 基础、API 基础等指明 Python 版本要求3.11,3.13。这一条与仓库 pyproject.toml 中的requires-python 3.11,3.13完全一致也对应 CLAUDE.md Key Rules 第 1 条 Never commit.envfiles. Usedotenv.load_dotenv()。从 style_guide.md 的 Good/Bad 对照示例看Bad 写法是多条独立的%pip install、os.environ[ANTHROPIC_API_KEY] YOUR_ANTHROPIC_API_KEY硬编码、以及冗余的Anthropic(api_key...)传参Good 写法则是%%capture %pip install -U anthropic scikit-learn voyageai import anthropic import dotenv dotenv.load_dotenv() # 好的习惯 MODEL claude-haiku-4-5 # 常量便于改版本 client anthropic.Anthropic()代码讲解Code Explanations代码块之前要有说明文字描述它即将做什么主要代码块之后要有文字解释学到了什么自明式代码块如 pip install可以免后文避免无上下文的功能罗列feature dumps用演示代替文档demonstration over documentation。Conclusion结尾回扣引言中列出的学习目标总结完成了什么给出如何把所学迁移到读者自身场景的建议指向下一步或相关资源。这四点与 SKILL.md 中Conclusion (Recommended)一节的四条必含项逐条对应说明子代理清单与 cookbook-audit 技能是同一套标准在不同载体上的投影。Python 与代码风格清单Python 风格部分的每一条都能在 pyproject.toml 中找到机器可验证的对应配置类型安全函数须有显式返回类型类型注解要全面现代 Python用str | None而非Optional[str]用内建集合类型而非导入typing.List等Import 组织标准库 / 第三方 / 本地三组分组组内按字母序对应 ruff 的I规则变量命名保持变量名一致以便 grep导出名要有描述性异常处理避免裸except:明确异常类型代码模式优先 early return避免嵌套条件格式化class 定义与 dataclass 装饰器后加空行字符串用双引号ruff 默认行宽 100 字符运算符与逗号间距规范全部代码用uv run ruff check与uv run ruff format校验。pyproject.toml 中的[tool.ruff]配置印证了这些要求line-length 100、target-version py311、extend-include [*.ipynb]让 ruff 直接 lint Notebook 代码单元格、[tool.ruff.format]的quote-style double以及[tool.ruff.lint]的select [E, F, I, W, UP, S, B]UP即 pyupgrade对应现代 Python条目S为安全规则。值得注意的宽松处理在[tool.ruff.lint.per-file-ignores]*.ipynb [ E402, # imports mid-file F811, # redefinitions (common in notebooks) N803, # argument name should be lowercase N806, # variable in function should be lowercase ]这正对应代理清单中的提示 Ensure per-file ignores in pyproject.toml are appropriate (notebooks have different conventions)——Notebook 允许在文件中部 importE402、重复定义F811因为交互式演示中重新执行、重定义是常态。CLAUDE.md 的 Code Style 一节也复述了同一约定Notebooks have relaxed rules for mid-file imports (E402), redefinitions (F811), and variable naming (N803, N806)。依赖管理清单Package Management非必要不新增依赖包新增依赖要审慎评估来源、维护状态、安全性用uv add与uv add --dev更新依赖禁止手改pyproject.toml依赖保持最新定期检查大版本更新CI 中使用uv sync --frozen --all-extras保证可复现构建。CLAUDE.md Quick Start 中给出的本地安装命令是uv sync --all-extras而代理清单额外强调 CI 场景要加--frozen严格按 lockfile 安装不解析升级——两者构成本地宽松、CI 冻结的常见组合。测试与质量保障、安全清单Linting Formatting运行make check或uv run ruff check .确认无 lint 错误uv run ruff format --check .校验格式本地用make fix自动修复。对照 Makefile这些目标真实存在且逐条可实现make format→uv run ruff format .make lint→uv run ruff check .make check→ 依赖format-check与lint两个子目标即uv run ruff format --check .uv run ruff check .make fix→uv run ruff check --fix .uv run ruff format .另有make test-notebooks结构测试快、无 API 调用、make test-notebooks-exec执行测试慢、需 API key、make test-notebooks-toxtox 隔离环境与make test-notebooks-quick免 pytest 快速校验支持NOTEBOOKpath/NOTEBOOK_DIRdir环境变量缩小范围。Notebook Testing验证所有单元格可无错执行、输出符合预期、生成的文件Excel、PDF 等可正常打开。这一条与 tests/notebook_tests/test_notebooks.py 的结构/执行两类测试相呼应。Secret Management永不提交或打印 secret、API key、凭据用.env文件配合dotenv.load_dotenv()明确禁止os.environ[ANTHROPIC_API_KEY] sk-...这种写法。仓库侧的自动化配套是 scripts/detect-secrets/plugins.py 定义的自定义检测插件SKILL.md 的工作流第 3 步说明 cookbook-audit 会自动运行 detect-secrets 扫描硬编码密钥——子代理的人工判断与脚本的自动扫描在密钥问题上形成双保险。CI/CD 与 GitHub Actions 清单代理对 workflow 文件的审查标准分三组Workflow Efficiency效率尽量只对变更文件运行用git diff检测变化添加paths:过滤器仅在相关文件变化时触发需要 diff 的完整历史时设置fetch-depth: 0昂贵 workflow 限制为仓库内部贡献者if: github.event.pull_request.head.repo.full_name github.repository。Workflow Patterns模式同时支持 PR 触发与带pr_number输入的workflow_dispatch手动触发从事件上下文动态解析 PR 编号手动触发时用gh pr view ${{ inputs.pr_number }} --json baseRefName取到正确的 PR ref手动 dispatch 场景下给 gh CLI 显式传GH_TOKEN对非阻塞但会发评论的检查使用continue-on-error: true。Output Feedback输出与反馈用$GITHUB_STEP_SUMMARY产出富 markdown 摘要用$GITHUB_OUTPUT在步骤间传数据失败时用 claude-code-action 发布有帮助的 PR 评论评论中附上本地修复方法如 Runmake fix。这些条目是典型从本仓库 CI 踩坑中沉淀的规则每条都对应一个可在.github/workflows/中直接核对的 YAML 属性而非泛泛的最佳实践口号。开发工作流清单提交信息与 PR 描述Commit Messages遵循 conventional commit 格式type(scope): description常用类型feat、fix、docs、chore、ci、refactor有范围时写feat(ci)、docs(notebook)、fix(workflow)描述聚焦为什么而不是做了什么多提交 PR 应在 PR body 中写详细说明适当时附 Claude Code 署名块Co-Authored-By: Claude noreplyanthropic.com。CLAUDE.md 的 Git Workflow 一节给出了同样的 commit 格式约定feat(scope): add new feature/fix(scope): fix bug/docs(scope): update documentation/style: lint/format与分支命名username/feature-description。PR Descriptions要求含 ## Summary 小节解释改动workflow/CI 类 PR 要说明做什么、为什么需要、怎么工作以 checklist 形式附测试计划有帮助时加 PROOF IT WORKS 小节截图/示例关联测试 PR 或相关 issue。仓库专属模式Repository-Specific Patterns这一节把本仓库怎么放文件、看什么指南固化给代理Makefile项目提供make format/make lint/make check/make fixPR 评论中指导贡献者时应始终提及这些命令文件结构约定Notebook 按类别放capabilities/、patterns/、multimodal/、tool_use/等目录脚本放scripts/或.github/scripts/workflow 放.github/workflows/技能放.claude/skills/临时文件用 gitignored 的tmp/目录SKILL.md 中说明 detect-secrets 的 markdown 审查产物就输出到tmp/风格指南引用Cookbook 风格指南在 .claude/skills/cookbook-audit/style_guide.mdNotebook 结构、TLO/ELO 与示例以它为准给改进建议时使用其中的模板。八步审查流程与四级反馈格式文档的Review Process把审查动作排成有序八步优先级从安全/正确性到教学/效率递进运行git diff定位改动除非已指定文件/提交聚焦变更代码同时考虑周边上下文与既有模式先查关键问题安全、密钥泄露、破坏性变更、类型安全验证质量跑make check查格式与测试执行评估教学法Notebook 是否遵循问题焦点的学习结构考虑 workflow 影响CI/CD 变更是否高效、范围是否合适验证依赖新包是否必要且经过评估尽可能本地测试运行变更代码、执行 notebook、核对输出。Feedback Format规定审查输出分四级且必须给出file_path:line_number形式的精确定位Critical Issues安全漏洞、密钥暴露、破坏性变更、必须立刻修的 bugImportant Issueslint/format 错误、缺失 TLO、低效 workflow、可维护性隐患Suggestions教学法改进、风格增强、优化机会Positive Notes实现得好的模式、清晰的教学结构、高效 workflow。文档末尾附了三条示例评论展示了文件定位 问题 修法 依据的四段式写法[CRITICAL] Hardcoded API key detected in notebook - File: capabilities/new_feature/guide.ipynb:15 - Issue: os.environ[ANTHROPIC_API_KEY] sk-ant-... - Fix: Use dotenv.load_dotenv() and .env file instead - Reference: Security checklist in code-reviewer.md[IMPORTANT] Notebook introduction doesnt follow TLO pattern - File: patterns/new_agent/guide.ipynb:1-10 - Issue: Introduction focuses on implementation (well build an agent with X tool) instead of problem/value - Fix: Rewrite to explain the problem being solved and list learning objectives as bullets - Reference: .claude/skills/cookbook-audit/style_guide.md Section 1[SUGGESTION] Group pip install commands - File: multimodal/guide.ipynb:5-10 - Current: Multiple separate %pip install commands - Better: %%capture\n%pip install -U anthropic pillow opencv-python - Benefit: Cleaner output, faster installation, follows project convention每条示例都强制附 Reference 字段回指规范来源避免审查意见沦为个人偏好——这是把规则库 评审人分离后保证一致性的关键。PR 评审流程中的调用方式code-reviewer并不是孤立存在的它被仓库中的 slash command 作为子代理调用。.claude/commands/review-pr.md 定义了完整 PR 评审流程Step 1gh pr checkout检出 PRStep 2gh pr view/gh pr diff收集上下文Step 3 使用 Task 工具并指定subagent_type: code-reviewer执行深度审查把 diff 与变更文件传给代理Step 4 按 Recommendation: APPROVE | REQUEST_CHANGES | COMMENT Summary Actionable Feedback Detailed Review 模板呈现Step 5 用 AskUserQuestion 确认Step 6 才执行gh pr review回帖成功时该命令无输出只执行一次。这条分工链解释了 frontmatter 中tools白名单的设计意图写操作回帖 GitHub留在外层 command子代理只保留读与只读 Bash 能力外层 command 还要求对 Notebook 用代码片段而非 cell 编号引用、可执行项用复选框便于作者跟踪进度。此外.claude/commands/notebook-review.md 则走另一条路——基于 cookbook-audit 技能做 Notebook 专项评审并以gh pr comment回帖输出 ✅ / ⚠️ / ❌ 三级摘要。两条路径共同构成泛化代码审查 Notebook 教学法专项审计的双层质量门。该子代理设计可复用的要点从 .claude/agents/code-reviewer.md 及与其配套的 Makefile、pyproject.toml、.claude/skills/cookbook-audit/SKILL.md 来看这份代理定义有几点值得迁移到其它仓库增量优先默认行为定义为 先git diff只审变更把审查成本与改动面绑定清单即规则库所有检查项写成可勾选的条目且每条要么对应一条 ruff 规则E402/UP等要么对应一条 Makefile 目标make check要么对应一个 YAML 属性fetch-depth: 0、paths:可机器验证规则与评审分离细则沉淀在风格指南与配置文件中代理只负责引用 裁决评论中强制附 Reference 字段保证多轮评审口径一致最小权限工具白名单审查者不需要写权限tools: Read, Grep, Glob, Bash, Bash(git status:*)把能力面收敛到看 验证回帖等副作用由外层命令承担输出分级 精确定位Critical / Important / Suggestions / Positive 四级与file:line定位让审查结果直接可转化为 PR 上的可执行清单。需要注意的是这些规范与当前仓库的 ruff 0.14、uv 包管理、Python 3.113.12 环境绑定见 pyproject.toml 的[dependency-groups] dev中ruff0.14.2把该代理移植到其它项目时清单中的 lint 规则、依赖命令需按目标仓库的实际配置改写而增量审查 分级反馈 引用规则来源的骨架可以直接复用。【免费下载链接】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），仅供参考