write-the-docs

编写文档

为某项功能或发布撰写全新的 Supabase 文档内容（或基于产品实际情况重写内容）。这不同于 work-linear-issue：后者用于实施和修复现有文档工单；也不同于 edit-the-docs：后者用于重组和精简已有页面，不收集全新的产品意图。这项技能适用于内容尚不存在（或必须根据意图和代码重写）的情况，应以四项输入为依据，而不是靠猜测。

核心规则

1. 先收集，再起草。 切勿仅凭工单标题起草内容。先获取以下四项输入；收集阶段过于粗略，草稿就会对功能的实际工作方式产生误解。
2. 区分已确认的行为、产品意图和推断。 代码说明功能当前的行为。Linear/PRD/PRFAQ（或先前 Frame/Shape 的输出）说明功能的预期用途和定位。凡是需要猜测的内容，都要明确标出，不要当作事实陈述。
3. 遵循风格指南中的写作规范，包括语气、术语、格式、页面结构和元素。切勿将其作为内容准确性的依据。 它只是风格参考，并非事实来源：页面实际内容应由规则 2 中对 Linear 和代码的查阅结果决定。不要自行编造语气或结构规则。如果风格指南和 Google 的开发者文档风格指南都没有明确规定，应在交接说明中指出，而不是照搬最相近页面的做法。
4. 复用，不要重复。 对于文档应用的架构和页面放置问题，请使用 ask-the-docs 和 audit-docs-ia，而不是在此重新推导相关知识。
5. 明确要起草的内容类型。 看似“功能文档”的内容不一定都需要手写页面——开始撰写前，请查看下方的内容类型判断。如果需求是重组、调整顺序、补充衔接文字，或提高清晰度，且不涉及新的产品叙述，请改用 edit-the-docs。

阶段 1 — 收集（只读）

按以下顺序阅读四类输入（这是阅读顺序，不是优先级；根据规则 2 和阶段 1 第 3 步，Linear 仍是产品意图的来源，代码仍是行为的来源）：

1. 风格指南 — 语气和术语参考。 阅读 style-guide/README.md，并遵循与当前撰写内容对应的步骤。查看 WORD_LIST.md，确认你计划引入的术语。指南的结尾部分说明了未涵盖相关情况时应查阅的内容；请遵循该指引，不要照搬相邻页面的写法。
2. Linear — 工单及其产品背景。 Linear 是 Supabase 的内部工具：有条件时优先使用，但开源贡献者不必使用。若有 Linear issue，请先查看该 issue，再查看其父级项目或计划的描述（PRD、PRFAQ、RFC 或计划说明）以及所有 PM 评论。产品定位和表述通常位于比工单高一级的内容中，即父级项目或计划描述，而非工单正文。区分工单实际承诺的范围与 PRD 中的愿景性表述。如果没有 Linear issue，也没有之前的 Frame/Shape 产品意图输出，请停止撰写：向内部作者索要 Linear URL；否则转交给 pm-the-docs（Frame），如果 Shape/IA 尚未确定，则转交给 ask-the-docs。只有在产品意图明确后才能继续——绝不要自行编造产品定位，也不要在此 Draft 技能中运行 Frame/Shape。
3. 代码。 在撰写任何行为描述前，先阅读实际实现——PRD 描述意图，代码描述已发布的行为。先检查 Linear issue/项目中是否关联了 supabase/supabase PR——其差异和描述是关于“实际发布内容”最准确的来源，比泛泛阅读代码库更精确。如果没有关联 PR，请直接在 supabase/supabase（或产品自身的代码库）中定位该功能，并运用 ask-the-docs 的复用/简约原则：先了解现有内容，再进行描述。如果行为涉及多个服务（CLI、Auth、migrations、platform 等），请遵循 pm-the-docs → universe-lookup 的能力门槛（universe 可访问时使用，否则使用 OSS 公开搜索/关联代码库——不要使用 ask-the-docs）。如果代码与 PRD 不一致，行为描述以代码为准——指出差异，不要默默择一。
4. 作者提供的其他资料。 截图、示例项目、相关页面、Slack 讨论串、特定的语气示例等。截图不只是提供一般背景信息——在撰写引用截图内容的操作步骤前，请用截图核实准确的按钮/菜单/字段标签；UI 标签不匹配是草稿中最容易避免的错误之一。如果在完成第 1–3 步后，功能面向用户的形态仍不明确，请索取这些资料，不要猜测。

撰写前，先向请求者总结以上四类信息：哪些内容已确认，哪些属于产品意图、哪些属于已发布行为，以及还有哪些缺口。如果确实存在的缺口会改变草稿结构或范围，请停止并询问。

阶段 1.5 — 内容类型门槛

起草前，请根据 apps/docs 的实际内容类型对请求进行分类（参见 ask-the-docs 的 app-map.md 中的“Content types”表，以及此处的 reference/content-type-gate.md）：

• 指南 / 教程 — content/guides/ 下由人工编写的 MDX。这是此技能负责起草的内容。
• 故障排查 — content/troubleshooting/ 下由人工编写的 MDX，有时会从 GitHub issue 同步。这也属于负责范围。
• 参考文档 — 由 spec/（OpenAPI、SDK YAML、CLI 配置）生成 → features/docs/generated/**。不能通过标准 MDX 流程手动编写。 如果请求实际针对参考文档类型内容（需要新增参考条目的 API 端点、配置选项或 SDK 方法），请停止起草 MDX——否则内容会与生成器不一致，或被生成器悄悄覆盖。请改为指向 spec/codegen 流程（apps/docs/spec/、apps/docs/generator/；OpenAPI 专属流程请参阅 ask-the-docs 的 management-api-reference.md），并明确说明这一点，不要产出一个看似完成、实际却没有解决问题的页面。

如有疑问，请询问 ask-the-docs，而不是自行猜测——如果不了解应用的实际情况，这项分类最容易出错。

阶段 2 — 起草

• 遵循 apps/docs 的 MDX 规范（组件用法、frontmatter、代码示例接线方式）——请参阅 ask-the-docs 了解流程详情，而不是自行推断。
• 根据现有信息架构先例确定页面位置；如果位置不明显，请参考 audit-docs-ia 中有关导航和信息架构的知识，而不是猜测导航位置。
• 将页面接入导航，而不只是保存到磁盘。 页面位置（属于哪个版块）和导航启用（页面是否实际显示）是两回事——请通过 ask-the-docs/audit-docs-ia 确认当前的导航注册机制，不要假设只要文件位于正确文件夹中，用户就能找到它。
• 每项行为说明都要以阶段 1 的代码阅读为依据（如有相关 PR，则以该 PR 为依据）；每项关于“为何重要”的说明都要以 Linear/PM 上下文或之前的 Frame/Shape 输出为依据；对推断内容进行行内标记（例如使用 HTML 注释，或在交接摘要中标记），方便审核者快速定位。
• 编写经久适用的文档，删减冗余，并优先使用段落而非只有一项的列表。 参见经久适用的文档、简洁和列表。
• 在最终稿中删除内部业务背景。 MDX 中标记 PRD 意图、路线图推测、内部工单讨论或“补缺”说明的 HTML 注释，必须在交接前移除。开源文档不应暴露内部规划。请在 PR 描述中向审核者标记假设和待解问题，而不是将其写入发布内容。
• 起草时引入或审核技术术语、UI 操作、缩写和可能存在歧义的措辞，请查阅 WORD_LIST.md。请遵循与 AI Agent 配合使用中的两轮流程，而不是从头到尾通读该文件。
• 对于重复使用的内容，请通过 apps/docs/content/_partials/ 复用，而不是复制。有关导航接线、partials 和文件位置，请参阅 ask-the-docs 的 app-map.md 和 federated-docs.md。

阶段 2.5 — 审核清单

交接前，请确认：

• 遵循了风格指南；如果没有，已在交接说明中明确指出差距
• 每项行为描述都能追溯到已阅读的代码（最好是链接的 PR），而不只是 PRD
• 每条“为何重要”或定位说明都能追溯到 Linear/PM 上下文或之前的 Frame/Shape 输出，而非凭空编造
• 已标记推断或假设内容，未将其表述为事实
• 已确认内容类型为指南/故障排除（而非应放在生成式参考文档中的内容）
• 已配置导航位置和导航启用，两者都已完成，而不仅是设置了位置
• 内部链接有效；新术语/首字母缩写在首次出现时已作定义
• 如果草稿中包含操作步骤片段（CLI、SQL、客户端代码或示例应用），已提出运行 test-the-docs（可选；Docker Compose 沙盒 — DB/API 使用 stack 配置，example-app 使用 examples 配置）
• 尽可能减少对未来的承诺（遵循文档经久耐用的原则）
• 没有不必要的重复（以多种方式反复表达同一点）
• 避免仅含单个条目的列表，除非有特定原因
• 已从 MDX 中移除内部补充说明和业务上下文评论（如有需要，仅在 PR 描述中保留以供审核）

合规性清单

交接前，请按照与 AI Agent 配合使用中的说明完成两轮检查：阅读短语分组，查看其中的字面术语列表；然后运行 grep '^### ' WORD_LIST.md，并仅阅读与页面中词语匹配的条目。检查你未新增的术语，而不只是起草时搜索过的术语。然后根据风格指南中的每个编号文件检查草稿。

• 括号仅用于首字母缩写或 (Optional)，不用于插入说明性文字
• 粗体、斜体和代码格式仅用于各自特定用途（UI 标签、不可忽略的术语），不单纯用于视觉强调
• 不使用破折号插入说明；直接陈述更清晰时，应改用完整句子
• 术语符合 WORD_LIST.md（包括被标记为不准确的术语，不只是拼写/大小写）
• 语态、时态和简洁程度符合 01-voice-and-tone.md
• 文档类型、章节分组和内容分块符合 03-page-structure.md
• 提示框、标题、链接和其他组件符合 02-elements.md

阶段 3 — 交接

此技能止步于可供审阅的草稿，不会自行创建 worktree 或 PR：

• 如果草稿包含可运行的操作片段，请提供 test-the-docs。开始验证前先征求同意。按工件类别检查前置条件（DB/API 工件需使用 Docker Compose stack profile；example-app 需使用 examples profile / Node in-runner）。如果对方拒绝，或该类别缺少必需的前置条件，仅将这些工件标记为 deferred，然后继续。对方接受后，将验证报告附在 PR 正文或自我审查备注中。
• 然后运行 review-the-docs 进行本地自我审查（构建／分类）。
• 将实际 PR 操作交接给 create-pull-request；如果工单需要完整的 worktree+PR 流程，也交接给 work-linear-issue。明确将阶段 1/2 标记的假设列表一并交接——应将其写入 PR 描述（例如放在「需要审查」部分），以便审阅者能看到，而不只是作为内联评论埋在草稿中。
• 如果该功能由 UI 驱动，且 PR 需要截图／GIF，请将 proof-it-works 标记为下一步，而不是在此处采集证据。
• 打开 PR 前，运行 review-the-docs 进行本地自我审查：在适用时运行 pnpm build:guides-markdown，并按照 reference/drafting-mechanics.md 检查锚点。

其他资源

• 风格：style-guide/README.md 指向各个层级对应的文件
• 仓库机制（导航配置、partials、参考资料流水线）：apps/docs/CONTRIBUTING.md
• 草拟机制：reference/drafting-mechanics.md
• 内容类型门槛详情：reference/content-type-gate.md
• 现有页面的重组／清晰度：edit-the-docs
• 「编写文档」检查清单（草拟阶段）：pm-the-docs 的 reference/write-the-docs-checklist.md
• 跨仓库产品查询：pm-the-docs → universe-lookup
• 可运行验证：test-the-docs
• 文档应用架构／页面位置：ask-the-docs、audit-docs-ia
• PR 操作：create-pull-request、work-linear-issue
• 截图／效果证明：proof-it-works