名前が曖昧だと、どれほどのコストになるのか？

では、「優れた検索語」とそうでない場合、具体的にどれだけ違うのでしょうか。彼らは3つの関数で比較しました。

これら3つの関数は機能が完全に同じで、どれも外部サービスを呼び出すAPIクライアントを作成します。違いは名前だけです。

export function create(apiKey: string) { ... }
export function createClient(apiKey: string) { ... }
export function createStripeClient(apiKey: string) { ... }

Modemの約2,900ファイルからなるTypeScriptリポジトリで、それぞれを検索してみます。

つまり問題は検索の速さではありません。grepが返すのはマッチした行であり、答えではありません。const client = create(config)という一行を見ても、それがAIに求められているクライアントなのか、それとも同じcreateという名前の数百あるうちの一つなのかは分かりません。

それを判断するには、ファイルを開いてヒット箇所の周辺を読み、さらに範囲を広げたり、別の箇所を開いたりする必要があります。ファイルは数十行から数千行まで様々で、1行あたり約10トークン（トークンはAIが読み書きするテキストの単位。一度の会話で扱える量や料金はこれで計算され、おおよそ英単語1つが1トークン強に相当）とすると、誤った候補を1つ排除するだけで数百〜数千トークンを消費します。それを十数個続ければ、数万トークンが消えていきます。お願いした作業はまだ一字も実行されていないのに。

あの1,585件のヒットは、数百の無関係なものに散らばっています。テスト用のダミーデータ、データベースへのレコード挿入、バックグラウンドタスクの登録などです。一方、createStripeClientの43件のヒットは、定義、呼び出し箇所、テストで、すべて同じクライアントについて語っています。

節約になるのは今回だけではありません。コンテキスト（一度に扱える情報量）は有限です。無関係なcreateを排除するために使ったトークンは、今回の変更ではもう使えません。さらに厄介なのは、コンテキストがこれらの似て非なるマッチで埋め尽くされると、モデルがその情報を信頼して使う度合いが低下することです。grep一回で特定できる名前は、AIの注意力と予算の両方を守ってくれます。

importがあるのに、なぜ十分ではないのか？

ここで疑問が湧きます。ファイルの先頭に「これがどこから来たか」が書いてある（importの行）のだから、それを辿っていけばいいのでは？と。

もし目的が呼び出し箇所から定義を見つけることだけなら、その通りです。importは前方を指す道標ですが、冒頭の「名前を変える」タスクは逆方向です。定義から出発して、それを呼び出している全ての箇所を見つける必要があります。プレーンテキスト検索には逆引きインデックスがありません。定義が置かれているファイルには、誰がそれを参照しているかを記した行は一切存在しないのです。

モジュールは一方向しか指さず、barrelやパッケージ名に出くわすと曖昧になります。オブジェクトのメソッドに至っては一切言及しません。結局、働いているのは名前なのです。

パラメータの型を明確に書くと、AIのどんな作業が省けるのか？

ここまでは「AIがあなたのコードを見つけられるか」という話でした。見つけた後、どう使うかは別の要素に依存します。それが「型」です。

型はコメントやREADMEとは根本的に異なります。コメントは読まなくても済みますが、型はコンパイラが強制します。コンパイルを一度実行すれば、型エラーは具体的なフィードバックとなり、AIはしばしば1ラウンド以内で自分で修正します。

コンパイラが口を開く前に、すでに型はコストを節約しています。次のようなシグネチャを見れば、何が入って何が出るか一目瞭然で、関数本体を開く必要すらなくなります。

function enrichUser(user: User): EnrichedUser;

TypeScriptのanyはさらに陰湿です。害は同じ大きさなのに、型らしい見た目をしているからです。

型の名前が適切かどうかも、同じくらい重要

次の関数は、3つのパラメータがすべて文字列のため、順序を間違えて渡してもコンパイラは何も言いません。

transferOwnership(
  userId: string,
  orgId: string,
  projectId: string
)

transferOwnership(
  userId: UserId,
  orgId: OrgId,
  projectId: ProjectId
)

この自己修正ループを観察した研究もあります。モデルにコンパイラのエラーを持たせて何度か修正させると、成功率はおよそ3倍になりました。

ここに連鎖があり、先ほどの話に繋がります。エラーメッセージに指名されたOrgIdは、おそらく別のファイルで定義されています。AIがエラーに従って修正するには、その定義を読む必要があり、そこに辿り着く唯一の方法は、やはりその名前を検索することです。

型名と関数名は同じ規則に従います。OrgId、UserEnrichmentResultのような名前は、検索すれば即座に定義に辿り着けます。Result、Data、Configといった名前は、AIを再び針探しの海に放り込みます。コンパイラは「どこを見るべきか」を教えてくれますが、名前が「その参照にどれだけ時間がかかるか」を決めるのです。

anyの問題はまさにここにあります。コンパイラは何も言わず、AIは検索する言葉すら持てません。下手な名前であれば、少なくとも手がかりは残っているのです。

実験データ：この方法は本当に効果があるのか？

ここまではすべて理屈です。名前は具体的に、型は正確に。もっともらしい話ですが、実際にどれだけ節約になるのでしょうか。Modemはこれを実験にしました。

彼らはFable 5にこのブログ記事を1ページのスキルファイルに圧縮させ、コーディング時にコンテキストへ読み込ませました。そして、どちらの立場にも関係ない要件定義（リトライ、レート制限、署名付きの通知パイプライン用の小さなライブラリ）を、2つのライターモデルにそれぞれ2回書かせました。1回はスキルファイルなし、もう1回はスキルファイルあり。執筆者はHaiku 4.5（Claude Code）とGPT-5.6 Sol（Codex CLI）。これで、同じライブラリの4つのバージョンができました。

Haikuがスキルなしで書いたコードは、まさにこの記事が警告している典型例です。

Solがスキルなしで書いたコードは元々丁寧で、backoff.tsにはcalculateBackoffDelay、token-bucket.tsにはTokenBucketが置かれていました。スキルありではさらに深く、backoff.tsはnotification-retry-backoff.tsになりました。ただし、2つのバージョンの差は、Haikuの場合よりも明確に小さいものでした。

次に読む側の実験です。4つのバージョンをそれぞれ、実際のリポジトリから取った同じ500ファイルに埋め込み、クリーンなセッションで検索・読み取りツールだけを与え、次のような質問をしました。

次のリトライまでにどれだけ待つのか、その待ち時間はどこで計算されている？
計算されたHMAC署名（送信データに付与する偽造防止スタンプ）は、どの段階で送信データに添付される？
通知IDが与えられたとき、過去の配信試行履歴はどこで確認できる？

14種類のモデル・ツール組み合わせが、4つのバージョンそれぞれに10問、3回ずつ、合計1,680回の実行を行い、消費トークンと正誤を記録しました。

Solが書いたコードを読む場合、14の組み合わせ中12で改善し、中央値で12%減。残り2つは改善しませんでした。

傾向は一貫しています。元の書き方が粗いほど改善の余地が大きく、Solは元々うまく書けているため、節約できる分も少ないのです。

自分で書いたコードを読むときも、モデルに特権はない

特に注目すべきデータが1行あります。Solがスキルなしで書いた自分のコードを読む際、スキル版に置き換えた後でも13%〜38%（駆動するツールによって異なる）のトークンを節約できました。

コードを書いたモデルにも「どこに何を置いたか覚えている」という記憶はありません。彼らが実行する検索は、他者とまったく同じです。

曖昧な名前のバージョンにだけ現れる失敗

誤答はほぼHaikuの曖昧な名前のコードでのみ発生し、しかも自信満々の誤答でした。この通知ライブラリの配信履歴はどこかと尋ねると、リポジトリ内の別の何かのSlack配信台帳を指し示しました。HMAC署名がどの段階で付与されるか尋ねると、2回ともメディアプロキシサービスのURL署名器を指しました。

スキル版の誤答はゼロでした。似ているが違うコードは、hmac-payload-signer.tsという名前には太刀打ちできません。Solが書いた2つのバージョンでは、この種の失敗はほとんど見られず、840回の実行で834回正解。誤答はごく稀で、両バージョンに散発的に見られる程度でした。

実プロジェクトでも成立するのか？（4,943行のファイル）

合成されたコードベースは一部の問題しか説明しません。そこで彼らは実際の難しいケースを選びました。オープンソースのセルフホスト型AIワークベンチ「Odysseus」です。公開初週に数万のGitHubスターを獲得しました。

Odysseusのインターフェース。画像出典：Modem

そのroutes/email_routes.pyは4,943行あり、うち約3,900行が1つの関数です。81個のルートハンドラ（それぞれがウェブリクエストに応答する）がすべてその中に詰め込まれています。1つの関数が、メールクライアント全体を形成しているのです。

Modemはこの1ファイルだけをリファクタリングしました。動作は変えず、ルートも変更せず、機械的に検証した上で、概念ごとに名前を付けたモジュールへ分割しました。

email_routes.py
  4,943 行
  81個のハンドラが1つの関数に

email/
  smtp_settings.py
  message_rendering.py
  folder_fallbacks.py
  delivery_history.py

そして、同じ6つの質問を4つのモデルに投げました。結果はまたもや同じ傾向です。モノリスで迷っていたモデルほど節約が大きく（Haiku 4.5は34.3%減、Grok 4.5は31.5%減）、迷っていなかったモデルはほとんど節約できませんでした（GPT-5.6 Solは5.9%減、Sonnet 5は3.9%減）。Haikuは以前、40万トークンを費やして、その壁を1ページずつめくっていましたが、リファクタリング後はそうする必要がなくなりました。

さらに重要なのは最悪ケースです。「40万トークン費やして、結局何も見つからなかった」という壊滅的な実行は、ほぼ全てリファクタリング前のバージョンで発生しました。「ほぼ」というのは、リファクタリング版でもHaikuが1回発生させたためです。そして、その発生場所が非常に示唆的です。彼らは1ファイルしかリファクタリングしておらず、Haikuは隣の手つかずの1,800行からなるemail_helpers.pyという雑多なファイルの中で迷子になりました。リファクタリングが床を引き上げましたが、新しい床は、手つかずのまま残った最も悪いファイルだったのです。

節約したトークンで、何が得られるのか？

前の2つの実験は「どれだけコストがかかるか」を測ったものです。さらに重要なのは「安く済ませられるなら、正しく実行できるのか」という問いです。

彼らは2つのバージョンのメールコードに、4つの同一の隠れたバグを仕込みました（バイト単位で同一の変更なので、両バージョンは全く同じ欠陥を持ちます）。そして、4つのモデルに固定8ラウンドの検査予算を与え、これらのコードが要件通りに書かれているか確認させました。各モデルは各バグを2回確認し、各バージョンで32回のレビュー、2バージョン合計で64回のレビューを行いました。

Grok 4.5とGPT-5.6 Solは両バージョンで全て発見しました。8ラウンドあれば、検索に秩序立てて取り組めるモデルにとって、4,943行のファイル内でこれらの欠陥をgrepするのは十分可能なのです。

HaikuとSonnetはそれができず、モノリス版ではそれぞれ4/8と3/8しか発見できませんでした。失敗したレビューのほとんどは誤った回答をしていません。彼らは8ラウンドの予算を全てファイル探索に費やし、結論を出す前に時間切れとなっていました。リファクタリング後のコードでは、両者とも満点を獲得しました。

Sonnetの行は特に注目に値します。先ほどの検索実験では、彼はこのリファクタリングからほぼトークンを節約できませんでした。しかし、予算制限を加えると、正解率は3/8から8/8へと変わりました。巨大ファイルの中で「検索する余裕がある」ことと「その中で結論を導き出せる」ことは、別問題なのです。

AIフレンドリーなコードの書き方（実践的アドバイス）

メカニズムとデータの話はここまで。最後はすぐに行動に移せる部分です。

実験で使われたスキルファイルはMITライセンスで公開されています。本サイトが取得して読み終えたところ、ブログ本文には書かれていない、より実践しやすいルールがいくつかありました。

これらのアドバイスのほとんどは新しいものではありません。説明的な命名、正確な型、「なぜ」を説明するコメント。私たちは数十年、互いにそう勧め合いながら、いつも実行できずに許してきました。なぜなら、人間は同僚に聞いたり、git blameを辿ったりできるからです。しかしAIにはそれができません。彼らが持っているのは、あなたの文章と型、そして一つの検索ボックスだけなのです。 — Modem エンジニアリングブログ

最後に、この結論の適用範囲について。著者が明記している限界は3つあります。このスキルは命名・ファイル分割・型・構造を同時に変更しており、節約できたトークンを命名だけに帰属させることはできません。Odysseusの表のトークン数は同じ行内でのみ比較可能で、ツールを跨いだ比較はできません。Odysseusの実験は1ファイルのリファクタリングのみです。さらに、著者が指摘していない限界が1つ、本サイトの見解です。スキルファイルはFable 5にこのブログ記事自体から抽出させたものであり、それを使ってこのブログ記事を検証するのは自己検証です。彼らはまた、grepの上に埋め込み検索を重ねることで効果があるというCursorの優れたデータにも言及しており、プレーンテキスト検索が唯一の解ではないかもしれません。ただし、grepもリポジトリマップも埋め込み検索も、入力として食べているのは同じものです。それは、あなたのソースコードに含まれる言葉です。

差はどれほどか。Modemが3つの関数で試しました。機能は完全に同じで、Stripeを呼び出すAPIクライアントを作成します。違うのは名前だけ。3回の検索はすべて40〜50ミリ秒。お金がかかるのはヒットの後です。AIはヒットしたファイルを順番に開いて読み、探しているものかどうかを判断します。読むたびにトークン（AIが読み書きするテキストの単位。一度の会話で扱える量や料金はこれで計算）を消費します。

節約になるのは今回だけではありません。コンテキスト（AIが一度に同時に記憶しておける範囲）は有限です。無関係なcreateを除外するのに使ったトークンは、今回の変更ではもう使えません。しかも、似て非なるマッチで埋め尽くされると、モデルがその情報を使う信頼性も低下します。

理屈はもっともらしい。では実際にどれだけ節約になるのか。ModemはFable 5にこの書き方を1ページの規約に圧縮させ、2つのライターモデルに同じ要件（リトライ・レート制限・署名付きの通知ライブラリ）を2回ずつ書かせました。1回は規約なし、もう1回は規約あり。4つのバージョンをそれぞれ同じ500ファイルに埋め込み、14のモデル・ツール組み合わせが各10問、3回ずつ実行しました。

誤答の内容は印象的です。この通知ライブラリの配信履歴はどこかと尋ねると、リポジトリ内の別の何かのSlack配信台帳を、確信を持って指し示しました。リネーム後は、似ているが違うコードは、明確に書かれた名前に対抗できません。

最後のグループはさらに本質を突いています。同じ4つのバグ、同じ8ラウンドの予算で、弱いモデルは4,943行・81個のウェブリクエストハンドラを1つの関数に詰め込んだ実ファイルから、3〜4つしか見つけられませんでした。彼らのほとんどは誤った回答をしたわけではなく、8ラウンドの予算を全てファイル探索に費やし、結論に至らなかったのです。この1ファイルを概念ごとに分割・命名したモジュールに変えると、両モデルとも満点を獲得しました。

上記の数字はすべてModem自身が設計・実施した実験であり、第三者はまだ再現していません。本サイトは2026-07-25に同じブランチを取得しましたが、あの4,943行のファイルはすでに6,032行に成長していました。

あの規約はModemがMITライセンスで公開しています（そのまま取得してプロジェクトに導入可能）。その中でも取り組みやすく、動作を一切変えないものを選びました。

そして、直感に反するルールがもう一つ。人間もAIも質問にはスペース区切りの自然言語を使います（「rate limit」）。ところがRateLimiterのような連結された名前はフレーズ検索にマッチしません。そこで、各エクスポートの上のコメントに、普通の言葉でそのフレーズを書いておきます。Modemが約70万行のリポジトリで数えたところ、1語の名前がグローバルに一意なのは61%。3語で96%に達し、3語が分岐点です。