CLAUDE.md の目次に 3 行足したら、Claude の迷子が到達率 25%→100% になった

Claude Codeの運用で多い「CLAUDE.mdには要点とリンクだけを置き、詳細は子ファイルに逃がす」という構成が、本当に機能しているかをログから測った記事である。Claude Codeのセッションログには、どのファイルをどの順で読んだかと、そのターン時点のコンテキストサイズが残っている。それを使い、claude -pでまっさらなセッションに質問を投げて到達率を測る仕組みを作った。

最初に自分で書いた4問では到達率が50%だった。目次を3行足すと100%になった。ところが、ファイル内容から質問を自動生成すると到達率は25%に落ちた。よく読まれているファイルが目次に1つも載っていなかったためだ。そこで目次に3行を足すと、再び100%に戻り、平均コストは22%下がった。

面白いのは、迷子の故障モードが「遠回り」ではなかったことだ。Globでファイル一覧に対象が見えているのに開かず、「見つかりませんでした」と答えていた。あるドキュメントが充実していると、隣のドキュメントの存在を隠してしまう。さらに、書いた本人は答えの場所を知っているので自分では検証できない、という指摘は耳が痛い。本音で言えば、社内マニュアルも同じで、書き手が「これで全部」と思った瞬間が一番危ない。

中小企業でAI用の社内文書を持つなら、現場が実際に聞く質問を5〜10個集めて、AIに答えさせてみるとよい。答えが出ない、あるいは別の文書を見落とすなら、目次に1行足す。1ケース数セント程度の試行で済むので、文書を直すたびに測る習慣は現実的だ。