AI エージェントにきちんと「参照」させるMarkdown術〜目次を自動生成して Context 効率を上げる〜

Posted at 2025-11-07

はじめに

おはこんばんにちは！
株式会社ライトカフェ AI駆動開発G Group Manager の仙波（@semba_yui）です。

AI 駆動開発が流行りの昨今。
実プロジェクトで導入する場合、ただ vibe コーディングするのではなく、markdown 形式で設計ドキュメントを一度書いてからそれを元に実装させるという仕様駆動開発（SDD: Spec-Driven Development） での採用が増えています。

今回はこのような実践的なプロジェクトにおいて、AI エージェントをより活用するための、小さいながらも強力なテクニックを紹介します。

TL;DR

AI エージェントは大量のファイルを先頭から順に"head"して読むことが多く、無駄なコンテキストでトークンを浪費する
ファイルの最初に目次をおいておくことで、AI エージェントによる無駄なドキュメントの読み込みを防ぐ
目次は自動生成させておけばいちいち整備する手間が省ける

以上！たったこれだけ。
ここから下は理論の解説だったり実践編をやっていきます。

この記事の対象読者

Claude や Codex CLI、Cursor などの AI コーディングアシスタントを活用している方
プロジェクトドキュメントの効率化を考えている方
AI 駆動開発の導入を進めている開発チーム

環境

VS Code + Remark Extension
pnpm / npm / yarn / bun いずれか

背景: AI エージェントは必要な情報をどうやって集めているか

AI エージェントは CLI を使うのが異様に上手いです。

AI エージェントに指示を出すと、自分で必要な情報を探しにコードベースを隅から隅まで探しに行ってくれますが、この情報検索の際、コンテキストが圧迫してきたり、1ファイルに書かれている内容が500行を超えてきたあたりで head -100 などを組み合わせ、全文を一気に読まずに部分読みしていく特性があります。

私は膨大なログファイルを何も考えずに cat してフリーズさせたことが何度もあるので、AI エージェントはそうならないようにうまくチューニングされているんでしょうね。私の何倍も賢い…

Claude Code や Cursor などのエージェントを動かしているときの実行ログを目 grep してみてください。以下の流れでファイルを検索、読み込まれていることが多いはずです。

まず ls や find でファイル一覧を取得
関連しそうなファイルを head -n 50 で先頭部分だけ読む
必要そうなら tail や特定の行範囲を指定して続きを読む
全体が必要な場合のみ全文を読み込む

この戦略は非常に賢いのですが、ここに問題が隠れています。

問題: 目次が無いと起きる "無駄"

ここで、目次がドキュメントの最初にない場合に何が起きるか見てみましょう。

実際に起きる非効率なパターン

例えば、以下のような構成の README.md があったとします。

README.md

# プロジェクト名

プロジェクトの概要が書かれています...（100行）

## はじめに

詳しい背景説明...（150行）

## インストール方法

インストール手順...（80行）

## API リファレンス  ← エージェントが本当に知りたいのはここ！

API の詳細な説明...（200行）

## トラブルシューティング

よくある問題...（100行）

このとき、AI エージェントは「API の使い方を知りたい」と思っていても、以下のような非効率な探索をすることになります。

head -100 README.md → 概要部分だけ読む
「API リファレンスがあるかわからないから、もう少し読もう」
head -250 README.md → はじめに部分まで読む
「まだ見つからない...もっと読む必要がある」
head -330 README.md → インストール方法まで読む
ようやく API リファレンスに到達

無駄にトークンを3回も消費し、エージェントの思考ステップも増えています。

さらに深刻なケース

もっと深刻なのは、コンテキストウィンドウの制限に引っかかるケースです。
大量のドキュメントファイルがあるプロジェクトで、必要な情報が見つからなかったり、分散されていたりしてエージェントが順番に head -100 で探索していくと…

head -100 docs/architecture.md  # トークン消費
head -100 docs/api-guide.md     # トークン消費
head -100 docs/deployment.md    # トークン消費
head -100 docs/security.md      # トークン消費（本当に知りたいのはこれ！）
# でもここでコンテキスト制限に達してしまう...

結果、本当に読むべきファイルへ到達する前にコンテキストが埋まってしまい、エージェントは諦めるか、中途半端な情報で回答することになります。

これではハルシネーション祭りの始まりですね。~~台パンが止まりません。~~

解決策: 自動生成された目次を最初に置く理由

では、どうすればこの問題を解決できるでしょうか？
答えはシンプルに、ファイルの最初に目次を置くことです。

目次の例

## 目次

- [はじめに](#はじめに)
- [インストール方法](#インストール方法)
- [API リファレンス](#API リファレンス)
- [トラブルシューティング](#トラブルシューティング)

なぜ目次が効果的なのか

目次があると、AI エージェントは以下のように振る舞います。

head -50 README.md → 目次を発見！
「API リファレンスは3つ目のセクション、ということは300行目付近にありそうだ」と推測
sed -n '300,500p' README.md → 直接必要な箇所を読む

たった2回のファイルアクセスで目的達成できていて、トークンもステップも大幅に節約できます。
DB には Index、LLM には目次をというわけです。RAG とも考え方はほぼ同じですね。

人間にとってのメリット

もちろん、これは人間にとっても便利です。

GitHub や GitLab でドキュメントを開いたとき、すぐに全体像が把握できる
長いドキュメントでも目的のセクションにジャンプしやすい
チーム内への共有で目次のリンクを渡せてスムーズになる

AI と人間、両方にとって Win-Win なのです。

自動生成が重要な理由

markdown の目次を手動で管理すると、以下の問題が起きます。

見出しを追加・変更したとき、目次の更新を忘れる
リンクが壊れる
メンテナンスコストが高い

ツールを使った自動生成なら、これらの問題はすべて解決します。
ファイル保存時に自動で目次が更新されるので、常に最新の状態を保てます。

実装ハンズオン: remark を使った目次の自動生成方法について

それでは実際に目次の自動生成を導入してみましょう。
今回は remark, remark-toc を使います。

まずは、以下のコマンドで remark と必要なプラグインをインストールします。
npm や yarn, bun の場合は適宜コマンドを読み替えてください。

pnpmの場合

pnpm add -D remark remark-toc remark-cli

`.remarkrc` の設定

プロジェクトルートに .remarkrc ファイルを作成し、以下の内容を記述します。

.remarkrc

{
  "plugins": [
    [
      "remark-toc",
      {
        "heading": "目次|table of contents",
        "maxDepth": 3
      }
    ]
  ]
}

設定の解説

heading: 目次のセクション名（日本語と英語の両方に対応）
maxDepth: 目次に含める見出しの深さ（h3まで）

より実践的な設定

私の場合はいくつかプラグインを追加していて、最終的に以下のようになっています。

remark に markdown の Lint も追加することで、AI によって自動生成される大量のドキュメントのある程度の品質を保証することもできます。

.remarkrc

{
  "plugins": [
    "remark-preset-lint-consistent",
    "remark-preset-lint-recommended",
    "remark-gfm",
    [
      "remark-toc",
      {
        "heading": "目次|table of contents",
        "maxDepth": 3
      }
    ],
    ["remark-frontmatter", ["yaml"]]
  ],
  "settings": {
    "bullet": "-",
    "emphasis": "*",
    "strong": "*"
  }
}

追加したプラグインは以下。基本的に入れておいて損は無いはずです。

pnpmの場合

pnpm add -D remark-lint remark-preset-lint-consistent remark-preset-lint-recommended remark-frontmatter remark-gfm

各プラグインの役割

remark-lint: Markdown のチェックを有効化
remark-preset-lint-recommended: Markdown のベストプラクティスに従ったチェック
remark-preset-lint-consistent: スタイルの一貫性チェック
remark-frontmatter: YAML フロントマターのサポート
remark-gfm: GitHub Flavored Markdown のサポート（テーブル、タスクリストなど）

`.remarkignore` の追加

こちらもプロジェクトルートに .remarkignore ファイルを作成し、remark の対象から外します。基本的に gitignore と同じようなものや、目次がなくても良いものを外しておきましょう。

.remarkignore

node_modules
dist
coverage
.serena/memories

使い方

まず、目次を追加したい markdown ファイルに 「目次」もしくは「table of contents」というセクション ## 目次 をファイルの先頭の方に追加します。

これは先程の .remarkrc で設定した heading 項目に設定したものです。

.remarkrc

{
  "plugins": [
    [
      "remark-toc",
      {
        "heading": "目次|table of contents",
        "maxDepth": 3
      }
    ]
  ]
}

目次セクションの追加後、以下のコマンドで目次の自動生成が可能です。

pnpm remark . --output --quiet

lint チェックのみを実施する場合は以下です。
ちなみに目次の有無のチェックについては lint では検出してくれません。

pnpm remark . --frail --quiet

なお、コマンドにつけたオプションは以下です。

--frail: warning も1で終了する
--quiet: warning と error のみを出力

最初は --quiet オプションは外してどれが remark の対象になっているかを確認し、 .remarkignore に設定する対象を探ってから付与するのがオススメです。

完全に自動化するためには git の precommit hook に設定したり、CI で付与してあげたりすればよいということになります。

VS Code ユーザー向け

remark の拡張機能を追加する

以下の VS Code 拡張機能を追加します。

チームで統一したい場合は以下のように設定して下さい。

.vscode/extensions.json

{
  "recommendations": [
    "unifiedjs.vscode-remark"
  ]
}

VS Code でファイル保存時に自動で remark で保存するように設定する

VS Code のフォーマッタとして先程追加した remark の拡張機能を設定します。

.vscode/settings.json

{
  "[markdown]": {
    "editor.defaultFormatter": "unifiedjs.vscode-remark"
  },
  "editor.formatOnSave": true
}

これで Markdown ファイルを保存するたびに自動で目次が更新されます！

運用ルール: 見出し設計、目次の深さ、要約ルール

目次を効果的に活用するためには、いくつかの運用ルールを決めておくと良いでしょう。

見出し設計について

AI エージェントが理解しやすい見出しにするためのポイントです。

1. 明確で具体的な見出しをつける

AI エージェントは具体的なキーワードで検索します。曖昧な見出しだと、目次があってもエージェントが正しいセクションを見つけられません。

❌ 悪い例

## 使い方
## その他
## 注意点

✅ 良い例

## インストール手順
## API リファレンス
## トラブルシューティング

階層構造を適切に使う

見出しレベル（h2, h3, h4）を適切に使い分けることで、ドキュメントの構造が明確になります。

## クイックスタート
### 前提条件
### インストール
### 初回セットアップ

## 詳細ガイド
### アーキテクチャ
### 設定オプション
### ベストプラクティス

目次の深さ

目次の深さは、ファイルのタイプにもよりますが基本的には maxDepth: 3（h3まで）がおすすめです。

これは .remarkrc で設定した maxDepth 項目に設定したものです。

.remarkrc

{
  "plugins": [
    [
      "remark-toc",
      {
        "heading": "目次|table of contents",
        "maxDepth": 3
      }
    ]
  ]
}

理由は以下です。お好みよりの部分ですが。

h2-h3: ドキュメントの主要な構造を示すのに十分
h4以降: 細かすぎて目次が長くなり、かえって見づらくなる

# タイトル（h1）          ← 目次に含めない
## メインセクション（h2）  ← 目次に含める
### サブセクション（h3）   ← 目次に含める
#### 詳細（h4）           ← 目次に含めない（詳細すぎる）

要約ルールについて

ドキュメントの最初（目次の前）に、簡潔な要約を置くのも効果的です。

TL;DR セクションを設ける

AI エージェントは最初の数十行で全体像を把握しようとします。
TL;DR があると、エージェントはドキュメントの価値を素早く判断できます。

# プロジェクト名

プロジェクトの1行説明

## TL;DR

- 主な機能1
- 主な機能2
- 対象ユーザー

## 目次

...

各セクションの冒頭にも要約を入れる

長いセクションには、冒頭に要約を入れるとより親切です。

## API リファレンス

このセクションでは、本ライブラリが提供する全APIの詳細を説明します。
基本的な使い方は「クイックスタート」を、実践例は「チュートリアル」を参照してください。

### API一覧
...

これにより、セクション内でのナビゲーションも改善されます。

よくある問題と解決法

目次が生成されない

## 目次 セクションが存在するか確認
.remarkignore で対象ファイルが除外されていないか確認

VS Code拡張で保存時にフォーマットされない

editor.formatOnSave: trueが設定されているか確認
markdown ファイルの defaultFormatter が正しく設定されているか確認

おわりに

最近はエラーログや例外、テストの出力など、プロジェクトに関連する全てのものを AI が読みやすい形式にしてあげないといけないなと考えています。例外メッセージが出たらまず自分で読む前に一旦エージェントに読んでもらいますし。

この記事で紹介した markdown 活用術については、ぜひあなたのプロジェクトでも試してみてください！

おまけ

実はこの内容、Claude Code 公式の Agent Skills の Best practices にも書かれています。

For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.

実は私もこの公式の記載に気がついておらず、普段の AI エージェントのログを見て気がついていたことだったんですが、いつの日も公式ドキュメントを目を通しておくと良いことがあるものですね。

AI 駆動開発の関連記事

問い合わせ先

案件のご依頼・ご相談は、以下までご連絡ください。
info@lightcafe.co.jp

We are hiring!

ライトカフェはエンジニアを積極採用中です。

常にお客様に寄り添い課題を認識し、解決の手助けをさせていただく。業務SIerにとって当たり前の事ですが、わたしたちはそれを一番大切にしています。
この会社コンセプトに共感して頂ける方、世の中のWEBサービス開発に関わりたい方をお待ちしています。

#イツモトナリニライトカフェ

ライトカフェ採用ページはこちら

ライトカフェクリエイション採用ページはこちら

note はこちら

社内の雰囲気や制度など、ライトカフェの魅力を発信しています。

X（旧Twitter）はこちら

会社のニュースや日々の出来事、採用情報などを発信しています。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

AI エージェントにきちんと「参照」させるMarkdown術 〜目次を自動生成して Context 効率を上げる〜

はじめに

TL;DR

この記事の対象読者

環境

背景: AI エージェントは必要な情報をどうやって集めているか

問題: 目次が無いと起きる "無駄"

実際に起きる非効率なパターン

さらに深刻なケース

解決策: 自動生成された目次を最初に置く理由

なぜ目次が効果的なのか

人間にとってのメリット

自動生成が重要な理由

実装ハンズオン: remark を使った目次の自動生成方法について

.remarkrc の設定

設定の解説

より実践的な設定

各プラグインの役割

.remarkignore の追加

使い方

VS Code ユーザー向け

remark の拡張機能を追加する

VS Code でファイル保存時に自動で remark で保存するように設定する

運用ルール: 見出し設計、目次の深さ、要約ルール

見出し設計について

1. 明確で具体的な見出しをつける

❌ 悪い例

✅ 良い例

階層構造を適切に使う

目次の深さ

要約ルールについて

TL;DR セクションを設ける

各セクションの冒頭にも要約を入れる

よくある問題と解決法

目次が生成されない

VS Code拡張で保存時にフォーマットされない

おわりに

おまけ

AI 駆動開発の関連記事

問い合わせ先

We are hiring!

ライトカフェ採用ページはこちら

ライトカフェクリエイション採用ページはこちら

note はこちら

X（旧Twitter）はこちら

AI エージェントにきちんと「参照」させるMarkdown術〜目次を自動生成して Context 効率を上げる〜

`.remarkrc` の設定

`.remarkignore` の追加