Claude Codeのドキュメント検索を極力さぼれるようにした話

「あの調査どこだっけ」で済む世界がほしかった

ども！ドキュメントが70件を超えて検索がカオスになっている龍ちゃんです。

結論から言うと、ファイルパスを指定しなくても「あの調査どこだっけ」と話し言葉で聞くだけで、勝手に見つけてくれる仕組みを作りました。ファイルの作り方を工夫して、検索専用の Haiku サブエージェントを .claude/agents/ に置いただけ。今回はその仕組みの話です。

僕は Claude Code への指示を極力さぼりたいんですよね。ドキュメントのパスを毎回共有するようなことはしたくないので、文脈と単語で勝手に探してほしいんですよね。

以前、AIフレンドリーなドキュメント管理という記事で README にインデックスを作る方法を紹介しました。50件まではそれで回っていたんですが、70件を超えたあたりでClaude Codeの検索がポンコツになりました。

破綻からやったことは2つです。

1. ドキュメントにメタデータを埋め込む（まずはここから）
   — YAML Frontmatter で tags, keywords, use_when 等を付与して、検索精度を上げる
2. 検索専用サブエージェントを作る
   — .claude/agents/ にエージェント定義ファイルを置いて、特定ディレクトリに特化した検索エージェントを作る

今回の内容です。

• READMEインデックスが破綻した理由
• エージェントの検索精度を上げるメタデータ設計
• 検索専用サブエージェント（Haiku）の作り方と Explore との違い
• 実際のエージェント定義ファイル（ブログの最後に配置されています）

ドキュメント増えてきたら Claude Codeの検索がポンコツになる話

READMEインデックスとは

まず前提から。Claude Code でドキュメントを管理するときに、僕がやっていた方法がこれです。

ドキュメントが入っているディレクトリに README.md を置いて、ファイル名・タイトル・カテゴリの一覧表を作る。Claude Code は CLAUDE.md から @import でこの README を読み込む。全ファイルを開かなくても、README を1つ読めば「このディレクトリに何があるか」が分かる。ドキュメントの「目次」を作って、AI に目次から探させる手法ですね。

まずは、AIフレンドリーなドキュメント管理を読んでみるとスムーズに話が入ってくるかも？

70件を超えたら破綻した

50件程度まではこれで回ってました。70件を超えたあたりから破綻しましたね。

ファイル数が増えるとタイトルだけでは区別がつかないドキュメントが出てくるんですよ。実際に起きたのが、Claude Code の Skills について調べたかったのに、GitHub Copilot の Agent Skills の記事が出てきたケース。README のタイトル一覧を見ると、こういう状態です。

「Skills」でタイトルを探すと、Claude Code と GitHub Copilot の記事が混在しています。README のインデックスにはタイトルしかないから、どっちの「Skills」なのか区別がつかない。

MCP 関連はもっとひどくて、調査ドキュメントだけで6件が「MCP」をタイトルに含んでました。「MCPが遅いんだけど」と聞いたとき、「MCP設計ベストプラクティス」「MCPの課題と制限」「CLI tools vs MCP 比較」「MCP計測・ログ方法」…どれを読めばいいのか、タイトルだけでは Claude にも判断できないんでファイルパス出して問い合わせが来ます。。

結果、Explore が全ファイルパスから探しに行ってトークンを消費する。本質的な問題は、README インデックスが「タイトルベースの検索」にのみ対応していること。ユーザーが言葉で表現する「やりたいこと」から適切なドキュメントを探す——こういう意図ベースの検索に対応できないんですよね。

メタデータで検索精度を上げる

まずサブエージェントの話の前に、ドキュメント側の改善から。実はこれだけでもビルトインの Explore の検索精度が上がるんですよね。

YAML Frontmatter を設計する

僕の docs/research/ では、各ドキュメントの冒頭に YAML Frontmatter を付けています。

---
title: "MCPの課題と制限"
date: 2026-01-29
category: Claude Code
tags:
  - MCP
  - パフォーマンス
related:
  - 2026-01-29-cli-tools-vs-mcp-comparison.md
use_when:
  - "MCP接続でパフォーマンス問題に直面"
  - "MCPが遅いと感じたとき"
keywords:
  - Notion MCP
  - Playwright MCP
---

それぞれのフィールドの役割はこんな感じです。

use_when が鍵

一番大事なのは use_when です。

「MCPが遅い」に対して、タイトルだけでは6件の中から選べない。でも use_when: "MCP接続でパフォーマンス問題に直面" が入っていれば、「パフォーマンスの話だ」と判断できるようになる。タイトルでは区別できなかった意図ベースの検索が、ここで実現するんですよね。

use_when には「〇〇のとき」「〇〇に直面」のように、ユーザーの状況を書きます。タイトルよりも具体的で、本文よりもコンパクト。
ここは何を知りたいと思ったか？というキーワードで考えるとつけやすいです。人間の頭は忘れるようにできるんで、気になったときには疑問のほうが先に浮かびます。

メタデータの管理もAIに任せる

「Frontmatter を全ドキュメントに手で書くのは大変じゃない？」——大変です。

だからこの仕組み自体の管理も AI に任せちゃってます。ドキュメントを作成する Skill や Agent の中に「保存時に Frontmatter を自動付与する」って指示を組み込んでおけば、ドキュメントが作られるたびにメタデータが勝手に付きます。

実際にうちの /research スキルでは、調査ドキュメントを保存する際に Frontmatter を自動生成してます。人間が手作業で tags や use_when を考える必要はない。仕組みを作る手間は最初の1回だけで、あとは放っておいても自動管理です。

んで既にドキュメントある人も安心してください。そんなことはAIさんにお願いすればいいんです。寝る前に「Sonnetの並列でYAML Formatterをつけといて」と依頼しておけばきっと布団でごろごろしている間に終わってます。

CLAUDE.md に Frontmatter の構造を教える

サブエージェントを作らない人はここ注意です。Frontmatter を付けただけだと、ビルトインの Explore はその構造を知らないんですよね。use_when というフィールドがあって意図ベースの検索に使える——この情報がないと、Explore は普通に本文を Grep するだけになります。

CLAUDE.md に「docs/research/ のファイルには YAML Frontmatter があり、use_when で利用シーン、tags でカテゴリ、keywords で固有名詞を検索できる」と書いておいてください。サブエージェントはエージェント定義ファイルにこの知識を仕込んでいるから不要ですが、Explore だけで運用するならこの一手間が必要です。

README インデックスは残す

サブエージェントを入れたから README インデックスは不要……ではないです。後述する3段階検索の Level 1 で、まず README のカテゴリ別テーブルから候補を絞るんですよね。この高速な絞り込みが最初のフィルターになります。

README インデックス + メタデータ + サブエージェント。置き換えじゃなくて、積み上げです。

検索専用サブエージェント（Haiku）を作る

Frontmatter を整えるだけでも検索精度は上がる。こっからは専門のエージェントを作って管理をしてもらうという話をしていきます。

Explore ではダメなのか？

「検索なら Explore があるじゃん」と思った方、鋭いです。

でも Explore はプロジェクト全体から検索をかけるんで、時間食った挙句に違うファイルを出してくることがあったんですよね。

実は Claude Code のビルトインエージェント Explore も Haiku で動いてます。Claude Code 自体が、ドキュメント検索に Haiku を使ってるんですよね。じゃあなぜわざわざ専用エージェントを作るのか。

専用エージェントは description でスコープを絞れるし、エージェント定義の本文にドメイン知識を注入できる。Explore が図書館の一般案内係だとしたら、専用サブエージェントはその棚の構造を熟知した専門の司書みたいなもんです。

モデルは同じ Haiku。違いは「どこまで知っているか」だけ。ちなみにサブエージェントから別のサブエージェントは起動できないんで（公式の制限）、検索エージェントはメインセッションから直接呼び出す設計にしてください。

エージェント定義ファイルの書き方

実際に僕が使っている research-searcher の定義ファイルを見てもらうのが早いです。.claude/agents/research-searcher.md に置いています。

---
name: research-searcher
description: >
  docs/research/配下の調査ドキュメントを検索・要約するエージェント。
  「前に調べた〜の調査」「〜についての調査結果どこだっけ」
  「MCPの課題をまとめた調査があったはず」等のリサーチドキュメント検索、
  タグ・キーワードベースの横断検索に使用します。
tools: [Read, Grep, Glob]
model: haiku
---

それぞれ見ていきます。

model: haiku — 検索は読み取りがメインなので、Opus の 1/5 のコストで済みます。

tools: [Read, Grep, Glob] — 読み取り専用にしています。検索エージェントにファイルの編集はさせない。

description が最重要 — ここが一番大事。Claude はこの description を見て「この質問はこのエージェントに任せよう」と判断します。

description に自分の会話パターンを埋め込む

description をもう一度見てください。

「前に調べた〜の調査」「〜についての調査結果どこだっけ」
「MCPの課題をまとめた調査があったはず」

これ、僕が普段 Claude に話しかけるフレーズそのままなんですよね。丁寧な説明文じゃなくて、ラフな口語をそのままぶち込んでます。

なぜかというと、Claude はこの description を見て「この質問はこのエージェントに委譲すべきか？」を判断するから。自分の口癖に寄せておいたほうが、実際の会話パターンとマッチしやすいんですよね。公式のベストプラクティスでも「いつ委譲すべきかを明確に記述する」ことが推奨されてます。入れなくても比較的意図を察してくれるんですが、入れておくと精度が上がります。

ポイントは、description をドキュメントっぽく書かないこと。自分がどういう場面でそのエージェントを使いたいかを具体的に書く。「ドキュメントを検索するエージェント」みたいな汎用的な説明だと、Claude の Explore が優先されて起動されます。

3段階検索戦略

エージェント定義ファイルの本文（--- の下）には、検索の手順を書きます。僕のエージェントでは3段階で検索させてます。

1. Level 1: README インデックスを読む
   — docs/research/README.md のカテゴリ別テーブルから候補を絞る。これが一番安い
2. Level 2: Frontmatter を確認する
   — 候補ファイルの冒頭にある YAML Frontmatter（tags, use_when, keywords）で内容を精査する
3. Level 3: 本文を Grep で横断検索
   — 上の2段階で見つからなかった場合の最終手段

ポイントは、いきなり本文を全部読まないこと。README → Frontmatter → 本文の順に、段階的に情報を絞り込む。これでサブエージェントのトークン消費も抑えられます。

実際に使ってみた結果

さっきの破綻の例、覚えてますか。Claude Code の Skills について聞いたのに GitHub Copilot の Agent Skills の記事が出てきたやつ。

サブエージェント導入後に同じように「Skills の調査どこだっけ」と聞いたら、ちゃんと Claude Code の Skills の記事から出してくれるようになりました。サブエージェントが Frontmatter の tags: Claude Code と use_when を見て、文脈から「これは Claude Code の話だ」と判断してるんですよね。タイトルだけで探してた頃とは精度が全然違います。大満足です。

まとめ

「あのファイルどこだっけ」が増えてきた人、まず YAML Frontmatter を付けてください。特に use_when。これだけでビルトインの Explore でも検索精度が変わります。既存ドキュメントが大量にある人も、Sonnet に並列で投げれば寝てる間に終わるんで気にしなくていいです。

んでさらに速度と精度がほしくなったら .claude/agents/ に検索専用サブエージェントを足す。description に自分の口癖をぶち込んでおけば、Claude が勝手に使い分けてくれます。

一回仕組み作っちゃえばあとはさぼれるんで、ドキュメント増えてきた人は試してみてください。

ではまた！

関連記事

• Claude Codeへの指示を少しでもさぼりたい！AskUserQuestionツール
  — 聞き返し機能で指示の手間を減らす。「さぼりシリーズ」の原点
• Claude Code設計術：AIフレンドリーなドキュメント管理
  — READMEインデックスの作り方。本記事の前提になる話
• Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善
  — CLAUDE.md設計で無駄な検索を減らして高速化する方法
• Claude Code サブエージェントの最適構成：Opus で考え、Sonnet で動かす
  — Opus/Sonnet/Haikuの使い分け設計。本記事のHaikuサブエージェントもこの考え方がベース
• Claude Code /research の待ち時間をゼロに：Skill × サブエージェント構成
  — Skillとサブエージェントを組み合わせて調査を並列実行する構成
• Claude Codeに専門知識を仕込む：調査→構造化→注入の設計パターン
  — 調査結果をエージェントに注入するパターン。Frontmatterの設計思想に近い

付録：実際のエージェント定義ファイル全文

僕が使っている research-searcher の定義ファイル（.claude/agents/research-searcher.md）をそのまま載せます。コピーして自分の環境に合わせて書き換えれば動きます。

---
name: research-searcher
description: docs/research/配下の調査ドキュメントを検索・要約するエージェント。「前に調べた〜の調査」「〜についての調査結果どこだっけ」「MCPの課題をまとめた調査があったはず」等のリサーチドキュメント検索、タグ・キーワードベースの横断検索に使用します。
tools: [Read, Grep, Glob]
model: haiku
---

# Research Searcher Agent

`docs/research/` 配下の調査ドキュメントを検索・情報抽出するエージェントです。

## 役割

メインセッション（Opus）から Task tool で呼び出され、調査ドキュメントの検索・照合・要約を行い結果を返却します。

## データ構造の理解

### ファイル命名規則

```
YYYY-MM-DD-topic-name.md
```

### Frontmatter（検索に活用）

各ファイルには以下の YAML Frontmatter がある：

| フィールド | 説明 | 検索への活用 |
|-----------|------|-------------|
| `title` | ドキュメントタイトル（日本語） | タイトルマッチ |
| `date` | 調査日 | 時期での絞り込み |
| `category` | 主カテゴリ | カテゴリ絞り込み |
| `tags` | 検索用タグ（3-8個） | タグベース検索 |
| `related` | 関連ファイル名 | 関連調査の芋づる検索 |
| `use_when` | 利用シーン | 「〇〇のとき」で検索 |
| `keywords` | 重要キーワード（固有名詞等） | 技術名での検索 |

### カテゴリ一覧

- Claude Code / Azure / マーケティング / ライティング品質
- ライセンス / マネジメント / ツール・変換 / AI・LLM

## 検索戦略（3段階）

### Level 1: インデックス検索（最初に必ず実行）

`docs/research/README.md` を読み、カテゴリ別テーブルから候補を絞り込む。

```
Read({ file_path: "docs/research/README.md" })
```

- カテゴリ別にファイル名・調査内容・調査日がテーブルで整理されている
- **多くの検索はこの段階で候補が絞れる**

### Level 2: Frontmatter 確認（候補の詳細確認）

候補ファイルの frontmatter を読み、`tags`, `use_when`, `keywords`, `related` で内容を精査する。

```
Read({ file_path: "docs/research/[候補ファイル].md", limit: 30 })
```

frontmatter の `tags` と `keywords` は本文を読まずに関連性を判断できる強力な手がかり。

### Level 3: 本文検索（キーワードがタイトル・タグに含まれない場合）

Grep で本文内を横断検索する。

```
Grep({ pattern: "検索キーワード", path: "docs/research/", glob: "*.md" })
```

## 検索パターン別の処理

### パターン1: トピック検索

「MCPの調査あったよね」「RAGについて調べたはず」等の場合：

1. README.md のテーブルからトピック名でマッチ
2. 候補の frontmatter で `tags` / `keywords` を確認
3. 該当ファイルのタイトル・要約・タグを返却

### パターン2: 用途ベース検索

「〜するときに参考になる調査」等の場合：

1. Grep で `use_when` フィールドを横断検索
2. マッチしたファイルの frontmatter を確認
3. 利用シーンと合致する調査を返却

### パターン3: 関連調査の探索

「この調査と関連する他の調査は？」等の場合：

1. 基準ファイルの frontmatter から `related` フィールドを取得
2. 関連ファイルの frontmatter を確認
3. さらに同じ `tags` を持つファイルを探索（芋づる式）

### パターン4: カテゴリ・時期での絞り込み

「最近のClaude Code関連の調査一覧」等の場合：

1. README.md のカテゴリ別テーブルから該当カテゴリを抽出
2. 日付で絞り込み
3. 一覧として返却

### パターン5: 技術名での検索

「FastMCP」「SCANOSS」等の固有名詞での検索：

1. Grep で `keywords` フィールドを検索
2. マッチしない場合、本文を横断検索
3. 該当ファイルを返却

## 出力形式

```markdown
## 検索結果

| ファイル | タイトル | カテゴリ | 調査日 |
|----------|---------|---------|--------|
| YYYY-MM-DD-topic.md | タイトル | カテゴリ | YYYY-MM-DD |

### 要約
[該当調査の概要。frontmatter の title + tags から構成、または本文冒頭から抽出]

### 関連調査
- [関連ファイル名] - [タイトル]（related フィールドから取得）
```

## 制約事項

- **読み取り専用**: 調査ファイルの編集・作成は行わない
- **スコープ限定**: `docs/research/` 配下のみを対象とする
- **Web検索なし**: ローカルファイルの検索のみ
- **トークン節約**: 本文全体を読むのは必要最小限にとどめる

ポイントを補足しておくと:

• description は自分の口癖に合わせて書き換えてください。ここが委譲判断の精度に直結します
• カテゴリ一覧やFrontmatter スキーマは自分のドキュメント構造に合わせて変更してください
• 検索パターンは増やしても減らしても OK。自分がよく使う検索パターンだけ残せば十分です

参考リンク

• Claude Code Sub-agents 公式ドキュメント
• Anthropic Multi-Agent Research