Back to Details

cookbook-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cookbook Audit

Cookbook 审核

Instructions

操作说明

Review the requested Cookbook notebook using the guidelines and rubrics in 
style_guide.md
. Provide a score based on scoring guidelines and recommendations on improving the cookbook.
The style guide provides detailed templates and examples for:
  • Problem-focused introductions with Terminal Learning Objectives (TLOs) and Enabling Learning Objectives (ELOs)
  • Prerequisites and setup patterns
  • Core content structure
  • Conclusions that map back to learning objectives
IMPORTANT: Always read 
style_guide.md
first before conducting an audit. The style guide contains the canonical templates and good/bad examples to reference.
使用
style_guide.md
中的指南和评估标准评审指定的Cookbook笔记本。根据评分标准给出分数，并提供改进该Cookbook的建议。
该风格指南提供了详细的模板和示例，涵盖：
  • 以问题为导向的介绍，包含终端学习目标（TLOs）和辅助学习目标（ELOs）
  • 前置条件和设置模式
  • 核心内容结构
  • 与学习目标呼应的结论
重要提示：在进行审核前，请务必先阅读
style_guide.md
。该风格指南包含了可参考的标准模板和优劣示例。

Workflow

工作流程

Follow these steps for a comprehensive audit:
  1. Read the style guide: First review 
    style_guide.md
    to understand current best practices
  2. Identify the notebook: Ask user for path if not provided
  3. Run automated checks: Use 
    python3 validate_notebook.py <path>
    to catch technical issues and generate markdown
    • The script automatically runs detect-secrets to scan for hardcoded API keys and credentials
    • Uses custom patterns defined in 
      scripts/detect-secrets/plugins.py
    • Checks against baseline at 
      scripts/detect-secrets/.secrets.baseline
  4. Review markdown output: The script generates a markdown file in the 
    tmp/
    folder for easier review (saves context vs raw .ipynb)
    • The tmp/ folder is gitignored to avoid committing review artifacts
    • Markdown includes code cells but excludes outputs for cleaner review
  5. Manual review: Read through the markdown version evaluating against style guide and rubric
  6. Score each dimension: Apply scoring guidelines objectively
  7. Generate report: Follow the audit report format below
  8. Provide specific examples: Show concrete improvements with line references using the style guide templates
遵循以下步骤进行全面审核：
  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/
      文件夹已被git忽略，避免提交评审 artifacts
    • Markdown包含代码单元格，但会排除输出内容，使评审更清晰
  5. 手动评审：通读markdown版本，对照风格指南和评估标准进行评估
  6. 各维度评分：客观应用评分标准
  7. 生成报告：遵循以下审核报告格式
  8. 提供具体示例：结合风格指南模板，给出带有行号引用的具体改进建议

Audit Report Format

审核报告格式

Present your audit using this structure:
请按照以下结构呈现审核结果：

Executive Summary

执行摘要

  • Overall Score: X/20
  • Key Strengths (2-3 bullet points)
  • Critical Issues (2-3 bullet points)
  • 总体评分：X/20
  • 主要优势（2-3个要点）
  • 关键问题（2-3个要点）

Detailed Scoring

详细评分

1. Narrative Quality: X/5

1. 叙述质量：X/5

[Brief justification with specific examples]
[带有具体示例的简短说明]

2. Code Quality: X/5

2. 代码质量：X/5

[Brief justification with specific examples]
[带有具体示例的简短说明]

3. Technical Accuracy: X/5

3. 技术准确性：X/5

[Brief justification with specific examples]
[带有具体示例的简短说明]

4. Actionability & Understanding: X/5

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

[Brief justification with specific examples]
[带有具体示例的简短说明]

Specific Recommendations

具体建议

[Prioritized, actionable list of improvements with references to specific sections]
[按优先级排列的可操作改进列表，包含对特定章节的引用]

Examples & Suggestions

示例与建议

[Show specific excerpts from the notebook with concrete suggestions for improvement]
[展示笔记本中的具体摘录，并给出明确的改进建议]

Quick Reference Checklist

快速参考检查表

Use this to ensure comprehensive coverage:
Introduction (See style_guide.md Section 1)
  • Hooks with the problem being solved (1-2 sentences)
  • Explains why it matters (1-2 sentences)
  • Lists learning objectives as bullet points (2-4 TLOs/ELOs)
  • Focuses on value delivered, not machinery built
  • Optional: mentions broader applications (1 sentence)
Prerequisites & Setup (See style_guide.md Section 2)
  • Lists required knowledge clearly
  • Lists required tools (Python version, API keys)
  • Mentions recommended background if applicable
  • Uses %%capture for pip install to suppress output
  • Uses dotenv.load_dotenv() not os.environ
  • Defines MODEL constant at top
  • Groups related installs in single command
Structure & Organization
  • Has logical section progression
  • Each section teaches through demonstration
  • Code blocks have explanatory text before them
  • Includes what we learned after code blocks
  • Uses headers to break up sections
Conclusion (See style_guide.md Section 4)
  • Maps back to learning objectives
  • Summarizes what was accomplished
  • Suggests ways to apply lessons to user's context
  • Points to next steps or related resources
Code Quality
  • All code blocks have explanatory text before them
  • No hardcoded API keys (automatically checked by detect-secrets)
  • Meaningful variable names
  • Comments explain "why" not "what"
  • Follows language best practices
  • Model name defined as constant at top of notebook
Output Management
  • pip install logs suppressed with %%capture
  • No verbose debug output
  • Shows relevant API responses
  • Stack traces only when demonstrating error handling
Content Quality
  • Explains why approaches work
  • Discusses when to use this approach
  • Mentions limitations/considerations
  • Provides transferable knowledge
  • Appropriate model selection
Technical Requirements
  • Executable without modification (except API keys)
  • Uses non-deprecated API patterns
  • Uses valid model names (claude-sonnet-4-5, claude-haiku-4-5, claude-opus-4-5)
  • Model name defined as constant at top of notebook
  • Includes dependency specifications
  • Assigned to primary category
  • Has relevant tags
使用此检查表确保全面覆盖：
介绍（参见style_guide.md第1节）
  • 包含要解决的问题的切入点（1-2句话）
  • 解释其重要性（1-2句话）
  • 以要点形式列出学习目标（2-4个TLOs/ELOs）
  • 聚焦于交付的价值，而非构建的机制
  • 可选：提及更广泛的应用场景（1句话）
前置条件与设置（参见style_guide.md第2节）
  • 清晰列出所需知识
  • 列出所需工具（Python版本、API密钥）
  • 如有需要，提及推荐的背景知识
  • 使用%%capture来抑制pip install的输出
  • 使用dotenv.load_dotenv()而非os.environ
  • 在顶部定义MODEL常量
  • 将相关的安装命令合并为单个命令
结构与组织
  • 具有逻辑化的章节递进
  • 每个章节通过演示进行教学
  • 代码块前有解释性文本
  • 代码块后包含我们学到的内容
  • 使用标题来划分章节
结论（参见style_guide.md第4节）
  • 与学习目标相呼应
  • 总结所完成的内容
  • 建议如何将所学应用到用户的实际场景中
  • 指出后续步骤或相关资源
代码质量
  • 所有代码块前都有解释性文本
  • 无硬编码的API密钥（由detect-secrets自动检查）
  • 有意义的变量名
  • 注释解释“为什么”而非“是什么”
  • 遵循语言最佳实践
  • 模型名称在笔记本顶部定义为常量
输出管理
  • 使用%%capture抑制pip install日志
  • 无冗长的调试输出
  • 展示相关的API响应
  • 仅在演示错误处理时显示堆栈跟踪
内容质量
  • 解释方法有效的原因
  • 讨论何时使用该方法
  • 提及局限性/注意事项
  • 提供可迁移的知识
  • 选择合适的模型
技术要求
  • 无需修改即可执行（除API密钥外）
  • 使用非过时的API模式
  • 使用有效的模型名称（claude-sonnet-4-5, claude-haiku-4-5, claude-opus-4-5）
  • 模型名称在笔记本顶部定义为常量
  • 包含依赖项说明
  • 分配到主类别
  • 有相关的标签

Content Philosophy: Action + Understanding

内容理念：行动 + 理解

Cookbooks are primarily action-oriented but strategically incorporate understanding and informed by Diataxis framework.
Core Principles:
  • Practical focus: Show users how to accomplish specific tasks with working code
  • Problem-first framing: Lead with the problem being solved and value delivered, not the machinery
  • Builder's perspective: Written from the user's point of view, solving real problems
  • Agency-building: Help users understand why approaches work, not just how
  • Transferable knowledge: Teach patterns and principles that apply beyond the specific example
  • Critical thinking: Encourage users to question outputs, recognize limitations, make informed choices
  • Learning contracts: State learning objectives upfront, then map back to them in conclusions
Cookbooks主要以行动为导向，但会战略性地融入理解内容，并遵循Diataxis框架。
核心原则：
  • 实用聚焦：向用户展示如何通过可运行的代码完成特定任务
  • 问题优先框架：从要解决的问题和交付的价值入手，而非技术机制
  • 构建者视角：从用户的角度出发，解决实际问题
  • 培养自主性：帮助用户理解方法有效的原因，而不仅仅是操作步骤
  • 可迁移知识：教授可应用于特定示例之外的模式和原则
  • 批判性思维：鼓励用户质疑输出、认识局限性、做出明智选择
  • 学习契约：提前说明学习目标，然后在结论中呼应

What Makes a Good Cookbook

优秀Cookbook的特质

A good cookbook doesn't just help users solve today's problem, it also helps them understand the underlying principles behind the solutions, encouraging them to recognize when and how to adapt approaches. Users will be able to make more informed decisions about AI system design, develop judgement about model outputs, and build skills that transfer to future AI systems.
优秀的Cookbook不仅能帮助用户解决当下的问题，还能帮助他们理解解决方案背后的原则，鼓励他们识别何时以及如何调整方法。用户将能够对AI系统设计做出更明智的决策，培养对模型输出的判断力，并构建可迁移到未来AI系统的技能。

What Cookbooks Are NOT

Cookbook 不是什么

Cookbooks are not pure tutorials: We assume users have basic technical skills and API familiarity. We clearly state prerequisites in our cookbooks, and direct users to the Academy to learn more on topics. They are not comprehensive explanations: We don't teach transformer architecture or probability theory. We need to understand that our users are following our cookbooks to solve problems they are facing today. They are busy, in the midst of learning or building, and want to be able to use what they learn to solve their immediate needs. Cookbooks are not reference docs: We don't exhaustively document every parameter, we link to appropriate resources in our documentation as needed. Cookbooks are not simple tips and tricks: We don't teach "hacks" that only work for the current model generation. We don't over-promise and under-deliver. Cookbooks are not production-ready code: They showcase use cases and capabilities, not production patterns. Excessive error handling is not required.
Cookbook不是纯教程：我们假设用户具备基本的技术技能和API使用经验。我们会在Cookbook中明确列出前置条件，并引导用户到Academy学习更多相关主题。 它们不是全面的解释：我们不教授Transformer架构或概率论。我们需要理解，用户遵循我们的Cookbook是为了解决他们当前面临的问题。他们时间有限，正在学习或构建过程中，希望能将所学用于解决即时需求。 Cookbook不是参考文档：我们不会详尽记录每个参数，而是在需要时链接到我们文档中的相应资源。 Cookbook不是简单的技巧和窍门：我们不教授仅适用于当前模型世代的“捷径”。我们不会夸大承诺却交付不足。 Cookbook不是生产就绪代码：它们展示用例和功能，而非生产模式。不需要过多的错误处理。

Style Guidelines

风格指南

Voice & Tone

语气与语调

  • Educational and agency-building
  • Professional but approachable
  • Respectful of user intelligence and time
  • Either second person ("you") or first person plural ("we") - be consistent within a notebook
  • 具有教育性且培养自主性
  • 专业但亲切
  • 尊重用户的智慧和时间
  • 使用第二人称（“你”）或第一人称复数（“我们”）——在一个笔记本中保持一致

Writing Quality

写作质量

  • Clear, concise explanations
  • Active voice preferred
  • Short paragraphs (3-5 sentences)
  • Avoid jargon without definition
  • Use headers to break up sections
  • 清晰、简洁的解释
  • 优先使用主动语态
  • 短段落（3-5句话）
  • 避免未定义的行话
  • 使用标题划分章节

Code Presentation

代码呈现

  • Always explain before showing: Every code block should be preceded by explanatory text
  • Explain after running: Include what we learned after code blocks execute
  • Comments explain why, not what: Use meaningful variable names
  • Use constants: Define MODEL as a constant at the top
  • Good habits: Use 
    dotenv.load_dotenv()
    instead of 
    os.environ
  • 始终先解释再展示：每个代码块前都应有解释性文本
  • 运行后解释：代码块执行后包含我们学到的内容
  • 注释解释“为什么”而非“是什么”：使用有意义的变量名
  • 使用常量：在顶部将MODEL定义为常量
  • 良好习惯：使用
    dotenv.load_dotenv()
    而非
    os.environ

Output Handling

输出处理

Remove extraneous output with %%capture:
  • pip install logs (always suppress these)
  • Verbose debug statements
  • Lengthy stack traces (unless demonstrating error handling)
Show relevant output:
  • API responses that demonstrate functionality
  • Examples of successful execution
使用%%capture移除无关输出：
  • pip install日志（始终抑制这些输出）
  • 冗长的调试语句
  • 冗长的堆栈跟踪（除非在演示错误处理）
展示相关输出：
  • 展示功能的API响应
  • 成功执行的示例

Structural Requirements

结构要求

See style_guide.md for detailed templates and examples
详细模板和示例请参见style_guide.md

1. Introduction (Required)

1. 介绍（必填）

Must include:
  • Problem hook (1-2 sentences): What problem are we solving?
  • Why it matters (1-2 sentences): Why is this important?
  • Learning objectives (2-4 bullet points): "By the end of this cookbook, you'll be able to..."
    • Use action verbs (Build, Implement, Deploy, etc.)
    • Be specific about capabilities
    • Include context/constraints
  • Optional: Broader applications (1 sentence)
❌ Avoid: Leading with machinery ("We will build a research agent...") ✅ Do: Lead with problem/value ("Your team spends hours triaging CI failures...")
必须包含：
  • 问题切入点（1-2句话）：我们要解决什么问题？
  • 重要性（1-2句话）：这为什么重要？
  • 学习目标（2-4个要点）：“完成本Cookbook后，你将能够……”
    • 使用动作动词（构建、实现、部署等）
    • 明确说明能力
    • 包含上下文/约束
  • 可选：更广泛的应用场景（1句话）
❌ 避免：从技术机制入手（“我们将使用Claude SDK构建一个研究agent……”） ✅ 推荐：从问题/价值入手（“你的团队花费数小时排查CI故障……”）

2. Prerequisites & Setup (Required)

2. 前置条件与设置（必填）

Must include:
  • Required Knowledge: Technical skills needed
  • Required Tools: Python version, API keys with links
  • Recommended: Optional background that helps
  • Setup: Step-by-step with explanations
    • Use 
      %%capture
      for pip installs
    • Use 
      dotenv.load_dotenv()
      not 
      os.environ
    • Define 
      MODEL
      constant at top
必须包含：
  • 所需知识：必备的技术技能
  • 所需工具：Python版本、带链接的API密钥
  • 推荐：有帮助的可选背景知识
  • 设置：带解释的分步说明
    • 对pip安装使用
      %%capture
    • 使用
      dotenv.load_dotenv()
      而非
      os.environ
    • 在顶部定义
      MODEL
      常量

3. Main Content (Required)

3. 主要内容（必填）

Organized by logical steps or phases, each with:
  • Clear section headers
  • Explanatory text before code blocks (what we're about to do)
  • Code examples
  • Explanatory text after code blocks (what we learned)
  • Expected outputs (where relevant)
  • Optional: Understanding callouts (why it works, when to use, limitations)
按逻辑步骤或阶段组织，每个阶段包含：
  • 清晰的章节标题
  • 代码块前的解释性文本（我们即将做什么）
  • 代码示例
  • 代码块后的解释性文本（我们学到了什么）
  • 预期输出（如适用）
  • 可选：理解提示（为什么有效、何时使用、局限性）

4. Conclusion (Recommended)

4. 结论（推荐）

Must include:
  • Recap: Map back to learning objectives
  • What was accomplished: Summary of key points
  • Application guidance: How to apply lessons to user's context
  • Next steps: Related resources or ideas to pursue
❌ Avoid: Generic summaries ("We've demonstrated how the SDK enables...") ✅ Do: Actionable guidance ("Consider applying this to X... Next, try Y...")
必须包含：
  • 回顾：与学习目标相呼应
  • 完成内容：关键点总结
  • 应用指导：如何将所学应用到用户的实际场景中
  • 后续步骤：相关资源或可探索的想法
❌ 避免：通用总结（“我们演示了SDK如何实现……”） ✅ 推荐：可操作的指导（“考虑将此应用于X……接下来，尝试Y……”）

Optional Sections

可选章节

  • How It Works: Brief explanation of underlying mechanism
  • When to Use This: Appropriate use cases and contexts
  • Limitations & Considerations: Caveats, failure modes, constraints
  • Troubleshooting: Common issues and solutions
  • Variations: Alternative approaches or extensions
  • Performance Notes: Optimization considerations
  • Further Reading: Links to relevant docs, papers, or deeper explanations
  • 工作原理：对底层机制的简要解释
  • 何时使用此方法：适用的用例和场景
  • 局限性与注意事项：警告、失败模式、约束
  • 故障排除：常见问题与解决方案
  • 变体：替代方法或扩展
  • 性能说明：优化注意事项
  • 进一步阅读：相关文档、论文或深入解释的链接

Common Anti-Patterns to Flag

需要标记的常见反模式

Refer to style_guide.md for detailed good/bad examples. Watch for these issues:
请参见style_guide.md中的详细优劣示例。注意以下问题：

Introduction Anti-Patterns

介绍反模式

❌ Leading with machinery: "We will build a research agent using the Claude SDK..." ❌ Feature dumps: Listing SDK methods or tool capabilities ❌ Vague learning objectives: "Learn about agents" or "Understand the API" ✅ Problem-first framing with specific, actionable learning objectives
❌ 从技术机制入手：“我们将使用Claude SDK构建一个研究agent……” ❌ 功能罗列：列出SDK方法或工具功能 ❌ 模糊的学习目标：“了解agents”或“理解API” ✅ 以问题为导向的框架，包含具体、可操作的学习目标

Setup Anti-Patterns

设置反模式

❌ Noisy pip install output without 
%%capture
❌ Multiple separate pip install commands ❌ Using 
os.environ["API_KEY"] = "your_key"
instead of dotenv ❌ Hardcoding model names throughout instead of using a MODEL constant ✅ Clean setup with grouped installs, dotenv, and constants
❌ 未使用
%%capture
导致pip install输出杂乱 ❌ 多个独立的pip install命令 ❌ 使用
os.environ["API_KEY"] = "your_key"
而非dotenv ❌ 在整个笔记本中硬编码模型名称，而非使用MODEL常量 ✅ 整洁的设置，包含合并的安装命令、dotenv和常量

Code Presentation Anti-Patterns

代码呈现反模式

❌ Code blocks without explanatory text before them ❌ No explanation of what we learned after running code ❌ Comments that explain "what" the code does (code should be self-documenting) ❌ Over-explaining obvious code ✅ Context before code, insights after code, comments explain "why"
❌ 代码块前无解释性文本 ❌ 代码运行后无“我们学到了什么”的解释 ❌ 注释解释“是什么”而非“为什么”（代码应自文档化） ❌ 过度解释显而易见的代码 ✅ 代码前有上下文，代码后有见解，注释解释“为什么”

Conclusion Anti-Patterns

结论反模式

❌ Generic summaries: "We've demonstrated how the SDK enables..." ❌ Simply restating what the notebook did without guidance ❌ Not mapping back to the stated learning objectives ✅ Actionable guidance on applying lessons to user's specific context
❌ 通用总结：“我们演示了SDK如何实现……” ❌ 仅重述笔记本内容而无指导 ❌ 未与所述学习目标呼应 ✅ 关于如何将所学应用到用户特定场景的可操作指导",