wsl-docs

Cookbook Notebook 审核规范与评分清单

发布日期：2026-02-17原文链接：https://github.com/anthropics/claude-cookbooks/blob/main/.claude/skills/cookbook-audit/SKILL.md,https://github.com/anthropics/claude-cookbooks/blob/main/.claude/skills/cookbook-audit/style_guide.md16分钟阅读

摘要

1) 一句话摘要

本文档提供了 Anthropic Cookbook 笔记本的标准化审核流程、评分框架与样式指南，旨在确保内容以解决实际问题为导向、代码规范且具备高教育价值。

2) 关键要点

  • 审核工作流：包含运行自动化脚本（validate_notebook.py 捕获技术问题并生成无输出的 Markdown 以供审查）、扫描密钥，以及对照标准进行人工评估。
  • 评分体系：审核报告满分为 20 分，分为四个维度（叙述质量、代码质量、技术准确性、可操作性与理解度），每个维度各占 5 分。
  • 引言规范：必须以要解决的问题和交付价值作为切入点（严禁以技术机制开头），并明确列出 2-4 个终极/促成性学习目标（TLOs/ELOs）。
  • 环境与代码设置：强制要求使用 capture，pip install 的输出会打印到 Jupyter 标准输出中，导致页面极其嘈杂。
  • 技术合规风险：使用带日期的模型 ID（如 claude-sonnet-4-6-20250514）或已弃用的 API 模式不符合技术要求。
  • 审查产物残留：自动生成的 Markdown 审查文件若未被 .gitignore 忽略，可能会将审查产物（tmp/ 文件夹）错误提交到代码库中。

正文

来源文档：.claude/skills/cookbook-audit/SKILL.md

Cookbook 审核

指示

使用 style_guide.md 中的指南和评分标准审查请求的 Cookbook 笔记本。根据评分指南提供分数，并提供改进该 cookbook 的建议。

样式指南为以下内容提供了详细的模板和示例：

  • 以问题为中心的引言，包含终极学习目标 (TLOs) 和促成性学习目标 (ELOs)
  • 先决条件和设置模式
  • 核心内容结构
  • 与学习目标相呼应的结论

重要提示：在进行审核之前，请务必先阅读 style_guide.md。样式指南包含可供参考的标准模板以及正面/反面示例。

工作流

遵循以下步骤进行全面审核：

  1. 阅读样式指南：首先查阅 style_guide.md 以了解当前的最佳实践
  2. 确认笔记本：如果未提供路径，请向用户询问
  3. 运行自动检查：使用 python3 validate_notebook.py <path> 捕获技术问题并生成 Markdown
    • 脚本会自动运行 detect-secrets 以扫描硬编码的 API 密钥和凭据
    • 使用 scripts/detect-secrets/plugins.py 中定义的自定义模式
    • 根据 scripts/detect-secrets/.secrets.baseline 中的基线进行检查
  4. 审查 Markdown 输出：脚本会在 tmp/ 文件夹中生成一个 Markdown 文件以便于审查（与原始 .ipynb 相比可节省上下文）
    • tmp/ 文件夹已被 gitignore 忽略，以避免提交审查产物
    • Markdown 包含代码单元格，但排除了输出内容，使审查更清晰
  5. 人工审查：通读 Markdown 版本，对照样式指南和评分标准进行评估
  6. 各维度评分：客观地应用评分指南
  7. 生成报告：遵循下方的审核报告格式
  8. 提供具体示例：使用样式指南模板，通过行号引用展示具体的改进建议

审核报告格式

使用以下结构呈现你的审核报告：

执行摘要

  • 总分：X/20
  • 主要亮点（2-3 个要点）
  • 关键问题（2-3 个要点）

详细评分

1. 叙述质量：X/5

[带有具体示例的简短理由]

2. 代码质量：X/5

[带有具体示例的简短理由]

3. 技术准确性：X/5

[带有具体示例的简短理由]

4. 可操作性与理解度：X/5

[带有具体示例的简短理由]

具体建议

[按优先级排列的、可操作的改进列表，并引用具体章节]

示例与建议

[展示笔记本中的具体摘录，并提供具体的改进建议]

快速参考清单

使用此清单确保全面覆盖：

引言（参见 style_guide.md 第 1 节）

  • 以要解决的问题作为切入点（1-2 句话）
  • 解释其重要性（1-2 句话）
  • 以要点形式列出学习目标（2-4 个 TLOs/ELOs）
  • 侧重于交付的价值，而不是构建的机制
  • 可选：提及更广泛的应用（1 句话）

先决条件与设置（参见 style_guide.md 第 2 节）

  • 清晰列出所需知识
  • 列出所需工具（Python 版本、API 密钥）
  • 提及推荐的背景知识（如适用）
  • 使用 capture 抑制 pip install 日志
  • 没有冗长的调试输出
  • 展示相关的 API 响应
  • 仅在演示错误处理时显示堆栈跟踪

内容质量

  • 解释方法生效的原因
  • 讨论何时使用此方法
  • 提及局限性/注意事项
  • 提供可迁移的知识
  • 合适的模型选择

技术要求

  • 无需修改即可执行（API 密钥除外）
  • 使用未弃用的 API 模式
  • 使用有效的模型名称（claude-sonnet-4-6, claude-haiku-4-5, claude-opus-4-6）
  • 使用无日期的模型别名（绝不使用带日期的 ID，如 claude-sonnet-4-6-20250514）
  • 模型名称在笔记本顶部定义为常量
  • 包含依赖项规范
  • 分配到主类别
  • 具有相关标签

内容理念：行动 + 理解

Cookbook 主要以行动为导向，但战略性地融入了理解，并受 Diataxis 框架的启发。

核心原则：

  • 注重实用：向用户展示如何使用可运行的代码完成特定任务
  • 问题优先框架：以要解决的问题和交付的价值为导向，而不是机制
  • 构建者视角：从用户的角度编写，解决实际问题
  • 建立能动性：帮助用户理解方法为什么有效，而不仅仅是如何做
  • 可迁移知识：教授适用于特定示例之外的模式和原则
  • 批判性思维：鼓励用户质疑输出、认识局限性并做出明智的选择
  • 学习契约：预先声明学习目标，然后在结论中予以呼应

什么是优秀的 Cookbook

优秀的 Cookbook 不仅能帮助用户解决当前的问题，还能帮助他们理解解决方案背后的基本原理，鼓励他们认识到何时以及如何调整方法。用户将能够对 AI 系统设计做出更明智的决策，培养对模型输出的判断力，并建立可迁移到未来 AI 系统的技能。

Cookbook 不是什么

Cookbook 不是纯粹的教程：我们假设用户具备基本的技术技能和对 API 的熟悉程度。我们在 Cookbook 中明确说明先决条件，并引导用户前往 Academy 了解更多相关主题。 它们不是全面的解释：我们不教授 Transformer 架构或概率论。我们需要理解，我们的用户遵循我们的 Cookbook 是为了解决他们今天面临的问题。他们很忙，正处于学习或构建的过程中，并希望能够利用所学知识来解决他们的燃眉之急。 Cookbook 不是参考文档：我们不会详尽地记录每个参数，我们会根据需要在文档中链接到适当的资源。 Cookbook 不是简单的提示和技巧：我们不教授仅适用于当前模型生成的“黑客技巧”。我们不会过度承诺而兑现不足。 Cookbook 不是生产就绪的代码：它们展示的是用例和功能，而不是生产模式。不需要过度的错误处理。

样式指南

语气与基调

  • 具有教育意义并建立能动性
  • 专业但平易近人
  • 尊重用户的智力和时间
  • 使用第二人称（“你”）或第一人称复数（“我们”）——在同一个笔记本中保持一致

写作质量

  • 清晰、简洁的解释
  • 首选主动语态
  • 短段落（3-5 句话）
  • 避免使用未定义的行话
  • 使用标题分隔章节

代码展示

  • 始终在展示前解释：每个代码块之前都应有解释性文本
  • 运行后解释：在代码块执行后包含我们学到的内容
  • 注释解释为什么，而不是是什么：使用有意义的变量名
  • 使用常量：在顶部将 MODEL 定义为常量
  • 良好习惯：使用 dotenv.load_dotenv() 而不是 os.environ

输出处理

使用 capture

  • 使用 dotenv.load_dotenv() 而不是 os.environ
  • 在顶部定义 MODEL 常量

3. 主要内容（必填）

按逻辑步骤或阶段组织，每个部分包含：

  • 清晰的章节标题
  • 代码块之前的解释性文本（我们即将做什么）
  • 代码示例
  • 代码块之后的解释性文本（我们学到了什么）
  • 预期输出（相关时）
  • 可选：理解提示（为什么有效、何时使用、局限性）

4. 结论（推荐）

必须包含：

  • 回顾：与学习目标相呼应
  • 已完成的内容：关键点总结
  • 应用指南：如何将所学内容应用到用户的上下文中
  • 后续步骤：相关资源或可探索的想法

❌ 避免：通用总结（“我们已经演示了 SDK 如何实现……”） ✅ 推荐：可操作的指南（“考虑将其应用于 X……接下来，尝试 Y……”）

可选章节

  • 工作原理：底层机制的简要说明
  • 何时使用：合适的用例和上下文
  • 局限性与注意事项：警告、故障模式、约束条件
  • 故障排除：常见问题及解决方案
  • 变体：替代方法或扩展
  • 性能说明：优化注意事项
  • 延伸阅读：相关文档、论文或更深入解释的链接

常见的反面模式（需标记）

有关详细的正面/反面示例，请参阅 style_guide.md。注意以下问题：

引言反面模式

❌ 以机制开头：“我们将使用 Claude SDK 构建一个研究代理……” ❌ 功能堆砌：列出 SDK 方法或工具功能 ❌ 模糊的学习目标：“了解代理”或“理解 API” ✅ 采用问题优先框架，并设定具体、可操作的学习目标

设置反面模式

❌ 没有使用 `capture 以避免将 pip install 打印到 jupyter 的标准输出中（这可能会非常嘈杂）。

## 先决条件
 
在遵循本指南之前，请确保你具备以下条件：
 
* [必备知识/工具 - 没有这些，cookbook 将无法运行]
 
## 设置
 
[带有解释的逐步说明]
[首选 `dotenv` 而不是 `os.setenv`]

正面示例：

capture
%pip install -U anthropic scikit-learn numpy python-dotenv
~~~
 
**注意：** 确保你的 `.env` 文件包含：
ANTHROPIC_API_KEY=your_key_here
 
加载环境变量并配置客户端：
 
~~~python
import anthropic
from dotenv import load_dotenv
 
load_dotenv()
 
MODEL = "claude-sonnet-4-6"
 
client = anthropic.Anthropic()
~~~

3. 核心 Cookbook 章节

每个功能/概念都有自己的独立章节，通过演示而不是文档进行教学。

你可能希望包含架构概述、展示整个项目或逐步构建一个更大的项目。可以随意包含视觉效果以帮助分隔长篇内容。首选内联图像，而不是链接到外部内容。

避免功能堆砌、过度解释显而易见的内容以及没有上下文的代码。

代码块在引入之前应解释它们即将做什么，并在运行之后解释我们刚刚学到了什么。

4. 结论

结论应与学习目标相呼应，并引导读者阅读其他材料、链接或探索其他想法。

正面示例：

## 本指南内容回顾

在本指南中，我们探讨了如何构建可通过 SDK 以编程方式调用的 MCP 工具，从而实现可扩展且容错的工作流。我们涵盖了：

* 设置 MCP 服务器
* 一个未优化的示例
* 一个更好的示例
* 生产用例的注意事项 

你可以将这些经验进一步应用到实际项目中。考虑以下几点：

1. 通过 X 和 Y 添加额外的可观测性
2. 考虑此问题在大规模情况下的性能特征

等等……

反面示例：

这较少强调如何将读者学到的知识应用到他们特定的上下文中。

我们已经演示了 Claude Code SDK 如何使你能够构建复杂的多代理系统

相关文档

关联主题

关系图谱

反向链接