review-the-docs

审查文档 PR

针对 supabase/supabase 文档变更的本地审查工作流。先分类，再按照对应清单操作。

两种模式：

• 审查已开启的 PR（默认）——通过 gh 进行分流、检出、验证并报告。从 阶段 1 开始。
• 本地自我审查——尚未开启 PR；开启 PR 前先验证当前分支。从本地自我审查开始。

对于实施文档修复（Linear 工单、工作树、平台 E2E），请改用 work-linear-issue。

核心规则

1. 审查前先分类——路径模式决定适用哪份清单。
2. 从底向上审查堆叠的 PR——每个 PR 的基准分支可能是前一个分支。
3. 在本地运行验证——不要仅凭差异就批准。
4. 当 PR 声称修复了缺失或错误的输出时，与 master 比较。
5. 每批次提交一份报告——依次审查，最后汇总输出。
6. 区分阻碍项和细枝末节——类型或风格方面的说明属于建议，除非输出受到影响。

仓库布局

路径	用途
你的本地 supabase/supabase 检出目录	用于审查检出的主克隆
apps/docs/content/guides/	源 MDX
apps/docs/internals/	Markdown 流水线（generate-guides-markdown.ts 等）
apps/docs/internals/markdown-schema/	组件处理器 → 纯 Markdown 字符串
apps/docs/public/markdown/guides/	生成的输出（由构建生成）
apps/docs/components/	React MDX 组件
examples/	由 $CodeSample 引用的教程/快速入门应用
apps/studio/	控制面板 UI；可能会链接到托管的文档
.agents/skills/	仓库内的 Agent 技能（规范来源；.claude/skills 通过符号链接指向此处）

本地自我审查（尚未开启 PR）

在你自己的分支上、开启 PR 之前使用此流程（清单阶段 4）。无需使用 gh pr。

cd <your supabase/supabase checkout>
# Ensure you're on the feature branch, not master
git branch --show-current
git diff --name-only master...HEAD

1. 使用 阶段 2 表格，根据 git diff --name-only master...HEAD 进行分类。
2. 按照 pm-the-docs 的清单中的“理想效果”和自我审查复选框，逐项检查标准。
3. 在当前分支上根据对应部分运行特定类型的检查（无需检出步骤）。常用命令：

# Pipeline / schema handler
cd apps/docs && pnpm build:guides-markdown
# inspect public/markdown/guides/ for affected pages
pnpm build:reference-markdown   # when reference pipeline changed

4. 对内容变更抽查 frontmatter、内部链接和导航配置。
5. 提供可运行的验证——对于包含新增或变更的程序性围栏代码块的内容/教程 PR，询问是否运行 test-the-docs。前置条件因类别而异（DB/API 需要 Docker Compose 堆栈配置；example-app 需要 examples 配置）。如果对方同意，请附上验证报告；如果对方拒绝，或者该类别缺少必需的前置条件，则仅针对相应的产物记录可信的 deferred 原因。不要在此处重新实现沙箱执行。
6. 撰写简短的自我审查说明（区分阻碍项和细枝末节），以便粘贴到后续 PR 正文的“自我审查”标题下。

然后开启 PR；如需第二轮审查，再继续执行已开启 PR 的审查流程。

阶段 1 — 分流（只读）

列出 PR

按作者或标签筛选，或列出所有未关闭的文档 PR：

# By author
gh pr list --repo supabase/supabase --author <github-user> --state open \
  --json number,title,url,reviewDecision,latestReviews,changedFiles,additions,deletions,labels

# All open docs-labeled PRs
gh pr list --repo supabase/supabase --state open --label documentation \
  --json number,title,url,reviewDecision,latestReviews,author,changedFiles

reviewDecision 为空且没有 APPROVED 审查的 PR 需要批准。

绘制堆栈图

gh pr view <number> --repo supabase/supabase \
  --json number,title,baseRefName,headRefName,body,files

堆叠的系列：master → PR A → PR B → PR C。按从底向上的顺序审查并合并。

阶段 2 — 对 PR 类型进行分类

从 gh pr view 检查更改的文件，或运行：

gh pr diff <number> --repo supabase/supabase --name-only

PR 类型	路径信号	主要技能章节
Markdown-schema 处理器	apps/docs/internals/markdown-schema/、generate-guides-markdown.ts	Schema 处理器审查
流水线 / 内部实现	apps/docs/internals/（不只是一个新处理器）	流水线审查
仅内容 MDX	仅 apps/docs/content/**	内容审查
教程 / 快速入门	apps/docs/content/guides/**/tutorials/、quickstarts/，以及 examples/	教程审查 → 另请参阅 work-linear-issue
仅示例应用	examples/**，且没有匹配的 MDX	示例审查
Studio ↔ 文档链接	apps/studio/**	Studio 审查
文档 UI / 组件	apps/docs/components/、apps/docs/features/（无流水线）	组件审查
文档工具	.agents/skills/、apps/docs/AGENTS.md、apps/docs/CONTRIBUTING.md、apps/docs/DEVELOPERS.md、apps/docs/style-guide/	文档工具审查
混合类型	上述多个路径组	运行所有适用章节；注明重叠部分

当一个 PR 涉及多种类型（例如，Schema 处理器 + 组件重构）时，运行所有匹配的章节。

阶段 3 — 按顺序进行本地审查

对每个 PR（从堆栈底部开始）重复以下步骤。

通用步骤（适用于所有 PR 类型）

检出并安装：

cd <your supabase/supabase checkout>
gh pr checkout <number> --repo supabase/supabase
pnpm install --filter docs...   # when node_modules missing or deps changed

CI 抽查：

gh pr checks <number> --repo supabase/supabase

以 master 为基线（当 PR 修复缺失或损坏的输出时）：

git checkout master
# run type-specific verify command (see sections below)
git checkout -   # return to PR branch

---

Schema 处理器审查

适用于为 React MDX 组件添加静态 Markdown 回退内容的 PR。

代码检查 — apps/docs/internals/markdown-schema/ 中的每个处理器：

检查项	验证内容
数据源	与 React 组件使用相同的数据/常量 — 不重复配置
CJS 互操作	通过 createRequire(import.meta.url) 引入 shared-data（参见 SharedData.ts）
本地 JSON	apps/docs/data/ 可直接导入
链接前缀	链接使用 withDocsBasePath
SCHEMA 接线	已在 generate-guides-markdown.ts 的 SCHEMA 中注册
Props / 结构	覆盖所有 MDX 用法 — 扁平数组和 { items: [...] } 分节
静默回退	如果与现有处理器保持一致，未知 props 使用 '' 即可

查找用法：rg '<ComponentName' apps/docs/content/

构建并检查：

cd apps/docs && pnpm build:guides-markdown
# Expect: "Generated N markdown files" where N roughly matches the .mdx count under content/guides/

检查 public/markdown/guides/ 中受影响的页面：

• 之前空白的部分现在包含列表、表格或链接
• 所有使用该组件的 MDX 页面均已覆盖，而不只是 PR 描述中提到的页面
• 链接格式：本地使用 /docs/guides/...；当 VERCEL_ENV=production 时使用绝对 URL

---

流水线审查

适用于 AST 重构、链接重写、参考文档生成等。

cd apps/docs
pnpm build:guides-markdown
pnpm build:reference-markdown   # when reference pipeline changed
pnpm test:local:unwatch internals/internal-links.test.ts   # when link handling changed (needs local Supabase — see apps/docs/AGENTS.md)

如果修改了 generate-reference-markdown.ts 或 internal-links.ts，请同时验证指南和参考文档输出。

---

内容审查

MDX 正文、局部内容、导航 — 不涉及流水线或示例更改。

请自行根据风格指南检查正文。没有 CI 或本地检查会覆盖风格或术语。CodeRabbit 会审查 apps/docs/content/**/*.mdx 中的风格、术语和结构，但只有在 PR 开放后才会进行。

最后，按照与 AI Agent 一起使用中的两轮流程，对照 WORD_LIST.md 检查完成后的页面：先检查短语分组中的固定术语列表，然后运行 grep '^### ' WORD_LIST.md，只阅读与页面中出现的词语匹配的条目。也要包含作者未引入的术语。

检查清单：

• 语气符合 01-voice-and-tone.md
• 章节分组和内容分块符合 03-page-structure.md
• 组件符合 02-elements.md
• 术语符合 WORD_LIST.md
• Frontmatter 有效（需要时包含 title、description）
• 内部链接有效（使用 /docs/guides/...，而非失效的锚点）
• $CodeSample 路径与现有示例目录匹配
• PR 预览中，提示框、标签页和局部内容引入均能正常呈现
• 移除组件后，没有意外的纯空白或空内容章节
• 新增/更改的过程性代码片段已提供 test-the-docs；存在验证报告，或记录了可信的 deferred 原因

涉及布局组件时，请将 PR 预览 URL（来自 Vercel/部署评论）与生产环境对比，检查是否存在视觉回归。

---

教程审查

教程 MDX 及匹配的示例应用。阅读 work-linear-issue，了解完整的平台端到端流程 — 涉及身份验证流程时，未完成此项则审查不完整。

# Example build (from work-linear-issue)
cd examples/<example-dir>
npm install && npm run build

检查清单：

• 执行 pnpm codegen:examples 后，MDX 步骤与示例代码一致（如果使用了 $CodeSample）
• 环境变量名称和 Supabase 客户端设置符合当前的 @supabase/ssr 模式
• 示例固定使用目录中的版本 — 仓库内的包不能使用 "latest"
• 对于程序性教程步骤，提供了 test-the-docs（或标记为 deferred 并说明原因）
• 平台端到端（涉及身份验证时）：已应用 SQL 迁移、完整走过身份验证流程、验证了用户资料 — 参见 work-linear-issue 第 3 阶段

---

示例审查

仅涉及示例的 PR（或教程 PR 中的示例部分）。

cd examples/<example-dir>
npm install && npm run build

检查清单：

• 构建通过且没有类型错误
• .env.example 说明了必需的变量（未提交任何机密）
• 如果文档引用了此示例，$CodeSample 路径仍然有效

---

Studio 审查

链接到文档的仪表板变更。

检查清单：

• 链接指向已托管文档中的锚点（例如 /guides/auth/auth-email-templates#terminology）
• 不要仅将本地开发专用的文档路径用作链接目标
• 链接文本与目标章节相符

---

组件审查

对 apps/docs/components/ 下的 React 组件进行变更，但不新增架构处理程序。

检查清单：

• 仅限浏览器的 API 不会泄漏到构建脚本导入中
• Markdown 处理程序也会使用共享常量时，应妥善提取这些常量
• 视觉表现没有变化，或已得到有意改进 — 检查 PR 截图
• 如果组件用于导出为 Markdown 的 MDX，请确认存在架构处理程序，否则提交后续问题

---

文档工具审查

Agent 技能、贡献者文档或技能符号链接配置 — 无需更改 MDX/流水线。

检查清单：

• .agents/skills/ 是规范位置 — 不要在其他任何位置添加技能内容
• .claude/skills 仍是指向 ../.agents/skills 的单个 Git 符号链接 — 不要在 .claude/ 下创建单个技能的符号链接或副本
• 跨技能链接均可访问：仓库内技能使用相对链接；只有仍留在该私有仓库中的技能才使用绝对 docs-agent-skills URL
• 没有个人知识库路径、Obsidian 引用或仅适用于私有流程的说明
• apps/docs/CONTRIBUTING.md / DEVELOPERS.md / AGENTS.md 中的引用与技能名称和检查清单阶段相符
• 添加到技能中的样式规则应改放到 apps/docs/style-guide/，并在技能中链接到该规则
• 技能下的参考文件应遵守约 250 行的建议（过长时拆分）

# Symlink smoke check
test "$(readlink .claude/skills)" = "../.agents/skills"
test -f .claude/skills/<skill-name>/SKILL.md

# Leftover internal refs
rg -n 'Obsidian|pm-the-docs-full|Priorities/' .agents/skills

---

第 4 阶段 — 审查报告

审查完所有 PR 后，提交一份汇总报告。

报告模板

# PR review report — <author, label, or topic>

Reviewed locally in a `supabase/supabase` checkout.

**Stack order:** master → #NNN → … (if applicable)

---

## [#NNN — Title](https://github.com/supabase/supabase/pull/NNN)

**Type:** schema handler | pipeline | content | tutorial | example | studio | component | docs tooling | mixed

**Verdict:** Approve | Approve with nits | Request changes

| Check              | Result |
| ------------------ | ------ |
| PR type checks     | …      |
| Build / lint       | …      |
| Baseline vs master | …      |
| CI                 | …      |

**Verified:**

- …

**Notes:**

- …

---

## Summary

| PR   | Type | Recommendation | Blockers |
| ---- | ---- | -------------- | -------- |
| #NNN | …    | …              | …        |

**Merge order:** bottom-up after approval (if stacked).

结论指南

结论	适用情况
批准	所有特定类型的检查均已通过；输出正确
批准，但有小问题	功能正常；只有细微的类型、样式或文档问题
请求修改	构建/检查失败、链接失效、数据错误、覆盖缺失或平台端到端检查失败

行内审查评论

https://github.com/supabase/supabase/pull/<number>/files#diff-<blob-sha>R<line>

gh api repos/supabase/supabase/pulls/<number>/files \
  --jq '.[] | select(.filename | endswith("<file>")) | .sha'

请提供具体证据 — JSON 行号、前后输出片段、失败的命令输出。

处理程序模式参考

// apps/docs/internals/markdown-schema/Example.ts
import { withDocsBasePath } from '../internal-links'

export const Example = ({ props }: { props: Record<string, unknown> }): string => {
  // Same data source as React component → plain markdown string
}

并行工作

相互独立的 PR：子 Agent 可以在各自的工作树中分别审查。堆叠的系列：在同一个克隆中自下而上依次审查。

输出检查清单

• 已获取所有请求的 PR 的审批状态
• 已对每个 PR 进行类型分类
• 已记录堆叠顺序（如适用）
• 已在本地运行特定类型的验证（而不仅仅是模式处理程序默认验证）
• PR 修复了缺失输出时，已与主分支基线进行比较
• 已注明教程 / 身份验证 PR 的平台端到端测试（或说明延后的原因）
• 已针对每个 PR 说明结论和阻塞项
• 已推荐合并顺序
• 已提供细节问题的行内评论链接