🐡
# CodexのAGENTS.md超徹底解説 ―― AIエージェントをプロジェクト規約に完全準拠させるための設計哲学・実践ノウハウ・運用フロ
はじめに
生成AI時代、コードを書く主体は人間だけではなくなりました。OpenAI Codexのようなコーディングエージェントは、リポジトリを読み込み、テストを実行し、Pull Requestを生成してくれます。しかし「誰が」「どのようなルールで」書いたコードかが曖昧になりやすく、チーム開発では一貫性の欠如が大きなリスクになります。
そのギャップを埋める鍵がAGENTS.mdです。本稿では、AGENTS.mdの役割、記述パターン、ディレクトリスコープ設計、CI/CDとの連携、そして運用時の落とし穴と改善策までを網羅的に解説します。
AGENTS.mdとは何か
AGENTS.mdの核心
- 人間向けREADMEに対するAIエージェント向け開発ガイド
- コーディング規約・ビルド手順・テスト実行・PRフォーマットを宣言的に記述
- ルート/サブディレクトリ/ユーザホームに配置し、階層ごとにマージされる
人間にとっての利点
- 新人開発者ドキュメントと兼用できる
- ドメイン知識やプロジェクト慣習をドリフトなく学習型エージェントへ伝達
- ルール違反が減り、コードレビューコストを定量的に削減
エージェントにとっての利点
- 処理開始時に自動パースされ、内部プロンプトへ組み込み
- テスト/リンタを自律実行し、PRが緑色の状態で提出されやすい
- ファイル階層ごとの適切な規約を選択しやすい
AGENTS.mdを構成する五つの柱
1. コーディングスタイル
- インデント幅・改行規則・命名規則
- 利用フォーマッタ(例: Black, Prettier)の具体的コマンド
- モノレポの場合は各パッケージのスタイル差分を明示
2. テストと品質保証
-
実行コマンド例
pytest tests/
npm run test
-
カバレッジ閾値
-
失敗時の自動リトライ回数やキャッシュ利用可否
3. ビルド・デプロイ手順
- ローカルビルド:
make build
ordocker compose up --build
- 本番リリース: GitHub ActionsやArgoCD等のワークフロー名
- 機密情報の取り扱い指針(環境変数 vs シークレットマネージャ)
4. ドキュメント更新ポリシー
- コード変更時に同時に修正すべき Markdown ファイル一覧
- 自動生成ドキュメント(例: Sphinx, Typedoc)の再生成ルール
- Architectural Decision Record(ADR)の追加判定基準
5. コミット・PRメッセージ規約
-
Conventional CommitsやGitmojiなどのタグ付け方
-
PRテンプレート必須項目
- 変更概要
- テスト結果
- 影響範囲
-
自動レビュアーアサインの条件
ディレクトリ階層と適用スコープ
ルートAGENTS.md
- プロジェクト全体に共通する最小限の原則を記述
- 別ツール導入時もここを修正するだけで全体反映
サブディレクトリAGENTS.md
- モノレポやプラグイン構成でドメイン専用ルールを上書き
- 例:
packages/frontend/AGENTS.md
ではReact特有の eslint 設定を追加
ホームディレクトリAGENTS.md
- 個人のタイピングスタイルやエイリアスを宣言
-
CODEX_DISABLE_PROJECT_DOC
で一時的に無効化可能
具体的な記述例
## Code Style
- Format Python with `black --line-length 88`
- Disallow wildcard imports
## Testing
- Run `pytest tests/` on every commit
- Minimum coverage: 90%
## Commit Message
- Follow Conventional Commits
- Prefix hotfixes with `fix:` and feature work with `feat:`
## Build
- To launch local dev, run `docker compose up --build`
CI/CDとAGENTS.mdの連携
自動整形チェック
- pre-commit hookで
AGENTS.md
のコマンドを呼び出す - フォーマット漏れをCI前にブロック
カバレッジゲート
- CI設定ファイルに閾値変数を定義し、AGENTS.mdと同期
- 規約変更時は片方の更新で自動反映
PRテンプレート自動生成
- CodexがAGENTS.mdのフォーマットを読み取り、PR本文を組み立て
- レビュアーはレビュー本質に集中できる
よくある失敗と対処
ルールの粒度が細かすぎる
- エージェントのプロンプトが冗長になり生成速度低下
- 解決策: 最小実行セットを維持し、詳細は別ドキュメントへ分離
テスト時間が長い
- AGENTS.mdで全テストを要求するとCIがタイムアウト
- 解決策: 変更ファイルのパスに応じてサブセット実行を明記
階層ルール競合
- 深いディレクトリで上位規約が陰に隠れる
- 解決策: 下位AGENTS.mdに「上書き禁止」フラグをコメントで明示
メンテナンス実践フロー
-
変更提案
- 新ツール導入やスタイル変更をIssue化
-
レビュー
- 技術リーダーとQAがAGENTS.md変更を確認
-
CI反映
- 変更に応じてpre-commit・Actionsを更新
-
教育・周知
- 社内Wikiやオンボーディング資料に記載
-
定期棚卸し
- 半年ごとにAGENTS.mdをレビュー会議で検証
まとめ
AGENTS.mdは、AIエージェントと人間開発者が同じ土俵で協働するための設計図です。
- コード品質の自動保証
- エージェント出力の一貫性向上
- レビューコスト削減
これらを実現する鍵は、
- 規約を宣言的に、
- 階層スコープを意図的に、
- 運用を継続的に
整備し続けることです。
AGENTS.mdを戦略的に活用し、Codexを信頼できるペアプログラマへと進化させましょう。
Discussion