Codex をカスタマイズすると、チームの仕事の進め方に合わせて動作を調整できます。
Codex のカスタマイズでは、次の仕組みを組み合わせて使います。
- プロジェクトの指針（
AGENTS.md）：毎回適用する指示を定めます。 - メモリ：過去の作業から得た有用なコンテキストを引き継ぎます。
- スキル：ワークフローや分野固有の専門知識を繰り返し活用できます。
- MCP：外部ツールや共有システムにアクセスできます。
- サブエージェント：それぞれの専門に応じた作業を任せられます。
これらの仕組みは互いに補い合います。AGENTS.md は Codex の振る舞いを定め、メモリはローカルのコンテキストを次の作業に引き継ぎます。スキルは繰り返し使う手順をまとめ、MCP は Codex をローカルのワークスペース外のシステムに接続します。
AGENTS.md によるプロジェクトの指針
AGENTS.md には、Codex が継続して従うプロジェクトの指針を記述します。このファイルはリポジトリと一緒に管理され、指針はエージェントが作業を始める前に適用されます。内容は簡潔にまとめてください。
そのリポジトリで Codex に毎回守ってほしいルールを記載します。たとえば、次のような内容です。
- ビルドやテストに使うコマンド
- レビューで確認してほしいこと
- リポジトリ固有の規約
- ディレクトリごとの指示
エージェントがコードベースについて誤った前提で作業したら、正しい前提を AGENTS.md に記載します。訂正するたびにエージェントに AGENTS.md の更新を依頼し、そのフィードバックを次の作業に生かしましょう。
AGENTS.md の更新：まずは重要な指示だけを記載します。レビューで繰り返し伝える指摘はルールとして明文化し、そのルールが適用される場所に最も近いディレクトリに置きます。誤りを訂正したら、エージェントに AGENTS.md の更新を依頼し、以降のセッションにも訂正内容を引き継ぎます。
AGENTS.md を更新するタイミング
- 同じ誤りを繰り返す場合：エージェントが同じ誤りを繰り返したら、ルールを追加します。
- 読む資料が多すぎる場合：必要なファイルは見つけられても、余分な資料まで読んでしまう場合は、優先して参照するディレクトリやファイルを指定します。
- PR で同じ指摘を繰り返す場合：同じフィードバックを複数回伝えたら、その内容をルールとして明文化します。
- GitHub から更新を依頼する場合：pull request のコメントで
@codexをメンションし、@codex この内容を AGENTS.md に追加してくださいのように依頼すると、更新をクラウドのチャットに任せられます。 - 指針と実態のずれを自動で確認する場合：スケジュール済みタスクを使って、たとえば毎日、指針に不足がないかを確認し、
AGENTS.mdに追加する内容を提案させます。
AGENTS.md と併せて、ルールを自動で適用する仕組みも整えます。コミット前のフック、リンター、型チェッカーを使うと、人が気づく前に問題を検出でき、同じ誤りを繰り返しにくくなります。
Codex は複数の場所から指針を読み込めます。Codex のホームディレクトリには開発者個人向けのグローバルファイルを置き、各リポジトリにはチームでバージョン管理できるファイルを置きます。作業ディレクトリに近いファイルほど優先されます。 グローバルファイルには、レビューのスタイル、回答の詳しさ、既定の設定など、Codex と自分とのやり取りに関する指針を記載します。リポジトリ内のファイルには、チームとコードベースに関するルールをまとめます。
-
~/.codex/
- AGENTS.md グローバル（開発者個人向け）
-
-
repo-root/
- AGENTS.md リポジトリ固有（チーム向け）
-
スキル
スキルを使うと、繰り返し行う作業に必要な機能を Codex で再利用できます。詳細な指示、スクリプト、参考資料をひとまとめにして複数のタスクで使えるため、ワークフローを再利用するにはスキルが最適な場合が多くあります。 エージェントは各スキルのメタデータを最初から参照できるため、ユーザーが明示的に指定しなくても、Codex は適切なスキルを見つけて選択できます。最初から大量のコンテキストを読み込まずに、詳細なワークフローを利用できます。
ワークフローをローカルで作成し、改善を重ねるには、スキルフォルダーを使います。目的のワークフローに対応するプラグインがすでにあれば、まずインストールして、実績のある構成を再利用します。自作のワークフローを複数のチームに配布したり、コネクタと一緒に提供したりする場合は、プラグインとしてパッケージ化します。ワークフローの作成にはスキル形式を使い、配布とインストールはプラグイン単位で行います。
スキルは通常、SKILL.md ファイルと、必要に応じて追加するスクリプト、参考資料、アセットで構成されます。
-
my-skill/
- SKILL.md 必須：指示とメタデータ
- scripts/ 任意：実行可能なコード
- references/ 任意：ドキュメント
- assets/ 任意：テンプレートやリソース
-
スキルのディレクトリには scripts/ フォルダーを置き、ワークフローの中で Codex が呼び出す CLI スクリプトを格納できます。たとえば、初期データの投入や検証の実行に使えます。ワークフローで課題トラッカー、デザインツール、ドキュメントサーバーなどの外部システムが必要な場合は、スキルを MCP と組み合わせます。
SKILL.md の例：
---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---
1. `git add .` は実行しないでください。ファイルを変更の目的ごとにまとめてステージしてください。
2. feat → test → docs → refactor → chore の順に、種類ごとにコミットを分けてください。
3. 各コミットの変更範囲が伝わる簡潔なコミットメッセージを書いてください。
4. 各コミットの目的を一つに絞り、レビューしやすくしてください。スキルは次のような用途に適しています。
- 繰り返し行うワークフロー（リリース手順、定例のレビュー、ドキュメントの更新）
- チーム固有の専門知識の活用
- 例、参考資料、補助スクリプトが必要な手順
スキルは、開発者個人向けにユーザーディレクトリに置いてグローバルに使うことも、チーム向けにリポジトリの .agents/skills にチェックインして使うこともできます。特定のプロジェクト向けのワークフローは .agents/skills に、すべてのリポジトリで使いたいスキルはユーザーディレクトリに置きます。
| 種類 | グローバル | リポジトリ |
|---|---|---|
| AGENTS | ~/.codex/AGENTS.md |
AGENTS.md（リポジトリのルートまたは配下のディレクトリ） |
| スキル | ~/.agents/skills |
.agents/skills（リポジトリ内） |
Codex はスキルの情報を段階的に読み込みます。
- まず、メタデータ（
name、description）を使ってスキルを探します。 - スキルを選択したときにだけ
SKILL.mdを読み込みます。 - 参考資料の読み込みやスクリプトの実行は、必要な場合に限ります。
スキルは明示的に呼び出せます。また、タスクがスキルの説明に一致すれば、Codex が自動で選択することもできます。スキルの説明を明確に書くと、意図した場面で呼び出されやすくなります。
MCP
MCP（Model Context Protocol）は、Codex を外部ツールやコンテキストプロバイダーに接続するための標準プロトコルです。 Figma、Linear、GitHub、チームが利用する社内ナレッジサービスなど、リモートでホストされるシステムとの接続に特に役立ちます。
課題トラッカー、デザインツール、ブラウザ、共有ドキュメントシステムなど、ローカルのリポジトリの外にある機能を Codex で使う場合は、MCP を利用します。
各要素の役割は次のとおりです。
- ホスト：Codex
- クライアント：Codex 内の MCP 接続
- サーバー：外部ツールまたはコンテキストプロバイダー
MCP サーバーは次の機能を公開できます。
- ツール（実行できる操作）
- リソース（読み取り可能なデータ）
- プロンプト（再利用可能なプロンプトテンプレート）
これらを区別すると、何をどこまで信頼できるか、どのような操作が可能かを判断しやすくなります。主にコンテキストを提供するサーバーもあれば、強力な操作機能を公開するサーバーもあります。
実際の作業では、MCP はスキルと組み合わせると特に役立つことがよくあります。
- スキルでワークフローを定義し、使用する MCP ツールを名前で指定します。
サブエージェント
役割ごとにエージェントを作成し、それぞれに異なるツールの使い方を指示できます。たとえば、あるエージェントには指定したコマンドと設定でテストを実行させ、別のエージェントにはデバッグ用に本番ログを取得する MCP サーバーを用意できます。各サブエージェントは担当作業に集中し、その作業に適したツールを使います。
スキルと MCP の組み合わせ
スキルと MCP を組み合わせると、スキルで繰り返し使うワークフローを定義し、MCP を通じてそのワークフローを外部ツールやシステムに接続できます。
スキルが MCP に依存する場合は、agents/openai.yaml にその依存関係を宣言します。これにより、Codex が必要な MCP サーバーのインストールと接続設定を自動で行えます（スキルの作成を参照）。
次のステップ
次の順に進めます。
- AGENTS.md を使ったカスタム指示を用意し、Codex がリポジトリの規約に従うようにします。コミット前のフックとリンターを追加して、規約を自動で適用します。
- 再利用できるワークフローがすでにあれば、プラグインをインストールします。なければスキルを作成し、共有するときにプラグインとしてパッケージ化します。
- ワークフローで外部システム（Linear、GitHub、ドキュメントサーバー、デザインツール）が必要になったら、MCP を使います。
- 出力が多く主作業を追いにくくなるタスクや専門性の高いタスクを切り分ける準備ができたら、サブエージェントに任せます。