AI エージェントが迷子になる本当の理由 — フォルダ構造の罠とたった一つの解決策
先週、私たちがまだ遭遇したことのないコロナウイルスに対するワクチンを設計した AI について読みました（ScienceDaily）。ケンブリッジ大学が初めての人体実験を実施し、39 人のボランティアが抗原を接種しました。
あるアルゴリズムがウイルスの遺伝子ファミリー全体を分析し、まだ動物の間で循環していて人間に感染するのを待っているメンバーに対する防御策を設計したなんて、考えただけで驚きです。しかし、私が AI に最新のブリーフをドキュメント一覧から取得してほしいと頼むと、3 ヶ月前のブリーフを表示するだけのために、私の保管庫で間違ったファイルを開くのに約 2 分も費やしてしまうのです。
もちろん、ケンブリッジ大学はカスタムトレーニングされた AI を使っていることは分かっています。しかし、ここでお見せしたいのは、AI が本来できることと、実際のセットアップが許していることのギャップこそが、ワークフローと生産性を左右するという点です。
最近まで、私は意図的に scaffolding（足場）を構築したことがありませんでした。それは偶然エージェントの周りに積み上がり、フォルダごとに、私が自分で作り上げた混乱の中でエージェントが道に迷うまでになりました。
そこで、1 日かけてすべての失敗を計測したところ、あるパターンが見えてきました。今回の記事では、なぜあなたのエージェントが簡単なことでつまずき続けるのか、そして世界がそれを天才と呼ぶ一方で、あなたの側に引き戻す修正方法をお見せします。
この記事で扱う内容:
- フォルダ構造がエージェントの失敗を招いた理由 — フォルダが AI のナビゲート方法ではなく、人間の思考方法で整理されていたから
- 主要フォルダのルートに 1 つのインデックスファイルを置くだけで、遅い検索が 30 秒の読み取りに変わった方法
- エージェントの周りの目に見えない scaffolding が、エージェント自身の能力よりも重要である理由と、その構築方法
- フォルダ構造が本当の問題かどうかを 5 分で確認できる診断テスト
エージェントが見ることのできない構造
私はほとんどの人がやるように保管庫を整理していました。記事、研究、アセット、戦略ドキュメント — それぞれに専用のフォルダを割り当てていました。この構造は、コンテンツタイプで考える私にとってはすっきりしていました。フォルダは私のカテゴリに対応しており、どこを探せばいいか考える必要はありません。下書きは記事、ノートは研究 — ファイリングシステムはオートパイロットで動いていました。
しかし、エージェントはカテゴリで考えません。Hermes に製品ローンチの計画を依頼すると、そのタスクは戦略ノート、ブランドガイドライン、過去のローンチ情報を、異なるフォルダから収集する必要があります。
それらのコンテキストは、私のコンテンツタイプ構造の中の異なる場所に散らばっています。エージェントは毎回すべてを検索しなければならず、どの下書きが最新でどれがアーカイブなのか、どの研究ノートが今月のものでどれが 6 ヶ月前のものなのかを認識できません。
コンテンツタイプによる整理は人間には完璧に機能します。あなたは一生をかけてカテゴリ別にファイルを整理してきており、あなたの脳は自動的に相互参照を行います。AI も同じように動くと思うのは自然なことですが、実際にはエージェントはその相互参照を手動で行わなければならず、そこで構造が崩壊するのです。
エージェントの周りの構造は、エージェント自身の能力よりも多くの仕事をしている。
パターンに気づいたとき、原因は明らかでした。私は人間の脳（どこに何があるか覚えている）のために保管庫を構築し、それを毎回ゼロから検索しなければならないエージェントに渡していたのです。そして、それがフォルダの混乱の奥にある本当の問題を浮き彫りにしました。
検索者には地図が必要です。なぜなら、地図がなければエージェントは暗闇の中を歩き回り、すべてのファイルを答えかもしれないものとして扱ってしまうからです。
能力が浪費される場所
Hermes は正しいファイルにたどり着く前に多くのファイルを開き続け、現在のファイルが別の場所にあるのにアーカイブ版を取得していました。さらに悪いことに、文脈から明らかであるべき時にどのファイルを使うべきか尋ねてくることもありました。これは Opus、GPT 5.5、Qwen、GLM を含む、私が使用したすべてのモデルで発生しました。
このパターンは繰り返され、私は同じ遅い検索がタスクごとに繰り広げられるのを見ているだけでした。
エージェントは物を見つける能力は十分にあったものの、フォルダ構造が実際の作業に到達する前の主要なボトルネックになっていました。
限界点に達したのは、失敗を計測した日でした。Hermes が正しいファイルに到達するまでに何ファイルを開いたか、そしてそこにどれだけの時間がかかったかを追跡しました。何も変更する前の 5 つの一般的なタスクは次のとおりです。
何も変更する前:
- 現在の記事ブリーフを見つける: 7 ファイルを開き、正しいファイルまで 2:00
- ブランドカラー定義を見つける: 5 ファイルを開き、1:12
- 計画用の記事キューを確認する: 4 ファイルを開き、0:48
- 同じトピックの以前の記事を見つける: 6 ファイルを開き、1:36
- ローンチのプロモーション戦略を取得する: 3 ファイルを開き、0:34
大まかな実験なので、正確な数値は方向性として捉えてください。
すべてのタスクが複数のフォルダを横断していました。ほとんどのタスクで、アクティブなバージョンを見つける前にアーカイブ版を開いていました。私のエージェントは仕事をする代わりにナビゲーションに能力を浪費していたのです。あるローンチ計画では、3 つの異なるフォルダにある 3 つのファイルが必要でしたが、正しいファイルにたどり着くまでに 3 回も間違った試行をするのを目の当たりにしました。
記事を書き、コードを書き、計画を立てるエージェントが、ほとんどの時間を物探しに費やすべきではない。
機能する最小のケージ
関心事ごとに 1 フォルダ、順序付けのために番号を付け、すべてをマッピングする INDEX.md をルートに配置する。これが修正のすべてであり、詳細は連携して機能する 3 つのルールにあります。
各主要フォルダのルートにある INDEX.md は地図です。すべてのサブフォルダと正規ファイル、そしてエージェントがどこから始めるべきかをリストします。エージェントはこれを最初に読み、他のものに触れる前に中身を把握します。エージェントが作業対象を理解するまで作業を開始できない、ソフトな承認ゲートと考えてください。
再編成後の私のブランドフォルダ構造は次のようになります。
105.Brand/2├── INDEX.md3├── 01.Brand System/4├── 02.Editorial Strategy/5├── 03.Promotion/6├── 04.Public Deliverables/7├── 05.Operating Plan/8└── 06.Archived/
この構造は、コンテンツタイプではなく関心事ごとに整理されています。各関心事には専用のフォルダがあるため、ブランド作業はブランド作業とともに、戦略は戦略とともに保たれます。エージェントは本来属さないものを探して境界を越えることはありません。
フォルダに番号を付けることで、アルファベット順に頼るのではなく、読み取り順序を明示的にします。01.Brand System は 02.Editorial Strategy の前に読み取られます。エージェントは推測しません。フォルダ内の番号もファイルに対して同じことを行うため、エージェントは 01.Articles が 02.Previous Articles より先に出発点であることを認識します。
フォルダ名の先頭に番号を付けるのは、私にとっても覚えやすいからです。
これにより、私の完全な $30 Hermes スタックが、エージェントを迷子にすることなく、数十のフォルダを簡単に移動できるようになります。
アーカイブされたものは 06.Archived に置かれ、古いブリーフや廃止された計画はそこで待機します。エージェントは、私が特に過去のコンテキストを要求しない限り、そこを探さないことを認識しています。この分離こそが、アクティブなフォルダをクリーンに保ち、検索を高速にするものです。
エージェントにデフォルトでその境界を越えないように指示してから、アクティブフォルダ内のすべてのタスクが高速になった。
私の INDEX.md は次のようになります。
1# Brand Index23このフォルダには現在のブランドシステムが格納されています。45## フォルダマップ67| フォルダ | 目的 | 更新日 |8|---|---|---:|9| `01.Brand System/` | ビジュアルアイデンティティ、トピックスコープ、ボイス | 2026-06-11 |10| `02.Editorial Strategy/` | 記事の方向性、タイトルルール、キュー | 2026-06-11 |11| `03.Promotion/` | ローンチ、配信、ツール戦略 | 2026-06-11 |1213## 正規ファイル1415| ファイル | 目的 |16|---|---|17| `01.Brand System/01. Brand System.md` | ビジュアルアイデンティティ、カラー、タイポグラフィ |18| `02.Editorial Strategy/01. Articles.md` | 記事キュー、タイトルルール |1920## どこから始めるか2122- ミッションについては `01.Brand System/04. Direction.md` から始める23- 記事選択には `02.Editorial Strategy/01. Articles.md` を使用する
INDEX.md は 3 つのバージョンを経ました。最初のバージョンはブランドフォルダ内のすべてのファイルをリストし、40 行に及びました。技術的には完全でしたが、エージェントが毎回それを解析する必要があり、長さ自体がオーバーヘッドになっていました。2 番目のバージョンは短すぎて約 15 行で、エージェントはまだ答えていない質問をしていました。この 3 番目のバージョンはサブフォルダと正規ファイルのみをリストし、エージェントに出発点を伝える短い「どこから始めるか」セクションがあります。
エージェントにローンチのプロモーション戦略を取得するよう依頼すると、05.Brand/INDEX.md を読み、03.Promotion/01. Promotion Strategy.md を開き、作業を開始します。再編成後のタイミングは次のようになります。
再編成後:
- 現在の記事ブリーフを見つける: 1 ファイルを開き、0:10
- ブランドカラー定義を見つける: 3 ファイルを開き、0:22
- 計画用の記事キューを確認する: 1 ファイルを開き、0:10
- 同じトピックの以前の記事を見つける: 2 ファイルを開き、0:18
- ローンチのプロモーション戦略を取得する: 1 ファイルを開き、0:12
最も遅いタスクは 2 分から 26 秒に短縮され、最速の実行は約 10 秒になりました。エージェントは INDEX.md を開き、必要な出発点に従い、迷うことなく作業を開始します。エージェント側の能力は何も変わっていません。フォルダ構造が、タスクが始まる前にその大部分を無駄にしなくなったのです。
フォルダ構造は私が構築したケージであり、エージェントの動きを制約するが、エージェントの能力を制約するものではない。ケージの中で、エージェントは自由に動く。それがないと、Hermes は迷い出してしまい、私は正しいファイルを指し示すために時間を無駄にしなければならない。
Hermes に移行したことで、ファイル、プロバイダー、メモリ全体にわたってこの種のシステムを一度に構築でき、INDEX.md パターンは日常的に最も大きな違いを生み出した最小のピースです。
すべてのケージには鍵がある
最初の失敗は、すべてのサブフォルダに INDEX.md を追加したことでした。マップが多すぎると、エージェントは仕事をする代わりにインデックスを読むことに時間を費やします。INDEX.md は、Brand や Editorial Strategy のような主要フォルダのルートにのみ配置し、マップを必要とするほどのサブフォルダがある場合に限定しています。4 つか 5 つのファイルしかない小さなサブフォルダ内では、Hermes はマップなしで直接ナビゲートします。
番号付けは、新しいフォルダを追加するときに面倒になることを覚えておいてください。新しいフォルダがシーケンスのどこに収まるかを決める必要があり、すべてを番号変更する代わりに末尾に追加することもあります。それで問題ありません。番号は方向性を示すものであれば、完璧である必要はありません。完璧に順序付けられたフォルダが目標ではなく、それを目標にすると、実用的な修正が外観上のプロジェクトになってしまいます。
より大きな失敗は、エージェントが混乱を示す前に構造を構築することです。ほとんどの人は、適切なインフラストラクチャが必要だと考えて、エージェントのセットアップを過剰に設計します。
私の現在のルールは、MCP と CLI、独自ツールの選択と同じ原則に従っています。仕事を達成する最小のインターフェースを使用するのです。エージェントが迷子になったときにのみ構造を追加し、その特定の問題を修正するのに十分な構造だけを追加します。
もう一つの失敗は、構造の中に構造をネストしたことです。サブフォルダの中にサブフォルダを追加してすべてを完全に分類しようとした結果、2 レベルの階層が 5 レベルになってしまいました。エージェントは 1 つのファイルに到達するために複数の INDEX ファイルを読み、複数の番号シーケンスを解析しなければならなくなりました。それらの余分なレベルをフラットなサブフォルダに戻したところ、ナビゲーションが再び高速化しました。
深さは高速なファイル検索の敵であり、ほとんどの再編成は精度だと思って深さを追加する。
再編成前に測定する
1 つのフォルダにも触れる前に、エージェントが最も頻繁に処理する 3 つの実際のタスクでこのテストを実行してください。それぞれの時間を計測し、正しいファイルを見つけるまでに何ファイルを開くかに注意してください。間違ったファイルを選択したり、どれを使うべきかあなたに尋ねて停止したりする頻度を追跡してください。
エージェントが 30 秒以上かかる、または 3 つ以上の間違ったファイルを開くタスクは、そのタスクの背後にあるフォルダが壊れていることを示しています。
最も頻繁に発生する 1 つの失敗を選んでください。そのフォルダを開き、すべてのサブフォルダと重要なファイル、そしてエージェントがどこから始めるべきかをリストした INDEX.md を作成してください。保存してください。同じタスクを再度実行してください。
エージェントが 30 秒以内に正しいファイルを見つけた場合、修正は成功で、パターンがわかりました。次の壊れたフォルダに適用してください。まだ失敗する場合、問題は番号付けまたは 1 フォルダ 1 関心事である可能性が高く、これらが次に修正すべき 2 つのことです。
最も時間を浪費する 1 つのフォルダから始め、それを修正し、準備ができたときにのみ次のフォルダに移る。
バーがまだ曲がる場所
アーカイブされたコンテンツは、過去のブリーフをコンテキストとして必要とするときに参照されることがあります。エージェントはアクティブフォルダではなく 06.Archived を探すことを認識する必要があり、INDEX.md でこれに言及して、歴史的な素材がどこにあるかを知らせています。そのメモがないと、エージェントはアーカイブされたコンテンツが存在しないと想定します。
また、Obsidian Sync はデバイス間でクリーンに同期できない場合に時々問題を引き起こします。ラップトップでファイルを更新しても、VPS に古いバージョンが残っている場合、Hermes は VPS のコピーを読み込み、それを現在のソース オブ トゥルースとして扱います。これはフォルダ構造の問題というより同期の問題ですが、エージェントは目の前のファイルしか見えないため、フォルダシステム内に現れます。
番号付けは、フォルダが多すぎてシーケンスが意味をなさなくなると崩壊します。1 つのレベルで 10 から 12 の番号付きアイテムを超えると、番号は恣意的になり始めます。
主要カテゴリはそのしきい値以下に保ち、トップレベルを拡張する代わりに、より深い構造を内部にネストするようにしています。
リネームも摩擦の原因です。再編成時にフォルダの目的により合うように名前を変更することがありますが、古い名前への INDEX.md 参照は更新されるまで壊れます。現在は、フォルダ名を一度設定してそのままにしておくようにしています。なぜなら、少し不格好な名前でも、壊れた参照よりもコストがかからないからです。
この構造は、コンテンツ中心のワークフローと計画中心のワークフローに最も適しています。純粋なコードやデータ中心のセットアップでは、まったく異なる編成原則が必要になる場合があり、INDEX.md パターンがすべてのナビゲーション問題を解決するわけではありません。
この記事で私が書いたすべてのことは、1 つの本能にさかのぼります。重要なレイヤーを自分で所有することです。私は、どの企業も私のツールを管理できないようにスタックを構築しました。混乱がエージェントを管理できないように保管庫を構築しました。プロバイダーからフォルダ、そして次に来るものまで、同じ原則です。
その周りの scaffolding が壊れているとき、能力は安価です。scaffolding を構築すれば、能力は自然に機能します。1 つのインデックスファイルとフォルダ名の前のいくつかの番号が、迷子になるエージェントと機能するエージェントの違いを生みます。
もしこの記事が役に立ったなら — @wandermist をフォローして、このようなコンテンツをもっとチェックしてください！
