Supabase write-the-docs 技能解析：为 AI Agent 设计的文档起草工作流

本文围绕 Supabase 仓库中 .agents/skills/write-the-docs/SKILL.md 展开，拆解这套面向 AI Agent 的"从零起草文档"技能的完整工作流：四输入的信息收集协议、内容类型门禁、草稿规范、评审清单与交付流程。读完后你将理解 Supabase 是如何把"写新文档"这一模糊任务，工程化为一套可被 LLM 严格遵循、可追溯、可验证的标准化流程，并掌握其中"代码优先于 PRD""时态不变的文档"等可直接借鉴的文档工程原则。

技能定位：何时起草新文档，何时该用别的技能

write-the-docs 是 Supabase 仓库随仓库内置的一组文档作者技能（docs authoring skills）之一。apps/docs/CONTRIBUTING.md 中列出了完整的技能矩阵：

技能	对应清单阶段	用途
pm-the-docs	Frame / Shape	受众、产品阶段与跨仓范围决策
ask-the-docs	Frame / Shape	apps/docs 架构、信息架构（IA）放置、内容落位
write-the-docs	Draft	基于代码事实起草全新内容
edit-the-docs	Edit	重构与改进已有页面
test-the-docs	Draft / Self-review	在 Docker 隔离栈中执行文档代码片段并产出验证报告
review-the-docs	Self-review / PR review	草稿与 PR 的检查、分类与验证

write-the-docs 的适用边界被精确限定为：内容尚不存在（或必须基于产品意图 + 代码重写）时，为新功能或产品发布起草全新文档。原文明确将其与另外两类任务区分开：

• 已有文档工单的修复与实现——交给 work-linear-issue；
• 对已存在页面的重组、精简——交给 edit-the-docs，因为它不需要收集新的产品意图；
• 需求只是"重组、重排、补充连接性文字或澄清现有页面"（无新产品故事）时，也明确应改用 edit-the-docs。

技能的核心主张是：文档必须基于四个输入来写，而不是靠猜测——这正是整个工作流的骨架。

核心规则：五条起草总纲

技能正文给出的五条 Core rules 是整个流程的约束层，其中几条直接针对 LLM 常见的"幻觉成文"风险：

1. 先收集，后起草（Gather before drafting）。绝不允许只凭工单标题开写。四个输入必须先全部拉取——"收集阶段越薄，草稿就越容易把功能实际行为写错"。
2. 区分三种信息的性质：
   • 代码告诉你功能今天实际做什么（行为事实）；
   • Linear / PRD / PRFAQ（或先前的 Frame/Shape 产物）告诉你功能应该做什么、如何定位（产品意图）；
   • 凡是靠猜的部分，必须显式标记，不能当作事实陈述。
3. 风格文件只管文风，不管内容正确性。apps/docs/CONTRIBUTING.md 与 apps/docs/WORD_LIST.md 仅作为 voice / 术语 / 格式参照，内容正确性由规则 2 的"Linear + 代码阅读"说了算。同时禁止凭空发明文风规则——应改为指名引用你遵循的最近邻现有页面作为先例（见 reference/style-fallback.md）。
4. 复用，不要重复推导。文档应用的架构 / 落位问题，交给 ask-the-docs 与 audit-docs-ia 技能回答，而不是在本技能里重新发明这套知识。
5. 弄清你到底在起草什么。并非一切看起来像"功能的文档"的东西都是手写页面——动手前必须先过下文的内容类型门禁。

Phase 1 — Gather：四个输入按序读取

收集阶段是只读的，四个输入有固定的读取顺序（原文明确"顺序而非优先级"——Linear 始终是产品意图来源，代码始终是行为来源）：

1. 风格指南：voice 与术语参照

起点是 apps/docs/CONTRIBUTING.md 和 apps/docs/WORD_LIST.md，覆盖 voice、结构与术语。若两者未覆盖某场景，回退策略在 reference/style-fallback.md 中给出：

1. 先读 apps/docs/CONTRIBUTING.md 获取写作约定（voice、结构、文档类型）；
2. 再读 apps/docs/WORD_LIST.md 获取首选拼写、大小写与术语；
3. 仍不够，就在 apps/docs/content/ 下找最近似的现有页面（同一产品域、相似内容类型——reference 对 guide 对 quickstart），沿用它的小节结构与代码示例风格；
4. 在交付摘要中声明你参照了哪个页面，例如"尚无专门风格指南——遵循 guides/storage/uploads.mdx 的先例"；
5. 一旦仓库出现专门风格指南，优先采用它并弃用本回退。

该回退文件同时强调：它只管 voice、格式与术语，不是行为或产品定位的事实来源。

2. Linear：工单与产品上下文

Linear 是 Supabase 内部工具——内部作者首选，开源贡献者非必需。当 Linear 工单可用时：

• 拉取工单本体，以及其父级项目 / 举措的描述（PRD、PRFAQ、RFC 或举措叙述）和 PM 评论；
• 原文指出一个关键经验：产品定位 / framing 语言通常不在工单正文里，而在高一层的项目或举措描述中；
• 要区分"工单实际承诺的范围"与"PRD 中的愿景性表述（aspirational language）"；
• 若既无 Linear 工单，也无先前 Frame/Shape 产品意图产物，停止起草：向内部作者索要 Linear URL，否则把任务移交给 pm-the-docs（Frame）与 ask-the-docs（Shape/IA 未定）。产品意图存在之前绝不自造定位，也不得在本技能内部运行 Frame/Shape。

3. 代码：行为事实的最终来源

写任何行为断言之前必须先读真实实现——"PRD 描述意图，代码描述已交付物"。具体策略：

• 先在 Linear 工单 / 项目中找关联的 supabase/supabase PR：其 diff 与描述是"实际交付了什么"的最精确来源，精确度超过泛泛的仓库阅读；
• 无关联 PR 时，直接在 supabase/supabase（或产品自有仓库）中定位该功能，并套用 ask-the-docs 的"复用/最小化"视角——先理解已有什么，再描述它；
• 行为跨多个服务（CLI、Auth、migrations、平台等）时，走 pm-the-docs 的 universe-lookup capability gate（universe 可访问时用 universe，否则用 OSS 公开搜索 / 关联仓库）；
• 代码与 PRD 冲突时，行为断言以代码为准——把不一致标记出来，而不是默默二选一。

4. 作者提供的一切补充材料

截图、示例项目、相关页面、Slack 讨论、特定 voice 样本等。原文特别强调截图的用途不只是泛化背景：要用它核对确切的按钮 / 菜单 / 字段标签后再写引用这些 UI 元素的操作步骤——"UI 标签不匹配是草稿中最好避免的错误之一"。若经过输入 1–3 后功能面向用户的形态仍不清晰，应主动索要这些材料而不是猜。

收集完成后，把四个输入汇总回报给请求方：什么已确认、什么是产品意图 vs 已交付行为、还有什么缺口；若某个真实缺口会改变草稿结构或范围，停下来提问。

Phase 1.5 — 内容类型门禁

起草前必须先对需求分类，依据是 apps/docs 的真实内容类型（权威表在 ask-the-docs 的 reference/app-map.md "Content types" 一节，本地详解见 reference/content-type-gate.md）：

类型	落位	本技能是否手写
Guide / tutorial	content/guides/	是——手写 MDX，目标导向，默认场景
Troubleshooting	content/troubleshooting/	是（部分条目从 GitHub issues 同步——动手前先确认是否真的需要新页面）
Reference	由 spec/（OpenAPI、SDK YAML、CLI config）生成 → features/docs/generated/**	否——不走标准 MDX 路径
Federated	外部仓库，构建时拉取	否——超出本技能范围

这是该技能最容易"从外部知识出发误判"的一步，reference/content-type-gate.md 点出了一个常见陷阱：工单写着"给新的 X 配置项写文档"或"给新 API 端点加文档"，听起来像普通写作需求，实际上是 spec 变更。此时正确动作是：

1. 不要手写 MDX reference 页——它要么与生成器分叉，要么在下一次 generate-reference-markdown.ts 运行时被静默覆盖；
2. 找到正确的 spec 源（apps/docs/spec/ 下的 OpenAPI、SDKSpec、ConfigSpec 或 CLISpec）；
3. 在交付中明确说明"真正的修复是 spec/codegen 变更，而非本技能产出的 docs PR"。

对于同时跨两类的需求（例如新 API 端点需要 Reference 条目，同时还需要一篇任务导向的 Guide），拆分工作：Reference 部分按上述流程移交，本技能只起草 Guide 部分。拿不准时，问 ask-the-docs 而不是猜。

Phase 2 — Draft：起草规范

草稿阶段的核心要求：

• 遵循 apps/docs 的 MDX 约定（组件用法、frontmatter、代码示例接线），管线细节交给 ask-the-docs 而非重新推导；
• 放置页面时沿用现有 IA 先例；落位不明确时咨询 audit-docs-ia 的 nav/IA 知识，不靠猜 nav 槽位；
• 接入导航，而不只是落盘：放置（放哪个 section）与导航启用（是否真的可见）是两件事——不能因为文件放对了目录就假设页面可被发现；
• 每条行为断言都锚定 Phase 1 的代码阅读（有链接 PR 时以 PR 为准）；每条"为什么重要"的定位语锚定 Linear/PM 上下文或先前的 Frame/Shape 产物；推断性材料要行内标记（HTML 注释或交付摘要中的标记行），让评审者能快速定位；
• 为"永恒"写作（timeless documentation）：优先记录当下已存在的东西，而不是承诺未来功能；
• 保持简洁、避免冗余，优先用段落而非单项列表；
• 起草前剥除内部业务上下文：标记 PRD 意图、路线图推测、内部工单讨论、"gap-fill" 注释的 HTML 注释必须在交付前从 MDX 中移除——开源文档不应暴露内部规划。假设与未决问题改放到 PR 描述里，而不是写进交付内容；
• 引入或审校技术术语、UI 动作、缩写和易歧义表达时，检索 apps/docs/WORD_LIST.md（这是针对性检索，补充但不替代 Phase 2.5 的全文件合规检查）；
• 重复内容通过 apps/docs/content/_partials/ 复用，而不是复制粘贴。

常见陷阱（reference/common-pitfalls.md）

reference/common-pitfalls.md 从评审反馈中沉淀出六类陷阱，是理解 Supabase 文档质量标准的窗口：

1. 开源文档中混入内部规划上下文——PRD/路线图引用、"planned but not shipped"的 gap-fill 注释、对任何项目管理系统（内部或贡献者自有的）的引用都应清除；内部上下文应放进 PR 描述、团队的项目管理工具或内部文档中。
2. 时态不变的文档（Timeless documentation）——警惕 "Coming soon"、"will be available"、"once finalized"、"This page is a placeholder" 等表述。替代做法：记录今天已存在的、功能完成后再发布、若分阶段上线则给出具体资格条件（如"Available to organizations on Pro and Enterprise plans"）。注意上下文区分：changelog 与 roadmap 天然谈未来，此原则主要针对功能文档。
3. 占位页面——原则上避免发布明说"这是占位、细节稍后"的页面；例外包括导航结构需要、federated 文档中带链接的占位、以及"页面存在本身即有价值"的交叉引用场景。
4. 冗余与过度解释——"It's free" + "You won't be billed" + "No charge" 式的多重同义复述、admonition 声明风险后正文又逐字复述、相邻句子互相改写，都是要清除的模式。自检方法：若删掉一句话不丢失信息，它大概率是冗余。
5. 单项列表——单项 bullet list 可能暗示内容不完整，优先改写成段落；合理例外包括跨小节版式一致、预期扩展、需要视觉强调。
6. Admonition 与正文重复——告警框与正文应覆盖不同要点。

该文件末尾还有一段元说明：这些是"风格指导而非技能专属流程"，将来应并入仓库级共享风格指南，届时本文件按 style-fallback.md 的模式替换为指针——即"文档自己也会过期，需要机制性维护"的自我约束。

Phase 2.5 — 评审清单与合规清单

交付前确认（Review checklist）：

• [ ] 已遵循 CONTRIBUTING.md / WORD_LIST.md，或已显式指名所参照的先例页面
• [ ] 每条行为断言可回溯到代码阅读（理想情况是链接 PR），而非仅 PRD
• [ ] 每条"why it matters"/定位语可回溯到 Linear/PM 上下文或先前 Frame/Shape 产物，非杜撰
• [ ] 推断或假设材料已被标记，而非陈述为事实
• [ ] 内容类型确认为 Guide/Troubleshooting（而非本应属于 generated Reference 的内容）
• [ ] nav 放置与 nav 启用都已接线，而非只有放置
• [ ] 内部链接可解析；新术语/缩写首次出现处已定义
• [ ] 若草稿含可操作步骤（CLI、SQL、客户端代码或示例应用），已提议运行 test-the-docs（可选；Docker Compose 沙箱——DB/API 用 stack profile，example-app 用 examples profile）
• [ ] 未来承诺已尽量最小化（时态不变原则）
• [ ] 无不必要的冗余（同一点用多种方式重述）
• [ ] 避免单项列表（除非有特定理由）
• [ ] 内部 gap-fill 与业务上下文注释已从 MDX 移除

随后是合规清单（Compliance checklist）：交付前通读（而非只检索起草时搜过的片段）apps/docs/CONTRIBUTING.md 与 apps/docs/WORD_LIST.md 全文，确认：

• 括号只用于缩写或 (Optional)，不用于行内补充语；
• 粗体、斜体、code 各有独立用途（UI 标签、不可忽略的术语等），不单为视觉强调；
• 有直接句子可表达的地方不用破折号插入语；
• 术语与 WORD_LIST.md 一致——包括被标记为"不精确"的术语，而非只看拼写/大小写；
• 标题、admonition 与链接遵循 CONTRIBUTING.md 的 "Styling, formatting, and grammar" 与 "Components and elements" 两节。

Phase 3 — Handoff：停在"可评审草稿"处

该技能止步于一个可评审的草稿，自己不开 worktree 或 PR，交接流程为：

1. 提议 test-the-docs（草稿含可运行步骤时）。开始验证前先询问。前置条件按工件类别把关（DB/API 工件用 Docker Compose stack profile；example-app 用 examples profile / Node in-runner）。若被拒绝或该类别所需前置条件缺失，仅对相关工件记 deferred 后继续。若被接受，验证报告附到 PR body / self-review note。
2. 运行 review-the-docs 的本地自检（lint/build/分类）。
3. 移交给 create-pull-request（工单需要完整 worktree+PR 流程时再叠加 work-linear-issue）处理实际 PR 机制。Phase 1/2 标记的假设清单要显式带入交接，放进 PR 描述（如 "needs review" 一节）让评审者看到，而不是埋在草稿里的行内注释。
4. 若功能以 UI 为主且 PR 需要截图/GIF，把 proof-it-works 标记为下一步，而不是在此处取证。
5. 开 PR 前运行本地自检：pnpm lint:mdx、适用时 pnpm build:guides-markdown，以及 reference/drafting-mechanics.md 中的 anchor 检查。

这些命令在当前仓库中是真实存在的脚本入口：apps/docs/package.json 定义了 "lint:mdx": "supa-mdx-lint content --config ../../supa-mdx-lint.config.toml" 与 "build:guides-markdown": "tsx ./internals/generate-guides-markdown.ts"，其中 supa-mdx-lint 是仓库自研的 MDX lint 工具，规则集位于 supa-mdx-lint/（标题大小写、拼写、用词规则等 TOML 规则文件）——这正是合规清单在 CI 层面的落地。

起草机制细节：drafting-mechanics.md

reference/drafting-mechanics.md 补充了三个起草中会遇到的机制问题：

链接路径约定：Supabase 文档内的页面用 /docs/... 路径；文档站之外的页面用站点根路径（如 /dashboard）；链接文字要描述性，admonition 要克制并带正确严重级别。

Anchor 稳定性：anchor ID 由标题文本在渲染时生成，CI 中没有任何检查验证 #anchor 链接是否仍能解析。因此重命名、删除或大幅改写标题前，先执行：

grep -rn "#<old-anchor-slug>" apps/docs/content

更新所有页内与跨文件匹配。若某标题需要不随措辞变化的稳定 anchor，用自定义 anchor 固定，例如 ## Some heading [#some-heading]。

Lint 与格式：从 apps/docs 运行

pnpm lint:mdx
pnpm build:guides-markdown

pnpm lint:mdx 覆盖 apps/docs/content 下所有内容（含 troubleshooting 条目）；pnpm build:guides-markdown 只针对 guides、explainers 与 tutorials。从仓库根目录运行 pnpm format 用 Prettier 格式化改动的 MDX 文件，强制仓库级格式规则（包括代码示例中 SQL 关键字的小写）。最后一条经验性提醒：把 supa-mdx-lint 的替换建议当作建议——当上下文重要时，改写整句而不是套用会改变技术含义的机械替换。

技能生态中的位置：一份可复用的文档工程蓝图

把 write-the-docs 放回 apps/docs/CONTRIBUTING.md 描述的"六阶段清单"（Frame → Shape → Draft → Self-review → PR review → Keep it honest，完整清单见 pm-the-docs 的 reference/write-the-docs-checklist.md），它的角色很清晰：Draft 阶段的可执行技能——上游的 pm-the-docs/ask-the-docs 负责 Frame/Shape，下游的 test-the-docs/review-the-docs 负责验证与评审。CONTRIBUTING.md 还说明这些规范文件存放于 .agents/skills/，.claude/skills 是指向该目录的 Git 符号链接，使 Claude Code 等 Agent 也能以 /name 斜杠命令发现它们。

这套设计对"用 LLM 写文档"场景有普适参考价值，其核心机制可归纳为三点：

1. 信息源分层：行为事实（代码/PR）、产品意图（Linear/PRD）、风格参照（CONTRIBUTING/WORD_LIST）严格分离，任何越界（用 PRD 写行为、用风格文件写内容）都被显式禁止，推断必须标记；
2. 门禁与路由：内容类型门禁把"看起来像写作"的需求路由到正确的管道（手写 MDX vs spec 生成），避免了"产出看似完成实则会被覆盖"的错误工件；
3. 验证闭环：草稿不停在"写完"，而是经 lint:mdx、markdown 重建、Docker 沙箱执行代码片段、anchor 检查等多层机械验证后才进入 PR，且验证报告随 PR body 交接。

对贡献者而言，这套流程的入口很简单：在仓库中向 Agent 指名技能（write-the-docs），按 Phase 1 补齐四个输入，随后即可获得一份行为断言可回溯到代码、定位语可回溯到产品意图、且通过全部 lint/格式检查的可评审文档草稿。