【要約】AGENTS.mdには何を書くべき？その2 〜4モデル×330実験で検証〜 [Qiita_Trend] | Summary by TechDistill
> Source: Qiita_Trend
Execute Primary Source
// Problem
AIエージェントの指示ファイル「AGENTS.md」の書き方について、経験則に基づいた議論が先行し、客観的な根拠が不足していた。開発者は、指示の長さがモデルの理解に与える影響や、禁止事項が守られないリスクといった課題に直面している。
- ・指示を長く書くと、重要な指示が希釈されるのではないかという懸念。
- ・上位モデルを使用する場合、指示をどこまで簡略化できるかの判断基準の欠如。
- ・「生成物を直接編集しない」といった禁止事項が、文書のみでは守られないリスク。
// Approach
著者は、4つのClaudeモデルと2つのテストベッドを用い、330回の実験を通じてAGENTS.mdの有効性を定量的に検証した。実験では、あえて失敗を誘発する「罠」をリポジトリに仕込み、モデルの挙動を測定している。
- ・「罠」を仕込んだテスト環境の構築：テストコマンドの誤選択や生成物の直接編集など、二値判定可能な失敗条件を設定。
- ・セクション別のバリエーション検証：推奨構成案を分解し、各要素がモデルの挙動に与える影響を測定。
- ・ガード手法の比較検証：文書による指示、権限による無言のガード、エラーメッセージを伴うポリシー文付きhookの有効性を比較。
// Result
実験により、AGENTS.mdの設計指針が明確になった。モデルの能力に応じた使い分けと、文書の限界を補う多層防御の重要性が示されている。
- ・モデル選定の基準：安価なモデルを併用するなら、セットアップや生成物ルール、SoT（Source of Truth）の記載は必須。
- ・指示の配置：義務系の指示（DoD）は、長文の末尾ではなく冒頭にチェックリストとして配置することで遵守率が向上する。
- ・禁止事項の制御：文書による指示や権限制限は不完全であり、「理由を添えた機械的強制（PreToolUse hook等）」が最も確実な阻止策となる。
Senior Engineer Insight
> AIエージェントを実務に投入する際、指示の「質」だけでなく「防御層」の設計が不可欠である。AGENTS.mdは知識伝達（L1）として機能するが、禁止事項の遵守にはCIやツールレベルのガード（L2/L3）を組み合わせた多層防御が求められる。特に、エラーメッセージに「正しい経路」を明示する設計は、エージェントの自律的な修正を促すため、開発体験と堅牢性を両立させる極めて実践的なアプローチである。