AGENTS.md 徹底ガイド：Codex にリポジトルールを理解させる

一回限りのタスク要件は現在のプロンプトに残し、タスクをまたいで常に有効なリポジトリの事実だけを AGENTS.md に記載する。典型的な内容は権威あるビルドコマンド、ディレクトリの境界、コーディング規約、検証ステップ、改変禁止の生成ファイルである。

それはモデルの意思決定を導くものであり、フォーマッタや権限ポリシー、CI の代わりにはならない。必ず強制すべきルールは、テスト、lint、サンドボックス、hook によって機械的に保証されるべきである。

良いルールは具体的で短く、検証可能である。「高品質を保つ」のような実行不能な標語は書かず、ディレクトリ、コマンド、判断基準を明記する。

以下のテンプレートは構造の例示にすぎない。リポジトリの実際のコマンドに差し替えてから、チームのレビューに提出すること。存在しないコマンドはすべてのタスクを継続的に誤誘導する。

リポジトリのルートファイルはグローバル規約を記述し、サブディレクトリ内の AGENTS.md はそのサブツリー特有のルールのみを補足する。対象ファイルに近い指針ほどより具体的なスコープに対応し、ルートファイルにフロントエンド、バックエンド、モバイルの全詳細を堆積させない。

衝突が生じた場合は、モデルにチームの意図を推測させようとするのではなく、まずドキュメントの矛盾を取り除く。相互に矛盾するコマンドを異なる階層に残すと、タスクの挙動が不安定になる。

各項目は「これを読み込まなければ、Codex は間違える可能性が高いか」に答えるべきである。長大な API リファレンス、たまに使うリリース手順、特定種類の専用タスクは、ドキュメントへリンクするか、必要に応じて読み込む Skill として整理するのに適している。

ビルドとテストコマンドには適用範囲を明記する。例えばフロントエンドの変更で何だけを実行するか、共有プロトコルの変更ではさらに何を実行するか。これにより毎回すべてのチェックを実行することも、モジュール間の契約を見落とすことも避けられる。

AGENTS.md を変更したら、すぐに大きなタスクに渡さない。Codex に読み取り専用モードで該当ルールの要約、実行予定のコマンド、承認が必要なアクションを計画させることで、曖昧さを迅速に洗い出せる。

検証するのは理解結果であり、モデルに隠されたシステムプロンプトや内部コンテキストの出力を求めてはいけない。モデルは自身の言葉でどのリポジトリ規約に従うかを説明するだけでよい。

ビルドシステム、ディレクトリ、リリースフローが変化したら AGENTS.md を同期的に更新する。重複ルールが多いほど、一方だけ更新されもう一方が古いまま残りやすくなる。

AGENTS.md を通常のコードレビューに組み込む。コマンドが実際に実行可能か、スコープが正確か、シークレットやマシン固有のパスが含まれていないかを確認し、重要なルール変更の理由を記録する。