ChatGPT ドキュメント
日本語
お問い合わせ goolvyouyou@gmail.com

カスタマイズ

プロジェクトのガイダンス、スキル、MCP、サブエージェントを使用して Codex をカスタマイズする方法

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

Codex のカスタマイズは、連携して機能するいくつかのレイヤーで構成されます。

  • 永続的な指示を提供する プロジェクトガイダンス（AGENTS.md）
  • 過去の作業から得た有用なコンテキストを保持する メモリ
  • 再利用可能なワークフローと分野の専門知識を提供する スキル
  • 外部ツールや共有システムにアクセスするための MCP
  • 専門化されたサブエージェントに作業を委任するための サブエージェント

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

AGENTS ガイダンス

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

リポジトリ内で Codex に毎回従ってほしい、次のようなルールに使用します。

  • ビルドとテストのコマンド
  • レビューに関する要件
  • リポジトリ固有の規約
  • ディレクトリ固有の指示

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

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

  • 繰り返されるミス：エージェントが同じミスを繰り返す場合は、ルールを追加します。
  • 読み込みが多すぎる：正しいファイルを見つけても多くのドキュメントを読みすぎる場合は、ルーティングのガイダンス（優先するディレクトリやファイル）を追加します。
  • 繰り返される PR の指摘：同じ指摘を複数回行った場合は、ルールとして明文化します。
  • GitHub での操作：pull request のコメントで @codex をタグ付けして依頼（たとえば @codex add this to AGENTS.md）すると、更新をクラウドチャットに委任できます。
  • 差異チェックの自動化：スケジュール済みタスクを使用して、ガイダンスの不足を検出し、AGENTS.md に追加すべき内容を提案する定期チェック（たとえば毎日）を実行します。

AGENTS.md は、これらのルールを適用するインフラストラクチャと組み合わせてください。pre-commit フック、リンター、型チェッカーは、問題が目に入る前に検出するため、繰り返されるミスを防止する仕組みがさらに強化されます。

Codex は複数の場所からガイダンスを読み込めます。Codex ホームディレクトリにあるグローバルファイル（開発者個人用）と、チームでチェックインできるリポジトリ固有のファイルです。作業ディレクトリに近いファイルほど優先されます。グローバルファイルは、レビュー形式、詳細度、デフォルト値など、Codex とのコミュニケーション方法を調整するために使用し、リポジトリ内のファイルはチームとコードベースのルールに集中させます。

<FileTree class="mt-4" tree={[ { name: "~/.codex/", open: true, children: [ { name: "AGENTS.md", comment: "グローバル（開発者個人用）" }, ], }, { name: "repo-root/", open: true, children: [ { name: "AGENTS.md", comment: "リポジトリ固有（チーム用）" }, ], }, ]} />

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

スキル

スキルは、反復可能なワークフローに対応する再利用可能な機能を Codex に提供します。スキルは、豊富な指示、スクリプト、参考資料に対応しながら、タスクをまたいで再利用できるため、再利用可能なワークフローに適していることが多いです。スキルはエージェントに読み込まれ、少なくともメタデータが表示されるため、Codex は暗黙的にスキルを検出して選択できます。これにより、最初からコンテキストを膨らませることなく、高度なワークフローを利用できます。

スキルフォルダーを使用して、ワークフローをローカルで作成し、改善します。そのワークフロー用のプラグインがすでに存在する場合は、実証済みのセットアップを再利用するため、先にインストールしてください。独自のワークフローをチーム間で配布したり、接続器と一緒にまとめたりする場合は、プラグインとしてパッケージ化します。スキルは作成形式であり、プラグインはインストール可能な配布単位です。

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

<FileTree class="mt-4" tree={[ { name: "my-skill/", open: true, children: [ { name: "SKILL.md", comment: "必須：指示とメタデータ" }, { name: "scripts/", comment: "任意：実行可能コード" }, { name: "references/", comment: "任意：ドキュメント" }, { name: "assets/", comment: "任意：テンプレート、リソース" }, ], }, ]} />

スキルディレクトリには、ワークフローの一部として Codex が呼び出す CLI スクリプト（たとえば、シードデータの作成や検証の実行）を含む scripts/ フォルダーを配置できます。ワークフローで外部システム（Issue トラッカー、デザインツール、ドキュメントサーバー）が必要な場合は、スキルを 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
スキル ~/.agents/skills リポジトリ内の .agents/skills

Codex はスキルに段階的開示を使用します。

  • 検出時はメタデータ（name、description）から開始します
  • スキルが選択された場合にのみ SKILL.md を読み込みます
  • 必要な場合にのみ参考資料を読み、スクリプトを実行します

スキルは明示的に呼び出すことができ、タスクがスキルの説明に一致する場合は Codex が暗黙的に選択することもできます。スキルの説明を明確にすると、より確実に呼び出されます。

スキルを構築する

MCP

MCP (Model Context Protocol) は、Codex を外部ツールやコンテキストプロバイダーに接続する標準的な方法です。チームが利用する Figma、Linear、GitHub、社内ナレッジサービスなど、リモートでホストされるシステムに特に適しています。

Codex が Issue トラッカー、デザインツール、ブラウザー、共有ドキュメントシステムなど、ローカルリポジトリ外にある機能を必要とする場合に MCP を使用します。

次のように捉えることができます。

  • ホスト：Codex
  • クライアント：Codex 内の MCP 接続
  • サーバー：外部ツールまたはコンテキストプロバイダー

MCP servers は次のものを公開できます。

  • ツール（アクション）
  • リソース（読み取り可能なデータ）
  • プロンプト（再利用可能なプロンプトテンプレート）

この分離により、信頼と機能の境界を把握しやすくなります。主にコンテキストを提供するサーバーもあれば、強力なアクションを公開するサーバーもあります。

実際には、MCP はスキルと組み合わせると特に効果的です。

  • スキルがワークフローを定義し、使用する MCP ツールを指定します

Model Context Protocol

サブエージェント

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

サブエージェント

スキルと MCP の組み合わせ

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

次のステップ

次の順序で構築します。

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