Anthropic Cookbook 里躺着上百个 Jupyter notebook，教你怎么用 Claude 做检索，搭 agent，写评测。这些 notebook 大多出自不同工程师之手，质量像开盲盒。有的开头三句话就把问题讲透，有的上来先堆五个 SDK 方法名，读的人还没进入状态就跑了。AI 教学内容的通胀比我们想象的严重，同一件事十个人写出来是十个样。问题不在于没人写，而在于没人敢删。一个示例塞进五种用法、三段背景、两张无关截图，作者觉得信息量大，读者只觉得累。cookbook-audit 的存在，本质上是在替读者维权。
我一直在想一个问题：技术教学类的示例，到底有没有客观标准能判断”写得好不好”。以前靠 reviewer 凭感觉，今天心情好就多挑两个刺，明天赶进度就直接 merge。cookbook-audit 这个技能把这件事变成了可复用的流程，让标准不再依赖某个人当天的心情。
它本质上是一套”审计工作流”，针对一个 Cookbook notebook 做结构化体检。你给它一个 .ipynb 路径，它先读一份详细的 style_guide，再跑自动检查脚本，最后按四维 rubric 打分并给出带行号的改进建议。它不帮你写 notebook，它帮你说清楚”为什么这个 notebook 不行”。
如果你团队也在维护下面这类内容，这个技能的价值就凸显出来了：
-
教学示例库（Cookbook 式的实操 notebook） -
内部 how-to 文档与 onboarding 教程 -
面向开发者的实操技术博客或技能文档
下面我把它的工作流、内部架构和设计哲学拆开讲。
工作流拆解
cookbook-audit 的 SKILL.md 定义了 8 个步骤，从读规范到出报告一条龙。我第一次看的时候觉得步骤偏多，实际跑一遍才发现每一步都在压缩 reviewer 的认知负担，把最容易遗漏的环节变成了强制动作。
第一步永远是读 style_guide.md。这条规则被标成了 IMPORTANT，因为它就是整个审计的”真相源”。style_guide 里塞满了好例子和坏例子对照，比如”开头要讲问题不要讲机器”这种原则，都有 concrete 的反例可参照，reviewer 不用自己凭空判断。
第二步定位 notebook，如果用户没给路径就主动问。第三步是技术含量最高的一步：跑自动检查脚本。这个脚本不只是 lint，它会调用 detect-secrets 扫描硬编码的 API key，还带了一套自定义的正则插件，对照项目里的 .secrets.baseline 基线。
别小看这一步。硬编码密钥是 Cookbook 仓库最高频的事故源，一个 PR 把真实 key 推上去，后续轮换和排查的成本远超写示例本身。让脚本在评审前就拦下来，等于把风险堵在门口。
# 自动检查：扫描密钥 + 生成精简 markdown 供人工评审
python3 validate_notebook.py path/to/your_notebook.ipynb
第四步很有意思：脚本不直接给你满屏 notebook，而是在 tmp/ 目录生成一份干净的 markdown，只保留代码单元格、去掉输出。reviewer 看的是这份精简版，省下的上下文窗口能多审两个 notebook，这对长 notebook 尤其关键。
我特别喜欢这个 tmp 降噪的设计。平时审 notebook 最累的不是看懂代码，而是被几百行输出和警告刷屏，注意力被切碎。先把输出剥掉再看代码，reviewer 的火力能集中在真正的写作问题上。
后面的环节我拆成四步逐段展开：
-
人工评审：对照 style_guide 和 rubric 逐条判断 -
四维打分：每个维度给 1-5 分并写明理由 -
生成报告：按固定格式输出执行摘要与详细评分 -
给建议：用 style_guide 模板给出带行号的 concret 改进
整条链路的设计意图很明显：把能自动化的（密钥扫描、格式检查）全自动化，把需要判断力的（叙事质量、教学逻辑）留给人和模型一起做。
内部架构与关键设计
这个技能只有三个核心文件，但职责切得很清楚。SKILL.md 是流程控制层，告诉你”先做什么后做什么”；style_guide.md 是规范层，定义什么叫好、什么叫差；validate_notebook.py 是执行层，把规范里能机器校验的部分落地。
validate_notebook.py 这个脚本有 17.8KB，是三者里最重的一个。它真正厉害的地方是内置了 detect-secrets 的自定义插件（scripts/detect-secrets/plugins.py）和基线文件。这意味着它不只是”有没有 key”的粗糙判断，而是能结合项目自己的白名单做精确扫描，误报率比通用扫描低得多。
评分体系是四维度各 5 分、总分 20。每个维度看的东西不一样，拆开才看得清：
-
叙事质量：开头有没有”钩子”和明确的学习目标，是否先讲问题而非机器 -
代码质量：变量命名是否清楚，注释是否讲”为什么”而非”是什么” -
技术准确性：模型名是否过期、API 是否废弃、能否不改一行跑通 -
行动力与理解力：有没有讲清楚”什么时候该用、什么时候不该用”
我特别认可它对模型名的要求：必须用 claude-sonnet-4-6 这种非日期别名，禁止 claude-sonnet-4-6-20250514 这种带日期的快照 ID。这一个细节就暴露了大多数教程的过期问题，很多文章还在用半年前的模型快照，跑起来直接报错。
审计报告的产出格式也是固定的，照着这个骨架填就行：
### Executive Summary
- Overall Score: X/20
- Key Strengths（2-3 条）
- Critical Issues（2-3 条）
### Detailed Scoring
1. Narrative Quality: X/5
2. Code Quality: X/5
3. Technical Accuracy: X/5
4. Actionability & Understanding: X/5
使用场景
这个技能最对味的场景，是 Anthropic 自己的 Cookbook 贡献流程。任何想往官方仓库提 notebook 的人，先过一遍审计再提交，review 来回能少好几轮，维护者也不用每次都手把手教贡献者怎么写。
其余两类也很实用，按需取用：
-
团队内部文档治理：把技能接进你们的 notebook 库，白捡一份持续演进的写作规范加自动检查 -
个人内容自查：写完教程让它审一遍，比发给同事 review 快十倍，而且它不顾及你面子
把它接进 CI 也很顺手。每次有人提 notebook，自动跑一遍 validate_notebook.py，先把密钥和格式问题卡掉，人工只审最难的判断力部分。机器做机器擅长的事，人做人擅长的事，这个分工才是这个技能真正的聪明之处。
不适合的场景也得说清楚：它是审”教学示例”的，不是审生产代码的。如果你指望它当 linter 查业务逻辑 bug，那是找错工具了。它也不改你的 notebook，只给建议，最后动手的还是你。
洞察与反思
用下来最让我意外的，是这个技能背后那套 Diátaxis 框架思维。Cookbook 的定位很清醒：它是 action-oriented 的实操指南，不是教程、不是参考文档、不是 tips 合集。它明确说”假设读者有基础技术能力”，所以不教 transformer 原理，只教怎么把事做成。这种边界感恰恰是大多数技术内容缺的。我们写东西时总怕读者不懂，于是拼命往里塞背景，结果主线被淹没。cookbook-audit 反过来，它假设读者已经入门，只解决怎么做成这一件事，反而让人读得下去。
这种克制反而提高了质量上限。很多 AI 教学内容的烂，烂在想一口吃成胖子：既想当入门课，又想当 API 参考，结果两头不讨好。cookbook-audit 用 rubric 把这种”贪多”直接打回去了，逼着作者先做减法。还有一点容易被忽略：rubric 把”好”变成了可讨论的对象。团队里两个人吵一个 notebook 行不行，过去是口味之争，现在能指着四维分数说哪分扣得有理。冲突从情绪变成了证据。
TLO 和 ELO 这套学习目标设计也值得单独拎出来讲。Terminal Learning Objectives 是学完能干什么，Enabling Learning Objectives 是支撑它的子能力。开头就把目标摊开，结尾再映射回去，这个闭环让”这篇到底教了啥”变得可验证，而不是作者自嗨。
我甚至觉得这套思路能平移到我们写 AI 技能文档本身。一个 skill 的 SKILL.md 如果被当作 cookbook 来审，开头讲问题、中间演示、结尾映射目标，质量会立刻不一样。审计别人之前，先审计自己，这是我用这个技能最大的收获。
当然它也有边界。打分依然依赖模型判断，同一篇 notebook 换不同模型审，4 分和 5 分之间会有主观浮动。style_guide 再详细也覆盖不了所有创意写法，rubric 是底线不是天花板，它拦住差的东西，但拦不出惊艳的东西。
资源地址
总结
cookbook-audit 不是一个”写教程”的技能，它是一个”定义什么叫好教程”的技能。它的价值在于把模糊的写作品味，固化成了 style_guide 加 rubric 加自动扫描的三层结构。
只要你的产出是面向开发者的实操内容（比如 Cookbook 或内部 how-to），我都建议把它当模板研究一遍。重点不是抄它的脚本，而是抄它”先定标准、再自动化检查、最后留判断力给人”的分层哲学。
最后提醒一句：它审的是教学示例，不是生产代码；它给建议，不动手。工具再好，最后那一下修改还是得自己来。