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

Supabase 文档的风格回退机制没有专属风格指南时如何保持写作约定一致【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/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 工单加代码阅读“thats the Gather phases 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事实型如字典词条含参数、返回类型、代码示例不含多步说明组件与元素规范Admonitioncallout有danger、deprecation、caution、note四种类型各自规定了适用场景、开头必须先讲影响“the so what”以及title/children/actions的属性结构强调格式按用途严格区分——粗体标记 UI 标签与不可忽略的词、_斜体_用于首次定义新术语或书名式标题、代码标记读者要逐字输入或复制的内容文件名、命令、环境变量、配置键、字面量代码块约定SQL 优先小写select * from tableJS/TS 受 Prettier 约束格式检查不过 PR 无法合并可从仓库根运行pnpm format支持在围栏后附加文件名与mark行高亮Styling, formatting, and grammar标题用 sentence caseSet up authentication而非Set Up Authentication、使用牛津逗号、尽量使用现在时、括号只用于缩写展开与(Optional)标记。第 2 步WORD_LIST.md 管拼写、大小写与术语apps/docs/WORD_LIST.md 共 927 行按字母序记录高频术语的偏好拼写、大小写与用法。其开头明确了两条元规则它补充但不覆盖 CONTRIBUTING.md“If the two documents conflict, followCONTRIBUTING.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 ofguides/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 ofpage.”。它让评审者可以一步确认草稿跟随了哪条风格来源而不是事后猜测。第 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.” 设计意图很清楚回退机制是临时脚手架而非长期方案仓库的风格治理最终应收敛到一份专属风格指南上在那之前第 14 步保证风格约定既不缺失、也不失散。风格规则如何落到 lintersupa-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.tomlsupa-mdx-lint.config.toml 定义了规则分组标题 sentence caseRule001HeadingCase、允许的叫出类型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 驱动文档写作、又尚未沉淀专属风格指南的团队这种“风格与事实解耦、来源分层、规则可追溯且部分可机械验证”的设计是一个可以直接借鉴的模式。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考