Supabase《Write the docs》六阶段文档写作清单全解【免费下载链接】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/supabaseSupabase 仓库在 .agents/skills/pm-the-docs/reference/write-the-docs-checklist.md 中沉淀了一套「Write the docs」文档写作清单它用六个轻量阶段Frame、Shape、Draft、Self-review、PR review、Keep it honest规定了产品文档从规划、起草到评审的完整路径并明确 Product、Engineering、Docs 三类角色各自承担的检查项。读完本文你将掌握这套清单的质量标准What good looks like、每个阶段的勾选式检查点、与之配套的六个 AI Agent 技能pm-the-docs、ask-the-docs、write-the-docs、edit-the-docs、test-the-docs、review-the-docs的分工以及跨仓库事实核查universe lookup的能力门控与 OSS 回退路径可以据此为任何 Supabase 功能撰写、验证并评审符合官方标准的文档页面。清单的设计目标与角色模型清单开篇定义了三个角色缩写全文的检查项都以此为责任主体P Product产品E Engineering工程Docs Docs team文档团队写作流程被刻意设计为「六个短阶段」原文明确说明Keep it lightweight; the point is to make good docs the default, not to add ceremony——目标是让好文档成为默认结果而不是增加流程仪式感。原文还强调Self-serve first能自助完成的不要打扰人需要时再找 Docs 团队的 PM该技能入口见 pm-the-docs SKILL。这套清单不是孤立文件。它是 pm-the-docs 技能的镜像参考文件——pm-the-docs的 SKILL.md 自述它「backs the Frame and Shape stages of the Write the docs checklist」即专门支撑清单的前两个阶段。而 apps/docs/CONTRIBUTING.md 的「AI agent skills for docs authoring」一节进一步把清单与六个技能绑定技能对应清单阶段用途pm-the-docsFrame / Shape受众、产品阶段、跨切面范围判断有 Supabase org 访问权时用 universe否则走 OSS 路径ask-the-docsFrame / Shapeapps/docs架构、IA 放置、内容存放位置write-the-docsDraft以代码为依据起草全新内容edit-the-docsEdit重构与改进既有页面test-the-docsDraft / Self-review在 Docker 隔离的本地栈中执行文档代码片段并产出验证报告review-the-docsSelf-review / PR review草稿自审与 PR 分诊/验证从源码结构看规范文件的落盘位置也有讲究技能规范统一放在.agents/skills/canonical 位置.claude/skills是指向该目录的 Git 符号链接以便 Claude Code 等 Agent 自动发现review-the-docs 的「Docs tooling review」检查项也要求维护这一结构不被破坏如readlink .claude/skills应等于../.agents/skills。What good looks like质量标准清单开宗明义给出七条质量基线原文What good looks like小节后续每个阶段的勾选项都服务于它The why is explicit——读者应学到「这个功能解决什么问题、什么场景下该用它」而不只是操作步骤The content type is deliberate——内容类型要刻意选定且在一页之内保持一致Audience and prerequisites are stated up front——受众与前置条件在页面开头声明Examples are runnable and have been tested——示例必须可运行且已验证过命令、代码、预期结果并明确用/test-the-docs在Docker 隔离的本地栈上验证而非打生产环境Correct stage like GA is stated——如实声明功能所处阶段alpha/beta/GA并诚实列出局限The page lives in the right place——页面在信息架构IA中位置正确并与相关页面双向链接术语与排版和现有文档保持一致待风格指南落地后再对齐风格指南。六阶段流程Stage 1Frame定框——回答给谁写、为什么写配套技能用/ask-the-docs了解 docs 站当前的运作方式用/pm-the-docs确定受众、阶段与跨切面范围可访问 universe 时做跨仓库探查参见 universe-lookup.md。PProduct需完成的勾选项声明产品阶段private/public alpha、beta、GA指明受众和他们要完成的 jobjob-to-be-done用一句话写清这个功能为什么存在它解决什么问题而不只是它做了什么pm-the-docs 的 SKILL.md 给出了执行 Frame 阶段的具体方法先读清单中对应阶段的勾选项它们精确定义了要做的决定再读该功能已有的一切上下文关联 issue、项目、PRD、已上线代码或 PR当代码与 PRD 冲突时行为论断以代码为准若功能可能横跨多个服务CLI、Auth、migrations、Dashboard、平台等必须先走 universe-lookup 的 capability gate 再落定 Frame/Shape并记录搜索过哪些仓库最后直接回答清单的问题阶段、受众与 JTBD、一句话 why、内容类型、IA 位置、前置条件并且始终区分已确认事实ticket/PRD/代码中明确写出的与推断你的最佳解读推断必须显式标注而不能装作既定结论。若某个决定在组织层面尚未拍板而非文档写作层面的判断应明说并指出该由谁决定而不是编一个答案充数。Stage 2Shape塑形——回答写成什么类型、放在哪里配套技能/ask-the-docs用于 IA 放置、架构与内容位置判断。P 需完成的勾选项选定内容类型tutorial学习、how-to完成任务、reference查阅、explanation解释为什么。一页内不要混用类型原文参照 Diátaxis 框架决定页面在现有 IA 中的位置以及哪些链接进出此页避免孤儿页面在开头列出前置条件与假定知识这里的「内容类型」在 apps/docs/CONTRIBUTING.md 中有更细的定义可视为 Shape 阶段的落点参考Explainers概念性、以散文为主讲 what/why/when/how 的高层原理不含使用步骤Tutorials目标导向帮助读者完成一个大型复杂目标如搭一个用到多个 Supabase 功能的 Web 应用叙述与步骤混合并解释为什么给这些指令Guides面向更短、更聚焦的任务如为应用配置登录以步骤为主。CONTRIBUTING.md 还要求 Guide 开篇声明意图如 This guide explains how to set up email login.把背景概念拆到独立小节或 explainer 并交叉引用权威解释保持操作路径可扫读Reference事实性、简明如字典条目包含函数参数、返回类型、代码示例、关键错误警告不包含背景解释、用例示例或多步指令。此外从 write-the-docs 的 SKILL.md 可以看到仓库对 Reference 类内容的工程约束reference 页面是由spec/目录OpenAPI、SDK YAML、CLI 配置经代码生成管线产出的features/docs/generated/**不走手工 MDX 路径。如果实际需求是新增 API 端点、配置项或 SDK 方法这类 reference 条目正确做法是指向 spec/codegen 管线apps/docs/spec/、apps/docs/generator/而不是手写一个看起来完成但会被生成器覆盖的页面——这就是 Shape 阶段「content type gate」的实操含义。Stage 3Draft起草——以代码为依据写内容配套技能/write-the-docs基于 Linear 工单与真实代码起草全新内容pm-the-docs可访问 universe 时用 universe否则走公开搜索或指定产品仓库。各角色勾选项P先讲 why 和产出再讲 how/what产品叙事优先P至少包含一个你真正运行过的、可复制粘贴的示例或将在 Self-review 阶段用/test-the-docs运行P/E跨仓库行为需经 universe 确认可访问时若功能不局限于supabase/supabase仓库则用公开gh search/指定产品仓库查证此查询走/pm-the-docs而非/ask-the-docsE提供技术深度并核验准确性API、限制、边界情况P在文中内联标注当前阶段如 GA与已知局限原文还有一条重要的分流规则如果工作是对既有页面的改进重构、排序、连接性文字、精简而非撰写全新内容应改用/edit-the-docs而非/write-the-docs。write-the-docs 技能 把 Draft 阶段展开为「先收集、后起草」的硬性纪律Gather before drafting——绝不能只凭工单标题动笔。四个输入按序读取① 风格参考apps/docs/CONTRIBUTING.md与apps/docs/WORD_LIST.md仅作语气/术语参考不是内容事实来源② Linear 工单及其父项目/计划描述产品定位语言通常在上层 PRD/PRFAQ 中③ 代码先读关联 PR 的 diff——它是最精确的「实际交付了什么」来源无 PR 时直接在supabase/supabase内定位功能代码与 PRD 冲突时行为论断以代码为准并标记差异④ 作者提供的其他材料截图用于核对精确的按钮/菜单/字段标签——UI 标签写错是最容易避免却最常见的错误。四类事实分离确认行为代码、产品意图Linear/PRD、推断显式标注三者不得混写。写时纪律为「永恒性」写作优先记录现状而非承诺未来功能用段落替代单元素列表避免重复定稿前剥离所有内部业务上下文PRD 意图、路线图猜测、工单讨论内部假设放到 PR 描述中而不是发布内容里。Stage 4Self-review自审——开 PR 前对照标准配套技能/review-the-docs的 local self-review 流程/test-the-docs运行代码片段并产出验证报告。勾选项P/E开 PR 前对照 What good looks like 逐项检查P/E完成/test-the-docs运行验证报告就绪可贴进 PR 正文P/E条件允许时遵循 Authoring Experience 标准与工具从 review-the-docs 技能 可以看到自审的具体命令形态在特性分支上先git diff --name-only master...HEAD分类变更类型然后按类型跑检查——内容型 MDX 跑cd apps/docs pnpm lint:mdx管线/schema handler 变更跑pnpm build:guides-markdown并检查public/markdown/guides/产物最后写一段区分 blockers 与 nits 的自审笔记直接放进未来 PR 正文的 Self-review 小节。而 test-the-docs 技能 则落实了质量标准第 4 条「示例必须已验证」的机制。其核心规则是绝不打生产只用本地栈或临时目录绝不在宿主 shell 上跑 MDX 代码围栏一律走 Compose 沙箱sandbox-setup.md 与sandbox/run.sh比例原则Tier A一条端到端路径必做Tier B 只抽查新增/变更的程序性代码块测试中发现的产品 bug单独关联或另开工单只有文档本身写错才改文档。沙箱的执行模型值得展开宿主只负责 Docker Compose 生命周期每个 MDX 围栏shell、SQL、JS/TS、example-app 构建都在一次性runner容器内以非 root 用户执行。生命周期命令在 sandbox 目录 下# 栈档案DinD runner在 /work 内 supabase init/start ./run.sh up-stack # 有截止时间的围栏执行超时杀掉进程组 ./run.sh exec-timeout 60 -- bash -lc eval $(supabase status -o env | grep -E ^(API_URL|DB_URL|DATABASE_URL)); psql $DB_URL -c select 1 # 示例应用档案无 DinD挂载应用后构建 TTD_EXAMPLE_DIR/path/to/repo/examples/auth/hono ./run.sh up-examples ./run.sh exec-timeout 300 -- bash -lc cd /work/example npm install npm run build # 结束必须拆除 ./run.sh down配套的安全护栏包括只捕获连接 URL、绝不把PUBLISHABLE_KEY、SECRET_KEY、JWT_SECRET等凭据字段写进报告或日志curl/wget只允许访问本地栈 URLnpm/node只用于挂载的example-app构建某个工件类的前置条件缺失时标记deferred并记录原因绝不静默跳过。Stage 5PR review评审配套技能/review-the-docs负责分诊、分类、验证构建并出具报告。勾选项P/E按参与规则rules of engagement开 PR 并请求评审Docs对照已发布的质量标准the bar评审review-the-docs 技能 给出了该阶段的完整方法先用gh pr list/view/diff分诊先分类再评审路径信号决定适用哪份检查表apps/docs/internals/markdown-schema/是 schema handler、apps/docs/content/**是纯内容、examples/**是示例应用、.agents/skills/是文档工具链等堆叠 PR 自底向上逐个评审本地跑类型化验证不靠 diff 盲批需要时用 master 做基线对比最后输出统一评审报告含 Approve / Approve with nits / Request changes 三档判定与合并顺序建议。Stage 6Keep it honest保持诚实勾选项只有一条却定义了文档的长期义务P产品发布清单中「day 1 开始」的文档门槛要保持诚实直到功能上线——阶段或行为变化时同步更新文档这是对质量标准的收束文档不是上线瞬间的快照而是随产品阶段滚动维护的承诺。跨仓库事实核查universe capability gate清单中反复出现的「cross-repo 行为确认」由 universe-lookup.md 细化。它服务 Frame/Shape 阶段当功能可能横跨多个服务CLI、Auth、migrations、Dashboard、平台……时需要确认行为究竟落在一个仓库还是多个仓库。其核心是能力门控capability gate在运行任何 universe 克隆或 submodule 命令之前先跑本地克隆按序解析 universe 根目录先$SUPABASE_UNIVERSE_ROOT再$HOME/GitHub/supabase/universeUNIVERSE_ROOT${SUPABASE_UNIVERSE_ROOT:-$HOME/GitHub/supabase/universe} [[ -d $UNIVERSE_ROOT/.git || -f $UNIVERSE_ROOT/.git ]] echo local universe ok存在本地检出即走加速器路径跳过gh api探测。否则探测 org 访问只读、不克隆gh api repos/supabase/universe -q .full_name。成功则允许以--recurse-submodules克隆后检索返回 404/403 则只能走 OSS 路径不得对 universe 执行git clone或git submodule update。OSS 路径对所有人始终有效搜索公开代码gh search code --owner supabase query加工单中点名的公开 owner、阅读已检出或工单关联的产品仓库、优先用supabase/supabase仓内源码并在 Frame/Shape 总结中记录universe: unavailable (OSS)及使用的公开来源。原文强调Never treat missing universe access as a blocker or an incomplete Frame/Shape——没有 universe 权限是成功结果而非失败。加速器路径下私有子模块platform、branching可能需要 PAT失败就记录缺口并用公开子模块加 OSS 搜索继续。检索起点是一张「找什么→去哪找」的映射表schema/扩展/RLS 看repos/postgres/、repos/postgrest/、repos/pg-toolbelt/Auth 流程看repos/auth/与repos/supabase-js/下的auth-jsRealtime/Storage/Edge Functions 看各自repos/子模块Dashboard/Studio 看repos/supabase/apps/studioCLI、本地开发、config.toml看repos/cli/文档与自托管 Compose 看repos/supabase/apps/docs、docker/。在 Frame/Shape 中使用的五步法① 列出发布可能触及的产品面CLI、Auth、migrations、Dashboard……② 跑 capability gate③ 把产品面解析到仓库universe 子模块或公开搜索/关联检出④ 用一次简短检索确认行为在单仓还是多仓⑤ 在总结中记录 gate 结果、所查仓库、跨切面还是单仓、以及缺口。结尾再次强调永远区分已确认事实与推断。Ask the Docs PM自助与升级的边界清单的 Ask the Docs PM 小节定义了何时自己动手、何时找人自助上述清单足够清晰、标准已存在、且你已知道产品阶段与受众需要问范围或阶段不清晰、需要一条评审路径、质量门槛有歧义或发布文档触及跨切面表面quick starts、API keys、tutorials、onboarding、platform concepts;预期Docs PM 是提问、技能赋能与「对照 bar 评审」的对接人在哪问你团队的 PR 评审频道 当前 Docs PM在 contributor guide 里确认今天是谁。pm-the-docs 的 SKILL.md 的 Self-serve vs. escalate 一节与此完全一致二者互为镜像。关键文件索引文件内容write-the-docs-checklist.md本文主体六阶段写作清单与质量标准pm-the-docs/SKILL.md支撑 Frame/Shape 阶段的决策方法、自助/升级判断universe-lookup.md跨仓库产品核查capability gate、OSS 路径、加速器write-the-docs/SKILL.mdDraft 阶段的收集纪律、内容类型 gate、交接规则test-the-docs/SKILL.md 与 sandbox-setup.md沙箱执行模型、生命周期命令与安全护栏review-the-docs/SKILL.md自审与 PR 评审的分类表、类型化检查与报告模板apps/docs/CONTRIBUTING.md写作总则、四类文档定义、技能-阶段映射表apps/docs/WORD_LIST.md术语与措辞参考Draft/自审的合规依据这套清单的价值在于把「写好文档」从个人手感变成了可勾选、可分工、可验证的工程流程每个阶段有明确的角色责任与勾选项每个关键判断阶段、受众、内容类型、跨仓库范围有对应的技能文件与命令级工具支撑且所有验证都发生在 Docker 隔离的本地环境中——读者可以据此在自己的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Supabase《Write the docs》六阶段文档写作清单全解
Supabase《Write the docs》六阶段文档写作清单全解【免费下载链接】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/supabaseSupabase 仓库在 .agents/skills/pm-the-docs/reference/write-the-docs-checklist.md 中沉淀了一套「Write the docs」文档写作清单它用六个轻量阶段Frame、Shape、Draft、Self-review、PR review、Keep it honest规定了产品文档从规划、起草到评审的完整路径并明确 Product、Engineering、Docs 三类角色各自承担的检查项。读完本文你将掌握这套清单的质量标准What good looks like、每个阶段的勾选式检查点、与之配套的六个 AI Agent 技能pm-the-docs、ask-the-docs、write-the-docs、edit-the-docs、test-the-docs、review-the-docs的分工以及跨仓库事实核查universe lookup的能力门控与 OSS 回退路径可以据此为任何 Supabase 功能撰写、验证并评审符合官方标准的文档页面。清单的设计目标与角色模型清单开篇定义了三个角色缩写全文的检查项都以此为责任主体P Product产品E Engineering工程Docs Docs team文档团队写作流程被刻意设计为「六个短阶段」原文明确说明Keep it lightweight; the point is to make good docs the default, not to add ceremony——目标是让好文档成为默认结果而不是增加流程仪式感。原文还强调Self-serve first能自助完成的不要打扰人需要时再找 Docs 团队的 PM该技能入口见 pm-the-docs SKILL。这套清单不是孤立文件。它是 pm-the-docs 技能的镜像参考文件——pm-the-docs的 SKILL.md 自述它「backs the Frame and Shape stages of the Write the docs checklist」即专门支撑清单的前两个阶段。而 apps/docs/CONTRIBUTING.md 的「AI agent skills for docs authoring」一节进一步把清单与六个技能绑定技能对应清单阶段用途pm-the-docsFrame / Shape受众、产品阶段、跨切面范围判断有 Supabase org 访问权时用 universe否则走 OSS 路径ask-the-docsFrame / Shapeapps/docs架构、IA 放置、内容存放位置write-the-docsDraft以代码为依据起草全新内容edit-the-docsEdit重构与改进既有页面test-the-docsDraft / Self-review在 Docker 隔离的本地栈中执行文档代码片段并产出验证报告review-the-docsSelf-review / PR review草稿自审与 PR 分诊/验证从源码结构看规范文件的落盘位置也有讲究技能规范统一放在.agents/skills/canonical 位置.claude/skills是指向该目录的 Git 符号链接以便 Claude Code 等 Agent 自动发现review-the-docs 的「Docs tooling review」检查项也要求维护这一结构不被破坏如readlink .claude/skills应等于../.agents/skills。What good looks like质量标准清单开宗明义给出七条质量基线原文What good looks like小节后续每个阶段的勾选项都服务于它The why is explicit——读者应学到「这个功能解决什么问题、什么场景下该用它」而不只是操作步骤The content type is deliberate——内容类型要刻意选定且在一页之内保持一致Audience and prerequisites are stated up front——受众与前置条件在页面开头声明Examples are runnable and have been tested——示例必须可运行且已验证过命令、代码、预期结果并明确用/test-the-docs在Docker 隔离的本地栈上验证而非打生产环境Correct stage like GA is stated——如实声明功能所处阶段alpha/beta/GA并诚实列出局限The page lives in the right place——页面在信息架构IA中位置正确并与相关页面双向链接术语与排版和现有文档保持一致待风格指南落地后再对齐风格指南。六阶段流程Stage 1Frame定框——回答给谁写、为什么写配套技能用/ask-the-docs了解 docs 站当前的运作方式用/pm-the-docs确定受众、阶段与跨切面范围可访问 universe 时做跨仓库探查参见 universe-lookup.md。PProduct需完成的勾选项声明产品阶段private/public alpha、beta、GA指明受众和他们要完成的 jobjob-to-be-done用一句话写清这个功能为什么存在它解决什么问题而不只是它做了什么pm-the-docs 的 SKILL.md 给出了执行 Frame 阶段的具体方法先读清单中对应阶段的勾选项它们精确定义了要做的决定再读该功能已有的一切上下文关联 issue、项目、PRD、已上线代码或 PR当代码与 PRD 冲突时行为论断以代码为准若功能可能横跨多个服务CLI、Auth、migrations、Dashboard、平台等必须先走 universe-lookup 的 capability gate 再落定 Frame/Shape并记录搜索过哪些仓库最后直接回答清单的问题阶段、受众与 JTBD、一句话 why、内容类型、IA 位置、前置条件并且始终区分已确认事实ticket/PRD/代码中明确写出的与推断你的最佳解读推断必须显式标注而不能装作既定结论。若某个决定在组织层面尚未拍板而非文档写作层面的判断应明说并指出该由谁决定而不是编一个答案充数。Stage 2Shape塑形——回答写成什么类型、放在哪里配套技能/ask-the-docs用于 IA 放置、架构与内容位置判断。P 需完成的勾选项选定内容类型tutorial学习、how-to完成任务、reference查阅、explanation解释为什么。一页内不要混用类型原文参照 Diátaxis 框架决定页面在现有 IA 中的位置以及哪些链接进出此页避免孤儿页面在开头列出前置条件与假定知识这里的「内容类型」在 apps/docs/CONTRIBUTING.md 中有更细的定义可视为 Shape 阶段的落点参考Explainers概念性、以散文为主讲 what/why/when/how 的高层原理不含使用步骤Tutorials目标导向帮助读者完成一个大型复杂目标如搭一个用到多个 Supabase 功能的 Web 应用叙述与步骤混合并解释为什么给这些指令Guides面向更短、更聚焦的任务如为应用配置登录以步骤为主。CONTRIBUTING.md 还要求 Guide 开篇声明意图如 This guide explains how to set up email login.把背景概念拆到独立小节或 explainer 并交叉引用权威解释保持操作路径可扫读Reference事实性、简明如字典条目包含函数参数、返回类型、代码示例、关键错误警告不包含背景解释、用例示例或多步指令。此外从 write-the-docs 的 SKILL.md 可以看到仓库对 Reference 类内容的工程约束reference 页面是由spec/目录OpenAPI、SDK YAML、CLI 配置经代码生成管线产出的features/docs/generated/**不走手工 MDX 路径。如果实际需求是新增 API 端点、配置项或 SDK 方法这类 reference 条目正确做法是指向 spec/codegen 管线apps/docs/spec/、apps/docs/generator/而不是手写一个看起来完成但会被生成器覆盖的页面——这就是 Shape 阶段「content type gate」的实操含义。Stage 3Draft起草——以代码为依据写内容配套技能/write-the-docs基于 Linear 工单与真实代码起草全新内容pm-the-docs可访问 universe 时用 universe否则走公开搜索或指定产品仓库。各角色勾选项P先讲 why 和产出再讲 how/what产品叙事优先P至少包含一个你真正运行过的、可复制粘贴的示例或将在 Self-review 阶段用/test-the-docs运行P/E跨仓库行为需经 universe 确认可访问时若功能不局限于supabase/supabase仓库则用公开gh search/指定产品仓库查证此查询走/pm-the-docs而非/ask-the-docsE提供技术深度并核验准确性API、限制、边界情况P在文中内联标注当前阶段如 GA与已知局限原文还有一条重要的分流规则如果工作是对既有页面的改进重构、排序、连接性文字、精简而非撰写全新内容应改用/edit-the-docs而非/write-the-docs。write-the-docs 技能 把 Draft 阶段展开为「先收集、后起草」的硬性纪律Gather before drafting——绝不能只凭工单标题动笔。四个输入按序读取① 风格参考apps/docs/CONTRIBUTING.md与apps/docs/WORD_LIST.md仅作语气/术语参考不是内容事实来源② Linear 工单及其父项目/计划描述产品定位语言通常在上层 PRD/PRFAQ 中③ 代码先读关联 PR 的 diff——它是最精确的「实际交付了什么」来源无 PR 时直接在supabase/supabase内定位功能代码与 PRD 冲突时行为论断以代码为准并标记差异④ 作者提供的其他材料截图用于核对精确的按钮/菜单/字段标签——UI 标签写错是最容易避免却最常见的错误。四类事实分离确认行为代码、产品意图Linear/PRD、推断显式标注三者不得混写。写时纪律为「永恒性」写作优先记录现状而非承诺未来功能用段落替代单元素列表避免重复定稿前剥离所有内部业务上下文PRD 意图、路线图猜测、工单讨论内部假设放到 PR 描述中而不是发布内容里。Stage 4Self-review自审——开 PR 前对照标准配套技能/review-the-docs的 local self-review 流程/test-the-docs运行代码片段并产出验证报告。勾选项P/E开 PR 前对照 What good looks like 逐项检查P/E完成/test-the-docs运行验证报告就绪可贴进 PR 正文P/E条件允许时遵循 Authoring Experience 标准与工具从 review-the-docs 技能 可以看到自审的具体命令形态在特性分支上先git diff --name-only master...HEAD分类变更类型然后按类型跑检查——内容型 MDX 跑cd apps/docs pnpm lint:mdx管线/schema handler 变更跑pnpm build:guides-markdown并检查public/markdown/guides/产物最后写一段区分 blockers 与 nits 的自审笔记直接放进未来 PR 正文的 Self-review 小节。而 test-the-docs 技能 则落实了质量标准第 4 条「示例必须已验证」的机制。其核心规则是绝不打生产只用本地栈或临时目录绝不在宿主 shell 上跑 MDX 代码围栏一律走 Compose 沙箱sandbox-setup.md 与sandbox/run.sh比例原则Tier A一条端到端路径必做Tier B 只抽查新增/变更的程序性代码块测试中发现的产品 bug单独关联或另开工单只有文档本身写错才改文档。沙箱的执行模型值得展开宿主只负责 Docker Compose 生命周期每个 MDX 围栏shell、SQL、JS/TS、example-app 构建都在一次性runner容器内以非 root 用户执行。生命周期命令在 sandbox 目录 下# 栈档案DinD runner在 /work 内 supabase init/start ./run.sh up-stack # 有截止时间的围栏执行超时杀掉进程组 ./run.sh exec-timeout 60 -- bash -lc eval $(supabase status -o env | grep -E ^(API_URL|DB_URL|DATABASE_URL)); psql $DB_URL -c select 1 # 示例应用档案无 DinD挂载应用后构建 TTD_EXAMPLE_DIR/path/to/repo/examples/auth/hono ./run.sh up-examples ./run.sh exec-timeout 300 -- bash -lc cd /work/example npm install npm run build # 结束必须拆除 ./run.sh down配套的安全护栏包括只捕获连接 URL、绝不把PUBLISHABLE_KEY、SECRET_KEY、JWT_SECRET等凭据字段写进报告或日志curl/wget只允许访问本地栈 URLnpm/node只用于挂载的example-app构建某个工件类的前置条件缺失时标记deferred并记录原因绝不静默跳过。Stage 5PR review评审配套技能/review-the-docs负责分诊、分类、验证构建并出具报告。勾选项P/E按参与规则rules of engagement开 PR 并请求评审Docs对照已发布的质量标准the bar评审review-the-docs 技能 给出了该阶段的完整方法先用gh pr list/view/diff分诊先分类再评审路径信号决定适用哪份检查表apps/docs/internals/markdown-schema/是 schema handler、apps/docs/content/**是纯内容、examples/**是示例应用、.agents/skills/是文档工具链等堆叠 PR 自底向上逐个评审本地跑类型化验证不靠 diff 盲批需要时用 master 做基线对比最后输出统一评审报告含 Approve / Approve with nits / Request changes 三档判定与合并顺序建议。Stage 6Keep it honest保持诚实勾选项只有一条却定义了文档的长期义务P产品发布清单中「day 1 开始」的文档门槛要保持诚实直到功能上线——阶段或行为变化时同步更新文档这是对质量标准的收束文档不是上线瞬间的快照而是随产品阶段滚动维护的承诺。跨仓库事实核查universe capability gate清单中反复出现的「cross-repo 行为确认」由 universe-lookup.md 细化。它服务 Frame/Shape 阶段当功能可能横跨多个服务CLI、Auth、migrations、Dashboard、平台……时需要确认行为究竟落在一个仓库还是多个仓库。其核心是能力门控capability gate在运行任何 universe 克隆或 submodule 命令之前先跑本地克隆按序解析 universe 根目录先$SUPABASE_UNIVERSE_ROOT再$HOME/GitHub/supabase/universeUNIVERSE_ROOT${SUPABASE_UNIVERSE_ROOT:-$HOME/GitHub/supabase/universe} [[ -d $UNIVERSE_ROOT/.git || -f $UNIVERSE_ROOT/.git ]] echo local universe ok存在本地检出即走加速器路径跳过gh api探测。否则探测 org 访问只读、不克隆gh api repos/supabase/universe -q .full_name。成功则允许以--recurse-submodules克隆后检索返回 404/403 则只能走 OSS 路径不得对 universe 执行git clone或git submodule update。OSS 路径对所有人始终有效搜索公开代码gh search code --owner supabase query加工单中点名的公开 owner、阅读已检出或工单关联的产品仓库、优先用supabase/supabase仓内源码并在 Frame/Shape 总结中记录universe: unavailable (OSS)及使用的公开来源。原文强调Never treat missing universe access as a blocker or an incomplete Frame/Shape——没有 universe 权限是成功结果而非失败。加速器路径下私有子模块platform、branching可能需要 PAT失败就记录缺口并用公开子模块加 OSS 搜索继续。检索起点是一张「找什么→去哪找」的映射表schema/扩展/RLS 看repos/postgres/、repos/postgrest/、repos/pg-toolbelt/Auth 流程看repos/auth/与repos/supabase-js/下的auth-jsRealtime/Storage/Edge Functions 看各自repos/子模块Dashboard/Studio 看repos/supabase/apps/studioCLI、本地开发、config.toml看repos/cli/文档与自托管 Compose 看repos/supabase/apps/docs、docker/。在 Frame/Shape 中使用的五步法① 列出发布可能触及的产品面CLI、Auth、migrations、Dashboard……② 跑 capability gate③ 把产品面解析到仓库universe 子模块或公开搜索/关联检出④ 用一次简短检索确认行为在单仓还是多仓⑤ 在总结中记录 gate 结果、所查仓库、跨切面还是单仓、以及缺口。结尾再次强调永远区分已确认事实与推断。Ask the Docs PM自助与升级的边界清单的 Ask the Docs PM 小节定义了何时自己动手、何时找人自助上述清单足够清晰、标准已存在、且你已知道产品阶段与受众需要问范围或阶段不清晰、需要一条评审路径、质量门槛有歧义或发布文档触及跨切面表面quick starts、API keys、tutorials、onboarding、platform concepts;预期Docs PM 是提问、技能赋能与「对照 bar 评审」的对接人在哪问你团队的 PR 评审频道 当前 Docs PM在 contributor guide 里确认今天是谁。pm-the-docs 的 SKILL.md 的 Self-serve vs. escalate 一节与此完全一致二者互为镜像。关键文件索引文件内容write-the-docs-checklist.md本文主体六阶段写作清单与质量标准pm-the-docs/SKILL.md支撑 Frame/Shape 阶段的决策方法、自助/升级判断universe-lookup.md跨仓库产品核查capability gate、OSS 路径、加速器write-the-docs/SKILL.mdDraft 阶段的收集纪律、内容类型 gate、交接规则test-the-docs/SKILL.md 与 sandbox-setup.md沙箱执行模型、生命周期命令与安全护栏review-the-docs/SKILL.md自审与 PR 评审的分类表、类型化检查与报告模板apps/docs/CONTRIBUTING.md写作总则、四类文档定义、技能-阶段映射表apps/docs/WORD_LIST.md术语与措辞参考Draft/自审的合规依据这套清单的价值在于把「写好文档」从个人手感变成了可勾选、可分工、可验证的工程流程每个阶段有明确的角色责任与勾选项每个关键判断阶段、受众、内容类型、跨仓库范围有对应的技能文件与命令级工具支撑且所有验证都发生在 Docker 隔离的本地环境中——读者可以据此在自己的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考