---
title: "公式ドキュメント2,000ページを1日で教材化する｜スコープ設計とStep Ledger運用"
excerpt: "Supabaseの公式ドキュメントを対象に、1日で20章の日本語教材にまとめた記録です。「全部読む」を目標にせずスコープを先に切ること、Step Ledgerをセッション横断のstate of truthにすること、横断視点の統合章はサブエージェントに任せないこと——再利用できる運用パターンをまとめています。"
author: "AI活編集部"
author_username: ai-katsu-editorial
published_at: 2026-05-08T00:00:00+00:00
verified_at: 2026-05-08T00:00:00+00:00
models: ["Claude Code"]
tools: ["Supabase", "Astro"]
tasks: ["ナレッジ活用・RAG", "業務プロジェクト"]
domain: "教育・研修"
canonical_url: https://ai-katsu.jp/articles/supabase-textbook
---
# 公式ドキュメント2,000ページを1日で教材化する｜スコープ設計とStep Ledger運用

公式ドキュメントは読めば分かります。しかし**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トレンド |
| 検証 | `astro check` で 0 errors / 0 warnings（73ファイル） |

最後の行が重要です。**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導入を支援しています。ご相談は[お問い合わせフォーム](/contact)から、継続的な伴走支援については[AI参謀](/ai-sanbo)をご覧ください。