公式ドキュメントは読めば分かります。しかし2,000ページを読み切って、必要なときに引ける形に整えるのは別の仕事です。
この検証では、Supabaseの公式ドキュメントを対象に、1日で20章の日本語教材にまとめる作業を行いました。中核となる成果物は「安全に使える領域マップ」です。
この検証の概要
実施日 | 2026年5月8日（1日で完了） |
|---|---|
やりたかったこと | アップデート頻度の高いSupabaseについて「何がどこまで安全に使えるか」を整理し、判断軸として再利用できる状態にする |
スコープ | コア概念フル + セキュリティ網羅 + 最新アップデート（副）のハイブリッド（SDKリファレンスは目次レベル） |
成果物 | 20章の.mdxファイル（astro check で 0 errors / 0 warnings） |
取得したURL数 | 総数2,075件（うち章別に取得した一次ソース約130件） |
状況 | 完了 |
結論：スコープを先に切ると終わる
2,000ページを全部読むことはできません。この検証が1日で完了したのは、最初にスコープを3つに切ったからです。
領域 | 扱い |
|---|---|
コア概念 | フルで読む |
セキュリティ | 網羅する |
最新アップデート | 副次的に押さえる |
SDKリファレンス | 目次レベルで押さえるのみ |
「全部読む」を目標にすると終わりません。何を深く読み、何を目次だけにするかを決めておくことが、完了できるかどうかを分けます。
SDKリファレンスを目次レベルに留めた判断が特に効いています。リファレンスは必要になったときに引けばよく、事前に読み込む価値が低い領域だからです。
Step Ledgerをセッション横断の「唯一の真実」にする
この検証で最も再利用価値が高い運用パターンです。
実行計画とStep Ledger（24ステップ）を1つのファイルに置き、セッション横断のstate of truthとして運用しました。
効果は明確でした。1セッション1〜2ステップでも進捗が一目で分かり、復帰コストがほぼゼロになります。
AIとの長時間作業では、コンテキストやレート上限の都合でセッションが切れます。そのたびに「どこまでやったか」を思い出す作業が発生すると、実作業より確認のほうが時間を食います。台帳を1つに集約しておくと、これが消えます。
サブエージェントの並列分担
作業自体はサブエージェントに分担させています。
コア章8つを3並列バッチで進めることで、コンテキスト効率が良くなりました。
ただし全てを任せたわけではありません。横断視点が要る章はサブエージェントに任せず、統合者が自分で書くという方針をとっています。
実際、中核成果物である「安全に使える領域マップ」は最後の統合作業として自分で書いています。個別の章を集めても、横断的な判断軸は出てきません。ここは分担できない領域です。
成果物：安全に使える領域マップ
この教材の中核はこれです。
セキュリティ章のマトリクスを「機能 × 安全度4段階 × プラン依存」で整理しました。
技術選定で本当に知りたいのは、機能一覧ではありません。「この機能はどのプランで、どこまで安全に使えるのか」です。この形に整理しておくと、採用判断時にそのまま使えます。
つまずいた点
問題 | 原因 | 次回の対策 |
|---|---|---|
サブエージェントの出力を自分で書き戻す必要があった | エージェントの種類によってWrite権限の有無が違うことを見落としていた | 発注前に権限の有無を確認する |
公式docsの404が想定より多かった | URLを推測で渡していた | sitemapから実URLを引いてから依頼する |
一部リファレンスが取得サイズ上限超で取れず | ページが大きすぎた | 「要追記」として明示的に残す |
「AIエージェントに任せたのに書き込まれていない」というトラブルは、権限設定が原因のことがあります。実行前に確認しておく項目です。
404については、URLを推測して渡すのではなく、sitemapで実在を確認してから渡すという手順に改善しています。
並列数は3〜4を上限に
運用上の実用的な知見です。
並列バッチのバッチ数は3〜4を上限に固定するとレート制限に当たりません。
並列数を増やせば速くなるわけではなく、レート制限に当たれば結局待つことになります。安定して回る数を見つけて固定するほうが、全体としては速く終わります。
公開先と非公開ワークスペースを分ける
もう1つ、他プロジェクトにも踏襲したいという判断です。
区分 | 内容 |
|---|---|
公開用の正本 | 成果物の.mdxファイル（サイトのナレッジページとして公開） |
非公開ワークスペース | URL一覧・作業メモ |
「公開先と非公開ワークスペースを早い段階で分離する」——作業途中のメモと成果物が混ざると、公開時に選別作業が発生します。最初から分けておくほうが確実です。
クロールの前にrobots.txtを確認する
この検証では、作業開始前にrobots.txtを確認しています。
今回の対象は Allow: / でAI学習・検索とも明示的に許可されていました。教材化を前提としたクロールが問題なく行える状態です。
外部サイトを読み込む作業では、この確認を手順に組み込んでおくべきです。サイトによって方針は異なります。
調査で見えたSupabaseのトレンド
教材化の副産物として、プロダクトの方向性も整理できました。
- 「セキュリティ・バイ・デフォルト」への移行 — 匿名アクセスの廃止、Data APIのデフォルト非公開化、JWTの非対称署名
- AI/エージェント対応の機能追加が急速 — Remote MCP Server、AI Assistant等
- ブランチ運用の改善 — GitHub不要のブランチ運用が可能になり、本番ワークフローへの組み込み難度が下がった
まとめて読むと、個別のリリースノートでは見えない方向性が分かります。これも教材化の価値の1つです。
成果物の規模
項目 | 数値 |
|---|---|
公開ファイル数 | 20ファイル（概要 / コア8章 / セキュリティ5章 / アップデート2章 / リファレンス目次 / 改善ヒント / ソース） |
コア章のコード例 | 約50テーマ |
Launch Weekダイジェスト | 7イベント・49ハイライト |
Changelogダイジェスト | 43エントリ・6トレンド |
検証 |
|
最後の行が重要です。MDXの構文エラーを最終工程で機械的に検証しています。大量に生成した成果物は、目視では確認しきれません。
更新をどう保つか
この種の教材には賞味期限があります。
- アップデート頻度が高い領域は四半期に一度の更新運用が必要
- ナレッジページに「最終確認日」表示を追加すると更新追跡しやすい
作って終わりにすると、古い情報が残り続けます。いつ時点の情報かを明示しておくことが、読む側にとっても書く側にとっても有用です。
よくある質問
2,000ページを1日で読めるのですか？
全部は読んでいません。スコープを「コア概念フル + セキュリティ網羅 + 最新動向（副）」に切り、SDKリファレンスは目次レベルに留めています。章別に取得した一次ソースは約130件です。
サブエージェントに全部任せられますか？
横断視点が必要な章は任せられません。この検証でも、中核成果物である「安全に使える領域マップ」は最後に統合者が自分で書いています。
並列数はどのくらいが適切ですか？
3〜4を上限に固定するとレート制限に当たりません。増やせば速くなるわけではなく、制限に当たれば結局待つことになります。
外部ドキュメントを読み込む際の注意点は？
作業前にrobots.txtを確認してください。サイトによって、AI学習・検索利用の方針は異なります。
まとめ
- スコープを先に切ると終わる。「全部読む」を目標にすると完了しない
- Step Ledgerをセッション横断のstate of truthにすると、復帰コストがほぼゼロになる
- 作業は並列分担できるが、横断視点が要る統合章は自分で書く
- サブエージェント発注前にWrite権限の有無を確認する。種類によって違う
- URLは推測せずsitemapで実在を確認してから渡す
- 並列数は3〜4で固定するとレート制限に当たらない
- 公開先と非公開ワークスペースは早い段階で分離する
- 大量生成した成果物は最終工程で機械的に検証する
技術ドキュメントの読み込みは、量が多いほど後回しになります。範囲を決めて分担すれば、1日で判断に使える形まで持っていけます。
株式会社AI棒では、こうしたAI活用の検証を日々行い、企業のナレッジ整備とAI導入を支援しています。ご相談はお問い合わせフォームから、継続的な伴走支援についてはAI参謀をご覧ください。