适用场景
当代码就是内容时写示例 —— 一个模式、一次集成、一份值得整体复制的配置。它不是：
- 操作指南。 操作指南是流程 —— 跨多个界面的动作（控制台、CLI、代码），最后做验证。示例是清单 —— 读者唯一的动作是复制和改造。如果读者必须在代码之外做事情才能跑通，要么把它们收进一行假设说明，要么写操作指南。
- 参考。 参考完整且中立，按产品界面索引。示例有选择、有观点，按读者目标索引。参考展示
send()接受的每个字段；示例只展示你用来批量发送的那三个。 - 教程。 没有叙述、没有教学、没有分部。示例假设读者已具备能力，然后让开。
本类型的两条定律：
- 完整且可运行。 完整导入、完整配置、没有省略行 —— 一个 “你需要自己改改” 的片段不是示例，是作业。复制粘贴必须产生页面展示的结果。
- 经过测试。 不能运行的示例代码比没有更糟 —— 它会在读者编辑器里失败，却顶着产品的名字。尽量在 CI 中运行它们；无论如何都要盖上
lastVerified。
标题与描述
- 标题：目标加技术栈。 “在 Next.js 路由处理器中验证签名” · “用 Redis 消除 webhook 突发流量。” 操作指南陈述中立目标（“轮换签名密钥”）；示例要写出代码所处的环境，因为代码就是内容。不要 “示例 3” 或 “杂项片段”。
- 描述公式：“代码做什么，写在它面向的技术栈里。” —— 例如 “在 Next.js 路由处理器中验证 Hookline 签名，并拒绝重放。”
脚手架生成本页
安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整：
npx @cloudflare/nimbus-docs add content-example
yarn nimbus-docs add content-example
pnpm nimbus-docs add content-example
bunx @cloudflare/nimbus-docs add content-example食谱式（cookbook）页面。 若干相关示例可以共用一个页面，用名词短语作分类标题（“签名验证”“批量处理”）。每个 ## 条目遵循单页骨架但去掉 frontmatter：目标行、假设行、代码、展示结果、工作原理。
页面的 lastVerified 指其中验证时间最早的条目。先把相关示例加到分类页，等某个条目的代码超过一屏时再拆出去。
组件建议
- 带标题的代码块（
title="app/api/hooks/route.ts"）是标志性组件 —— 文件名是承重上下文。多文件示例用代码分组；如果诚实地只有一个文件，那就更好。 - 代码内的注释承载使用现场说明（
// rejects deliveries signed >5 min ago）—— 这是代码注释胜过散文的唯一地方，因为它们能挺过复制粘贴。 - 不适合： Steps（这里没有要执行的操作）、卡片、折叠面板（藏起来的代码既找不到也提不出）、按语言分标签页除非每个标签页都维护并测试过 —— 未测试的标签页是藏在已测试标签页背后的坏示例。
结尾
展示结果 → 工作原理（需要时）→ 另见。 没有验证分节（那是操作指南的动作 —— 这里由展示结果和测试承担），没有下一步旅程（读者是为代码而来，也会带着代码离开）。
阈值
- 每个示例一个目标。 标题测试：如果需要 “和”，就拆开。
- 解释不能超过代码。 当 “工作原理” 开始需要成段文字而不是要点时，说明有个概念或操作指南想逃出来 —— 链接过去。
- 处理该模式相关的错误；其余让它抛出。 开头就说明错误处理约定，避免条目在裸正常路径和生产加固之间来回摇摆。为目标不需要的代码加防御，是伪装的散文。
- 食谱页面：每个条目使用相同内部模板，按目标索引，最想要的排在最前。
链接与时效
链接模式背后的概念，以及每个魔法值对应的参考，并从相关操作指南反向链接到示例（“只要代码？→”）。
时效性是这个类型的全部声誉。在每个触及相关 API 的版本上重跑示例，尽量放进 CI，并盖上 lastVerified。不再能编译的代码，是产品无人维护最响亮的信号。
智能体说明
- 智能体会逐字搬用示例，所以完整就是正确：省略的导入会在别人的代码库里变成臆造的导入；代码里的
...会变成任何东西。 - 把假设写成页面上可核对的事实（版本、环境变量）—— 智能体无法从你项目的渲染截图推断它们。
- 全程使用真实值；占位符只放在尖括号里（
<angle-brackets>），且只在真实值不可能存在时使用。 - “工作原理” 要点是检索金矿：它们把不直观的那行代码和原因放在同一个块里，这正是阻止智能体 “简化” 承重部分（
req.text()→req.json()）的关键。任何依赖特定提供商行为的要点都要明确标出，让改造中的智能体知道要重新核对什么。
检查清单
建议性 —— 供作者或智能体自检，永不作为构建闸门：
- 标题是目标加技术栈（食谱页：名词短语分类）；一个目标
- 假设用一行写出，作为可核对的事实（版本、环境）
- 代码完整、粘贴即可运行 —— 完整导入、零省略、在严格设置下通过类型检查
- 有展示结果：粘贴代码产生的输出，以及如何触发它
- 使用真实值；占位符只放在尖括号中
- “工作原理” 只覆盖不直观的行；标出提供商特定假设
- 错误处理限定在该模式相关范围内
- 变体是链接，不是硬塞进来的清单；食谱条目共用一种内部模板
- 已针对当前版本测试（尽量放进 CI）；已盖上
lastVerified（食谱页：最早条目）