34,266のリポジトリをスキャン：4組織に1つがAIエージェント設定ファイルにギャップ

Claude Code、Cursor、GitHub CopilotなどのAIコーディングアシスタントの普及に伴い、チームはますますリポジトリレベルの指示ファイルに依存してエージェントの動作を導いています。しかし、ほとんどのチームはこれらのファイルを非公式なドキュメントとして扱い、本番レベルの設定とは見なしていません。AgentLinterによる34,266のリポジトリのスキャンは、あいまいな指示、失敗動作の欠如、セキュリティリスクという明確なギャップを明らかにしました。これらの問題はアプリケーションコードでは決してレビューを通過しないものです。

スキャンは1,353の組織をカバーし、13,000以上の理解可能性と明確性に関する問題、約5,000の脱出ハッチの欠如、約1,150のセキュリティリスクを発見しました。具体的な発見には、あいまいさが最も一般的で7,700以上の未定義用語、脱出ハッチの欠如によりエージェントが同じコマンドをループしたり無関係なファイルを編集し続ける可能性、セキュリティ問題は件数は少ないものの深刻度が高く、449の危険なコマンド権限、437のPII露出リスク、71のデータ漏洩脆弱性、21のハードコードされたシークレットが含まれます。

OWASP Top 10 for Agentic Applicationsは過剰なエージェンシーとツールの誤用を重要なリスクとして挙げています。チームはエージェント設定ファイルをアプリケーションのセキュリティ境界の一部として扱い、CI/CD設定、Infrastructure as Code、環境変数定義と同じカテゴリに位置付けるべきです。効果的な適用には、IDEでのスキャン、脱出ハッチのチェック、矛盾する指示の検出、セキュリティポリシーの適用が含まれます。今週実行すべきアクションとして、すべてのエージェント指示ファイルの棚卸し、コードレビューの範囲に明示的に含める、lintingの実行、ハードコードされたシークレットの削除、あいまいな指示の具体化、脱出ハッチの追加、重複・矛盾した指示の削除、危険なシェルコマンドの制限、PRチェックの追加、リポジトリ横断的な再発発見の追跡を推奨します。

なぜエージェント設定ファイルにセキュリティ管理が必要か？安全なAIエージェント設定の実践には、シークレットの外部化、アクセス制御の強制、明確性と安全性のための設定検証、漏洩した資格情報の継続的スキャンが含まれます。しかし、ほとんどのチームはまだアプリケーションコードと同じ規律でエージェント設定ファイルを扱っていません。McKinseyの調査では、AIガバナンス成熟度レベル3以上の組織はわずか約30%です。

Claude Code、Cursor、GitHub CopilotなどのAIコーディングエージェントは、リポジトリレベルの指示ファイル（CLAUDE.md、.cursorrules、copilot-instructions.md、AGENTS.mdなど）に依存して動作をガイドします。これらのファイルは、エージェントに従うべきコーディング標準、回避すべきディレクトリ、エラー処理方法、実行可能なコマンドを指示します。リスクは、指示ファイルがエージェントのコード読み取り、編集、シェルコマンド実行、機密データとの対話に影響を与える一方で、チームはこれらを通常のPull Requestよりも低い厳密さで作成・レビューすることです。指示ファイルがあいまい、矛盾、またはハードコードされたシークレットを含む場合、エージェントはその弱点をすべてのタスクで増幅します。

従来のドキュメントは人間が解釈し、意図を推測し、無関係な詳細を無視できます。一方、エージェント指示ファイルはLLMベースのシステムによって直接消費され、実行を形作ります。

発見1：あいまいさが最も一般的な問題。7,700以上の未定義用語のインスタンスがスキャンされたリポジトリに出現しました。その他の一般的な問題には、あいまいな指示と過度に複雑な文が含まれます。LLMベースのエージェントは不明瞭な言語に非常に敏感です。「コードを適切にフォーマットする」や「ベストプラクティスに従う」などの指示は、エージェントが意味を推測する必要があります。異なるエージェントや同じエージェントの異なる実行で解釈が異なる可能性があります。あいまいな指示は、より多くの幻覚行動、リポジトリ間での一貫性のないコード変更、修正可能なミスを修正するためのレビューアの労力増加につながります。

発見2：脱出ハッチの欠如が暴走行動を引き起こす。約5,000件の脱出ハッチ欠如、さらに2,000件以上の重複または矛盾する指示が出現しました。脱出ハッチは、何かがうまくいかなかったときにエージェントに何をすべきかを伝える明示的な指示です。従来のソフトウェアには例外、リトライ、タイムアウト、フォールバック、エスカレーションパスなどのエラー処理があります。エージェントワークフローも同じ概念の恩恵を受けます。明示的な失敗動作がないと、エージェントは同じ失敗コマンドをループしたり、無関係なファイルを編集し続けたり、欠落したコンテキストを発明したり、ツール障害後に継続したりする可能性があります。観察された一般的なアンチパターンは、チームが強い指示を繰り返すことで悪いエージェント行動を修正しようとすることです。繰り返しはコンテキストサイズを増やし、行動の推論を難しくし、実行可能性を必ずしも向上させません。重複や矛盾するルールは行動をより予測不能にします。より良いパターンは、明示的なフォールバックパスを与えることです：停止条件、欠落コンテキスト処理、構造検証、破壊的コマンド確認。

発見3：セキュリティ問題は件数は少ないが深刻度が高い。449件の危険なコマンド権限、437件のPII露出リスク、71件のデータ漏洩脆弱性、21件のハードコードされたシークレット。エージェント設定ファイルは、エージェントが読み取り、書き込み、実行、または送信できるものを定義できます。ファイルがMarkdownや軽量設定であることが多いため、チームはこれらをセキュリティセンシティブとは見なさないかもしれません。しかし、OWASP Agentic Applications Top 10は過剰なエージェンシーとツールの誤用を重要なリスクとして特定しています。見つかったリスクパターンの例：APIキーやトークンが指示ファイルに直接コミットされている、ユーザーデータがマスキングなしで例に貼り付けられている、シェルコマンド実行に対する過度に広い権限、curl | bashのような安全でないコマンドパターン、独自コードやデータを外部サービスにコピーすることを許可する指示。ヒント：エージェント設定ファイルをアプリケーションセキュリティ境界の一部として扱い、CI/CD設定、Infrastructure as Code、環境変数定義と同じカテゴリに入れます。

定義されたルールは強制されたルールと同じではない理由。多くのチームはすでにエージェント行動に対する非公式の期待を持っていますが、それらはREADMEファイル、内部ドキュメント、チャットメッセージ、コピーされたプロンプトスニペット、リポジトリ固有の設定ファイルに分散しています。結果として、ポリシーがどこかに存在する、開発者が異なる解釈をする、リポジトリがドリフトする、レビューアが一貫性なく問題を捕捉する、CI/CDが標準を確実に強制しないというギャップが生じます。ガバナンス成熟度はAI採用に追いついていません。Gartnerは、2027年までに企業の40%が自律型AIエージェントをダウングレードまたは廃止すると予測しています。これは、ガバナンスギャップが本番インシデント後にのみ明らかになるためです。エージェントの安全性は、一度完璧なプロンプトを書くことよりも、変更が発生する場所で許容可能な指示パターンを強制することにかかっています。

良好な執行とは？コード品質とセキュリティ執行と同じ原則に従います：開発者が作業する場所でスキャンする、あいまいさを品質問題として扱う、明示的な失敗動作を要求する、エージェント設定にセキュリティポリシーを適用する。IDEでエージェントファイルをスキャンし、Gitフックで迅速なローカルフィードバックを提供し、PRチェックでレビュー可視性を確保し、CI/CD執行で組織全体の一貫性を保証します。未定義用語、あいまいな指示、過度に複雑な文をフラグします。脱出ハッチの欠如をチェックし、繰り返し失敗に対する停止条件、不確実性や危険なコマンドに対するエスカレーションパスを要求します。重複や矛盾するルールを検出し、予測不能性を高める不必要なコンテキストを削減します。エージェントファイルでシークレット検出を実行し、危険なコマンド権限をフラグし、PII露出パターンを検出し、漏洩しやすい指示をチェックします。コマンド実行、ネットワークアクセス、機密パスへのアクセスを許可する権限のレビューを要求します。所有権を明確にし、共有エージェントルールのメンテナーを割り当て、エージェント設定変更にCODEOWNERSまたは同等のレビュールーティングを使用します。可能な場合は組織レベルのポリシーをリポジトリ固有のガイダンスから分離します。

今週エージェント設定ファイルを強化する方法。実用的なチェックリスト：すべてのエージェント指示ファイル（CLAUDE.md、.cursorrules、AGENTS.md、copilot-instructions.mdなど）をリポジトリ全体で棚卸しする、エージェント設定ファイルをコードレビューの範囲に明示的に追加する、あいまいさ、脱出ハッチの欠如、セキュリティ問題を捕捉するためにエージェントファイルに対してlintingを実行する、ハードコードされたシークレット、トークン、顧客データ、本番サンプルを削除する、あいまいな指示を具体的なルールに置き換える、失敗したテスト、欠落コンテキスト、コマンド失敗、不確実性に対する脱出ハッチを追加する、重複または矛盾する指示を削除する、危険なシェルコマンドを制限し、破壊的な操作に確認を要求する、エージェント設定変更がレビューを回避できないようにPRチェックを追加する、リポジトリ間で繰り返し発生する発見を追跡して共有ポリシーの問題を特定する。前進する道は明確です。より明確な指示を書き、失敗動作を定義し、危険な権限と機密データを削除し、リポジトリ全体で一貫してチェックを執行します。エージェント指示が本番コードに影響するなら、それらは同じエンジンに値します。