最近、CursorやClaude CodeのようなAIコーディングエージェントを使っている方が非常に増えましたね。プロジェクトのルートディレクトリにエージェント専用のガイドファイルを1つ置いておくだけで、エージェントがプロジェクトのスタイルを完璧に理解してコーディングしてくれる時代になりました。特にOpenAIが提案し、現在はLinux Foundation傘下のAgentic AI Foundation (AAIF) で公式オープン標準として管理されているAGENTS.mdが代表的です。

ところが、コーディングエージェントをより完璧に動作させようとして、このファイルにあらゆるルールやコーディングスタイルのガイドラインを事細かに記述する方が多く見受けられます。意外にも、これが逆効果になることがあるのです（笑）

最近のICLR 2026で発表された論文によると、プロジェクトのコンテキストファイルが重く複雑になるほど、エージェントの実作業における成功率は低下し、推論コストは約20%も増加したそうです。ルールが密集しすぎると、エージェントが不必要なファイル探索や意味のないテストに固執してしまい、肝心な解決策を見出せずに迷走してしまうからだと思われます。

結局のところ、鍵となるのは「そのプロジェクト固有のルール」と「主要なビルド/テストコマンド」のみを軽量に記述するという、賢い妥協です。ただでさえ優秀な最近のモデルに、当たり前の技術スタックの知識を事細かに教え込んでトークンを浪費する必要はありませんからね。

さらにもう一つ、ちょっとしたテクニックがあります。CursorやWindsurfはAGENTS.mdを上手くサポートしていますが、Claude CodeはまだCLAUDE.mdを優先して読み込みます。そんな時は、2つのファイルを別々に管理して同期をとるのに苦労するのではなく、以下のようにシンボリックリンクを使って軽量に連結しておく方法をおすすめします！

# AGENTS.md와 CLAUDE.md 싱크 맞추기 (macOS/Linux)
ln -s AGENTS.md CLAUDE.md

最も軽量で明確なコンテキストこそが、最も賢くコストパフォーマンスの良いAIエージェントを作るということを、ぜひ覚えておいてください。