基于 Rubric 的 Anthropic Cookbook Notebook 审计技能全解：工作流、评分体系与自动化检查

基于 Rubric 的 Anthropic Cookbook Notebook 审计技能全解工作流、评分体系与自动化检查【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks本篇文章围绕 claude-cookbooks 仓库中用于 Notebook 质量审计的 Claude Code 技能Skill展开主体文档为 .claude/skills/cookbook-audit/SKILL.md。该技能用于按评分标准审计 Anthropic Cookbook 笔记本是仓库在 Notebook 提交审查、PR 评审与 CI 质量把关环节所使用的核心方法论。读完本文你将掌握 cookbook-audit 技能的八步审计工作流、四维 20 分评分体系、结构化审计报告格式以及背后validate_notebook.py自动化检查与 detect-secrets 密钥扫描的实现原理并可直接在自己的 Notebook 质量保障流程中复用它定义的检查清单与反模式清单。一、技能定位与上下文cookbook-audit 是一个标准 Claude Code Skill 定义。其 frontmatter 声明了元信息见 SKILL.md--- name: cookbook-audit description: Audit an Anthropic Cookbook notebook based on a rubric. Use whenever a notebook review or audit is requested. ---它服务于一个明确场景当 Claude Code 被要求审查某个 Cookbook 笔记本时自动加载该技能按既定评分标准对 Notebook 打分并给出改进建议。该技能并非孤立存在而是与仓库中一组审查命令联动.claude/commands/notebook-review.md加载本技能对 Jupyter Notebook 与 Python 脚本做全面评审并以「✅ 亮点 / ⚠️ 改进建议 / ❌ 必须修复的关键问题」三段式输出.claude/commands/review-pr.md在 PR 评审中通过子代理做代码审查其中针对 Notebook 特别约定引用代码片段而非单元格编号CONTRIBUTING.md说明仓库内置的/notebook-review、/model-check、/link-review命令在 Claude Code 与 CI 中共享同一套校验逻辑。技能的审计依据是style_guide.md风格指南含规范模板与好坏示例和一套评分维度技术层面则依赖同目录下的 validate_notebook.py 做自动化预检。二、八步审计工作流SKILL.md 将一次完整审计定义为以下步骤见 SKILL.md先读风格指南审计前必须先阅读style_guide.md其中包含规范模板及好坏示例是审计的标准答案定位目标 Notebook如用户未给出路径先询问运行自动化检查执行python3 validate_notebook.py path捕获技术性问题并生成 Markdown审阅 Markdown 输出脚本把.ipynb转换为更易读的 Markdown只含代码单元格、剔除输出节省上下文生成物放在tmp/目录该目录已 gitignore避免提交审查副产物人工评审对照风格指南与评分标准通读 Markdown 版本逐维评分按评分指南客观打分生成报告遵循下述审计报告格式给出具体示例引用风格指南模板附行号给出可落地的改进样例。值得注意的是自动化步骤 4 的实现细节validate_notebook.py的convert_to_markdown()方法并非直接用nbconvert而是通过uv run --with nbconvert jupyter nbconvert --to markdown临时拉取依赖并显式携带--no-prompt去除输入/输出提示符与--TemplateExporter.exclude_outputTrue剔除输出从而得到适合大模型低成本审阅的中间产物见 validate_notebook.py。三、审计报告格式四维 20 分制技能规定报告必须采用固定结构SKILL.md目的是让分数跨 Notebook 可比较Executive Summary总览给出 Overall Score满分 20并各列 23 条关键优势与关键问题Detailed Scoring分维评分每个维度 5 分需给出具体佐证Narrative Quality叙事质量——开篇是否围绕问题展开、行文是否清晰、学习目标是否明确Code Quality代码质量——是否先解释后展示、有无硬编码密钥、变量命名是否有意义、注释是否解释为什么Technical Accuracy技术准确性——模型名是否有效且非过期、API 模式是否未弃用Actionability Understanding可操作性——读者能否照做、是否理解原理而非机械复制Specific Recommendations按优先级排序的可执行改进项附具体小节引用Examples Suggestions摘录原 Notebook 片段并给出对照的改写建议。该评分维度的取舍可在仓库实际内容中找到印证例如仓库的 README.md、capabilities/classification、patterns/agents下的guide.ipynb都采用了问题导向引言 前置条件/Setup 分节演示 结论回扣学习目标的写法正对应评分维度所奖励的行为。四、快速参考检查清单把抽象标准翻译成可勾选项技能将评分维度细化为一套可勾选的检查清单SKILL.md覆盖八大板块。审计时应逐项核对板块核心检查点Introduction1~2 句问题钩子1~2 句为何重要2~4 条学习目标TLO/ELO聚焦交付价值而非机制可选 1 句更广应用Prerequisites Setup明确必需知识与工具Python 版本、API Keypip install用%%capture抑制输出用dotenv.load_dotenv()而非os.environ模型名在文件顶部定义为常量MODEL相关安装合并为单条命令Structure Organization逻辑递进每节通过演示教学代码块前有解释文字代码后有我们学到了什么用小节标题切分Conclusion回扣学习目标总结成果建议如何迁移到读者场景给出下一步或相关资源Code Quality代码块前必有解释无硬编码密钥由 detect-secrets 自动检查变量名有意义注释解释 why 而非 what顶部定义模型常量Output Management%%capture抑制安装日志无冗长 debug 输出展示能说明功能的 API 响应堆栈信息仅在演示错误处理时出现Content Quality解释为何可行讨论适用时机提及局限提供可迁移知识模型选型恰当Technical Requirements除 API Key 外可直接执行使用未弃用 API模型名有效claude-sonnet-4-6、claude-haiku-4-5、claude-opus-4-6绝不使用带日期的模型 ID如claude-sonnet-4-6-20250514包含依赖规格说明归入主分类并打上相关标签其中模型名常量 禁用日期化 ID这一要求在validate_notebook.py中有直接对应的正则与判定逻辑check_model_constant会检查前 5 个代码单元格内是否存在MODEL claude-...形式定义若全文出现claude-引用却无常量定义则告警check_deprecated_patterns用[\]claude-\w-[\d.]-\d{8}[\]捕获带日期的 ID同时跳过 Amazon Bedrock 场景下必须带日期的anthropic.claude-*ID并维护一份有效模型与已弃用模型映射表如claude-opus-4-1→claude-opus-4-6做告警见 validate_notebook.py。五、自动化检查引擎实现解析validate_notebook.py是审计工作流第 3 步的技术支柱。它定义一个NotebookValidator类程序入口main()接收单个参数notebook.ipynb并以退出码传达结论0 表示无问题1 表示存在必须修复的关键问题见 validate_notebook.py。一次运行会顺序执行 9 类检查run_all_checks产出分级的 CRITICAL ISSUES (must fix) 与 WARNINGS (should review) 报告检查方法职责典型触发check_hardcoded_secrets调用 detect-secrets 扫描硬编码密钥出现sk-ant-*等凭据check_introduction首个单元格须为 markdown 且长度 ≥200 字符首格是代码格、无前置条件说明check_pip_install_outputpip install是否被%%capture/%pip抑制裸pip installcheck_code_explanations相邻两个代码格间缺少 markdown 解释连续代码格check_verbose_output是否有 debug 打印、verboseTrueprint(debug...)check_variable_names是否使用x、temp1、result1等无意义命名见方法内正则check_model_constant顶部是否定义MODEL常量引用模型却无常量check_deprecated_patterns模型有效性、弃用模式、日期化 ID见上文说明check_conclusion末尾是否有像样的结论小节末段 markdown 过短或缺失密钥扫描的协作链路check_hardcoded_secrets的扫描命令会先沿目录向上寻找项目根含.git的目录随后依次探测两个 baseline 位置validate_notebook.pyproject_root/scripts/detect-secrets/.secrets.baselineproject_root/.secrets.baseline找到 baseline 后用uvx --from detect-secrets detect-secrets-hook --baseline baseline --plugin plugins.py --verbose执行扫描若检出 Location: / Secret Type: 行则记为关键问题并打印完整输出。万一 detect-secrets 不可用则回退到_check_hardcoded_secrets_fallback的内置正则sk-ant-[a-zA-Z0-9-]Anthropic Key、sk-[a-zA-Z0-9]{32,}OpenAI Key以及(secret|password|token)\s*\s*[][^]{20,}[]等见 validate_notebook.py。仓库自带的 scripts/detect-secrets/plugins.py 正是被--plugin参数引用的自定义插件。它定义AnthropicSecretsDetector(BasePlugin)通过 denylist 正则数组识别 Notebook 中的凭据例如 Anthropic API keysk-ant-api03-[A-Za-z0-9_-]{95,}、普通sk-/pa-开头的超长 Key以及形如api_key...、apikey...的通用赋值模式。这就解释了 SKILL.md 中自动运行 detect-secrets、使用 plugins.py 自定义模式、对照 baseline 检查三句话背后的完整执行链。六、内容理念Action Understanding 与 Cookbook 边界六、内容理念Action Understanding技能反复强调Cookbook 以行动为主但要有策略地融入理解并受 Diataxis 框架说明、任务、概念、理解四种框架启发。核心原则包括SKILL.md实用导向展示如何用可运行代码完成具体任务问题优先先讲要解决的问题与交付的价值而非要构建的机制构建者视角站在用户角度解决真实问题能力构建Agency-building帮助用户理解为什么这样可行而不只怎么做可迁移知识传授能超出当前示例的模式与原理批判性思维鼓励用户质疑输出、识别局限、做出明智选择学习契约开篇即明确学习目标结论再回扣这些目标。Cookbook 是什么、不是什么技能用NOT 清单划定了边界SKILL.md这也是审计判断是否越界的依据不是纯教程——假定读者具备基础技术能力与 API 熟悉度前置条件需明确写出不是全面的原理讲解——不教 Transformer 架构或概率论不是参考文档——不逐一穷举参数而是按需链接官方文档不是小技巧合集——不教只对当前模型代际有效的hack不夸大承诺不是生产级代码——用于展示用例与能力不要求过度错误处理。写作风格规范审计还需检查行文细节SKILL.md声音上采用第二人称 you 或第一人称复数 we 且全文保持一致偏好主动语态段落短小35 句术语需定义代码展示前必解释、运行后必总结注释解释 why 而非 what使用常量与dotenv.load_dotenv()培养好习惯。七、结构要求与常见反模式四个必备结构板块Introduction必填含问题钩子1~2 句、为何重要1~2 句、2~4 条学习目标以 Build/Implement/Deploy 等动作动词开头、具体说明能力与约束、可选的应用延伸。反例是以机制开头We will build a research agent...正例是以问题开头Your team spends hours triaging CI failures...SKILL.md。Prerequisites Setup必填知识/工具/推荐背景三栏 分步 Setup含%%capture、dotenv、MODEL常量约定。Main Content必填按逻辑步骤分节每节遵守代码前解释——代码——代码后总结学到了什么必要时加为什么可行/何时使用/局限等理解性提示。Conclusion推荐回扣学习目标、总结成果、给出可落地的应用指引与下一步反对通用式总结主张具体引导Consider applying this to X... Next, try Y...。可选的扩展小节包括 How It Works、When to Use This、Limitations Considerations、Troubleshooting、Variations、Performance Notes、Further Reading。四类高频反模式技能给出审计时需要重点标记的反模式清单SKILL.md类别❌ 反模式✅ 期望做法引言以机制开场、堆砌 SDK 功能清单、Learn about agents这类空洞目标问题优先 具体可执行的学习目标环境搭建无%%capture的 noisy pip 输出、拆成多条独立 pip 命令、用os.environ写死 Key、通篇硬编码模型名合并安装、dotenv、顶部MODEL常量代码呈现代码块前无解释、跑完不总结、注释复述代码本身、过度解释显而易见的内容上下文前置、运行后给洞察、注释只解释 why结论空泛总结Weve demonstrated...、无迁移指引、不回扣学习目标结合读者场景给出可操作指引style_guide.md 中为每类反模式都配了 Good/Bad 对照样例。例如 Setup 的 Good 示例是%%capture%pip install -U anthropic scikit-learn voyageai单条安装、dotenv.load_dotenv()、顶部定义MODEL claude-haiku-4-5再创建client anthropic.Anthropic()Bad 示例则是五条裸%pip install连发、用os.environ[ANTHROPIC_API_KEY] ...写死密钥见 style_guide.md。八、在真实审查流程中落地本技能将上述标准串联到日常工作中完整的审计闭环大致是通过/notebook-review skills/my-notebook.ipynb或直接请求触发 cookbook-audit 技能对应 .claude/commands/notebook-review.md技能先读 style_guide.md再运行python3 .claude/skills/cookbook-audit/validate_notebook.py notebook.ipynb依据脚本返回的 CRITICAL/WARNING 清单结合人工审阅得出的四维分数按Executive Summary → Detailed Scoring → Recommendations → Examples格式产出报告在 PR 场景下把评审作为gh pr review或gh pr comment发布参考 review-pr.md 的分步流程。该技能与仓库的贡献质量体系相互印证CONTRIBUTING.md 中NB 最佳实践环境变量存取 API Key、使用claude-haiku-4-5等当前模型别名、一 Notebook 一概念、自顶向下可执行与技能检查清单逐条对应说明这套 rubrics 同时也是 contributors 自查与 CI 守护共同遵循的标准。对于希望自建 Notebook 质量门禁的团队cookbook-audit 提供的可执行检查清单 自动化验证脚本 分级报告三件套是可直接借鉴的成熟范式——把含糊的写得更好翻译成 20 分制的客观量化。【免费下载链接】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），仅供参考