ask-the-docs

docs-app の司書に質問する

apps/docs のナレッジに関するリファレンスです。アーキテクチャ、ビルドパイプライン、フェデレーションされたドキュメント、既知の脆弱性に加え、コードベースが重視する機能設計の原則を扱います。新しいコードを書く前に既存のコードを理解して再利用すること、そして、対象範囲を小さく保つためにコーディングをミニマルにすることです。

役割は 2 つあります。

1. ドキュメントアプリについて、すでに文書化されている内容を調べます。 アーキテクチャ、トレードオフ、注意点、過去の決定事項などを、ゼロから読み直して再導出するのではなく確認します。
2. PR を作成する前に、コードベースの再利用／ミニマリズムの原則を適用して、レビューでの指摘を未然に防ぎます。 「次のラウンドで修正してください」というコメントを早い段階で見つけられます。

呼び出すタイミング

• ユーザーが apps/docs のアーキテクチャ、規約、動作について質問するとき（「Markdown パイプラインはどう動くのか？」「リスティングのデータファイルはどこに置くのか？」「Troubleshooting に .mjs の utils ファイルがあるのはなぜか？」など）。
• LLM／エージェントによる利用について質問するとき（llms.txt、Markdown のネゴシエーション、searchDocs、一括エクスポート、エージェントのオンボーディングガイド、人間とエージェントとクローラーの違い、クイックスタート内の AI プロンプトブロックなど）。
• apps/docs/ 以下のコードに手を加える予定があり、MDX コンポーネント、internals/markdown-schema/、generate-guides-markdown.ts、コンテンツデータモジュール、lint パイプライン、テレメトリーイベント、コントリビューター向けスニペット、フェデレーションされたルート、リファレンスのコード生成、Management API／OpenAPI リファレンスページに関係するとき。
• 文書化されている原則に照らして確認しながら、docs-app の PR をレビューしたいとき。

対象外： Supabase のドキュメントの一般的な コンテンツ に関する質問（work-linear-issue、audit-quickstarts などを使用）、または apps/docs/ 外のアプリレベルの作業。

図を使った回答

アーキテクチャやパイプラインについての質問は、文章よりも図で説明したほうが分かりやすいことがよくあります。次の内容に回答する際は、Mermaid 図を含めることを基本とします。

• MDX のランタイムと Markdown エクスポートパイプラインの分離。
• ビルドの流れ（Turbo → pnpm prebuild / build / postbuild → Vercel）。
• LLM／エージェントによる利用経路（llms.txt、ネゴシエーション、一括エクスポート）。
• フェデレーションされたドキュメントの取得フロー。
• CI／PR のフロー。
• コンポーネントとデータレジストリの関係。
• Management API の OpenAPI → コード生成 → リファレンスページのフロー。

Mermaid のフェンス（`` ```mermaid ````）は、GitHub やほとんどの Markdown プレビューアでネイティブに表示されます。すでに複数のリファレンスファイルに Mermaid が埋め込まれているため、再導出するのではなく、それらを再利用または応用してください。

図は小さく、テーマを 1 つに絞ってください。ノードが 12 個を超える場合は、図を分割してください。

リファレンスファイル

reference/ 以下に、短く要点を絞ったドキュメントがあります。作業に関係するものを読んでください。背景情報が必要な箇所では、相互に参照先が記載されています。

ファイル	内容
reference/adding-features.md	apps/docs に機能を追加する際のベストプラクティスガイドです。まず既存コードを確認し、実現可能な最小の形を選び、パイプラインを再利用します。
reference/docs-app-direction.md	リファクタリングのビジョンと作業規範です。新しい作業で準拠すべき方針を説明します。
reference/known-issues.md	不具合がある、壊れやすい、または移行中のシステムをまとめた更新中のリストです。何かに依存する前に確認してください（フェデレーションされたドキュメント、検索、Sentry、リファレンスページのアーキテクチャ）。
reference/app-map.md	アーキテクチャの概要です。ディレクトリ、2 つのパイプライン（MDX ランタイム＋Markdown エクスポート）モデル、見出しとタイポグラフィの契約、テレメトリー、Lint 項目を説明します。
reference/build-pipeline.md	apps/docs をビルドするための Turborepo＋pnpm のライフサイクル手順です。コード生成、ビルド前処理、ビルド後処理、Vercel へのデプロイを扱います。Mermaid 図も含まれています。
reference/llm-agent-surface.md	対象読者に応じたルーティング、llms.txt、コンテンツネゴシエーション、一括エクスポートについて説明します。
reference/llm-agent-parity.md	HTML と Markdown の忠実性（AI プロンプトなど）、検索に関する注意点、エージェントのオンボーディングガイド、移行中の配線について説明します。
reference/federated-docs.md	ビルド時に外部リポジトリから Markdown を取得する仕組みを説明します。ルート、pageMap、remark/rehype プラグイン、リンク変換、既知の障害モードを扱います。
reference/ci-and-lint.md	すべての PR で実行される GitHub Actions（Docs Tests、型チェック、prettier、Vercel プレビューのゲート）について説明します。新しいチェックを作成する前にチェックを追加すべき場所も示します。
reference/management-api-reference.md	Management API の OpenAPI からリファレンスを生成する方法を説明します。スコープ付き PAT の権限表も含みます。また、Scalar/Redoc に置き換えるべきでない理由も扱います。
reference/graphql-endpoint.md	apps/docs/resources/ 配下の /api/graphql エンドポイントについて説明します。クエリごとのフォルダー構成、rootSchema.ts、接続／フィールドのユーティリティ、新しいトップレベルクエリの追加手順を扱います。
reference/search-embeddings.md	searchDocs を支える scripts/search/ の埋め込みパイプラインについて説明します。コンテンツソース、処理フロー、変更検出、page／page_section テーブルを扱います。
reference/gotchas.md	注意すべき具体的な落とし穴をまとめています。項目ごとに一文で説明します。

チャット中の使い方

1. まず読む　質問が設計上の選択や不慣れなコードパスに関わる場合は、adding-features.md と app-map.md を読んでください。どちらも意図的に短くしてあります。流し読みせず、両方読んでください。
2. 推奨する前に確認する。　参考資料の内容は、最新のコードと食い違っている場合があります。ファイルパス、関数名、動作について記憶を頼りに判断する前に、実際のファイル（apps/docs/...）で確認してください。
3. ルールだけでなく原則を引用する。　「adding-features.md の「Reuse pipelines, don't fork them」節に従い、別の経路を導入するのではなく、既存の markdown-schema ハンドラーを経由します。」
4. アーキテクチャ、フロー、関係性を説明する場合は、Mermaid を活用する。図を使った回答を参照してください。

librarian の更新

このスキルは supabase/supabase の .agents/skills/ask-the-docs/ にあります。apps/docs に変更があり、参考ファイルの内容が不正確になった場合や、PR レビューから汎用的に役立つ教訓が得られた場合は、リポジトリ内の他の変更と同様に、このリポジトリにプルリクエストを作成して該当ファイルを更新してください。

各正規ファイルは約250行以内にしてください。肥大化する前に分割してください。将来のコントリビューターに役立つ情報だけを記録してください。最新のコードをざっと読めばすぐにわかる事実は、書き残さないでください。

関連スキル

• pm-the-docs — 対象読者、段階、横断的なスコープの判断（「Write the docs」チェックリストの Frame 段階。pm-the-docs の参考ファイルにも記載）。リポジトリを横断した製品情報の検索（universe）は、このスキルではなくこちらで行います。
• test-the-docs — Docker で分離したローカルスタックに対するドキュメントのスニペットの実行と、検証レポートの作成。
• work-linear-issue — 割り当てられた DOCS-* チケットの実装。
• review-the-docs — 種類に応じた検証を行いながら、オープン中のドキュメント PR をレビュー。
• audit-content-listings — 概要ページをコンテンツ一覧に一括変換。
• create-pull-request — ドキュメント PR の作成または更新。