Supabase pm-the-docs文档创作 Frame/Shape 阶段的决策支持技能——受众、产品阶段与跨仓库范围判定【免费下载链接】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 仓库中的 pm-the-docs 技能定义 及其两个参考文件 write-the-docs-checklist.md 和 universe-lookup.md 展开讲解这个面向 AI Agent 的 Docs-PM 决策支持 技能如何工作它负责在正式动笔写文档之前替作者完成受众定位、产品阶段alpha/beta/GA、内容类型与信息架构位置的判断以及在功能横跨多个产品仓库CLI、Auth、migrations、platform 等时如何跨仓库查证事实。读完本文你将理解 Supabase 仓库如何用一套结构化的六阶段清单和能力门控capability gate机制把产品负责人会做的判断沉淀为可被 Agent 复用的流程并能判断何时该自行决策、何时必须升级给文档 PM。pm-the-docs 在文档创作流水线中的定位Supabase 仓库为文档创作流程提供了一组 Agent 技能分别对应 Write the docs 清单 的六个阶段。CONTRIBUTING.md 中的技能总表说明了分工技能清单阶段用途pm-the-docsFrame / Shape受众、产品阶段、跨切面范围判定有 Supabase 组织权限时用 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 分诊/验证pm-the-docs的定位是背稿前的 PM它不写内容。技能定义中的 Not for 部分明确划界——起草内容本身用write-the-docs重构现有页面用edit-the-docs运行代码片段用test-the-docs文档应用架构/IA 布局机制用ask-the-docs。它专门回答的是 Frame定位和 Shape塑形两个阶段的问题产品阶段是什么、给谁看、为什么做、内容类型怎么定、放在 IA 的哪个位置、前置知识是什么、这次发布是否横跨多个产品仓库。调用时机技能定义的 When to invoke 列出四类场景开始一个新的文档页面或一次发布需要在动笔前说清楚产品阶段、受众和 whyFrame需要为某个页面决定内容类型、IA 位置或前置条件Shape判断一次发布是否横跨多个产品仓库CLI、Auth、migrations、platform……此时要遵循 universe-lookup.md 的跨仓库查证流程不确定一个文档问题应该自行解决还是升级给文档 PM 签核。回答范围/阶段/受众问题的六步流程技能定义给出了一个明确的回答流程每一步都可直接操作读对应阶段的清单。打开 write-the-docs-checklist.md找到 Frame 或 Shape 小节——那里的复选框精确列出了需要决定什么。读完该功能存在的所有上下文关联的 issue/项目、PRD、已发布的代码或 PR。规则很硬当代码和 PRD 不一致时以代码为准针对行为类论断。涉及多服务时先过能力门控。当范围可能横跨服务CLI、Auth、migrations、Dashboard、platform……时在敲定 Frame/Shape 之前必须先执行 universe-lookup.md 的 capability gateuniverse 可访问就用它否则走 OSS 路径并记录你搜索过哪些仓库。直接回答清单问题产品阶段、受众与 job-to-be-done、一句话 why、内容类型、IA 位置、前置条件。区分确认的事实与推断。事实是工单/PRD/代码中明确写出的推断是你自己的最佳解读——必须显式标注不能伪装成已定论。组织级悬而未决的决定直说。如果某个决定在组织层面本来就开放而非文档创作层面的判断要说出来并指明该由谁决定而不是编一个答案来显得完整。六阶段清单镜像What good looks like 与 Frame/Shape 详解write-the-docs-checklist.md 是 Write the docs 清单的完整镜像角色标注为P 产品、E 工程、Docs 文档团队。清单开篇即声明质量底线What good looks likewhy 必须显式读者能知道这篇文档解决什么问题、何时该用它而不只是步骤内容类型是刻意选择的且单页内保持一致受众和前置条件在开头就写明示例可运行且经过实测命令、代码、预期结果——用/test-the-docs对着 Docker 隔离的本地栈验证而不是对着生产环境正确的阶段如 GA被明确声明局限性诚实命名页面位于 IA 的正确位置与相关页面双向链接术语和格式与现有文档一致。阶段 1Frame对应技能是/ask-the-docs了解文档表面现状与/pm-the-docs受众、阶段、跨切面范围含 universe 查证。Frame 阶段的复选框P陈述产品阶段private/public alpha、beta、GAP点名受众及其正在完成的 jobP用一句话写清楚功能为什么存在它解决的问题而不只是它做什么阶段 2Shape对应技能是/ask-the-docsIA 位置、架构、内容落位。复选框P选择内容类型tutorial学习、how-to任务、reference查阅、explanation为什么——不要在一页上混合类型参考 Diátaxis 框架P决定页面在现有 IA 中的位置、哪些链接进出避免孤儿页面P在开头列出前置条件和默认知识清单的后续阶段 3Draft/write-the-docs、4Self-review/review-the-docs/test-the-docs、5PR review/review-the-docs、6Keep it honest——保持发布清单中 start on day 1 文档门禁在上线过程中持续诚实不属于 pm-the-docs 的职责但该镜像文件将它们完整保留使 Frame/Shape 的决定能与后三个阶段衔接。值得注意的一个交叉引用Draft 阶段要求跨仓库行为在可访问时经 universe 确认否则走公开gh search/具名产品仓库且查证入口是/pm-the-docs而非/ask-the-docs——这与技能定义中跨仓库产品查证属于 pm-the-docs跨仓库文档应用架构才属于 ask-the-docs的划界完全一致。Ask the Docs PM自行处理还是升级镜像文件中的 Ask the Docs PM 小节与技能定义的 Self-serve vs. escalate 呼应自行处理self-serve清单清晰、标准存在、你已知道产品阶段和受众。升级escalate范围或阶段不明确、需要评审路径、标准模糊、或发布文档触及跨切面表面quickstarts、API keys、tutorials、onboarding、platform concepts。跨仓库产品查证capability gate、universe 加速器与 OSS 路径这是 pm-the-docs 最具操作性的部分完整规则在 universe-lookup.md。核心前提跨仓库确认对所有人都必需私有元仓库supabase/universe只是一个可选加速器有 Supabase 组织权限且最好有本地 clone 时使用没有该权限的贡献者走 OSS 路径——那是成功结局不是失败。能力门控流程在任何 universe clone 或 submodule 命令之前先跑这个门控第 1 步检查本地 clone按顺序解析 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该 checkout 存在 → 走加速器路径跳过gh api探测。第 2 步否则探测组织权限只读不 clonegh api repos/supabase/universe -q .full_name结果下一步成功返回supabase/universe加速器路径可以--recurse-submodulesclone或请用户代做然后搜索404、403 或其他失败仅 OSS 路径——不要对 universe 执行git clone或git submodule updateOSS 路径永远有效当门控判定 universe 不可用时搜索公开代码gh search code --owner supabase query加上工单中点名的其他公开 owner阅读已 checkout 的、或从 Linear/PR 链接过来的任何产品仓库足够时在树内supabase/supabase源码中查找优先在 Frame/Shape 总结中记录universe: unavailable (OSS)并列出用到的公开来源。规则最后强调永远不要把 universe 不可用当作阻塞项或不完整的 Frame/Shape。加速器路径在 universe 可访问时优先使用已有本地 clone只在门控通过后才 init/update submodulecd $UNIVERSE_ROOT git submodule update --init --recursive私有 submoduleplatform、branching可能需要 PAT失败时记录缺口用公开 submodule 加 OSS 搜索路径继续。从 universe README 的 Finding your way around 表出发然后在相应 submodule 内用rg搜索定位表如下找什么从哪开始Schema、扩展、RLSrepos/postgres/、repos/postgrest/、repos/pg-toolbelt/Auth 流程repos/auth/、repos/supabase-js/下的auth-jsRealtime / Storage / Edge Functionsrepos/realtime/、repos/storage/、repos/edge-runtime/Dashboard / Studiorepos/supabase/apps/studioManagement API / 托管基础设施repos/platform/私有CLI、本地开发、config.tomlrepos/cli/文档与自托管 Composerepos/supabase/apps/docs、docker/范围不明时用紧密的正则在已初始化的repos/**中搜索而不是通读整棵目录树。在 Frame/Shape 中的使用方式点名发布可能触及的产品表面CLI、Auth、migrations、Dashboard……跑能力门控把表面解析到仓库universe submodule或公开搜索/关联 checkout用一次简短搜索确认行为在一个仓库还是多个仓库中在 Frame/Shape 总结中记录门控结果universe: available或universe: unavailable (OSS)、查阅过的仓库、跨切面还是单仓库、以及缺口。并且始终区分确认事实与推断。与相邻技能的协作边界从源码结构看六个文档技能构成一条有明确交接点的流水线pm-the-docs处于最前端write-the-docs 的 Phase 1Gather明确写着当 Linear 工单缺失且没有既有 Frame/Shape 产品意图输出时停止起草交接给pm-the-docsFrame和ask-the-docsShape/IA 未定时产品意图存在之后才恢复——即 Draft 技能内部不允许自己跑 Frame/Shape行为横跨服务时它同样要求走pm-the-docs→ universe-lookup 的能力门控而不是ask-the-docs。test-the-docs 的 When to invoke 与 Core rules 表明它消费 Draft 产出、在 Docker 隔离沙箱中执行片段并产出验证报告与 pm-the-docs 无职责重叠仅在 Related skills 中互为索引。ask-the-docs 专注于apps/docs应用本身MDX 管线、federated docs、build pipeline、GraphQL 端点等产品层面的跨仓库查证被刻意留在 pm-the-docs 一侧避免两个技能的知识域互相污染。适用前提与实践要点小结这套流程适用于使用 AI 编码代理Claude Code、Codex 或任何读取.agents/skills/的 agent的 Supabase 文档贡献场景技能规范文件位于.agents/skills/apps/docs/CONTRIBUTING.md说明.claude/skills是指向该目录的 Git 符号链接Claude Code 中可用作/pm-the-docs等斜杠命令。三条硬性规则值得单独记住代码与 PRD 冲突时以代码为准universe 权限缺失不是失败OSS 路径是永远有效的完整方案组织级未决问题不要代答指名该由谁决定。若要在当前仓库中继续深入可对照阅读write-the-docs-checklist.md六阶段清单与 What good looks like 全文、universe-lookup.md门控与查证规则全文、write-the-docs 技能Draft 阶段的四个输入与内容类型门控、test-the-docs 技能 及其sandbox/run.sh验证沙箱的生命周期驱动以及 apps/docs/CONTRIBUTING.md 中的技能总表与文档写作规范。【免费下载链接】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），仅供参考 
长河君 · 2026/9/7 3:15:37 · 阅读 1.2k Supabase pm-the-docs：文档创作 Frame/Shape 阶段的决策支持技能——受众、产品阶段与跨仓库范围判定
Supabase pm-the-docs文档创作 Frame/Shape 阶段的决策支持技能——受众、产品阶段与跨仓库范围判定【免费下载链接】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 仓库中的 pm-the-docs 技能定义 及其两个参考文件 write-the-docs-checklist.md 和 universe-lookup.md 展开讲解这个面向 AI Agent 的 Docs-PM 决策支持 技能如何工作它负责在正式动笔写文档之前替作者完成受众定位、产品阶段alpha/beta/GA、内容类型与信息架构位置的判断以及在功能横跨多个产品仓库CLI、Auth、migrations、platform 等时如何跨仓库查证事实。读完本文你将理解 Supabase 仓库如何用一套结构化的六阶段清单和能力门控capability gate机制把产品负责人会做的判断沉淀为可被 Agent 复用的流程并能判断何时该自行决策、何时必须升级给文档 PM。pm-the-docs 在文档创作流水线中的定位Supabase 仓库为文档创作流程提供了一组 Agent 技能分别对应 Write the docs 清单 的六个阶段。CONTRIBUTING.md 中的技能总表说明了分工技能清单阶段用途pm-the-docsFrame / Shape受众、产品阶段、跨切面范围判定有 Supabase 组织权限时用 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 分诊/验证pm-the-docs的定位是背稿前的 PM它不写内容。技能定义中的 Not for 部分明确划界——起草内容本身用write-the-docs重构现有页面用edit-the-docs运行代码片段用test-the-docs文档应用架构/IA 布局机制用ask-the-docs。它专门回答的是 Frame定位和 Shape塑形两个阶段的问题产品阶段是什么、给谁看、为什么做、内容类型怎么定、放在 IA 的哪个位置、前置知识是什么、这次发布是否横跨多个产品仓库。调用时机技能定义的 When to invoke 列出四类场景开始一个新的文档页面或一次发布需要在动笔前说清楚产品阶段、受众和 whyFrame需要为某个页面决定内容类型、IA 位置或前置条件Shape判断一次发布是否横跨多个产品仓库CLI、Auth、migrations、platform……此时要遵循 universe-lookup.md 的跨仓库查证流程不确定一个文档问题应该自行解决还是升级给文档 PM 签核。回答范围/阶段/受众问题的六步流程技能定义给出了一个明确的回答流程每一步都可直接操作读对应阶段的清单。打开 write-the-docs-checklist.md找到 Frame 或 Shape 小节——那里的复选框精确列出了需要决定什么。读完该功能存在的所有上下文关联的 issue/项目、PRD、已发布的代码或 PR。规则很硬当代码和 PRD 不一致时以代码为准针对行为类论断。涉及多服务时先过能力门控。当范围可能横跨服务CLI、Auth、migrations、Dashboard、platform……时在敲定 Frame/Shape 之前必须先执行 universe-lookup.md 的 capability gateuniverse 可访问就用它否则走 OSS 路径并记录你搜索过哪些仓库。直接回答清单问题产品阶段、受众与 job-to-be-done、一句话 why、内容类型、IA 位置、前置条件。区分确认的事实与推断。事实是工单/PRD/代码中明确写出的推断是你自己的最佳解读——必须显式标注不能伪装成已定论。组织级悬而未决的决定直说。如果某个决定在组织层面本来就开放而非文档创作层面的判断要说出来并指明该由谁决定而不是编一个答案来显得完整。六阶段清单镜像What good looks like 与 Frame/Shape 详解write-the-docs-checklist.md 是 Write the docs 清单的完整镜像角色标注为P 产品、E 工程、Docs 文档团队。清单开篇即声明质量底线What good looks likewhy 必须显式读者能知道这篇文档解决什么问题、何时该用它而不只是步骤内容类型是刻意选择的且单页内保持一致受众和前置条件在开头就写明示例可运行且经过实测命令、代码、预期结果——用/test-the-docs对着 Docker 隔离的本地栈验证而不是对着生产环境正确的阶段如 GA被明确声明局限性诚实命名页面位于 IA 的正确位置与相关页面双向链接术语和格式与现有文档一致。阶段 1Frame对应技能是/ask-the-docs了解文档表面现状与/pm-the-docs受众、阶段、跨切面范围含 universe 查证。Frame 阶段的复选框P陈述产品阶段private/public alpha、beta、GAP点名受众及其正在完成的 jobP用一句话写清楚功能为什么存在它解决的问题而不只是它做什么阶段 2Shape对应技能是/ask-the-docsIA 位置、架构、内容落位。复选框P选择内容类型tutorial学习、how-to任务、reference查阅、explanation为什么——不要在一页上混合类型参考 Diátaxis 框架P决定页面在现有 IA 中的位置、哪些链接进出避免孤儿页面P在开头列出前置条件和默认知识清单的后续阶段 3Draft/write-the-docs、4Self-review/review-the-docs/test-the-docs、5PR review/review-the-docs、6Keep it honest——保持发布清单中 start on day 1 文档门禁在上线过程中持续诚实不属于 pm-the-docs 的职责但该镜像文件将它们完整保留使 Frame/Shape 的决定能与后三个阶段衔接。值得注意的一个交叉引用Draft 阶段要求跨仓库行为在可访问时经 universe 确认否则走公开gh search/具名产品仓库且查证入口是/pm-the-docs而非/ask-the-docs——这与技能定义中跨仓库产品查证属于 pm-the-docs跨仓库文档应用架构才属于 ask-the-docs的划界完全一致。Ask the Docs PM自行处理还是升级镜像文件中的 Ask the Docs PM 小节与技能定义的 Self-serve vs. escalate 呼应自行处理self-serve清单清晰、标准存在、你已知道产品阶段和受众。升级escalate范围或阶段不明确、需要评审路径、标准模糊、或发布文档触及跨切面表面quickstarts、API keys、tutorials、onboarding、platform concepts。跨仓库产品查证capability gate、universe 加速器与 OSS 路径这是 pm-the-docs 最具操作性的部分完整规则在 universe-lookup.md。核心前提跨仓库确认对所有人都必需私有元仓库supabase/universe只是一个可选加速器有 Supabase 组织权限且最好有本地 clone 时使用没有该权限的贡献者走 OSS 路径——那是成功结局不是失败。能力门控流程在任何 universe clone 或 submodule 命令之前先跑这个门控第 1 步检查本地 clone按顺序解析 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该 checkout 存在 → 走加速器路径跳过gh api探测。第 2 步否则探测组织权限只读不 clonegh api repos/supabase/universe -q .full_name结果下一步成功返回supabase/universe加速器路径可以--recurse-submodulesclone或请用户代做然后搜索404、403 或其他失败仅 OSS 路径——不要对 universe 执行git clone或git submodule updateOSS 路径永远有效当门控判定 universe 不可用时搜索公开代码gh search code --owner supabase query加上工单中点名的其他公开 owner阅读已 checkout 的、或从 Linear/PR 链接过来的任何产品仓库足够时在树内supabase/supabase源码中查找优先在 Frame/Shape 总结中记录universe: unavailable (OSS)并列出用到的公开来源。规则最后强调永远不要把 universe 不可用当作阻塞项或不完整的 Frame/Shape。加速器路径在 universe 可访问时优先使用已有本地 clone只在门控通过后才 init/update submodulecd $UNIVERSE_ROOT git submodule update --init --recursive私有 submoduleplatform、branching可能需要 PAT失败时记录缺口用公开 submodule 加 OSS 搜索路径继续。从 universe README 的 Finding your way around 表出发然后在相应 submodule 内用rg搜索定位表如下找什么从哪开始Schema、扩展、RLSrepos/postgres/、repos/postgrest/、repos/pg-toolbelt/Auth 流程repos/auth/、repos/supabase-js/下的auth-jsRealtime / Storage / Edge Functionsrepos/realtime/、repos/storage/、repos/edge-runtime/Dashboard / Studiorepos/supabase/apps/studioManagement API / 托管基础设施repos/platform/私有CLI、本地开发、config.tomlrepos/cli/文档与自托管 Composerepos/supabase/apps/docs、docker/范围不明时用紧密的正则在已初始化的repos/**中搜索而不是通读整棵目录树。在 Frame/Shape 中的使用方式点名发布可能触及的产品表面CLI、Auth、migrations、Dashboard……跑能力门控把表面解析到仓库universe submodule或公开搜索/关联 checkout用一次简短搜索确认行为在一个仓库还是多个仓库中在 Frame/Shape 总结中记录门控结果universe: available或universe: unavailable (OSS)、查阅过的仓库、跨切面还是单仓库、以及缺口。并且始终区分确认事实与推断。与相邻技能的协作边界从源码结构看六个文档技能构成一条有明确交接点的流水线pm-the-docs处于最前端write-the-docs 的 Phase 1Gather明确写着当 Linear 工单缺失且没有既有 Frame/Shape 产品意图输出时停止起草交接给pm-the-docsFrame和ask-the-docsShape/IA 未定时产品意图存在之后才恢复——即 Draft 技能内部不允许自己跑 Frame/Shape行为横跨服务时它同样要求走pm-the-docs→ universe-lookup 的能力门控而不是ask-the-docs。test-the-docs 的 When to invoke 与 Core rules 表明它消费 Draft 产出、在 Docker 隔离沙箱中执行片段并产出验证报告与 pm-the-docs 无职责重叠仅在 Related skills 中互为索引。ask-the-docs 专注于apps/docs应用本身MDX 管线、federated docs、build pipeline、GraphQL 端点等产品层面的跨仓库查证被刻意留在 pm-the-docs 一侧避免两个技能的知识域互相污染。适用前提与实践要点小结这套流程适用于使用 AI 编码代理Claude Code、Codex 或任何读取.agents/skills/的 agent的 Supabase 文档贡献场景技能规范文件位于.agents/skills/apps/docs/CONTRIBUTING.md说明.claude/skills是指向该目录的 Git 符号链接Claude Code 中可用作/pm-the-docs等斜杠命令。三条硬性规则值得单独记住代码与 PRD 冲突时以代码为准universe 权限缺失不是失败OSS 路径是永远有效的完整方案组织级未决问题不要代答指名该由谁决定。若要在当前仓库中继续深入可对照阅读write-the-docs-checklist.md六阶段清单与 What good looks like 全文、universe-lookup.md门控与查证规则全文、write-the-docs 技能Draft 阶段的四个输入与内容类型门控、test-the-docs 技能 及其sandbox/run.sh验证沙箱的生命周期驱动以及 apps/docs/CONTRIBUTING.md 中的技能总表与文档写作规范。【免费下载链接】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），仅供参考