はじめに
AIエージェントの出力品質は、タスクに取り組む前に何を知っているかで決まる。
同じ「認証機能を実装して」という指示でも、OAuth 2.0 PKCEの落とし穴やトークンストレージ戦略の比較を事前に知っているエージェントと、ゼロから推論するエージェントでは、成果物の質が根本的に異なる。
しかし、全ての事前知識をコンテキストウィンドウに載せることはできない。コンテキストはトークンという有限資源であり、知識を詰め込むほどエージェントが作業に使える余白が減る。
この矛盾を解決するClaude Code Skillを作った。
原体験: /docs で知識を貯めていた
Claude Codeを長時間使っていると、自然とこういう運用になる:
- 技術調査の結果を
docs/ディレクトリにMarkdownとして保存 - コンテキストが圧縮されても、ファイルシステムには残る
- 次のセッションで必要になったら読み直す
自分の場合、これをスラッシュコマンドとして定型化していた。~/.claude/commands/docs.md にこう書いてある:
ユーザーが調べて欲しいと思った内容を調査し,
適切なタイトルで`docs`ディレクトリに`.md`形式で
知見をドキュメント形式で保存してください.
/docs OAuth 2.0 PKCEの落とし穴 と打てば、エージェントがWeb検索して調査し、docs/oauth2-pkce-pitfalls.md として保存してくれる。コンテキストが圧縮されても知見はファイルとして残り、次のセッションで再利用できる。
これ自体は便利に機能していた。実際、プロジェクトの docs/ には十数個のMarkdownが蓄積されていく。だが根本的な問題がある。
docs/ に何が蓄積されているかが、エージェントにとって明示的でない。
コンテキスト圧縮後のエージェントが docs/ 内の30個のMarkdownファイルから関連知識を見つけるには、ファイル一覧を取得し、ファイル名から推測し、場合によっては中身を読むしかない。蓄積された知識の全体像を把握する手段がなく、関連知識があるのに使われないまま眠る。
INDEX パターン: 知識空間の地図
解決策はシンプルだ。INDEX.md — 知識の目次を1つ用意する。
┌──────────────────────────────────────────┐
│ コンテキストウィンドウ │
│ │
│ ┌───────────────────────┐ │
│ │ INDEX.md (~数百トークン)│ ← 常にロード │
│ │ タイトル | 要約 | タグ │ │
│ └───────────────────────┘ │
│ │ │
│ │ 関連記事のみ選択的にロード │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ article-a.md │ ← 必要な時だけ │
│ └───────────────────────┘ │
│ │
│ 残りのコンテキスト → 実際のタスクに使える │
└──────────────────────────────────────────┘
INDEX.mdはMarkdownテーブルで、1記事あたり1行。タイトル、1行要約、タグ、更新日。数十件の知識があっても数百トークンしか消費しない。
| id | title | summary | tags | updated |
|----|-------|---------|------|---------|
| oauth2-pkce-spa | OAuth 2.0 PKCE... | SPAでのPKCEフロー実装と落とし穴 | oauth, security | 2026-03-15 |
| token-storage | トークンストレージ戦略 | localStorage vs httpOnly Cookie比較 | auth, frontend | 2026-03-15 |
| session-vs-jwt | Session vs JWT | ステートフル/ステートレス認証の使い分け | auth, architecture | 2026-03-15 |
エージェントはこのテーブルだけ読んで「今のタスクに関連する知識はあるか?」を判断し、必要な記事だけをピンポイントでロードする。
なぜINDEX.mdは「ただの目次」以上の存在なのか
INDEX.mdは2つの役割を持つ。
1. コンテキスト効率
これは直感的だ。全記事をロードするのではなく、INDEXだけ読んで必要なものだけ選ぶ。Progressive Disclosureのパターンそのもの。
2. インテントINDEXデータベース
こちらの方が本質的。
コンテキストが圧縮された後、エージェントはそれまでに蓄積した知識の存在を忘れる。しかしINDEX.mdを1回読むだけで、プロジェクトの知識空間全体を即座に把握できる。
「何を知っていて、何を知らないか」をエージェントが自発的に判断できる。docs/ にファイルを放り込むだけでは決して実現できなかった、知識の発見可能性 を保証する仕組みだ。
CLAUDE.mdに「タスク着手前にINDEX.mdを読め」と書いておけば、新しいセッションでもエージェントは自動的に知識空間を参照してからタスクに着手する。
設計思想
知識の粒度 — 小さな参考資料の集合体
知識ベースの価値は「1つの巨大なリサーチ結果」ではない。小粒な参考資料が複数indexされている状態 にある。
❌ こうなってはいけない:
INDEX.md
└── authentication.md (5000行の巨大記事)
✅ こうあるべき:
INDEX.md
├── oauth2-pkce-overview.md ← PKCEの基本概念
├── oauth2-token-storage.md ← トークンストレージ戦略比較
├── session-vs-jwt.md ← Session vs JWT
├── auth-middleware-compliance.md ← 法務要件との関係
└── nextauth-v5-migration.md ← NextAuth v5移行の注意点
エージェントが認証トークンの保存方法で迷ったとき、5000行の巨大記事をロードするのではなく、oauth2-token-storage.md だけをピンポイントでロードする。
大きなトピックをリサーチする場合は、まず3-7個の観点に分解し、各々を独立した記事として保存する。これがINDEXパターンの真価。
プロジェクトローカル — グローバルに置かない理由
知識は docs/knowledge/ にプロジェクト単位で保存する。グローバルな知識ストアは持たない。
理由は単純で、LLMが既に持っている汎用知識(Reactの基本、HTTPの仕組み等)をわざわざ保存する価値がないからだ。保存する価値があるのはプロジェクト固有のリサーチ結果 — ドメイン知識、アーキテクチャ決定の背景、特定ライブラリの落とし穴など、LLMの訓練データに含まれない知見。
プロジェクトローカルにすることで、git管理され、チームで共有でき、プロジェクトと一緒に消える。
非同期リサーチ — Perplexity APIへの委任
リサーチにはPerplexity API(OpenRouter経由)を使う。エージェント自身がWeb検索を回すのではなく、検索特化のLLMに委任する。
エージェント Perplexity API
│ │
│ 具体的なクエリを設計 │
│──────────────────────────────▶│
│ │ 多言語ソース検索
│ │ 情報統合
│ フロントマター付きMarkdown │
│◀──────────────────────────────│
│ │
│ INDEX更新 + 品質確認 │
▼
リサーチの品質はクエリの具体性で決まる。「Reactについて」ではなく「React Server ComponentsにおけるSuspenseとuse()のデータフェッチパターン比較」のように、観点と制約を明示する。この品質制御はSKILL.md内の指示で担保している。
実装
スキルの構成
prior-knowledge-skill/
├── SKILL.md # スキル本体(エージェントへの指示書)
├── scripts/
│ ├── index-manager.ts # INDEX.mdのCRUD
│ ├── research.py # Perplexity APIでディープリサーチ
│ └── import-doc.ts # 既存Markdownの取り込み
├── references/
│ └── research-guide.md # クエリ設計・品質基準
├── assets/
│ └── article-template.md # 記事テンプレート
└── package.json
3つのモード
| モード | いつ使う | 何が起きる |
|---|---|---|
| リサーチ | 「調べて保存して」 | Perplexity APIでリサーチ → Markdown保存 → INDEX更新 |
| 取り込み | 既存ドキュメントを知識ベースに | フロントマター自動付与 → コピー → INDEX更新 |
| 参照 | タスク着手前 | INDEX.md読み → 関連記事のみロード |
リサーチ → 保存
uv run scripts/research.py \
"OAuth 2.0 PKCE フローの実装 — SPAにおけるセキュリティ考慮事項" \
--output docs/knowledge/articles/oauth2-pkce-spa.md \
--tags "oauth,security,spa"
bun run scripts/index-manager.ts add docs/knowledge/articles/oauth2-pkce-spa.md
既存ドキュメントの取り込み
bun run scripts/import-doc.ts docs/architecture-decision.md \
--title "認証基盤のアーキテクチャ決定" \
--summary "Session vs JWT比較、PKCE採用の経緯" \
--tags "auth,architecture"
元ファイルは変更しない非破壊コピー。フロントマターを自動付与してINDEXも自動更新。
知識の参照
CLAUDE.mdに以下を追加しておくと、エージェントがタスク着手前に自動で知識を確認する:
# 事前知識空間
タスクに取り組む前に、関連する事前知識がないか確認すること:
1. `docs/knowledge/INDEX.md` が存在すれば読み、関連する知識を特定
2. 関連する記事があれば `docs/knowledge/articles/<id>.md` を読んでからタスクに着手
Skills設計としてのベストプラクティス
このスキルはAnthropicとVercelのSkills設計ベストプラクティスに従って設計している。
Progressive Disclosure
-
起動時にロードされるもの: フロントマターの
name+descriptionのみ(~100トークン) - スキルが起動した時: SKILL.md本文(~100行)
-
必要時のみ:
references/research-guide.md(クエリ設計の詳細)
コンテキストウィンドウは公共財。使わない知識でトークンを消費しない。
descriptionはルーティングルール
description: "Prior knowledge space management. Index and accumulate
research results so the agent can autonomously select and load
relevant knowledge. Triggers: (1) 'research and save to knowledge
base' (2) 'search the knowledge base' (3) when importing existing
documents"
descriptionはタイトルではなく、いつこのスキルを使うかのルーティングルール。エージェントはこの文字列だけで起動判断する。
referencesとassetsの分離
-
references/— エージェントが参照するドキュメント(コンテキストにロードされる) -
assets/— 出力に使うテンプレート(コンテキストにロードされない)
インストール
npx skills add konaito/prior-knowledge-skill
または手動:
cd ~/.claude/skills
git clone https://github.com/konaito/prior-knowledge-skill.git
cd prior-knowledge-skill && bun install
リサーチ機能を使う場合はOpenRouterのAPIキーが必要:
echo 'OPENROUTER_API_KEY=sk-or-...' > ~/.claude/skills/prior-knowledge-skill/.env
取り込み・参照モードはAPIキー不要で動作する。
まとめ
AIエージェントにとって事前知識は思考の質を大きく左右する。だがコンテキストウィンドウは有限であり、全知識を載せることはできない。
INDEX パターン は、この矛盾を「知識の目次だけ常にロードし、必要な知識だけ選択的にロードする」というシンプルなアプローチで解決する。
- INDEXは インテントINDEXデータベース として、コンテキスト圧縮後も知識空間全体の発見可能性を保証する
- 知識は 小粒な参考資料の集合体 としてindex化し、エージェントがピンポイントで選択できるようにする
- 保存先は プロジェクトローカル にし、LLMが既に知っている汎用知識は保存しない
docs/ にMarkdownを放り込む時代は終わった。事前知識空間を構造化しよう。