claude-cookbooks 中的 Code-Reviewer 子代理：为 Jupyter Notebook 仓库构建专属代码审查 Agent

Claude 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 前缀。作为审查者它需要读文件、搜代码、跑 lint（make check 等），但不需要 gh pr review 这类会写回 GitHub 的操作；真正"回帖到 PR"的动作被留在外层命令中完成（见下文 PR 评审流程中的调用方式）。

正文第一行即角色设定："You are a senior software engineer specializing in code reviews for Anthropic's Cookbooks repo"，并给出默认行为约定：除非另有指定，先运行 git diff 查看变更，把审查聚焦在这些改动上。这一句把"全量审查"收敛为"增量审查"，是控制审查成本的关键设计。

四大核心审查领域（Core Review Areas）

代理把审查工作归纳为四个一级领域，每一句都对应仓库中的真实工程约束：

1. 代码质量与可读性：遵循 "write for readability" 原则——"想象一个 3～9 个月后才接手的人来读这段代码"。这是一个把长期可维护性量化成具体时间跨度的表述。
2. Python 惯用法：重点检查上下文管理器（context manager）与异常处理模式。
3. 安全：防止密钥泄露，确保认证方式正确。
4. 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）；
• 说明为什么重要、它解锁什么价值；
• 列出 2～4 条 TLO（Terminal Learning Objectives）作为要点列表；
• 聚焦结果（outcomes）而非实现细节；
• 可选：提及更广的应用场景。

Prerequisites & Setup（前置与安装）

• pip 安装命令使用 %%capture 或 pip -q 抑制嘈杂输出；
• 相关包装入单条 pip 命令，如 %pip install -U anthropic scikit-learn voyageai；
• API 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 .env files. Use dotenv.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 允许在文件中部 import（E402）、重复定义（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-tox（tox 隔离环境）与 make test-notebooks-quick（免 pytest 快速校验），支持 NOTEBOOK=path / NOTEBOOK_DIR=dir 环境变量缩小范围。

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 评论；
• 评论中附上本地修复方法（如 "Run make 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 <[e-mail]>）。

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 fix，PR 评论中指导贡献者时应始终提及这些命令；
• 文件结构约定：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.md，Notebook 结构、TLO/ELO 与示例以它为准，给改进建议时使用其中的模板。

八步审查流程与四级反馈格式

文档的 Review Process 把审查动作排成有序八步，优先级从"安全/正确性"到"教学/效率"递进：

1. 运行 git diff 定位改动（除非已指定文件/提交）；
2. 聚焦变更代码，同时考虑周边上下文与既有模式；
3. 先查关键问题：安全、密钥泄露、破坏性变更、类型安全；
4. 验证质量：跑 make check，查格式与测试执行；
5. 评估教学法：Notebook 是否遵循问题焦点的学习结构；
6. 考虑 workflow 影响：CI/CD 变更是否高效、范围是否合适；
7. 验证依赖：新包是否必要且经过评估；
8. 尽可能本地测试：运行变更代码、执行 notebook、核对输出。

Feedback Format 规定审查输出分四级，且必须给出 file_path:line_number 形式的精确定位：

• Critical Issues：安全漏洞、密钥暴露、破坏性变更、必须立刻修的 bug；
• Important Issues：lint/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 doesn't follow TLO pattern
- File: `patterns/new_agent/guide.ipynb:1-10`
- Issue: Introduction focuses on implementation ("we'll 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 1 gh pr checkout 检出 PR，Step 2 gh 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 来看，这份代理定义有几点值得迁移到其它仓库：

1. 增量优先：默认行为定义为 "先 git diff，只审变更"，把审查成本与改动面绑定；
2. 清单即规则库：所有检查项写成可勾选的条目，且每条要么对应一条 ruff 规则（E402/UP 等），要么对应一条 Makefile 目标（make check），要么对应一个 YAML 属性（fetch-depth: 0、paths:），可机器验证；
3. 规则与评审分离：细则沉淀在风格指南与配置文件中，代理只负责"引用 + 裁决"，评论中强制附 Reference 字段，保证多轮评审口径一致；
4. 最小权限工具白名单：审查者不需要写权限，tools: Read, Grep, Glob, Bash, Bash(git status:*) 把能力面收敛到"看 + 验证"，回帖等副作用由外层命令承担；
5. 输出分级 + 精确定位：Critical / Important / Suggestions / Positive 四级与 file:line 定位，让审查结果直接可转化为 PR 上的可执行清单。

需要注意的是，这些规范与当前仓库的 ruff 0.14+、uv 包管理、Python 3.11～3.12 环境绑定（见 pyproject.toml 的 [dependency-groups] dev 中 ruff>=0.14.2）；把该代理移植到其它项目时，清单中的 lint 规则、依赖命令需按目标仓库的实际配置改写，而"增量审查 + 分级反馈 + 引用规则来源"的骨架可以直接复用。