⚡

食谱笔记本审计指南 cookbook-audit

本指南详细说明了如何对Anthropic食谱笔记本进行系统化审计，包括工作流程、评分标准、风格规范和最佳实践。适用于技术文档审查、代码质量评估、AI应用开发规范检查，帮助团队确保技术教程的质量和一致性。关键词：技术文档审计、代码审查、AI教程规范、笔记本质量评估、开发指南检查

AI应用 0 次安装 0 次浏览 更新于 3/1/2026

名称: 食谱审计 描述: 基于评分标准对Anthropic食谱笔记本进行审计。每当需要笔记本审查或审计时使用。

食谱审计

说明

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

风格指南提供了详细的模板和示例，涵盖：

  • 以问题为中心的引言，包含终端学习目标（TLOs）和促成学习目标（ELOs）
  • 先决条件和设置模式
  • 核心内容结构
  • 映射回学习目标的结论

重要提示：在进行审计之前，务必先阅读style_guide.md。风格指南包含规范的模板和可供参考的好/坏示例。

工作流程

按照以下步骤进行全面审计：

  1. 阅读风格指南：首先查看style_guide.md以了解当前最佳实践
  2. 识别笔记本：如果未提供路径，请向用户询问
  3. 运行自动检查：使用python3 validate_notebook.py <路径>捕获技术问题并生成Markdown
    • 脚本自动运行detect-secrets以扫描硬编码的API密钥和凭据
    • 使用scripts/detect-secrets/plugins.py中定义的自定义模式
    • 根据scripts/detect-secrets/.secrets.baseline的基线进行检查
  4. 查看Markdown输出：脚本在tmp/文件夹中生成Markdown文件以便于审查（与原始.ipynb相比节省上下文）
    • tmp/文件夹被git忽略以避免提交审查工件
    • 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安装以抑制输出
  • [ ] 使用dotenv.load_dotenv()而非os.environ
  • [ ] 在顶部定义MODEL常量
  • [ ] 将相关安装分组在单个命令中

结构与组织

  • [ ] 具有逻辑性的章节进展
  • [ ] 每个章节通过演示进行教学
  • [ ] 代码块前有解释性文本
  • [ ] 代码块后包含所学内容
  • [ ] 使用标题分隔章节

结论（参见style_guide.md第4节）

  • [ ] 映射回学习目标
  • [ ] 总结完成的内容
  • [ ] 建议如何将经验教训应用于用户场景
  • [ ] 指向后续步骤或相关资源

代码质量

  • [ ] 所有代码块前都有解释性文本
  • [ ] 无硬编码API密钥（由detect-secrets自动检查）
  • [ ] 有意义的变量名
  • [ ] 注释解释“为什么”而非“是什么”
  • [ ] 遵循语言最佳实践
  • [ ] 模型名称在笔记本顶部定义为常量

输出管理

  • [ ] 使用%%capture抑制pip安装日志
  • [ ] 无冗长的调试输出
  • [ ] 显示相关的API响应
  • [ ] 仅在演示错误处理时显示堆栈跟踪

内容质量

  • [ ] 解释方法为何有效
  • [ ] 讨论何时使用此方法
  • [ ] 提及限制/注意事项
  • [ ] 提供可迁移的知识
  • [ ] 适当的模型选择

技术要求

  • [ ] 无需修改即可执行（API密钥除外）
  • [ ] 使用非弃用的API模式
  • [ ] 使用有效的模型名称（claude-sonnet-4-5、claude-haiku-4-5、claude-opus-4-5）
  • [ ] 模型名称在笔记本顶部定义为常量
  • [ ] 包含依赖项规范
  • [ ] 分配到主要类别
  • [ ] 具有相关标签

内容哲学：行动+理解

食谱主要是面向行动的，但战略性地融入了理解，并受到Diataxis框架的启发。

核心原则：

  • 实用导向：向用户展示如何使用工作代码完成特定任务
  • 问题优先框架：以解决的问题和交付的价值为先导，而非机制
  • 构建者视角：从用户角度出发，解决实际问题
  • 能力建设：帮助用户理解方法为何有效，而不仅仅是方法
  • 可迁移知识：教授适用于特定示例之外的模式和原则
  • 批判性思维：鼓励用户质疑输出、认识局限、做出明智选择
  • 学习契约：预先说明学习目标，然后在结论中映射回这些目标

优秀食谱的特点

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

食谱不是

食谱不是纯教程：我们假设用户具备基本技术技能和API熟悉度。我们在食谱中明确说明先决条件，并引导用户前往Academy了解更多主题。 它们不是全面的解释：我们不教授Transformer架构或概率论。我们需要理解，用户遵循我们的食谱是为了解决他们今天面临的问题。他们很忙，正在学习或构建中，希望能够使用所学知识解决他们的即时需求。 食谱不是参考文档：我们不详尽记录每个参数，我们根据需要链接到文档中的适当资源。 食谱不是简单的技巧和窍门：我们不教授仅适用于当前模型代的“技巧”。我们不夸大其词，也不交付不足。 食谱不是生产就绪的代码：它们展示用例和能力，而非生产模式。不需要过多的错误处理。

风格指南

语气与语调

  • 教育性和能力建设性
  • 专业但平易近人
  • 尊重用户的智力和时间
  • 第二人称（“你”）或第一人称复数（“我们”）——在笔记本内保持一致

写作质量

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

代码呈现

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

输出处理

使用%%capture移除无关输出：

  • pip安装日志（始终抑制这些）
  • 冗长的调试语句
  • 冗长的堆栈跟踪（除非演示错误处理）

显示相关输出：

  • 展示功能的API响应
  • 成功执行的示例

结构要求

参见style_guide.md获取详细模板和示例

1. 引言（必需）

必须包括：

  • 问题切入点（1-2句话）：我们正在解决什么问题？
  • 其重要性（1-2句话）：为什么这很重要？
  • 学习目标（2-4个要点）：“在本食谱结束时，您将能够…”
    • 使用动作动词（构建、实现、部署等）
    • 具体说明能力
    • 包含上下文/约束
  • 可选：更广泛的应用（1句话）

❌ 避免：以机制为先导（“我们将使用Claude SDK构建一个研究代理…”） ✅ 应做：以问题/价值为先导（“您的团队花费数小时处理CI故障…”）

2. 先决条件与设置（必需）

必须包括：

  • 所需知识：所需技术技能
  • 所需工具：Python版本、API密钥及链接
  • 推荐：有帮助的可选背景
  • 设置：分步说明
    • 使用%%capture进行pip安装
    • 使用dotenv.load_dotenv()而非os.environ
    • 在顶部定义MODEL常量

3. 主要内容（必需）

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

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

4. 结论（推荐）

必须包括：

  • 回顾：映射回学习目标
  • 完成的内容：关键点总结
  • 应用指导：如何将经验教训应用于用户场景
  • 后续步骤：相关资源或可探索的想法

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

可选章节

  • 工作原理：底层机制的简要解释
  • 何时使用此方法：适当的用例和场景
  • 限制与注意事项：注意事项、失败模式、约束
  • 故障排除：常见问题及解决方案
  • 变体：替代方法或扩展
  • 性能说明：优化注意事项
  • 进一步阅读：相关文档、论文或更深入解释的链接

常见反模式标记

参考style_guide.md获取详细的好/坏示例。注意以下问题：

引言反模式

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

设置反模式

❌ 无%%capture的嘈杂pip安装输出 ❌ 多个独立的pip安装命令 ❌ 使用os.environ["API_KEY"] = "your_key"而非dotenv ❌ 在整个笔记本中硬编码模型名称而非使用MODEL常量 ✅ 干净设置，包含分组安装、dotenv和常量

代码呈现反模式

❌ 代码块前无解释性文本 ❌ 运行代码后无解释 ❌ 解释代码“做什么”的注释（代码应自文档化） ❌ 过度解释明显的代码 ✅ 代码前提供上下文，代码后提供见解，注释解释“为什么”

结论反模式

❌ 通用总结：“我们已经演示了SDK如何实现…” ❌ 仅重述笔记本内容而无指导 ❌ 未映射回所述学习目标 ✅ 关于如何将经验教训应用于用户具体场景的可操作指导