エグゼクティブサマリー
この記事は、AIコーディングツールまわりで増えがちな AGENTS.md、CLAUDE.md、GEMINI.md、SKILL.md、agents系ファイルをどう分けるか、という話です。
結論はかなりシンプルで、「常に読ませるもの」「必要なときだけ読ませるもの」「役割を持つ別エージェント」を分けると扱いやすいです。
AGENTS.md を共通ルールの正本にしつつ、ツール固有ファイルは薄くし、手順は SKILL.md、役割分担は agents系ファイルに逃がす、という点です。
今回のキーメッセージはこれです。
常時ルールは
AGENTS.md
ツール固有の入口は薄くする
手順はSKILL.md
役割分担は agents系ファイル
結論
まずは、この理解で十分かなと思います。
| 書くもの | 一言でいうと | 向いている内容 |
|---|---|---|
AGENTS.md |
AIエージェント向けREADME | 共通ルール、ビルド、テスト、禁止事項 |
CLAUDE.md |
Claude Code向けの常時メモリ | Claude固有の補足、または AGENTS.md 参照 |
GEMINI.md |
Gemini CLI向けの常時コンテキスト | Gemini系の補足、または読み込む文脈の指定 |
SKILL.md |
必要時だけ使う専門手順 | レビュー手順、記事化手順、リリース手順 |
.codex/agents/*.toml |
Codexのcustom agent | レビュアー、調査役、実装役など |
.claude/agents/*.md |
Claude Codeのsubagent | 専門人格・専門役割 |
.agents/agents.md |
チーム型エージェント定義の例 | PM、Engineer、QAなどのペルソナ |
常に守ってほしいルールは短く、毎回読ませる。長い手順や専門的な進め方は、必要になったときだけ読ませる。さらに「誰にやらせるか」は、agents系ファイルで役割として分ける。
背景
AIコーディングツールを使っていると、似たような名前のファイルがどんどん出てきます。
AGENTS.md、CLAUDE.md、GEMINI.md、SKILL.md、.codex/agents、.claude/agents。名前だけ見ると、どれも「AIに何かを教えるファイル」に見えます。
ただ、実際には読むタイミングと役割が違います。ここを混ぜると、常時コンテキストが重くなったり、ツールごとに同じ内容を何回も管理することになります。
そこで今回は、「いつ読むか」と「何を担当するか」で整理しました。
補足：背景や課題感
ざっくり分けると、こうです。
| 観点 | 役割 | 例 |
|---|---|---|
| 常時読む文脈 | そのプロジェクトで常に守るルール |
AGENTS.md、CLAUDE.md、GEMINI.md
|
| 必要時だけ読む手順 | 特定作業の進め方 | SKILL.md |
| 別エージェントの定義 | 調査役、レビュー役、実装役など |
.codex/agents/*.toml、.claude/agents/*.md
|
常時読むファイルには、毎回必要なことだけを書きたいです。
たとえば、セットアップ、テストコマンド、コードスタイル、触ってはいけない設定。こういうものは、エージェントが毎回知っている方がよい情報です。
一方で、記事化手順、レビュー観点、リリース作業、長いチェックリストのようなものは、毎回読む必要はありません。必要な場面でだけ SKILL.md として読む方が、文脈が軽くなります。
やったこと
今回整理したかったのは、ファイル名ごとの暗記ではなく、実務で迷わない分類です。
私が意識したいのは、次の3つです。
- 常時ルールは、できるだけ
AGENTS.mdに寄せる - ツール固有ファイルは、共通ルールへの入口か、固有の補足だけにする
- 長い手順と専門ロールは、常時ルールから外に出す
つまり、AGENTS.md を正本にして、CLAUDE.md や GEMINI.md は必要ならそれを参照する。SKILL.md は作業手順、agents系ファイルは担当者定義として扱う。
補足：検討過程や却下案
最初に考えたのは、「全部 AGENTS.md に書けばいいのでは」という案でした。
でも、これはすぐ重くなります。レビュー手順、記事作成手順、リリース手順、媒体ごとの注意点まで全部入れると、毎回読むには情報が多すぎる状態になっている。
次に、ツールごとに完全に別ファイルで管理する案もあります。AGENTS.md、CLAUDE.md、GEMINI.md に同じようなルールをそれぞれ書く形です。
これも、最初は分かりやすいです。ただ、ルールを変えるたびに複数ファイルを直す必要があります。どこかだけ古くなる未来がかなり見えます。
最終的には、次のように考えるのがよさそうです。
| 目的 | Codex | Claude Code | Gemini CLI / Antigravity系 |
|---|---|---|---|
| 常に守るルール | AGENTS.md |
CLAUDE.md |
GEMINI.md |
| 共通ルールを横断運用する |
AGENTS.md を正本にする |
CLAUDE.md から AGENTS.md を参照する |
設定や取り込みで共通ファイルに寄せる |
| 必要時の手順を作る | SKILL.md |
.claude/skills/*/SKILL.md |
skills / workflows系 |
| 専門エージェントを作る | .codex/agents/*.toml |
.claude/agents/*.md |
.agents/agents.md など |
| ツール固有設定 | Codex config | .claude/settings.json |
.gemini/settings.json など |
公式ドキュメント上の細かい挙動も、この分類とだいたい相性がよいです。
- Codexは、グローバルやプロジェクト階層の
AGENTS.md系ファイルを読み、近い階層の指示ほど後に効く形で扱います。 - CodexのSkillsは、最初から全文を読むのではなく、名前・説明・パスを見て、必要になったときに
SKILL.md本文を読む設計です。 - Codexのcustom agentsは、個人用なら
~/.codex/agents/、プロジェクト用なら.codex/agents/にTOMLで置く形です。 - Claude Codeは、
CLAUDE.mdをメモリとして扱い、@pathで別ファイルを取り込めます。 - Claude Codeのsubagentsは、
.claude/agents/などにMarkdownファイルとして置きます。 - Gemini CLIは、標準では
GEMINI.mdをコンテキストとして扱い、設定で読み込むファイル名を変えられます。
このあたりを見ると、「常時読む入口」と「必要時に読む専門手順」を分ける考え方は、かなり現実的に使えます。
最終形
複数ツールを使うなら、まずは AGENTS.md を正本にするのが楽です。
おすすめ構成は、たとえばこうです。
repo/
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── .codex/
│ └── agents/
├── .claude/
│ ├── skills/
│ └── agents/
├── .agents/
│ └── skills/
└── src/
AGENTS.md には、プロジェクト共通のルールだけを書きます。
# AGENTS.md
## Setup
- 依存関係: `uv sync`
- 起動: `uv run app.py`
## Test
- `uv run pytest`
## Code style
- 既存の命名規則を優先する
- 型注釈を付ける
## Do not
- 本番設定を変更しない
- 秘密情報をログに出さない
CLAUDE.md は、共通ルールを読み込ませたうえで、Claude Code固有の補足だけにします。
@AGENTS.md
## Claude Code
Claude Code固有の補足だけをここに書く。
GEMINI.md も同じ考え方で、Gemini CLI / Antigravity系に必要な補足だけに寄せると管理しやすいです。
@AGENTS.md
## Gemini
Gemini系でだけ意識したい補足を書く。
長い手順は SKILL.md に分けます。
Codexのリポジトリ内Skillsなら .agents/skills、Claude Codeなら .claude/skills のように、ツールごとの置き場へ寄せます。
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
SKILL.md には「いつ使うか」「どう進めるか」だけを書く。長い仕様、サンプル、テンプレート、スクリプトは、references/ や scripts/ に逃がす方が読みやすいです。
役割を分けたいときは、agents系ファイルに寄せます。
name = "reviewer"
description = "Correctness, security, and test coverage focused reviewer."
developer_instructions = """
Review code like an owner.
Prioritize bugs, regressions, and missing tests.
"""
これは AGENTS.md とは別物です。
AGENTS.md は「このプロジェクトで守ること」。agents系ファイルは「誰にどんな役割を持たせるか」。ここを混ぜないのがポイントです。
補足：構成・手順・注意点
実務で使うなら、次の順番で整えると迷いにくいです。
- まず
AGENTS.mdに、全ツール共通のルールを書く -
CLAUDE.mdやGEMINI.mdには、共通ルールの参照と固有補足だけを書く - レビュー、記事化、リリースなどの長い手順は
SKILL.mdに分ける - レビュアー、調査役、実装役のような役割は agents系ファイルに分ける
- 迷ったら、「これは毎回読ませたいか？」で判断する
判断基準は、かなり単純でよいです。
| 判断したいこと | 置き場所 |
|---|---|
| 毎回守ってほしい | AGENTS.md |
| Claude Codeでだけ必要 | CLAUDE.md |
| Gemini CLIでだけ必要 | GEMINI.md |
| 特定作業の手順として使いたい | SKILL.md |
| 別人格・別担当として動かしたい | agents系ファイル |
私が一番大きかった気づきは、「ルール」と「手順」と「担当者」を同じファイルに置こうとすると、だんだん曖昧になるということです。
ルールは短く、手順は必要時だけ、担当者は別定義へ。これくらい割り切ると、AIにも人間にも読みやすくなります。
最後に
覚え方は、これでよさそうです。
常に守ることは
AGENTS.md
Claude固有はCLAUDE.md
Gemini系固有はGEMINI.md
手順化できるものはSKILL.md
役割分担は agents系ファイル
全部をひとつのファイルに詰め込むより、「常時読むもの」と「必要なときだけ読むもの」を分ける。
地味ですが、ここを分けるだけで、エージェントも人間もかなり扱いやすくなると思います。