テストが重要な理由

AI駆動のコードアシスタントでは、リポジトリに「ルール」ファイルを置いておけば、モデルがすべてのリクエストに対してその指示に従うだろうとチームが期待してしまうことがよくあります。実際には、モデルがそのファイルを全く認識していないか、認識していても内容を無視している可能性があります。Claude Codeを用いた最近の実験では、その両方の問題が示されました。そのツールは72KBのAGENTS.mdファイルを黙ってスキップしました。しかし、同じファイルの名前をCLAUDE.mdに変更したところ、アシスタントはそれを読み込み、各リクエストのトークン数が増加しました。その余分なトークン予算は、レイテンシとコストを増大させ、リクエストがモデルの制限を超えてしまう原因にもなり得ます。

「ファイルが存在する」ことが「モデルがルールに従う」ことと同義であると想定する開発者は、隠れた非効率性や予測不可能な出力のリスクを負うことになります。この3ステップのテストは、設定、読み込み、有用性の各段階において具体的な証拠を求めるものです。

問いかけるべき3つの質問

  1. 設定 (Configured) – ファイルはアシスタントが探す場所に配置されていますか？ツールによってパスやファイル名の命名規則がハードコードされていることがあり、不一致があるとファイルはプロンプトのパイプラインに決して入りません。
  2. 読み込み (Loaded) – アシスタントはファイルを受け取ったという証拠を示していますか？ハッシュ値でディスク上のファイルの同一性を確認することはできますが、モデルが実際にそれを認識したことを証明できるのは、配信トレース（例：ログ行やトークン数）のみです。
  3. 有用性 (Useful) – ファイルが存在することでタスクの結果が改善されますか？トークンを追加するだけで結果が変わらない読み込まれたファイルは、実質的な損失です。

テストの実行方法

この手順は、どのプラットフォームでも繰り返し実行できるように、意図的に最小限に抑えられています。

  1. 目に見えるルールを作成する – シンプルで観察可能な指示を書きます。例：「編集前に必ず2つのファイルだけをリストアップしてください」。ルールの効果はアシスタントの回答で確認できます。

  2. ツールのバージョンとモデルを確認する – 新しいセッションを開き、バージョン文字列とモデル識別子をメモします。バージョンによって認識されるファイル名が変わる場合があります。

  3. 2回の実行を行う 実行A: ツールが認識しないファイル名を使用します（例：AGENTS.md）。 実行B: ツールのネイティブなファイル名を使用します（例：CLAUDE.md）。

    記録事項:

    • ファイルのソースハッシュ（ディスク上の内容が変わっていないことを証明するため）。
    • 使用した正確なパス。
    • アシスタントがファイルの読み込みに関してログに記録した証拠（トークン数の増加、明示的な「loaded X.md」というメッセージなど）。
    • 各リクエストのトークン数。
    • タスクの結果（アシスタントは正確に2つのファイルをリストアップしましたか？）。

実行Bでルールが遵守され、トークン数が期待通りに増加していれば、そのファイルは読み込まれており、かつ有用です。トークン数が増えているにもかかわらずルールが無視される場合は、ファイルは読み込まれているものの、モデルのプロンプト解析によって指示が破棄されています。その場合、ファイルにテキストを追加しても解決しません。代わりに、ルールをハードコードされたポリシーゲートやテストハーネスに移動してください。

データが明らかにするもの

Claude Codeの事例は、設定と読み込みの間に著しい乖離があることを示しました。72KBのファイルは存在し、正しいハッシュを持ち、リポジトリに同期されていましたが、アシスタントはそれに一度も言及しませんでした。ファイル名をネイティブなCLAUDE.mdに変更すると読み込みがトリガーされましたが、同時に大幅なトークンのオーバーヘッドも発生しました。余分なトークンはそれぞれ計算リソースを消費し、リクエストがレート制限を超える原因となります。

この3ステップのテストは、こうした隠れたコストが本番環境の障害になる前に浮き彫りにします。トークンの差分（デルタ）を把握することで、チームはそのルールのメリットがコストに見合うかどうかを判断できます。

まとめ

ルールファイルがリポジトリにあるからといって、それが機能していると決して決めつけないでください。「設定、読み込み、有用性の証明」という3ステップのテストを用いて、その想定を測定可能な証拠に変えましょう。もしファイルが単なるトークンの無駄遣い（token sink）であることが判明した場合は、そのロジックをプロンプトから切り離し、決定論的なゲート（deterministic gate）に移動させてください。その結果、より軽量で高速、かつ予測可能なAIコーディングワークフローが実現します。