Supabase 文档的风格回退机制：没有专属风格指南时如何保持写作约定一致

在 Supabase 单仓中，文档写作由 .agents/skills/ 下的 AI agent 技能驱动，而 style-fallback.md 正是 write-the-docs 技能在仓库尚未发布专属风格指南时使用的回退（fallback）协议。本文完整拆解这条 5 步风格解析链——从 CONTRIBUTING.md 与 WORD_LIST.md 到先例页面匹配、交接声明与回退机制的自我退役路径——并结合仓库源码说明它的边界如何划定、风格规则又如何落到 supa-mdx-lint 上被机械执行。读完你可以在自己的项目中复用这套“风格与事实解耦、每条规则可追溯、部分可机器验证”的文档写作治理方案。

风格回退的定位与边界

style-fallback.md 全文只有 22 行，但开头就声明了两条关键边界。

第一条是前提声明：“There is no separate published style guide yet beyond what already lives in this repo”，即仓库中尚无独立发布的风格指南，写作约定就活在仓库内现有的文档里，回退链“按顺序”（in order）使用这些公开来源。截至当前仓库结构，确实没有检索到独立的 style guide 文件，因此这条回退链处于生效状态。

第二条是职责边界：“This fallback governs voice, formatting, and terminology only”，它只管辖语气（voice）、格式（formatting）和术语（terminology），并且文档明确声明它不是行为事实或产品定位的权威来源——那属于 Gather 阶段的 Linear 工单加代码阅读（“that's the Gather phase's Linear + code read, per SKILL.md rule 3”）。

这条边界与 SKILL.md 核心规则 3 完全呼应：

Follow CONTRIBUTING.md and WORD_LIST.md for voice, terminology, and formatting only, never for content accuracy.

也就是说，在这个仓库里风格层（怎么写）与事实层（写什么）被彻底解耦：行为声明来自代码，产品意图来自 Linear，风格约定则走这条回退链。任何拿 CONTRIBUTING.md 当内容权威、或拿先例页面的措辞当事实依据的写法，都被视为越界。

五步回退解析链

原文档给出的是一个有序编号列表，顺序本身就是机制的核心：层级靠前的来源优先，只有前者没覆盖到具体情形时才落到下一层。

第 1 步：CONTRIBUTING.md 提供写作约定

apps/docs/CONTRIBUTING.md 共 457 行，是语气、结构与文档类型的约定来源，主要内容包括：

• General principles：为读者写作、像说话一样写作、短句直述、一段一个主题、避免习语与俚语、用 you 指代读者（we 仅指 Supabase 团队）；
• 四种文档类型：Explainers（概念解释，不含操作指令）、Tutorials（大目标导向，混合叙述与步骤）、Guides（短目标导向，以步骤为主，且必须以一句意图声明开头，如 This guide explains how to set up email login.）、Reference（事实型，如字典词条，含参数、返回类型、代码示例，不含多步说明）；
• 组件与元素规范：Admonition（callout）有 danger、deprecation、caution、note 四种类型，各自规定了适用场景、开头必须先讲影响（“the so what”）以及 title/children/actions 的属性结构；强调格式按用途严格区分——粗体标记 UI 标签与不可忽略的词、_斜体_用于首次定义新术语或书名式标题、代码标记读者要逐字输入或复制的内容（文件名、命令、环境变量、配置键、字面量）；
• 代码块约定：SQL 优先小写（select * from table），JS/TS 受 Prettier 约束（格式检查不过 PR 无法合并，可从仓库根运行 pnpm format），支持在围栏后附加文件名与 mark= 行高亮；
• Styling, formatting, and grammar：标题用 sentence case（Set up authentication 而非 Set Up Authentication）、使用牛津逗号、尽量使用现在时、括号只用于缩写展开与 (Optional) 标记。

第 2 步：WORD_LIST.md 管拼写、大小写与术语

apps/docs/WORD_LIST.md 共 927 行，按字母序记录高频术语的偏好拼写、大小写与用法。其开头明确了两条元规则：它补充但不覆盖 CONTRIBUTING.md（“If the two documents conflict, follow CONTRIBUTING.md”）；字面代码、API 名、UI 标签与第三方产品名必须原样保留，即使与词表冲突。

规则普遍采用 “Recommended / Not recommended” 对照形式，例如：

• + 不能表示 “or later”：写 Postgres 15 or later，不写 Postgres 15+；
• 正文、标题、目录中用 and 代替 &（UI 标签、代码、空间受限的表格或图标签除外）；
• 不用 allowlist 作动词（“Allowlist the IP address” 不推荐），改用精确动词：“Add the IP address to the allowlist”；
• blacklist 与 whitelist 会被 linter 报为错误；字面代码中若含这类词，须格式化为代码并解释其含义。

第 3 步：找最近的可比页面作先例

当前两个来源没覆盖具体情形时，回退链的第三层是：在 apps/docs/content/ 下找“最近的可比既有页面”——判定标准是同一产品领域 + 相似内容类型（reference vs. guide vs. quickstart），然后跟随该页面的语气、标题结构与代码示例约定。

这里有一个值得注意的细节：原文档举的先例示例路径是 guides/storage/uploads.mdx，而在当前仓库中该位置已经演化为 apps/docs/content/guides/storage/uploads/ 目录，内含 standard-uploads.mdx、resumable-uploads.mdx、s3-uploads.mdx 等页面。这恰好印证了第 3 步为何要求按“内容类型”而非“固定路径”匹配：先例页面会随信息架构（IA）重组而移动，跟随的是它的语气与结构，而不是路径本身。

第 4 步：在交接摘要中声明所跟随的先例

第 4 步是透明度要求：一旦草稿走了先例页面，必须在 handoff summary 中显式点名。原文档给出的标准句式是：

"no dedicated style guide yet — following the precedent of guides/storage/uploads.mdx."

这一要求同样出现在 SKILL.md 的 Phase 2.5 审查清单中（“CONTRIBUTING.md / WORD_LIST.md followed, or precedent page named explicitly”），以及 Phase 1 第 1 步的风格来源说明中（“say explicitly: no dedicated style guide yet — following the precedent of <page>.”）。它让评审者可以一步确认草稿跟随了哪条风格来源，而不是事后猜测。

第 5 步：专属风格指南落地后，回退链整体退役

第 5 步为回退机制预留了自我退役路径：

When a dedicated style guide is added to the repo later, prefer it over precedent-matching and drop this fallback step.

SKILL.md 的合规检查清单也做了同一预告：“When a dedicated style guide lands in the repo, extend this checklist to cover it too.” 设计意图很清楚：回退机制是临时脚手架而非长期方案，仓库的风格治理最终应收敛到一份专属风格指南上；在那之前，第 1～4 步保证风格约定既不缺失、也不失散。

风格规则如何落到 linter：supa-mdx-lint

这条回退链的价值不只是“知道规则”，而是规则被机械执行。CONTRIBUTING.md 的 “Word usage and spelling” 一节明确写道：词表中的术语规则由 supa-mdx-lint 检查，编辑 MDX 后应在 apps/docs 下运行 pnpm lint:mdx 自查。

从仓库可以确认这条链的每一环：

• apps/docs/package.json 中的脚本定义："lint:mdx": "supa-mdx-lint content --config ../../supa-mdx-lint.config.toml"；
• supa-mdx-lint.config.toml 定义了规则分组：标题 sentence case（Rule001HeadingCase）、允许的叫出类型（Rule002AdmonitionTypes 限定为 note、caution、deprecation、danger）、拼写（Rule003Spelling）、禁用词（Rule004ExcludeWords）等；
• supa-mdx-lint/Rule004ExcludeWords/ 下的 12 个子规则文件（marketing.toml、filler.toml、first_person.toml、formal_corporate.toml、slang.toml、human_language.toml 等）与 CONTRIBUTING.md 的写作原则一一对应：像说话一样写、用 you 指代读者、避免营销化与空洞措辞、避免第一人称；
• WORD_LIST.md 开头也提醒：lint 警告仍需人工判断——“rewrite the sentence instead of applying a replacement that changes its meaning”，即宁可重写句子，也不做改变语义的机械替换。

分工因此很清晰：CONTRIBUTING.md 与 WORD_LIST.md 是人读的风格来源，supa-mdx-lint 是其机器可执行子集；回退链告诉作者“去哪查”，linter 告诉作者“过没过”。

交接前的风格合规清单

SKILL.md 的 Phase 2.5 Compliance checklist 是这条回退链的验收清单，要求交接前完整重读两个风格来源（而不是只读写作时检索过的那几节），并逐项确认：

• 括号只用于缩写展开或 (Optional) 标记，不用于 prose 插语；
• 粗体、斜体、代码 只按各自用途使用（UI 标签、不可忽略的词、需逐字复制的内容），不做纯视觉强调；
• 能用直接句子表达的，不用破折号做插入语（dash-based asides）；
• 术语与 WORD_LIST.md 一致——包括被标记为不精确的术语，不只是拼写与大小写；
• 标题、叫出（admonitions）与链接遵循 CONTRIBUTING.md 的 “Styling, formatting, and grammar” 与 “Components and elements” 两节。

小结

style-fallback.md 篇幅只有 22 行，却为 Supabase 文档仓库定义了一套完整的风格治理过渡方案：在专属风格指南缺位时，用 “CONTRIBUTING.md → WORD_LIST.md → 先例页面 → 交接声明” 的有序解析链保证风格一致且每条决定可追溯；用 pnpm lint:mdx 驱动的 supa-mdx-lint 把其中可机器化的规则落地强制执行；并预留了专属指南落地后整体退役的退出路径。对于用 AI agent 驱动文档写作、又尚未沉淀专属风格指南的团队，这种“风格与事实解耦、来源分层、规则可追溯且部分可机械验证”的设计，是一个可以直接借鉴的模式。