review-the-docs

ドキュメント PR のレビュー

supabase/supabase のドキュメント変更をローカルでレビューするワークフローです。まず分類し、該当するチェックリストに従ってください。

2 つのモードがあります。

• オープン PR のレビュー（デフォルト）— gh でトリアージし、チェックアウトして検証し、報告します。フェーズ 1 から始めてください。
• ローカルでのセルフレビュー — まだオープン PR がない場合に、PR を作成する前に現在のブランチを検証します。ローカルでのセルフレビュー から始めてください。

ドキュメントの修正を実装する場合（Linear チケット、worktree、プラットフォームの E2E）には、代わりに work-linear-issue を使用してください。

基本ルール

1. レビューの前に分類する — パスのパターンによって適用するチェックリストが決まります。
2. 積み重ねられた PR は下から順にレビューする — 各 PR のベースが前のブランチになっている場合があります。
3. ローカルで検証を実行する — 差分だけを見て承認しないでください。
4. PR が出力の欠落や不具合の修正を主張している場合は、master と比較する。
5. バッチごとに報告を 1 件にまとめる — 順番にレビューし、最後に統合した結果を出力します。
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/	リポジトリ内のエージェントスキル（正規の保存先。.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. git diff --name-only master...HEAD を実行し、フェーズ 2 の表を使って分類します。
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. コンテンツの変更については、フロントマター、内部リンク、ナビゲーションの接続を抜き取り確認します。
5. 実行可能な検証を提案する — 手順を記述したコードフェンスに新規追加または変更があるコンテンツ／チュートリアル PR では、test-the-docs を実行するか確認します。前提条件はクラスによって異なります（DB／API には Docker Compose のスタックプロファイル、example-app には examples プロファイル）。承諾された場合は検証レポートを含めます。辞退された場合、またはそのクラスに必要な前提条件が不足している場合は、該当する成果物のみに妥当な deferred の理由を記録します。ここでサンドボックス実行を再実装しないでください。
6. 将来の PR 本文の「Self-review」見出しの下に貼り付けられるよう、ブロッカーと細かな指摘を分けた短いセルフレビューノートを作成します。

その後、PR を作成し、2 回目の確認が必要な場合はオープン 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 スキーマハンドラー	apps/docs/internals/markdown-schema/、generate-guides-markdown.ts	スキーマハンドラーのレビュー
パイプライン／内部処理	apps/docs/internals/（新しいハンドラーだけではないもの）	パイプラインのレビュー
コンテンツのみの MDX	apps/docs/content/** のみ	コンテンツのレビュー
チュートリアル／クイックスタート	apps/docs/content/guides/**/tutorials/、quickstarts/、および examples/	チュートリアルのレビュー → work-linear-issue も実施
サンプルアプリのみ	対応する MDX がない examples/**	サンプルのレビュー
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 が複数の種類にまたがる場合（例：スキーマハンドラーとコンポーネントのリファクタリング）、該当するセクションをすべて実施します。

フェーズ 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

---

スキーマハンドラーのレビュー

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/ を確認します。

• 以前は空だったセクションにリスト、表、またはリンクが追加されている
• PR の説明にあるページだけでなく、このコンポーネントを使用するすべての MDX ページがカバーされている
• リンク形式が正しい：ローカルでは /docs/guides/...、VERCEL_ENV=production の場合は絶対 URL

---

パイプラインのレビュー

AST のリファクタリング、リンクの書き換え、リファレンス Markdown の生成などが対象です。

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 がオープンになってからのみ実施されます。

完成したページについて、最後に WORD_LIST.md を確認します。AI エージェントでの使用に記載された2段階の手順に従います。まずフレーズグループで用語の文字列リストを確認し、次に grep '^### ' WORD_LIST.md を実行して、ページ内の単語に該当する項目だけを読みます。著者が導入していない用語も含めます。

チェックリスト：

• 文体が 01-voice-and-tone.md に従っている
• セクションのグループ分けと区切り方が 03-page-structure.md に従っている
• コンポーネントが 02-elements.md に従っている
• 用語が WORD_LIST.md と一致している
• フロントマターが有効（必要な場合は title、description を含む）
• 内部リンクが解決できる（壊れたアンカーではなく /docs/guides/... を使用）
• $CodeSample のパスが既存のサンプルディレクトリと一致している
• 注意書き、タブ、パーシャルのインクルードが PR プレビューで適切に表示される
• コンポーネントを削除した箇所に、意図しない空白だけのセクションや空のセクションが残っていない
• 新規または変更された手順のスニペットについて test-the-docs を案内している。検証レポートがあるか、妥当な deferred の理由が記録されている

レイアウトコンポーネントが関係する場合は、PR プレビュー URL（Vercel／デプロイに関するコメントから取得）と本番環境を比較し、表示上のリグレッションがないか確認します。

---

チュートリアルのレビュー

チュートリアルの MDX と、それに対応するサンプルアプリです。プラットフォーム全体の E2E については 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 にしている）
• プラットフォーム全体の E2E（認証が関係する場合）：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 が混入していない
• マークダウンハンドラーでも使用される共有定数が適切に切り出されている
• 視覚的な動作に変更がないか、意図的に改善されている — PR のスクリーンショットを確認する
• コンポーネントがマークダウンにエクスポートされる MDX で使用されている場合、スキーマハンドラーが存在することを確認するか、フォローアップを起票する

---

ドキュメントツールのレビュー

エージェントスキル、コントリビューター向けドキュメント、またはスキルのシンボリックリンク設定に関する変更です — MDX／パイプラインの変更は不要です。

チェックリスト：

• .agents/skills/ が正式な配置場所である — ほかの場所にスキルの内容を追加していない
• .claude/skills は引き続き ../.agents/skills への単一の Git シンボリックリンクである — .claude/ 以下にスキルごとのシンボリックリンクやコピーを作成していない
• スキル間のリンクが解決できる：リポジトリ内のスキルには相対リンクを使用し、非公開リポジトリに残るスキルにのみ絶対 docs-agent-skills URL を使用する
• 個人用 Vault のパス、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 のレビュー後に、レポートを 1 つにまとめて提出します。

レポートのテンプレート

# 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).

判定の指針

判定	条件
承認	種類ごとのチェックがすべて合格し、出力が正しい
軽微な指摘付きで承認	正しく動作しており、軽微な種類／スタイル／ドキュメント上の指摘のみがある
変更を依頼	ビルド／Lint の失敗、リンク切れ、データの誤り、カバレッジ不足、またはプラットフォーム全体の E2E の失敗がある

インラインのレビューコメント

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 は、サブエージェントが別々のワークツリーでレビューできます。積み重ねた PR シリーズは、1 つのクローンで下から順にレビューしてください。

出力チェックリスト

• リクエストされたすべての PR の承認状況を取得
• 各 PR を種類別に分類
• スタック順を記録（該当する場合）
• 種類に応じた検証をローカルで実施（スキーマハンドラーのデフォルトだけでは不十分）
• PR で出力漏れを修正する場合は、マスターベースラインと比較
• チュートリアル／認証関連の PR について、プラットフォーム E2E を記録（または理由を添えて延期）
• PR ごとに判定とブロッカーを明記
• 推奨するマージ順を記載
• 軽微な指摘事項へのインラインコメントのリンクを提示