コーディングエージェントの設定ファイル整理

Codex、Claude Code、GitHub Copilot などのコーディングエージェントは、どれも「リポジトリ固有の作法」を読ませる仕組みを持っている。ただし、ファイル名や探索ルールはツールごとに違う。2026-05-04時点での実用的な整理としては、共通の中核を AGENTS.md に置き、各ツール固有のファイルからそこへ接続するのが扱いやすそう。

まず結論

完全に全ツール共通の設定仕様があるわけではない。ただし、AGENTS.md は「エージェント向けREADME」のようなオープンなMarkdown形式として広がっている。公式サイトでも、READMEは人間向け、AGENTS.md はエージェント向けの詳しい作業手順やテスト方法を置く場所として説明されている。

現時点のおすすめは次の形。

AGENTS.md                         # 共通の作業ルール
CLAUDE.md                         # Claude Code 用。AGENTS.md を import
.github/copilot-instructions.md   # Copilot Chat / Code Review 用
.github/instructions/*.instructions.md
.claude/rules/*.md                # Claude Code のパス別ルール

AGENTS.md を正にしておけば、CodexやCopilotのエージェント機能ではそのまま使いやすい。一方で、Claude Codeは CLAUDE.md を読む設計なので、CLAUDE.md から AGENTS.md をimportするのがよい。

AGENTS.md

AGENTS.md は、コーディングエージェントにプロジェクト固有の文脈を渡すためのMarkdownファイル。必須フィールドはなく、普通のMarkdownとして書ける。

入れる内容は、たとえば次のようなもの。

• セットアップコマンド
• 開発サーバーの起動方法
• テスト、lint、buildコマンド
• コードスタイル
• PRやコミットのルール
• セキュリティ上の注意
• 大きなデータや生成物の扱い

大きなモノレポでは、サブディレクトリごとに AGENTS.md を置く運用も想定されている。より近い場所の指示が優先される、という考え方だ。

Agent Skills

SKILL.md にも、Agent Skills というオープン標準がある。これは AGENTS.md が「リポジトリ全体の作業ルール」を置く場所なのに対して、特定タスクの手順や専門知識を再利用できる単位としてパッケージ化するもの。

最小構成は、スキル用ディレクトリと SKILL.md。

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

標準仕様では、SKILL.md はYAML frontmatterとMarkdown本文で構成される。name と description が必須で、license、compatibility、metadata、allowed-tools などを任意で追加できる。

---
name: article-writer
description: Research Hubの記事を作成する。記事テンプレート、画像配置、Markdown記法に従う必要があるときに使う。
---

## Workflow

1. `notes/article-template.md` を確認する
2. `notes/markdown-guide.md` を確認する
3. `src/content/daily/YYYY-MM-DD/{slug}.md` に記事を書く
4. 必要な画像を `public/images/daily/YYYY-MM-DD/{slug}/` に置く
5. `npm run build` を実行する

Agent Skills のポイントは progressive disclosure だ。エージェントは最初から全スキル本文を読むのではなく、起動時には name と description だけを見て、必要になったときに SKILL.md 本文や関連ファイルを読む。長い手順や参照資料を常時コンテキストに入れずに済む。

この意味で、使い分けはこうなる。

AGENTS.md
  いつも守るルール。
  例: ビルドコマンド、ディレクトリ構成、テスト方針、禁止事項。

SKILL.md
  必要なときだけ呼び出す手順。
  例: 記事作成、リリース作業、調査レポート作成、レビュー手順。

Claude Codeのdocsでは、Claude Code skills は Agent Skills open standard に従い、さらに呼び出し制御、サブエージェント実行、動的コンテキスト注入などを拡張していると説明されている。Codexのdocsでも、スキルは SKILL.md と任意の scripts/、references/、assets/ を持つディレクトリとして説明されており、同じ設計思想で使える。

Codex

Codex は AGENTS.md を明示的に読む。OpenAIのCodex docsでは、Codexは作業前に AGENTS.md を読み、グローバル指示とプロジェクト指示を重ねると説明されている。

主な探索ルールは次の通り。

• グローバル: ~/.codex/AGENTS.md
• 一時的な上書き: ~/.codex/AGENTS.override.md
• リポジトリ: AGENTS.md
• サブディレクトリ: より近い AGENTS.md または AGENTS.override.md
• project_doc_fallback_filenames で別名も追加できる

Codexは、ルートから現在の作業ディレクトリまでの指示を結合する。より深い場所の指示が後ろに来るため、実質的に近い指示が強くなる。

Codexには SKILL.md ベースのスキルもある。これは常時読む大きなルールというより、再利用できるワークフローを必要なときだけ読み込む仕組み。Codexの公式docsでは、スキルは SKILL.md と任意の scripts/、references/、assets/ などを持つディレクトリとして説明されている。

Claude Code

Claude Code の中心は CLAUDE.md。公式docsでは、プロジェクト、ユーザー、組織、ローカルなど複数スコープの CLAUDE.md が説明されている。

よく使う場所は次の通り。

./CLAUDE.md
./.claude/CLAUDE.md
./CLAUDE.local.md
~/.claude/CLAUDE.md
.claude/rules/*.md

Claude Code は AGENTS.md を直接読むのではなく、CLAUDE.md を読む。公式docsでは、既に AGENTS.md を使っているリポジトリでは CLAUDE.md に @AGENTS.md と書いてimportする方法が紹介されている。

@AGENTS.md

## Claude Code

- 大きな変更では先に計画を出す
- 課金や認証まわりは必ずテスト方針を確認する

また、Claude Codeには .claude/rules/ によるルール分割がある。frontmatterで paths を指定すれば、特定のファイルやディレクトリにだけ適用するルールを書ける。長い CLAUDE.md を1枚に育てるより、共通ルールとパス別ルールに分けた方が保守しやすい。

Claude Codeにも SKILL.md ベースのスキルがある。これは毎回読む恒久ルールではなく、特定作業の手順、参照資料、スクリプトをまとめる用途に向いている。

GitHub Copilot

GitHub Copilot は用途によって複数の指示ファイルを使う。

.github/copilot-instructions.md
.github/instructions/NAME.instructions.md
AGENTS.md
CLAUDE.md
GEMINI.md

GitHub Docsでは、リポジトリ全体のカスタム指示は .github/copilot-instructions.md に書くと説明されている。パス別の指示は .github/instructions/NAME.instructions.md に置き、frontmatterの applyTo で対象パスを指定する。

---
applyTo: "**/*.ts,**/*.tsx"
---

- Reactコンポーネントは既存のUIパターンに合わせる
- 変更後は `npm run build` を確認する

Copilotのdocsでは、AIエージェント向けの指示として AGENTS.md も扱われている。AGENTS.md はリポジトリ内の任意の場所に置け、Copilotが作業するときはディレクトリツリー上で最も近いものが優先される。また、ルートの CLAUDE.md や GEMINI.md も代替として使えると説明されている。

注意点は、Copilot Chat、Copilot Code Review、Copilot cloud agentで、どの指示がどこまで使われるかが異なること。GitHub Docsでも、複数タイプの指示ファイルがあり、機能ごとに対応が分かれている。実務では .github/copilot-instructions.md をCopilot Chat/Review向けに置きつつ、エージェント横断の共通ルールは AGENTS.md に寄せるのが無難。

運用案

自分のリポジトリで複数エージェントを使うなら、次の分担がよさそう。

AGENTS.md
  全ツール共通の事実を書く。
  セットアップ、ビルド、テスト、ディレクトリ構成、記事追加ルールなど。

CLAUDE.md
  @AGENTS.md で共通ルールを読み込む。
  Claude Code固有の振る舞いだけ追記する。

.github/copilot-instructions.md
  Copilot ChatやCode Review向けに短く書く。
  AGENTS.mdと内容がズレないよう、要点だけにする。

.github/instructions/*.instructions.md
  TypeScript、Astro、Markdownなど、パス別に効かせたいルールを書く。

.claude/rules/*.md
  Claude Codeだけに効かせたいパス別ルールを書く。

重要なのは、同じことを何枚にも重複して書きすぎないこと。指示ファイルは増えるほど矛盾しやすい。まず AGENTS.md を共通の正本にして、各ツール固有ファイルは「読み込み」「補足」「機能差分」だけにするのがよい。

Research Hub で作るなら

このサイトの場合は、まず次の3つがあれば十分。

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

AGENTS.md には、Astro構成、記事ファイルの置き方、画像ディレクトリ、npm run build、Cloudflare Pagesの設定を書く。CLAUDE.md は @AGENTS.md をimportし、Claude Code固有の補足だけを書く。Copilot用には .github/copilot-instructions.md に「記事を追加するときは notes/article-template.md と notes/markdown-guide.md を参照する」くらいの短い指示を書く。

次に足すなら、記事作成用のスキルを作る。

.codex/skills/article-writer/SKILL.md
.claude/skills/article-writer/SKILL.md

中身は同じAgent Skills形式をベースにして、ツール固有の拡張が必要になったらそれぞれに追記する。共通化したい場合は、まず skills/article-writer/SKILL.md のような中立ディレクトリに置き、各ツールの探索場所へコピーまたはシンボリックリンクする運用も考えられる。

参考リンク

• AGENTS.md
• Agent Skills
• Agent Skills Specification
• OpenAI Codex: Custom instructions with AGENTS.md
• OpenAI Codex: Agent Skills
• Claude Code: How Claude remembers your project
• Claude Code: Extend Claude with skills
• GitHub Docs: Adding repository custom instructions for GitHub Copilot