🐡

# 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 or docker 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に「上書き禁止」フラグをコメントで明示

メンテナンス実践フロー

  1. 変更提案

    • 新ツール導入やスタイル変更をIssue化
  2. レビュー

    • 技術リーダーとQAがAGENTS.md変更を確認
  3. CI反映

    • 変更に応じてpre-commit・Actionsを更新
  4. 教育・周知

    • 社内Wikiやオンボーディング資料に記載
  5. 定期棚卸し

    • 半年ごとにAGENTS.mdをレビュー会議で検証

まとめ

AGENTS.mdは、AIエージェントと人間開発者が同じ土俵で協働するための設計図です。

  • コード品質の自動保証
  • エージェント出力の一貫性向上
  • レビューコスト削減

これらを実現する鍵は、

  • 規約を宣言的に
  • 階層スコープを意図的に
  • 運用を継続的に

整備し続けることです。
AGENTS.mdを戦略的に活用し、Codexを信頼できるペアプログラマへと進化させましょう。

Discussion