コンテンツにスキップ

カスタマイズ

カスタマイズとは、Codex をチームの働き方に合わせて動作させることです。

Codex では、いくつかのレイヤーが連携してカスタマイズを実現します。

  • プロジェクトガイダンス (AGENTS.md)：永続的な指示
  • メモリ：過去の作業から学習した有用なコンテキスト
  • スキル：再利用可能なワークフローとドメイン知識
  • MCP：外部ツールや共有システムへのアクセス
  • サブエージェント：専門のサブエージェントへの作業の委任

これらは競合するものではなく、相互に補完し合います。AGENTS.md は動作を形作り、メモリはローカルのコンテキストを引き継ぎ、スキルは繰り返し可能なプロセスをパッケージ化し、MCP は Codex をローカルワークスペース外のシステムに接続します。

AGENTS ガイダンス

AGENTS.md は、リポジトリとともに維持され、エージェントが作業を開始する前に適用される、永続的なプロジェクトガイダンスを Codex に提供します。内容は小さく保ってください。

リポジトリで Codex が毎回従うべきルールには、次のようなものがあります。

  • ビルドおよびテストのコマンド
  • レビューに関する期待事項
  • リポジトリ固有の規約
  • ディレクトリ固有の指示

エージェントがコードベースについて誤った前提を置いた場合は、AGENTS.md で修正し、その修正が維持されるように AGENTS.md を更新するようエージェントに依頼してください。これをフィードバックループとして扱います。

AGENTS.md の更新：まず、重要な指示だけを記載します。繰り返し発生するレビューのフィードバックをルールとして明文化し、適用対象となる最も近いディレクトリにガイダンスを配置します。何かを修正した際は、将来のセッションに修正を引き継げるよう、エージェントに AGENTS.md を更新するよう伝えてください。

AGENTS.md を更新するタイミング

  • 同じミスの繰り返し：エージェントが同じミスを繰り返す場合は、ルールを追加します。
  • 読み取り量が多すぎる：適切なファイルを見つけているにもかかわらずドキュメントを読みすぎる場合は、どのディレクトリやファイルを優先するかというルーティングガイダンスを追加します。
  • 繰り返される PR フィードバック：同じフィードバックを複数回残す場合は、ルールとして明文化します。
  • GitHub 内での対応：プルリクエストのコメントで、リクエスト（例：@codex add this to AGENTS.md）を添えて @codex にタグ付けし、クラウドチャットに更新を委任します。
  • ドリフトチェックの自動化：スケジュールされたタスクを使用して、ガイダンスの不足を確認し、AGENTS.md に追加すべき内容を提案するチェックを定期的（例：毎日）に実行します。

AGENTS.md と、ルールを適用するインフラストラクチャを組み合わせてください。pre-commit フック、リンター、型チェッカーが問題を発見する前に検出するため、繰り返し発生するミスを防ぐ仕組みがより賢くなります。

Codex は複数の場所からガイダンスを読み込めます。開発者であるあなた向けの Codex ホームディレクトリにあるグローバルファイルと、チームがチェックインできるリポジトリ固有のファイルです。作業ディレクトリに近いファイルが優先されます。 グローバルファイルは Codex があなたとどのようにコミュニケーションするか（例：レビューのスタイル、詳細度、デフォルト設定）を形作るために使用し、リポジトリのファイルはチームとコードベースのルールに集中させてください。

AGENTS.md を使ったカスタム指示

スキル

スキルは、繰り返し可能なワークフローのための再利用可能な機能を Codex に提供します。 スキルは、再利用可能なワークフローに適していることが多く、再利用性を保ちながら、より豊富な指示、スクリプト、リファレンスをサポートするためです。 スキルはエージェントに読み込まれ、少なくともメタデータが表示されるため、Codex はスキルを暗黙的に発見して選択できます。これにより、最初からコンテキストを過度に膨らませることなく、豊富なワークフローを利用できます。

スキルフォルダーを使用して、ローカルでワークフローを作成し、反復的に改善してください。そのワークフロー用のプラグインがすでに存在する場合は、実績のあるセットアップを再利用するため、まずインストールしてください。独自のワークフローをチーム間で配布したり、コネクターとともにバンドルしたりする場合は、プラグインとしてパッケージ化します。スキルは作成形式として残り、プラグインはインストール可能な配布単位になります。

通常、スキルは SKILL.md ファイルと、任意のスクリプト、リファレンス、アセットで構成されます。

スキルディレクトリには 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. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

次の用途にはスキルを使用します。

  • 繰り返し可能なワークフロー（リリース手順、レビュー手順、ドキュメント更新）
  • チーム固有の専門知識
  • 例、リファレンス、ヘルパースクリプトを必要とする手順

スキルはグローバル（開発者であるあなたのユーザーディレクトリ内）にも、リポジトリ固有（.agents/skills にチェックイン）にもできます。ワークフローがそのプロジェクトに適用される場合は、リポジトリのスキルを .agents/skills に配置し、すべてのリポジトリで使用したいスキルにはユーザーディレクトリを使用してください。

レイヤー グローバル リポジトリ
AGENTS ~/.codex/AGENTS.md AGENTS.md（リポジトリルートまたはネストされたディレクトリ）
スキル $HOME/.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 ツールの名前を指定します

Model Context Protocol

サブエージェント

異なる役割を持つエージェントを作成し、それぞれに異なる方法でツールを使うようプロンプトを指定できます。たとえば、あるエージェントには特定のテストコマンドと設定を実行させ、別のエージェントにはデバッグ用に本番ログを取得する MCP サーバーを持たせることができます。各サブエージェントは作業に集中し、その役割に適したツールを使用します。

サブエージェント

スキル + MCP の連携

スキルと MCP を組み合わせることで、すべてが連携します。スキルが繰り返し可能なワークフローを定義し、MCP がそれらを外部ツールやシステムに接続します。 スキルが MCP に依存する場合は、その依存関係を agents/openai.yaml で宣言してください。これにより、Codex が自動的にインストールして接続できます（スキルを構築するを参照）。

次のステップ

次の順序で構築します。

  1. AGENTS.md を使ったカスタム指示を設定し、Codex がリポジトリの規約に従うようにします。これらのルールを適用するため、pre-commit フックとリンターを追加します。
  2. 再利用可能なワークフローがすでに存在する場合は、プラグインをインストールします。存在しない場合は、スキルを作成し、共有する場合はプラグインとしてパッケージ化します。
  3. ワークフローで外部システム（Linear、GitHub、ドキュメントサーバー、デザインツール）が必要になったら、MCPを使用します。
  4. ノイズの多いタスクや専門的なタスクをサブエージェントに委任する準備ができたら、サブエージェントを使用します。