京都のシステム開発・ホームページ制作会社　株式会社Nextat（ネクスタット）

はじめに：AGENTS.mdが「秘伝のタレ」化していませんか？

こんにちは、モリです。私も業務でCodexを活用するようになり、コードを書かせたり、レビューをさせたり、設計を書かせたりしています。
Codexを使い込むほど、（何も考えないのであれば）AGENTS.mdにルールを追記していくことになり、以下のような問題が起こります。
 

問題点

• （人間側）：肥大化したAGENTS.mdは、可読性が悪く、人間がメンテナンスするのが困難
• （人間側）：AGENTS.mdをチームで共有する場合、巨大なAGENTS.mdファイル全体をレビューしなければならず、差分が分かりにくくなる
• （AI側）：バックエンド開発者に「フロントエンドのルール」まで読み込ませるのは非効率であり、コンテキストの「ノイズ」となって回答精度を低下させる

そこで、完璧な解ではないものの、AGENTS.mdを分割して運用するために現時点で試している方法をご紹介します。

理想：AIにも「専門分野」を持たせたい

AGENTS.mdを分割するにしても、どういう基準で分割するのか？そこで注目したのがClaude Codeのサブエージェント機能です。
Anthropic社のClaude Codeには、特定のタスク（例：テストコード生成、ドキュメント作成）に特化した「サブエージェント」を定義し、呼び出す機能があります。AIに「あなたは今からレビュワーです」と明確に役割（コンテキスト）を与えられます。CodexのAGENTS.mdを役割ごとに設定できるようなものです。

しかし残念ながら、Codex CLI（2025年11月現在）には、このようなサブエージェント機能や、コンテキストを動的に切り替える標準機能は提供されていません。この機能はコミュニティからも強く要望されており、GitHubにIssueがあがっています（GitHub Issue #2604）。そこで、Codex CLIの既存機能（カスタムプロンプト）を活用し、この機能を「擬似的に」実装しようと考えました。
 

実装ステップ1：役割（コンテキスト）の物理的な分割

まず、肥大化したAGENTS.mdを、AIに与えたい「役割」ごとに分割し、プロジェクト内の myproject/.codex/agents/配下に配置します。

ディレクトリ構成例：

myproject/  <-- プロジェクトルート
├── AGENTS.md          # 共通ルールファイル
├── .codex/
│   └── agents/
│       ├── backend.md     # バックエンドエンジニアの固有ルール
│       ├── frontend.md    # フロントエンドエンジニアの固有ルール
│       ├── designer.md    # 設計作成担当の固有ルール
│       └── reviewer.md    # コードレビュワーの固有ルール
└── ...

 

なぜプロジェクト配下なのか？

この配置は、チーム開発において、以下のようなメリットを生み出します。

• Gitによるチーム共有: これらのAIルールファイルはプロジェクトのソースコードやドキュメントの一部となり、Gitでバージョン管理され、チームメンバー全員に自動で共有されます。
• コンテキストのローカル性: 特定のプロジェクトに特化したルールを、他のプロジェクトの設定と分離し、独立して管理できます。
• メンテナンスの容易性: AGENTS.md全体をレビューする必要がなく、変更があった役割ファイル（例: backend.md）だけをレビューすれば済むため、差分が明確になります。

最後に、プロジェクトのAGENTS.mdには全役割に共通するルールのみを残しておきましょう。

分割して作成したmyproject/.codex/agents/配下のファイルは以下のような役割ごとのルール（指示）を書きます。

myproject/.codex/agents/backend.md の内容例

# 役割プロファイル: 熟練のバックエンドエンジニア


**【重要な指示】** あなたは、このセッションでは**バックエンドエンジニア**としてのみ振る舞います。他の`.codex/agents/`ディレクトリ内のプロファイル（frontend.md、reviewer.mdなど）の指示は**完全に無視し**、それらに基づく提案は行わないでください。

## 技術スタックと原則

* **優先技術**: Go (Gin/Echo) または Java (Spring Boot) を中心に使用します。
* **データ永続化**: マイクロサービスにおける分散トランザクションを考慮し、PostgreSQLまたはCassandraを推奨します。
* **API**: RESTful API設計のベストプラクティスに従い、OpenAPI Specification (Swagger) を用いたドキュメント作成を同時に提案します。
* **品質**: 負荷テスト容易性、低レイテンシ、そしてシステムの耐障害性を最優先します。

## 制限事項

* UI/UXに関するアドバイスや、ブラウザ側の実装（HTML/CSS/DOM操作など）は一切行いません。
* 提案するコードは、必ずサーバー側またはデータベース関連のものです。

実装ステップ2：カスタムプロンプトで「役割切り替えスイッチ」を作る

Codexの機能（~/.codex/prompts/配下のmdがカスタムコマンドになる）を利用します。（※役割ファイルと違いプロジェクト配下でなくホームディレクトリ配下に作成することに注意）
以下の例のように「$1引数」で役割切り替え切り替えるロジックを記述します。
役割を特定した直後に、プロジェクト内のパス（.codex/agents/）をAIに指示として渡していますが、実行コンテキスト（プロジェクトのルート）からの相対パスを解釈し、そのファイルの内容を読み込んでくれます。
  
~/.codex/prompts/agents.md の内容例

**【最重要指示】** あなたは、ユーザーが入力した引数（`$1`）に基づき、このセッションでのあなたの役割を厳格に切り替えます。

##  役割切り替えロジック

1.  **引数の確認**: ユーザーが入力した引数は `$1` です。
2.  **役割の特定**:
    * もし `$1` が `backend` の場合、.codex/agents/backend.md* の規約に従い、あなたは直ちに「**バックエンドエンジニア**」としての役割を採用し、それ以外の役割を完全に忘却します。
    * もし `$1` が `frontend` の場合、.codex/agents/frontend.md* の規約に従い、あなたは直ちに「**フロントエンドエンジニア**」としての役割を採用し、それ以外の役割を完全に忘却します。
    * もし `$1` が `reviewer` の場合、.codex/agents/reviewer.md* の規約に従い、あなたは直ちに「**コードレビュワー**」としての役割を採用し、それ以外の役割を完全に忘却します。
    * もし `$1` が `designer` の場合、.codex/agents/designer.md* の規約に従い、あなたは直ちに「**設計作成担当**」としての役割を採用し、それ以外の役割を完全に忘却します。
3.  **役割未指定の場合**: `$1` が上記以外の場合、または空の場合、あなたは単に「利用可能な役割を指定してください」と案内し、役割を採用してはいけません。

実行デモ

作成したカスタムプロンプトを使用して、あたかもサブエージェントを呼び出すかのようにAIの役割を切り替えてみます。

（例）バックエンドAIの起動

$ /prompts:agents backend

→ AIは「了解しました。以後はバックエンドエンジニアとしての指針（.codex/agents/backend.md）に従います。」のように回答し、今後セッション内ではbackend.mdルールだけを見て回答します。
なお、同じセッションで再度カスタムプロンプトを実行すれば別の役割へ切り替え可能ですが、コンテキストが混ざるのを防ぐため、できれば別タブ・別セッションで起動することをおすすめします。
 

まとめ

今回ご紹介した、カスタムプロンプトと役割別ファイル（myproject/.codex/agents/に配置するmdファイル）を組み合わせる手法は、チーム開発におけるAGENTS.mdの肥大化とコンテキスト汚染という問題を解決に向けた、現時点でできる一例です。AIに与える指示を役割ごとに明確に分離・管理できるため、AIの回答精度を少しでも高く維持したまま、チーム全体でAI活用のナレッジを共有できるメリットはあるかと思います。

しかし、この方法はあくまでCodex CLIの既存機能を用いた、プロンプトによる指示分けにすぎません。Codex CLI公式がClaude Codeのような「サブエージェント機能」や、プロジェクト固有のコンテキストファイルを動的に読み込む仕組みを標準で実装してくれる日を、望んでいます。