write-the-docs

ドキュメントを作成する

機能やリリースについて、新しい Supabase ドキュメントのコンテンツを作成するか、製品の実態に基づいて書き直します。既存のドキュメントチケットを実装・修正する work-linear-issue や、新たな製品意図を収集せずに既存ページを再構成して簡潔にする edit-the-docs とは異なります。このスキルは、コンテンツがまだ存在しない場合（または意図とコードに基づいて書き直す必要がある場合）に、推測ではなく以下の4つの入力に基づいて作成するためのものです。

基本ルール

1. 作成前に情報を集めます。 チケットのタイトルだけをもとに作成してはいけません。まず、以下の4つの入力をすべて集めてください。情報収集が不十分だと、機能の実際の動作について誤った内容を作成することになります。
2. 確認済みの動作、製品の意図、推測を区別します。 コードからは、機能が現時点で何をするかがわかります。Linear／PRD／PRFAQ（または以前の Frame／Shape の出力）からは、機能の目的と位置付けがわかります。推測が必要な場合は、事実として述べず、明示してください。
3. 文体、用語、書式、ページ構成、要素など、執筆規則についてはスタイルガイドに従います。ただし、内容の正確さについては従いません。 これは文体の参考資料であり、情報源ではありません。ページに実際に記載する内容は、ルール2の Linear とコードの確認結果に基づいて決めます。文体や構成のルールを勝手に作らないでください。スタイルガイドと Google の開発者向けドキュメント スタイルガイドのどちらにも答えがない場合は、近くにあるページの内容をそのまま採用せず、引き継ぎ時にその旨を伝えてください。
4. 重複を避け、既存の情報を活用します。 docs アプリのアーキテクチャや配置に関する質問には、ここで知識を一から再構築するのではなく、ask-the-docs と audit-docs-ia を使ってください。
5. 何を作成するのかを把握します。 「機能に関するドキュメント」に見えるものが、すべて人手で作成するページとは限りません。執筆を始める前に、以下のコンテンツタイプ判定を確認してください。依頼が既存ページの再構成、順序の変更、つなぎの文章の追加、または明瞭化であり、新たな製品の説明を含まない場合は、edit-the-docs を使ってください。

フェーズ 1 — 情報収集（読み取り専用）

次の 4 つの情報を、この順番で読みます（優先順位ではありません。ルール 2 およびフェーズ 1 のステップ 3 に従い、Linear は引き続き製品意図の情報源、コードは動作の情報源です）。

1. スタイルガイド — 文体と用語の参照資料。 style-guide/README.md を読み、作成する内容に合ったステップに従います。使う予定の用語については WORD_LIST.md を確認します。ガイドの末尾には、記載がない場合に参照すべき内容が書かれています。隣接するページに合わせるのではなく、そちらに従ってください。
2. Linear — チケットと製品コンテキスト。 Linear は Supabase 内部のツールです。利用可能な場合は推奨されますが、オープンソースのコントリビューターに必須ではありません。Linear の課題がある場合は、その課題を確認し、さらに親プロジェクト／イニシアチブの説明（PRD、PRFAQ、RFC、またはイニシアチブの説明文）と PM のコメントも確認します。製品の位置付けや説明の表現は通常、チケット本文ではなく、その 1 つ上の親プロジェクトまたはイニシアチブの説明にあります。チケットが実際に約束している範囲と、PRD にある意欲的な表現を区別してください。Linear の課題も、Frame／Shape で作成された製品意図の成果物もない場合は、執筆を中断してください。社内の作成者に Linear の URL を依頼し、それができない場合は pm-the-docs（Frame）に引き継ぎ、Shape／IA が未確定の場合は ask-the-docs に引き継ぎます。製品意図が定まってから再開してください。位置付けを決して創作せず、この Draft スキル内で Frame／Shape を実行しないでください。
3. コード。 動作についての記述を書く前に、実際の実装を確認します。PRD が意図を示すのに対し、コードはリリースされた動作を示します。Linear の課題／プロジェクトに supabase/supabase の PR へのリンクがあるか、最初に確認してください。その差分と説明が「実際にリリースされた内容」を最も正確に示しており、コードベース全体を一般的に確認するよりも正確です。リンクされた PR がない場合は、supabase/supabase（またはその製品独自のリポジトリ）で機能を直接探し、ask-the-docs の再利用／最小限の記述という観点を適用します。説明する前に、何が存在するかを把握してください。動作が複数のサービス（CLI、Auth、マイグレーション、プラットフォームなど）にまたがる場合は、pm-the-docs → universe-lookup の利用可否の確認に従います（universe にアクセスできる場合は universe、そうでない場合は OSS の公開検索／リンクされたリポジトリを使います。ask-the-docs は使いません）。コードと PRD の内容が食い違う場合、動作に関する記述ではコードを優先し、どちらかを黙って選ぶのではなく、相違点を明示します。
4. 作成者から提供されたその他の情報。 スクリーンショット、サンプルプロジェクト、関連ページ、Slack のスレッド、特定の文体のサンプルなどです。スクリーンショットは一般的なコンテキストの把握だけに使うものではありません。画面を参照する手順を書く前に、ボタン／メニュー／フィールドの正確なラベルを確認するためにも使います。UI のラベルの不一致は、下書きで最も簡単に防げるミスの 1 つです。1〜3 を確認しても機能のユーザー向けの形が不明確な場合は、推測せず、これらの情報を依頼してください。

執筆を始める前に、4 つの情報すべてについて、確認できたこと、製品意図とリリース済みの動作の違い、まだ不明な点を依頼者に要約して伝えてください。実際の不明点によって下書きの構成や範囲が変わる場合は、作業を止めて確認してください。

フェーズ 1.5 — コンテンツタイプの判定

作成に取りかかる前に、実際に求められているものを apps/docs の実際のコンテンツタイプに照らして分類します（ask-the-docs の app-map.md にある「Content types」テーブルと、こちらの reference/content-type-gate.md を参照してください）。

• ガイド／チュートリアル — content/guides/ 配下の手書きの MDX です。このスキルで作成するのはこれです。
• トラブルシューティング — content/troubleshooting/ 配下の手書きの MDX で、GitHub の Issue から同期される場合もあります。これも対象です。
• リファレンス — spec/（OpenAPI、SDK YAML、CLI 設定）から features/docs/generated/** に生成されます。標準的な MDX の手順で手書きするものではありません。 依頼内容が実際にはリファレンスタイプのコンテンツ（リファレンス項目が必要な新しい API エンドポイント、設定オプション、SDK メソッド）の場合は、MDX の作成を中止してください。生成物と食い違うか、生成時に気づかないまま上書きされてしまいます。代わりに、spec／コード生成のパイプライン（apps/docs/spec/、apps/docs/generator/。OpenAPI 固有の手順は ask-the-docs の management-api-reference.md を参照）を案内し、実際の修正ではないのに完成したように見えるページを作成するのではなく、その旨を明確に伝えてください。

判断に迷ったら、推測するのではなく ask-the-docs に尋ねてください。この分類は、アプリについての知識がない状態で判断すると、このスキルで最も間違いやすい部分です。

フェーズ 2 — 草案の作成

• apps/docs の MDX 規約（コンポーネントの使用、フロントマター、コードサンプルの連携）に従います。手順を再構築するのではなく、パイプラインの詳細については ask-the-docs を参照してください。
• 既存の情報アーキテクチャの前例に従ってページを配置します。配置先が明らかでない場合は、ナビゲーションの枠を推測せず、audit-docs-ia のナビゲーション／情報アーキテクチャに関する知識を参照してください。
• ディスク上に置くだけでなく、ナビゲーションにも追加してください。 配置（どのセクションに置くか）とナビゲーションへの登録（実際に表示されるかどうか）は別のものです。ファイルが適切なフォルダーにあるだけで見つけられると思い込まず、現在のナビゲーション登録の仕組みを ask-the-docs／audit-docs-ia で確認してください。
• すべての動作に関する説明はフェーズ 1 のコード調査（該当する場合はリンクされた PR）に基づかせ、「これが重要な理由」の説明は Linear／PM の背景情報または以前の Frame／Shape の出力に基づかせます。推測した内容には、インラインで印を付けます（HTML コメントや引き継ぎの要約内の注記など）。そうすればレビュアーがすぐに見つけられます。
• 時代に左右されないドキュメントを作成し、重複を削り、1 項目だけのリストよりも段落を優先してください。 時代に左右されないドキュメント、簡潔さ、リストを参照してください。
• 最終草案から社内のビジネス情報を取り除いてください。 PRD の意図、ロードマップの推測、社内チケットでの議論、「不足箇所の補完」に関するメモを示す HTML コメントは、引き渡し前に MDX から削除する必要があります。オープンソースのドキュメントで社内の計画を明かすべきではありません。前提や未解決の質問は、公開するコンテンツではなく PR の説明に記載して、レビュアーに伝えてください。
• 草案の作成時に、専門用語、UI 操作、略語、意味が曖昧になり得る表現を導入または確認する場合は、WORD_LIST.md を検索してください。ファイルを最初から最後まで読むのではなく、AI エージェントとの使用方法に記載された 2 段階の手順に従ってください。
• 繰り返し使うコンテンツはコピーせず、apps/docs/content/_partials/ を通じて再利用してください。ナビゲーションへの登録、パーシャル、ファイルの配置については、ask-the-docs の app-map.md と federated-docs.md を参照してください。

フェーズ 2.5 — レビューチェックリスト

引き継ぐ前に、以下を確認してください。

• スタイルガイドに従っているか、従っていない箇所を引き継ぎ時に明示している
• すべての動作に関する説明が、PRD だけでなく、読んだコード（できればリンク先の PR）に基づいている
• すべての「重要な理由」や位置づけに関する記述が、Linear／PM のコンテキスト、または以前の Frame／Shape の出力に基づいており、創作した内容ではない
• 推測または仮定した内容に印を付け、事実として記載していない
• コンテンツタイプが Guide／Troubleshooting であると確認している（生成される Reference に含めるべき内容ではない）
• ナビゲーションへの配置とナビゲーションの有効化の両方を設定している（配置だけではない）
• 内部リンクが有効で、新しい用語や略語の初出時に定義している
• ドラフトに手順を示すスニペット（CLI、SQL、クライアントコード、サンプルアプリ）がある場合、test-the-docs の実行を提案した（任意。Docker Compose サンドボックスを使用。DB/API には stack プロファイル、example-app には examples プロファイル）
• 可能な限り将来の約束を最小限にしている（時代に左右されないドキュメントの原則）
• 不必要な重複がない（同じ内容を異なる言い方で繰り返していない）
• 特別な理由がない限り、項目が 1 つだけのリストを避けている
• 内部向けの不足部分の補足やビジネスコンテキストに関するコメントを MDX から削除している（レビューに必要な場合は PR の説明にのみ残す）

コンプライアンスチェックリスト

引き継ぐ前に、Use with an AI agent に記載された 2 つの確認を両方とも実施してください。文字列の用語リストについては Phrase groups を読み、その後 grep '^### ' WORD_LIST.md を実行して、ページ内の単語に該当する項目だけを読んでください。ドラフト作成時に検索した用語だけでなく、自分で追加していない用語も確認してください。その後、ドラフトをスタイルガイドの番号付きファイルそれぞれと照らし合わせて確認してください。

• 括弧は略語または (Optional) にのみ使用し、文章中の補足には使用していない
• 太字、斜体、コードは、それぞれの用途（UI ラベル、見落としてはならない用語）にのみ使用し、視覚的な強調だけを目的として使用していない
• 直接的な文のほうが読みやすい場合に、ダッシュを使った挿入句を使用していない
• 用語が WORD_LIST.md に一致している（スペルや大文字・小文字だけでなく、不正確として指摘された用語も含む）
• 文体、時制、簡潔さが 01-voice-and-tone.md に従っている
• ドキュメントの種類、セクションのグループ化、内容の分割が 03-page-structure.md に従っている
• 注意書き、見出し、リンク、その他のコンポーネントが 02-elements.md に従っている

フェーズ 3 — 引き継ぎ

このスキルで作成するのは、レビュー可能なドラフトまでです。worktree や PR は作成しません。

• ドラフトに実行可能な手順のスニペットが含まれる場合は、test-the-docs の利用を提案してください。検証を始める前に確認を取ってください。前提条件は成果物の種類ごとに確認してください（DB/API の成果物には Docker Compose のスタックプロファイル、example-app には examples プロファイル／ランナー内の Node）。断られた場合、またはその種類に必要な前提条件が不足している場合は、該当する成果物のみ deferred と記録して続行してください。承諾された場合は、検証レポートを PR 本文／セルフレビューノートに添付してください。
• 次に、review-the-docs によるローカルのセルフレビュー（ビルド／分類）を実行してください。
• 実際の PR 作成作業は、create-pull-request に引き継いでください（チケットで worktree の作成から PR までの一連の作業が必要な場合は、work-linear-issue も利用します）。フェーズ 1／2 でフラグを付けた前提事項の一覧を、明示的に引き継いでください。これは PR の説明（例：「要レビュー」セクション）に記載し、レビュー担当者が確認できるようにします。ドラフト内のコメントに埋もれさせないでください。
• 機能が UI 主導で、PR にスクリーンショット／GIF が必要な場合は、ここで証拠を取得するのではなく、次のステップとして proof-it-works を指定してください。
• PR を作成する前に、review-the-docs によるローカルのセルフレビューを実行してください。該当する場合は pnpm build:guides-markdown を実行し、reference/drafting-mechanics.md に従ってアンカーチェックを行ってください。

追加リソース

• スタイル：style-guide/README.md から各レベルのファイルを参照できます
• リポジトリの仕組み（ナビゲーションの設定、パーシャル、参照パイプライン）：apps/docs/CONTRIBUTING.md
• ドラフト作成の仕組み：reference/drafting-mechanics.md
• コンテンツタイプの確認基準：reference/content-type-gate.md
• 既存ページの再構成／明確化：edit-the-docs
• 「ドキュメントを書く」チェックリスト（ドラフト段階）：pm-the-docs の reference/write-the-docs-checklist.md
• リポジトリ横断の商品情報の検索：pm-the-docs → universe-lookup
• 実行可能な手順の検証：test-the-docs
• Docs アプリのアーキテクチャ／配置：ask-the-docs、audit-docs-ia
• PR 作成作業：create-pull-request、work-linear-issue
• スクリーンショット／動作証明：proof-it-works