はじめに
ども！龍ちゃんです。Claude Codeを使っていて、ドキュメントが増えてきていませんか？
以前、/research コマンドで調査品質を安定させる記事を書きました。調査結果が docs/research/ に蓄積されていくのは便利なんですが、気づいたらドキュメントが爆増していました。
こんな悩みが出てきたんですよね：
- どこに何があるか分からない: 「あの調査結果、どこだっけ？」
- 同じ調査を繰り返す: 既存のドキュメントに気づかず重複作業
- 全部読み込むとトークンが…: コンテキストが膨らんでコスト増
今回は、この問題をREADMEインデックス + AI自動メンテナンスで解決する方法を紹介します。
この記事で紹介すること
- READMEをドキュメントの「目次」として設計する方法
- Claude Codeに確実に読み込ませる
@import構文 - Skills/Commandsでインデックス更新を自動化する方法
関連記事
| 記事 | 内容 |
|---|---|
| Markdown保存でトークン削減 | Fetch時のトークン削減テクニック |
| /research コマンドの紹介 | 調査品質を安定させるコマンド |
| この記事 | 増えたドキュメントの管理方法 |
解決策：READMEインデックス戦略
方針はシンプルです：
- READMEにインデックス（目次）を作る
- Claude Codeに確実に読み込ませる
- メンテナンスをAIに丸投げする
これにより、Claudeは全ファイルをスキャンせずに、必要なドキュメントだけを選択的に読み込めます。
前提知識：Claude Codeが自動で読むファイル
まず、Claude Codeが自動的に読み込むファイルを確認しておきましょう。
| ファイル | 自動読み込み |
|---|---|
CLAUDE.md / CLAUDE.local.md | される |
.claude/rules/*.md | される |
README.md | されない |
README.mdは自動読み込みの対象ではありません。
ただし、以下の方法で読み込ませることができます：
@import構文でCLAUDE.mdから参照- Skills/Commandsで明示的に「READMEを読め」と指示
体感として: Claudeはタスク遂行中にREADMEを探索して読むことが多いです。ただ、それは自発的な行動なので確実ではない。確実に読ませたい場合は
@importを使いましょう。
実装方法
1. READMEインデックスの設計
docs/research/README.md の例です：
# Research Documents
調査結果をまとめたドキュメント集です。
## 調査一覧
### Claude Code
| ファイル | 調査内容 | 調査日 |
|----------|----------|--------|
| [claude-code-hooks-skills](./2026-01-06-claude-code-hooks-skills.md) | Hooks/Skills/Commands の使い分け | 2026-01-06 |
| [claude-code-skills-best-practices](./2026-01-23-claude-code-skills-best-practices.md) | Skillsのベストプラクティス | 2026-01-23 |
### Azure
| ファイル | 調査内容 | 調査日 |
|----------|----------|--------|
| [azure-container-apps-deploy](./2026-01-07-azure-container-apps-deploy.md) | Container Apps デプロイ方法 | 2026-01-07 |
ポイント:
- カテゴリ別にテーブルで整理
- ファイル名、概要、日付を含める
- Claudeがこれを読めば全体構造を把握できる
2. CLAUDE.mdでの@import設定
CLAUDE.mdに以下を追加すると、起動時に自動で読み込まれます：
# CLAUDE.md
## ドキュメント参照
See @docs/research/README for research documents index.
この @path/to/file 構文により、CLAUDE.md読み込み時にREADMEも一緒に読み込まれます。
3. なぜCLAUDE.mdではなくREADMEにインデックスを置くのか
「インデックスをCLAUDE.mdに直接書けばいいのでは？」と思うかもしれません。
READMEに置く理由：
| 観点 | README | CLAUDE.md |
|---|---|---|
| 人間も参照する | する | あまりしない |
| GitHubで表示される | される | されない |
| 役割 | ドキュメントの目次 | Claudeへの指示 |
関心の分離ができて、メンテナンスもしやすくなります。
応用：Skills/Commandsで自動メンテナンス
インデックスを作っても、更新を忘れたら意味がないですよね。
そこで、Skills/Commandsのワークフローに組み込んで自動化します。
/research コマンドでの実装例
僕の /research コマンドでは、以下のステップを組み込んでいます：
### Step 0: Check Existing Research
Before starting new research, **always read `docs/research/README.md`** to:
1. Check if the topic has already been researched
2. Identify related research that can be referenced
3. Avoid duplicate work
### Step 5: Update README.md
After saving the research document, **always update `docs/research/README.md`**
効果:
| 課題 | 解決策 |
|---|---|
| インデックス更新を忘れる | Commandのワークフローに組み込み |
| 重複調査してしまう | Step 0で既存ドキュメントを確認 |
| フォーマットがバラバラ | Claudeが一貫した形式で更新 |
これで、人間がREADME更新を意識する必要がなくなります。
補足：.claude/rules/ でも対応可能
2025年12月にリリースされた .claude/rules/ を使う方法もあります（公式ドキュメント）。
# .claude/rules/readme-update.md
---
paths:
- "docs/**/*.md"
---
ドキュメントを追加・編集した場合は、一番近い階層のREADME.mdを更新してください。
paths を指定すると、該当ファイル作業時のみルールが適用されます。
ディレクトリ別CLAUDE.mdとの比較:
| 方法 | 特徴 |
|---|---|
| ディレクトリ別CLAUDE.md | 各ディレクトリに配置、そのディレクトリ作業時に読み込み |
.claude/rules/ + paths | 中央で管理、glob パターンで適用範囲を制御 |
READMEインデックス戦略と組み合わせることも可能です。
まとめ：結果的にAIフレンドリーな設計になる
READMEインデックス戦略のポイント：
- READMEにドキュメントの目次を作る
@importで確実に読み込ませる- Skills/Commandsでメンテナンスを自動化
これって、結果的にAIフレンドリーな設計になっているんですよね：
- AIが必要な情報を効率的に見つけられる
- AIがメンテナンスを担当できる
- 人間にとっても分かりやすい構造
ドキュメントが増えてきたら、ぜひ試してみてください。
参考リンク
公式ドキュメント
関連記事
ここまで読んでいただき、ありがとうございました！
ドキュメント管理は地味だけど、放置すると後で困る作業。AIに丸投げして楽しましょう。
