コードをテストしています。では、AIの指示（インストラクション）もテストしないのはなぜですか？
モデル選定よりも「指示品質」が結果を左右する理由、そしてそれを測るためのツール。
AIコーディングツールを使うあらゆるチームは、命令ファイルを書きます。Claude Code にはCLAUDE.md、Codex にはAGENTS.md、GitHub Copilot にはcopilot-instructions.md、Cursor には.cursorrulesです。これらのファイルを作り込む時間を使い、段落を変えてプッシュし、結果は何とかなるだろうと願うだけです。
あなたのコードベースにはテストがあります。APIには契約（コントラクト）があります。AIの指示には「希望」しかありません。
私はそれを直すためにagentevalを作りました。
誰もテストしていない変数
最近の研究では、同じモデルを731のコーディング問題に適用して、3つのエージェントフレームワークをテストしました。同じモデル。 同じタスク。違いは、指示の足場（instruction scaffolding）だけでした。
分散（ばらつき）は17ポイントでした。
私たちは、どのモデルを使うかにこだわります。Sonnet vs Opus vs GPT-5.4。 しかし、モデルそのものよりも、あなたがモデルに与える指示のほうが結果に与える影響はずっと大きいのに、誰もそれをテストしていません。
考えてみてください。テストなしでAPIをデプロイしないでしょう。CIなしで機能を出荷しないでしょう。では、あなたのAIがコードを書く方法を制御するファイルは？ テキストエディタで編集して、あとは運です。
指示ファイルで何がうまくいかなくなるのか
ここまででかなり多くの指示ファイルを読み込みました。どこでも同じ問題が出てきます。
行き止まりの参照（デッド・リファレンス）
あなたはsrc/auth.tsをsrc/authentication.tsにリネームしてから6か月前です。それでも指示ファイルには「認証モジュールは src/auth.ts を参照」と書かれています。AIはその指示を読み、存在しないファイルを探して混乱します。
これは最もよくある問題です。3か月以上前に作られた指示ファイルのほとんどすべてに、少なくとも1つはデッド参照があります。
文脈（コンテキスト）予算を食い潰す“詰め物”
「必ず、あらゆるものを徹底的にテストし、頑健な形であらゆるエッジケースに包括的なカバレッジを確保してください」
この一文は25トークンを燃やし、モデルがすでに知っていないことは何も言いません。コンテキストウィンドウが200Kで、指示予算が30%なら、使えるのはだいたい60,000トークンです。「必ず～」のようなフレーズに費やしたトークンは、実際のコードのためのコンテキストに使えないトークンです。
最悪の犯人：「it is important that」, 「in order to」, 「at the end of the day」, 「make sure to」, 「please ensure that」。どこにでもいます。
矛盾
コードスタイルのセクションで「常にセミコロンを使う」。そして3セクション後に「Prettierの設定に従う」。Prettierはセミコロンを削除します。モデルには相反する指示が入り、どちらかをランダムに選びます。
これは思っている以上に起きます。特に、複数人が数か月かけてメンテしているファイルではなおさらです。
コンテキスト予算のオーバー
CLAUDE.mdは300行。AGENTS.mdは200行。copilot-instructions.mdは150行。これらを合計すると、コードの1行目が読み込まれる前に、モデルのコンテキストウィンドウの40%を消費します。
指示の数が増えるほど、AIのパフォーマンスは一様に劣化します。後半の指示が無視されるという話ではありません。すべての指示が、より正確には守られなくなるのです。
ファイル間の重複
CLAUDE.mdには「TypeScriptのstrictモードを使い、インデントにはタブを使う」とあります。AGENTS.mdにも同じことが書いてあります。同じ指示が重複しており、価値はゼロなのにトークンだけが2倍に消費されます。さらに、片方を更新してもう片方を忘れると、ズレて矛盾し始めます。
agentevalがやること
agentevalはCLIです。インストールして、1つコマンドを実行するだけで、何が問題かが分かります。
curl -fsSL [https://raw.githubusercontent.com/lukasmetzler/agenteval/main/install.sh](https://raw.githubusercontent.com/lukasmetzler/agenteval/main/install.sh) | bash
agenteval lint
指示ファイルを読み取り、markdownを解析し、トークン数を数え、ファイル参照をチェックして、実際の問題を「実行可能な提案」とともにレポートします。LLMは介在しません。決定論的です。1秒未満で動きます。
こちらが、私が初回に自分のプロジェクトで実行したときに見つけた内容です：
CLAUDE.md
ERROR 参照しているファイル "docs/schema.md" が存在しません
→ 参照を削除するか、不足しているファイルを作成してください
info セクション "Testing" にフィラー句（使い回しフレーズ）が1つ含まれています
→ 'make sure to' のようなフレーズを除いて書き直してください
info 指示が曖昧です: "be careful with error handling"
→ 具体的な例、または閾値に置き換えてください
どの問題にも提案があります。どうすればいいかを考える必要はありません。
あらゆる主要な指示形式に対応しています：
-
CLAUDE.md（Claude Code） -
AGENTS.md（OpenAI Codex） -
.github/copilot-instructions.mdおよびスコープ付き.instructions.mdファイル（GitHub Copilot） -
.cursorrules（Cursor） -
.claude/skills/*/SKILL.md（Anthropic skills）
リンティングを超えて：時間経過に沿った指示品質の測定
リンターは静的に問題を検出します。しかし、指示の変更が本当にAIのパフォーマンスを良くしたのかを知りたい場合はどうすればいいのでしょう？
agentevalにはそれのための、より深いパイプラインがあります：
- Harvest（収集）：git履歴をスキャンして、AI支援によるコミットを探します。14種類のツール（Claude、Copilot、Cursor、Devin、Aider、Amazon Q、Geminiなど）を検出し、そこから再実行可能なベンチマークタスクを生成します。各タスクには、そのコミット時点での指示ファイルの状態スナップショットが含まれます。合成的なテストケースは不要です。あなた自身のgit履歴がベンチマークです。
- Run（実行）：タスクをAIエージェントに渡し、隔離されたgit worktree上で実行して、作成物を取得し、結果をスコアリングします。4つの次元：正しいファイルを変更したか（correctness）、必要な変更だけに留めたか（precision）、どれだけのトークンを使ったか（efficiency）、規約に従ったか（conventions）。
- Compare（比較）：2回の実行結果を並べて表示します。指示ファイルを変更し、同じタスクを再実行して、スコアが改善したかを確認します。両方の実行に指示スナップショットがある場合、スコア差分（delta）と一緒に、指示の中で何が変わったのかが正確に表示されます。
- CI：すべてのタスクを実行し、指示品質が悪化した場合はビルドを失敗させます。GitHub Actionsのワークフローに1行追加するだけで、指示品質がテストと同じようにマージゲートになります：
- run: agenteval ci
PRで誰かが指示を変更し、品質が閾値を下回ったら、ビルドは失敗します。
-
Live review（ライブレビュー）：コミットする前に、作業ツリーの変更をスコアリングします。変更は一点に集中していますか、それとも散らばっていますか？テストを更新しましたか？デバッグ用の成果物が残っていませんか？
--analyzeを追加すると、差分（diff）をAIツールに送って、規約遵守のスコアリングを行います。 - Trends（トレンド）：スコアの推移を追跡します。この四半期、チームは指示の書き方が良くなっていますか？改善しているタスクはどれですか？悪化しているのはどれですか？
はたまたま不快な質問
チームは、どのAIモデルを使うかを議論するのにどれくらいの時間を費やしてきましたか？では、指示ファイルが実際に機能するかどうかを検証するのに、どれくらい時間を費やしましたか？
モデルはコモディティです。指示は、あなたの競争上の優位性です。
試してみる
curl -fsSL [https://raw.githubusercontent.com/lukasmetzler/agenteval/main/install.sh](https://raw.githubusercontent.com/lukasmetzler/agenteval/main/install.sh) | bash
agenteval lint
1つのコマンド。スタンドアロンのバイナリ。LinuxとmacOSで動作します。指示ファイルを含む任意のプロジェクトを指定して、そこから何が見つかるかを確認してください。
リポジトリ: https://github.com/lukasmetzler/agenteval
もし試してみたら、どんなものを検出したのか、そしてどんなチェックが不足していたのかをぜひ教えてください。
