技術資料

Codexをプロジェクト開発で継続的に使っていると、毎回同じような前提や注意点を説明する場面が増えてきます。

例えば、使用している言語やフレームワークのバージョン、プロジェクト内の仕様書の場所、テストの実行方法などです。日本語を含む文書を更新する場合は、文字コードについての注意点も毎回伝えたくなるかもしれません。

このような情報やルールを記述しておく方法として、CodexにはAGENTS.mdやSkillsがあります。

今回は、私が実際に使っていて効果を感じた内容をもとに、AGENTS.mdとSkillsをどのように使い分けるとよいかを整理します。

AGENTS.mdとSkillsの違い

AGENTS.mdとSkillsは、どちらもCodexへ作業上の情報を伝えるために使えますが、役割は同じではありません。

仕組み	主な役割	記述する内容の例
AGENTS.md	プロジェクト全体の前提や規約を伝える	技術スタック、仕様書の場所、共通の確認事項
Skills	特定の作業で使う手順を再利用する	文書更新、バックエンド実装、テストやビルド

Codexの公式資料では、AGENTS.mdは作業前に読み込まれる指示ファイルとして説明されています。プロジェクトの階層に応じて指示を組み合わせられるため、リポジトリ全体のルールや、特定のディレクトリだけに適用するルールを記述できます。

詳しくは、OpenAIのCustom instructions with AGENTS.mdを参照してください。

一方、Skillsは、指示や関連するリソースをまとめたフォルダーです。SKILL.mdに、Skillの名前、用途、作業手順などを記述し、必要に応じてreferences、scripts、templatesなどを追加できます。

Skillsについては、OpenAIのSkillsで説明されています。

AGENTS.mdに書くと効果を感じた内容

私の場合、AGENTS.mdには、プロジェクト内の複数の作業で共通する情報を記述しています。

技術スタックを明示する

まず、バックエンドとフロントエンドで使用している言語、フレームワーク、バージョンなどを記述します。

Codexが既存のコードを調査したり、新しいコードを作成したりする場合、使用している技術スタックが明確になっている方が、実装方針や利用するコマンドを判断しやすくなります。

例えば、以下のような項目です。

## 技術スタック

- バックエンド: PHP 8.x、使用中のフレームワークとバージョン
- フロントエンド: Vue.js、TypeScript、使用中のバージョン
- データベース: 使用中のデータベースとバージョン
- 実行環境: OS、Webサーバー、コンテナなど
- パッケージ管理: Composer、npmなど

ここで重要なのは、一般的な技術名を並べることではなく、実際のプロジェクトで採用しているバージョンを記述することです。バージョンが変わった場合は、AGENTS.mdの記述も更新します。

仕様書ファイルのパスを記述する

プロジェクト内に仕様書や設計書がある場合は、そのファイルやディレクトリの場所も記述しておくと便利です。

## プロジェクト内の資料

- 全体仕様: docs/specification.md
- API仕様: docs/api/
- 画面仕様: docs/screens/
- 開発手順: docs/development.md

仕様書の内容を毎回プロンプトへ貼り付けるのではなく、まず参照すべきファイルを示しておきます。作業を依頼するときも、「関連する仕様書を確認してから実装してください」と指示しやすくなります。

ただし、ファイルのパスを記述しただけで、仕様書の内容が常に正しいとは限りません。仕様書が古くなっている場合や、今回の作業に関係しない場合もあるため、実装前に対象資料を確認する手順まで書いておくとよいでしょう。

使用できるSkillsのユースケースを案内する

プロジェクト内に複数のSkillsがある場合は、AGENTS.mdに一覧と使いどころを記述しています。

## 使用できるSkills

- document-encoding-safety:
  日本語を含む文書を更新するときに使用する
- backend-development:
  バックエンドの実装、テスト、構文チェックを行うときに使用する
- frontend-development:
  フロントエンドの実装、テスト、ビルドを行うときに使用する

ここにはSkillの詳細な手順を重複して書かず、どのような作業で使うものなのかを記述します。詳細な手順は、それぞれのSkillに置いておきます。

共通する確認事項を記述する

どの作業でも必要になる確認事項も、AGENTS.mdに記述する候補です。

## 共通ルール

- 変更前に関連するファイルと仕様書を確認する
- 変更対象を必要な範囲に限定する
- 変更後は差分を確認する
- 必要に応じてテスト、構文チェック、ビルドを実行する
- 私が確認するまでGitのcommitとpushを実行しない

こうしたルールは、バックエンドやフロントエンドなど、作業の種類に関係なく適用したい場合に向いています。

Skillsに分けて便利だった作業

一方で、作業ごとに手順が異なるものは、Skillsとして分けています。

日本語を含む文書のエンコードルール

日本語を含むMarkdownやHTMLを更新する場合は、文字コードに注意が必要です。読み書きの方法や、編集後に文字化けがないことを確認する手順を毎回説明するのは手間がかかります。

このような内容は、文書更新用のSkillにまとめておくと、文書を変更する作業で再利用できます。

# 文書更新時のエンコードルール

1. 編集前にファイルの文字コードを確認する
2. 日本語を含むファイルは、文字コードを明示して読み込む
3. 文字化けした内容を、そのまま上書きしない
4. 書き込み時も文字コードを明示する
5. 編集後にファイルを読み直し、文字化けがないことを確認する
6. Gitの差分を確認する

この手順は、バックエンドやフロントエンドの実装ルールとは直接関係ありません。そのため、文書更新時に使うSkillとして独立させる方が、必要な作業だけに適用しやすくなります。

バックエンドとフロントエンドの実装ルール

バックエンドとフロントエンドでは、使用する言語やフレームワークだけでなく、ディレクトリ構成、命名規則、エラー処理、テスト方法なども異なります。

これらを一つのSkillへまとめると、関係のないルールまで読み込むことになり、手順が分かりにくくなる場合があります。

そこで、例えば以下のように分けます。

.agents/
└── skills/
    ├── document-encoding-safety/
    │   └── SKILL.md
    ├── backend-development/
    │   └── SKILL.md
    └── frontend-development/
        └── SKILL.md

バックエンドのAPIを変更するときはバックエンド用のSkill、フロントエンドの画面を変更するときはフロントエンド用のSkillを使います。両方に関係する作業では、必要なSkillsを組み合わせます。

テスト、構文チェック、ビルドの実行ルール

実装ルールだけでなく、変更後に何を確認するかもSkillsへ記述しておくと便利です。

## 変更後の確認

- PHPの構文チェックを実行する
- バックエンドの対象テストを実行する
- APIのレスポンス形式を確認する
- 実行したコマンドと結果を報告する

フロントエンド用のSkillでは、例えば以下のような確認を定義します。

## 変更後の確認

- TypeScriptの型チェックを実行する
- フロントエンドのテストを実行する
- 本番用ビルドを実行する
- ビルド結果と警告の有無を報告する

実際に使うコマンドは、プロジェクトのcomposer.json、package.json、CI設定などに合わせて記述します。存在しないコマンドを一般論で書くのではなく、そのプロジェクトで実際に実行できる手順にすることが重要です。

AGENTS.mdとSkillsの分け方

どちらへ記述するか迷った場合は、そのルールがどの範囲に適用されるかで考えると判断しやすくなります。

• プロジェクトのほぼすべての作業に適用する前提や規約は、AGENTS.md
• 特定の作業で繰り返し使う手順は、Skills
• バックエンドやフロントエンドなど、対象領域が限定される手順は、個別のSkill
• 一回限りの依頼や、その場だけの判断は、通常のプロンプト

例えば、「PHPとLaravelを使っている」という情報はプロジェクト全体の前提なので、AGENTS.mdに記述します。一方、「LaravelのAPIを変更したら、このテストを実行する」という手順は、バックエンド用のSkillに記述する方が適しています。

また、AGENTS.mdから利用できるSkillsと用途を案内し、詳細な手順はSkill側だけに置くと、同じ内容を二重に管理せずに済みます。

運用中にルールを育てる

最初から完璧なAGENTS.mdやSkillsを作ろうとすると、記述量が多くなり、実際には使わないルールまで追加してしまうことがあります。

私の場合は、Codexを運用していて不都合が発生するたびに、再発防止に必要なルールを随時追記しています。

例えば、次のように考えます。

1. どのような不都合が発生したのかを整理する
2. すべての作業に共通する問題か、特定の作業だけの問題かを切り分ける
3. 共通の問題ならAGENTS.md、作業固有の問題なら該当するSkillへ追記する
4. 同じ作業をもう一度行い、ルールが適用されるか確認する
5. 時間が経ってから、古くなったパスやコマンドを見直す

例えば、プロジェクトで使用するフレームワークのバージョンを間違える問題なら、技術スタックの記述をAGENTS.mdへ追加します。日本語ファイルの保存方法を誤る問題なら、文書更新用のSkillへエンコードと確認手順を追加します。

一度追加したルールが、別の作業や別の環境では不要になることもあります。ルールを増やすだけでなく、現在の運用に合っているか、ほかの指示と重複していないかも確認します。

AGENTS.mdの内容が読み込まれているか確認する

AGENTS.mdを作成しただけで、意図した内容が必ず適用されていると考えない方が安全です。作業を始める前に、読み込まれている指示ファイルを確認する習慣をつけます。

Codex CLIを使っている場合は、例えば以下のように確認できます。

codex "現在読み込まれている指示ファイルと、主なルールを説明してください。"

実際のオプションや表示内容は、利用しているCodexの環境やバージョンによって変わる可能性があります。確認方法は、執筆時点のCodex公式ドキュメントも参照してください。

GitHub上のCodexコードレビューを利用する場合は、AGENTS.mdにレビュー用のルールを記述することもできます。レビューで確認したいプロジェクト固有の問題を短く書き、フォーマットやLintなどの機械的なチェックはCIへ任せる、という分け方が公式資料で案内されています。

まとめ

今回は、CodexのAGENTS.mdとSkillsの使い分けについて整理しました。

AGENTS.mdには、技術スタック、仕様書ファイルのパス、利用できるSkillsのユースケース、プロジェクト全体の共通ルールなどを記述します。

Skillsには、日本語を含む文書更新時のエンコードルール、バックエンド・フロントエンド個別の実装ルール、テスト・構文チェック・ビルドの実行手順などを記述します。

最初からすべてを決める必要はありません。Codexを使っていて不都合が発生したときに、プロジェクト全体のルールなのか、作業固有の手順なのかを考え、適切な場所へ少しずつ追記していくとよいかと思います。

AGENTS.mdとSkillsの内容が増えてきたら、重複や古くなった記述がないかも確認しましょう。