AGENTS.md vs CLAUDE.md 完全決断ガイド -- どちらを選ぶかを決める判断フレームワーク（2026年版）

多くのデベロッパーはAGENTS.mdとCLAUDE.mdを同時期に知り、すぐに間違った問いを立てる。「どちらを使えばいいのか？」

この問いの立て方は、この2つのファイルが実際に何であるかを見誤っている。AGENTS.mdとCLAUDE.mdは重なる部分もあるが、根本的に異なる目的を持っている。正しい問いは「何を設定したいのか、誰のために、どんな制約のもとで」だ。

このガイドは基礎知識のある人向けに書いている。各ファイルの役割や構文は知っていて、どんな状況でどちらを選ぶか、判断の完全なフレームワークが欲しいという人に向けた内容だ。決断マトリクス、実際のリポジトリ構成のウォークスルー、双方向のマイグレーションパターン、両ファイル共存時の実際の動き、経験者でもハマる落とし穴、FAQまで網羅している。

入門的な比較から始めたい場合は AGENTS.md vs CLAUDE.md: 何が違うのか を先に読んでほしい。全体像を掴んだらここに戻ってきてほしい。

多くのデベロッパーが間違える問い

最も多い誤解は、AGENTS.mdとCLAUDE.mdを「どちらかを選ばなければならない競合する代替案」として捉えることだ。

実際、この選択はほぼ排他的にならない。問うべきことは「どちらを使うか」ではなく「それぞれに何を担当させるか」だ。AIの設定を真剣に考えているプロダクション環境では、最終的に両方のファイルを持つケースがほとんどだ。片方しかないリポジトリはたいていこのどちらかだ。

1. そのファイルの限界にまだぶつかっていない
2. 要件がシンプルで、1ファイルで十分に足りている

決断マトリクスを見る前に、各ファイルが根本的に何のために設計されているかを理解しておくと良い。設計意図がわかると、それぞれが何が得意かも自然と見えてくる。

それぞれのファイルが設計されている目的

AGENTS.md: 広さを取った設計

AGENTS.mdはSourcegraph、OpenAI、Google、Cursor、Factoryなどが共同で生み出し、現在はLinux Foundation傘下のAgentic AI Foundationが管理している。設計目標は相互運用性だ。どのAIコーディングエージェントでも読める1つのファイル、どの会社が作ったツールかは関係なく。

AGENTS.mdの仕様は意図的にミニマルだ。プレーンMarkdown、強制されるスキーマなし、検証ツールなし、コンパイルステップなし。このシンプルさが核心だ。Markdownを読めるモデルならAGENTS.mdを読める。独自フォーマットの知識は不要だ。

トレードオフは表現力だ。AGENTS.mdはすべてのツールで動く最小公分母に準じなければならないので、一部のツールしか持たない機能には依存できない。インポートシステムなし、パス指定のルールなし、ユーザーレベルの上書きなし、ツール固有の設定なし。広さは得られるが、深さは得られない。

AGENTS.mdが設計されている用途: どのAIエージェントでも知っておくべきプロジェクトレベルのコンテキスト、1か所に書いて1か所でメンテする。

CLAUDE.md: 深さを取った設計

CLAUDE.mdはAnthropicがClaude Code向けに用意したネイティブの設定フォーマットだ。標準仕様ではなく、Claude Codeの固有機能を前提に設計されたプロダクト機能だ。Anthropicはその周りに丸ごとシステムを作っている。階層型ファイル読み込み、複数ソースから構成する@import構文、.claude/rules/のパス指定ルール、ユーザーレベルのグローバルファイル、ローカル上書きファイル、セッション動作設定。

この深さにはコストが伴う。CLAUDE.mdはClaude専用だ。他のAIツールはこれを探さず、パースせず、使えない。しかしClaude Codeで動いているチームにとっては、AGENTS.mdとの表現力の差は相当大きい。

CLAUDE.mdが設計されている用途: Claude Codeの動作を細かく制御する。AGENTS.mdのオープン標準に相当するものがない、Claude固有の機能を活用する。

決断マトリクス

以下のマトリクスは選択が重要になる状況を網羅している。各シナリオで、どのファイルを選ぶべきか、その理由と合わせて示す。

マトリクスの読み方

マトリクスからいくつかのパターンが見えてくる。

AGENTS.mdはポータビリティで勝ち、CLAUDE.mdはパワーで勝つ。 AGENTS.mdが主な選択になるシナリオはすべて、複数ツールで動かす必要がある、またはポータビリティが実質タダになるほどシンプルな要件という状況に行き着く。CLAUDE.mdが主な選択になるシナリオはすべて、AGENTS.mdでは表現できない機能が必要になっている。

規模のあるチームは最終的に両方使うことになる。 「ツール混在チーム」と「サブエージェント委譲」の行が最も多いプロダクション状況だ。どちらの答えも単一のファイルではなく、何をどちらに書くかの意図的な分担になる。

一人開発者はAGENTS.mdを省略できる。 自分一人で、Claude Codeしか使わず、それを変える予定もないなら、AGENTS.mdはコストだけかかって旨みがない。CLAUDE.mdへの投資の方が賢い。

機能比較

実リポジトリのウォークスルーに入る前に、機能の全体比較をまとめる。何をどちらのファイルで表現できるかを判断するときに参照してほしい。

実リポジトリのウォークスルー

抽象的なルールも、実際のリポジトリ構成に当てはめると具体的になる。異なるプロジェクトタイプを代表する4つのウォークスルーを示す。

ウォークスルー1: 一人のClaude Code開発者（TypeScript SPA）

状況: Claude Codeだけを使うソロ開発者がReact/TypeScriptアプリを作っている。シンプルな要件。

推奨ファイル構成:

my-spa/
├── CLAUDE.md
├── CLAUDE.local.md          # gitignore対象、個人の開発プリファレンス
├── .claude/
│   └── rules/
│       └── component-rules.md   # src/components/ 向けのパス指定ルール
├── src/
│   ├── components/
│   ├── hooks/
│   └── lib/

CLAUDE.md の内容:

# my-spa

React 18 SPA using TypeScript, Vite, and React Query. State management via Zustand. Tests with Vitest + React Testing Library.

## Commands
- `pnpm dev` — start dev server at localhost:5173
- `pnpm test` — run Vitest in watch mode
- `pnpm test:run` — single-pass test run for CI
- `pnpm build` — production build to dist/
- `pnpm lint` — ESLint + Prettier check
- `pnpm typecheck` — tsc --noEmit

## Code Style
- TypeScript strict mode. No `any` except in test files.
- Functional components only. No class components.
- Named exports. No default exports except for route-level pages.
- Collocate tests: `Button.test.tsx` adjacent to `Button.tsx`.

## Project Structure
- `src/components/` — presentational, no data fetching
- `src/features/` — feature-specific components + hooks
- `src/hooks/` — shared custom hooks
- `src/lib/` — pure utility functions

## Conventions
- Use React Query for all server state. No manual fetch in components.
- Error boundaries at route level only.
- Form validation with react-hook-form + Zod.

See @.claude/rules/component-rules.md for component authoring rules.

.claude/rules/component-rules.md (src/components/** を編集するときのみ読み込まれる):

---
paths:
  - "src/components/**/*.tsx"
---

# Component Rules

- Export a typed `Props` interface above each component
- Accessibility first: all interactive elements need aria labels
- No inline styles — use CSS modules or Tailwind classes only
- Stories: create a `.stories.tsx` for any component that will appear in Storybook

なぜAGENTS.mdがないのか? この開発者はClaude Codeしか使わない。AGENTS.mdを追加しても、メンテするファイルが増えるだけでメリットがゼロだ。後でCursorを使うチームメンバーが加わったとき、それがAGENTS.mdを追加するタイミングになる。

ウォークスルー2: ツール混在チーム（バックエンドAPI）

状況: 5人チームがGo APIを作っている。2人はClaude Code、2人はCursor、1人はGitHub Copilotを使っている。全ツールで一貫したAI動作を実現したい。

推奨ファイル構成:

go-api/
├── AGENTS.md              # 共通ルール -- 全ツールが読む
├── CLAUDE.md              # Claude Code の追加設定のみ
├── .claude/
│   └── rules/
│       ├── api-handlers.md    # handlers/ ディレクトリ向けルール
│       └── db-migrations.md   # migrations/ ディレクトリ向けルール
├── cmd/
├── internal/
│   ├── handlers/
│   ├── models/
│   └── db/
├── migrations/
└── docs/
    ├── api-conventions.md
    └── testing-guide.md

AGENTS.md の内容:

# go-api

REST API for [product]. Go 1.22 + PostgreSQL 16 + Redis.

## Build & Run
```bash
go build ./cmd/api
./api --config=config.yaml

Testing

go test ./... -race                 # all tests
go test ./internal/handlers/... -v  # handler tests only
go test -run TestIntegration ./...  # integration only (requires running DB)

Linting

golangci-lint run

Code Conventions

• Error wrapping: fmt.Errorf("operation: %w", err) — always wrap
• Context first: all public functions accept context.Context as first argument
• Table-driven tests in _test.go files adjacent to source
• Exported functions: descriptive names. Unexported: short names fine.

Project Structure

• cmd/api/ — main entrypoint
• internal/handlers/ — HTTP handlers (one file per resource)
• internal/models/ — domain types and repository interfaces
• internal/db/ — concrete repository implementations
• migrations/ — SQL migration files (sequentially numbered)

Boundaries

• Never modify files in migrations/ without explicit discussion
• Do not add new external dependencies without creating a GitHub issue first
• All database queries go through repository interfaces, not direct DB access in handlers

**CLAUDE.md の内容（Claude Code の追加設定）:**

```markdown
# go-api — Claude Code Configuration

See @AGENTS.md for project conventions and coding standards.
See @docs/api-conventions.md for REST API design rules.
See @docs/testing-guide.md for test patterns and helper utilities.

## Claude-Specific Commands
- Run `go test ./... -race -coverprofile=coverage.out` before any commit touching business logic
- Use `dlv debug ./cmd/api` for debugging — breakpoints already configured in .vscode

## Session Rules
- When modifying a handler, always check the corresponding `_test.go` file
- Before adding any struct, check `internal/models/` for an existing type that covers the need
- API convention: check @docs/api-conventions.md before adding any new endpoint

## Permissions
- Read/write: all files in `internal/` and `cmd/`
- Read only: `migrations/` — flag for human review before modifying
- Avoid: `vendor/` unless explicitly asked

なぜこの分担なのか? AGENTS.mdはCursor、Copilot、Claude Codeすべてが必要とする共通ルールを担う。CLAUDE.mdは@importで詳細なAPIとテストのドキュメントを参照して重複を避け、Claude固有のコマンドを追加し、Claude Codeのみが理解するパーミッション境界を設定する。Cursorユーザーはその AGENTS.md のベースラインを、Claude Codeユーザーはそれに加えてより深い設定を得る。

ウォークスルー3: OSSライブラリ（Python）

状況: GitHubスター200以上のPythonデータ処理ライブラリ。コントリビューターはあらゆるツールを使う。メンテナーは全員が使えるAI設定が必要だ。

推奨ファイル構成:

dataprocessor/
├── AGENTS.md             # AIの設定ファイルはこれ1つ
├── src/
│   dataprocessor/
│       __init__.py
│       core.py
│       transforms/
│       io/
├── tests/
├── docs/
└── CONTRIBUTING.md

AGENTS.md の内容:

# dataprocessor

Python library for high-performance data transformation pipelines.
Supports Python 3.10+ and is tested on Linux, macOS, and Windows.

## Setup
```bash
pip install -e ".[dev]"

Testing

pytest                     # all tests
pytest tests/unit/         # unit tests only
pytest -x --tb=short       # stop on first failure

Type Checking

mypy src/

Formatting

ruff check .
ruff format .

Project Structure

• src/dataprocessor/core.py — public API surface. Do not add new public functions without discussion.
• src/dataprocessor/transforms/ — transformation implementations
• src/dataprocessor/io/ — input/output adapters (one file per format)
• tests/unit/ — unit tests
• tests/integration/ — integration tests (require test fixtures)

Contribution Rules

• All public functions must have type annotations and docstrings
• New features require both unit and integration tests
• Breaking changes to the public API require a deprecation notice in the previous release
• Performance-sensitive code: include a benchmark in tests/benchmarks/

Boundaries

• Never modify CHANGELOG.md directly — it is generated by the release process
• Do not add dependencies to pyproject.toml without opening an issue first

Code Style

• Follow existing patterns in the file you are modifying before applying general rules
• Prefer explicit over implicit — avoid magic where a clear function call works

**なぜCLAUDE.mdがないのか?** コントリビューターがどんなツールを使うかメンテナーにはコントロールできない。AGENTS.mdが最大のリーチを持つ。CLAUDE.mdを追加してもClaude Codeを使うメンテナーにしか恩恵がない。CursorやCopilotからPRを出すコントリビューターの助けにはならない。この場合、2ファイルをメンテするコストに見合う恩恵はない。

---

### ウォークスルー4: エンタープライズモノレポ（マルチチーム、混在スタック）

**状況:** Reactフロントエンド、Goマイクロサービス、Python MLパイプライン、IaCにまたがる40以上のパッケージを持つモノレポ。複数チーム、一部はClaude Codeに統一済み。パッケージによってルールが異なる複雑な要件。

**推奨ファイル構成:**

monorepo/ ├── AGENTS.md # 共通ルート規約 ├── CLAUDE.md # ルートClaude設定 + インポート ├── .claude/ │ └── rules/ │ ├── infra-rules.md # infra/ ツリー向けルール │ └── ml-pipeline-rules.md # packages/ml-*/ 向けルール ├── packages/ │ ├── api-gateway/ │ │ ├── AGENTS.md # Gateway固有の共通ルール │ │ └── CLAUDE.md # Gateway向けClaude追加設定 │ ├── auth-service/ │ │ ├── AGENTS.md │ │ └── CLAUDE.md │ ├── ml-feature-store/ │ │ └── AGENTS.md # MLチームはツールが多様、CLAUDE.mdなし │ └── web-dashboard/ │ └── CLAUDE.md # フロントエンドチームは全員Claude Code ├── infra/ │ ├── AGENTS.md │ └── terraform/ └── docs/ ├── architecture.md ├── api-standards.md └── security-policy.md

**ルートAGENTS.md（抜粋）:**

```markdown
# Monorepo

Multi-team monorepo. Technologies vary by package — check the package-level AGENTS.md for package-specific rules.

## Workspace Commands
```bash
pnpm install                     # install all dependencies
pnpm build --filter=<package>    # build specific package
pnpm test --filter=<package>     # test specific package
pnpm lint                        # lint entire monorepo

Universal Conventions

• Semantic versioning for all packages
• Conventional commits (feat:/fix:/chore: prefixes)
• All cross-package API changes require a migration guide in docs/migrations/

Boundaries (universal)

• Never modify the root pnpm-workspace.yaml without team discussion
• External dependency additions require approval from package owner
• Secrets and credentials: see docs/security-policy.md

Finding Package-Specific Rules

Check the AGENTS.md (any tool) or CLAUDE.md (Claude Code) in the package directory.

**ルートCLAUDE.md（抜粋）:**

```markdown
# Monorepo — Claude Code Configuration

See @AGENTS.md for universal conventions.
See @docs/architecture.md for system architecture and decision records.
See @docs/api-standards.md for cross-service API conventions.

## Scope
When working in a specific package, prefer package-level AGENTS.md and CLAUDE.md for detailed rules. The root files apply everywhere as a baseline.

## Session Rules
- Before cross-package changes, check `docs/migrations/` for existing migration patterns
- API-breaking changes: flag for human review regardless of permissions

See @.claude/rules/infra-rules.md for infrastructure-specific rules.
See @.claude/rules/ml-pipeline-rules.md for ML pipeline rules.

エンタープライズモノレポのパターンは、なぜどちらか一方のファイルだけではスケールしないかを示している。ルートとパッケージレベルのAGENTS.mdで全AIツールに一貫したベースライン動作を与える。CLAUDE.mdはその上にClaude固有の深みを重ねる。Claude Codeに統一していないチーム（この例のMLチームなど）はCLAUDE.mdを使わない。AGENTS.mdのベースラインだけを受け取る。

マイグレーションパターン

パターン1: 既存のAGENTS.mdセットアップにCLAUDE.mdを追加する

最も多いマイグレーションパターンだ。互換性のためにAGENTS.mdから始め、チームがClaude Codeに収束し、より深い機能セットを使いたくなった場合。

ステップ1: AGENTS.mdをインポートするCLAUDE.mdを作る

# CLAUDE.md

See @AGENTS.md for project conventions, commands, and coding standards.

## Claude-Specific Rules
(add below)

@importから始めることで内容が重複しない。Claude Codeは両方を読み、他のツールは引き続きAGENTS.mdだけを読む。

ステップ2: Claude固有のコンテンツをCLAUDE.mdに移す

AGENTS.mdを見直し、Claude固有のものを探す。パーミッションレベル、セッション動作、サブエージェント委譲パターンなど、他のツールに恩恵がないものだ。それらをCLAUDE.mdに移す。

ステップ3: パス指定ルールとして.claude/rules/を追加する

複雑で条件付きのルールが必要なコードベースの領域を特定する。たとえば「APIハンドラーは入力バリデーションが必要」「テストファイルは本番DBクライアントをインポートしてはいけない」といった内容だ。これらがパス指定ルールになる。

---
paths:
  - "src/api/**/*.ts"
---

# API Handler Rules

All handlers must validate input with Zod before processing.
Return standardized error objects from `src/lib/errors.ts`.

ステップ4: 個人の上書きをセットアップする

CLAUDE.local.mdを.gitignoreに追加し、個人ファイルを作る。

# CLAUDE.local.md (コミットしない)

## Local Environment
- Dev database: postgresql://localhost:5432/myapp_dev
- Use `pnpm dev:debug` to start with verbose logging

## Personal Preferences
- When writing tests, use `describe`/`it` style over standalone `test`

やってはいけないこと: AGENTS.mdの内容をすべてCLAUDE.mdにコピーして修正するやり方だ。内容が重複し、場合によっては矛盾し、どちらもメンテしなければならない状況になる。

パターン2: 既存のCLAUDE.mdセットアップにAGENTS.mdを追加する

詳細なルールを持つ成熟したCLAUDE.mdがある。チームが大きくなり、新しいコントリビューターが異なるツールを使う、またはプロジェクトをOSS化する。全員のAI設定が欲しい。

ステップ1: CLAUDE.mdのポータブルなコンテンツを監査する

CLAUDE.mdの各セクションにタグをつける。

• ユニバーサル — 任意のAIツールに適用できる（コードスタイル、コマンド、プロジェクト構成、境界）
• Claude固有 — CLAUDE.mdの機能を使う、またはClaudeの機能を参照する

ステップ2: ユニバーサルなコンテンツをAGENTS.mdに抽出する

# AGENTS.md

(プロジェクト概要、共通コードスタイル、コマンド、境界)

このファイルはできるだけツール非依存にする。Claudeの機能、パーミッション、セッション動作への言及は入れない。

ステップ3: CLAUDE.mdをClaude固有の追加設定だけに絞る

# CLAUDE.md

See @AGENTS.md for project conventions.

## Claude-Specific Configuration
(インポート、パス指定ルール、パーミッション、セッション動作)

ステップ4: 別のツールでテストする

CursorやCopilotでAGENTS.mdに対してテストし、期待通りの動作を確認する。これにより、AGENTS.mdにClaude固有の前提を残してしまったケースを発見できる。

このマイグレーション中に壊れるもの: Claudeの会話動作を参照したり、Claude固有の言い回しを使ったりしていた指示（「Claudeが確認を求めたら…」など）はAGENTS.mdにきれいには移行できない。ツール非依存の動作指示として書き直す必要がある。

パターン3: .cursorrulesから両方へ

Cursorの旧フォーマットである.cursorrulesから、新しいAGENTS.md標準（オプションでCLAUDE.md追加）に移行する場合。

ステップ1: .cursorrulesのポータブルなコンテンツからAGENTS.mdを作る

.cursorrulesファイルのほとんどには、プロジェクト説明、コードスタイルルール、推奨ライブラリ、命名規則、境界が含まれている。これらはすべてAGENTS.mdに直接移行できる。Markdownのヘッダーで整理して明確にする。

ステップ2: CLAUDE.mdを作る（Claude Codeを使う場合）

# CLAUDE.md

See @AGENTS.md for project conventions.
(Claude固有のルールを以下に追加)

ステップ3: Cursorチームのために.cursorrulesを残す（または移行する）

最近のCursorはAGENTS.mdをネイティブサポートしている。チームのCursorバージョンを確認しよう。全員が0.44以上なら.cursorrulesを削除してCursorでもAGENTS.mdを使える。古いバージョンのユーザーがいる場合は移行期間中は両方を残す。

ステップ4: .cursorrulesはすぐに削除しない

1スプリント待つ。Cursorの動作が変わったという報告がなければ.cursorrulesを削除する。段階的な移行で、本当の損失が出る前に問題を発見できる。

共存パターン: 実行時に何が起きるか

同じリポジトリに両方のファイルがある場合、AIツールが読み込んだときに実際に何が起きるのか。

Claude Codeの場合:

Claude Codeは両方のファイルを読む。動作は加算式で、競合を解決する問題ではない。セッション開始時、Claudeは以下を読み込む。

1. 組織レベルのマネージドポリシー（設定されている場合）
2. ユーザーグローバルの~/.claude/CLAUDE.md
3. プロジェクトルートのCLAUDE.md
4. 現在の作業コンテキストに関連するサブディレクトリのCLAUDE.mdファイル
5. 適用可能な.claude/rules/*.mdファイル（パスマッチに基づく）
6. CLAUDE.local.md（個人の上書き、コミットされない）

AGENTS.mdはCLAUDE.mdが@importで参照できるファイルの1つだが、Claude CodeはAGENTS.mdを自動的にマージしない。CLAUDE.mdをプライマリソースとして読む。CLAUDE.mdにSee @AGENTS.md for coding standardsと書いてあれば、Claudeはその参照を辿って内容を取り込む。CLAUDE.mdがAGENTS.mdを参照していなければ、Claude CodeがAGENTS.mdを読むかどうかはバージョンによって異なる。

実際的な結論: 両方のファイルがある場合、CLAUDE.mdにSee @AGENTS.md for project conventionsを追加する。関係性を明示することで、Claudeが確実に両方を読む。

Cursor、GitHub Copilot、Gemini CLI、その他のAGENTS.md対応ツールの場合:

これらのツールはAGENTS.mdを読む。CLAUDE.mdは読まない（一部のツールはリポジトリ内の任意のMarkdownをパースするが、CLAUDE.mdを理解するわけではない）。これらのツールの観点からは、CLAUDE.mdは存在しないのと同じだ。

両方の標準をサポートするツールの場合（新興）:

一部の新しいツールはAGENTS.mdとCLAUDE.mdの両方を設定ソースとしてサポートし始めている。こうしたツールでの動作はさまざまで、優先ルールはツールのドキュメントを確認してほしい。迷ったら、AGENTS.mdはクロスツールのルール、CLAUDE.mdは特定ツールのネイティブ機能向けと考えればいい。

実行時の競合解決:

AGENTS.mdとCLAUDE.mdに矛盾する指示がある場合はどうなるか。Claude Codeの場合、CLAUDE.mdが勝つ。これがネイティブフォーマットだ。CLAUDE.mdに「タブを使う」、AGENTS.mdに「スペースを使う」と書いてあれば、Claude Codeはタブを使う。これが、同じ指示を両方のファイルに書いてはいけない理由でもある。重複するとメンテナンスコストが増え、競合が生まれる余地が増える。

最もクリーンな実行時セットアップは、CLAUDE.mdはClaude固有のルールを担い、See @AGENTS.mdのインポートで共通ルールを参照する形だ。重複なし、競合なし。

よくある落とし穴

落とし穴1: 両ファイルにコンテンツを重複させる

どんな状態か:

# AGENTS.md
- Use 2-space indentation
- Single quotes for strings

# CLAUDE.md
- Use 2-space indentation
- Single quotes for strings

なぜ問題か: スタイル規約を変更するとき、2つのファイルを更新しなければならない。1つ忘れると、ファイルが矛盾する。時間が経つにつれてファイルはどんどん食い違っていく。

対策: 共有コンテンツはCLAUDE.mdでAGENTS.mdをインポートし、Claude固有のルールだけをCLAUDE.mdに追加する。共通ルールは1か所だけに書く。

落とし穴2: Claude固有の機能をAGENTS.mdに入れる

どんな状態か:

# AGENTS.md
## Claude Configuration
- Use plan mode before any file modifications
- Request approval before deleting files

なぜ問題か: AGENTS.mdを読む他のツールが解釈できない指示に出くわす。最悪の場合、その指示がモデルを混乱させる。Claude固有の機能はクロスツール設定ファイルに入れるべきでない。

対策: AGENTS.mdにはどのAIツールでも理解して従える指示だけを入れる。Claude固有の動作はCLAUDE.mdに入れる。

落とし穴3: 大きなファイルをサブディレクトリのAGENTS.mdやパスルールで分割しない

どんな状態か: モノレポの全パッケージを網羅する600行のルートAGENTS.md。パッケージごと、技術ごと、チームの規約ごとにセクションがある。

なぜ問題か: 大きなファイルはコンテキストを無駄にする。フロントエンドのコンポーネントを編集しているAIがデータベースのマイグレーション規約を知る必要はない。無関係なルールのロードに費やすトークンは、実際のタスクに使えないトークンだ。一部のツールにはAGENTS.mdのファイルサイズの上限もある。

対策: AGENTS.mdはパッケージ固有のルールをサブディレクトリのAGENTS.mdに分割する。最近接のAGENTS.mdが優先される。CLAUDE.mdは.claude/rules/*.mdにパスマッチャーを使い、関連するときだけルールが読み込まれるようにする。

落とし穴4: テストできない曖昧な指示を書く

どんな状態か:

Write clean, well-structured code that follows best practices.

なぜ問題か: 「クリーン」「整理されている」の意味は開発者によっても、AIモデルによっても異なる。この指示は動作を実際には変えない。モデルはもともと良いコードを書こうとしている。伝えたいのは、あなたのコードベースで「良い」が何を意味するかだ。

対策: 抽象的な指示を、具体的で検証可能なものに置き換える。

- Organize utility functions by domain in src/lib/: auth.ts, api.ts, formatting.ts
- No function longer than 50 lines — extract helpers instead
- All error-handling paths must log the error before returning

これはテストできる指示だ。関数が50行を超えているか、エラー前にログを出しているかは確認できる。

落とし穴5: CLAUDE.local.mdを.gitignoreに追加し忘れる

どんな状態か: 開発者がローカルのデータベース認証情報と個人のパス上書きを含むCLAUDE.local.mdをコミットしてしまう。

なぜ問題か: バージョン管理に認証情報が入ることはセキュリティ問題だ。個人の設定をチームと共有することで摩擦が生まれる。このファイルはローカルに留まるよう設計されている。

対策: 最初からCLAUDE.local.mdを.gitignoreに追加する。テンプレートを用意する場合はCLAUDE.local.md.exampleをリポジトリに入れて出発点にする。

# Claude Code personal overrides
CLAUDE.local.md

落とし穴6: ファイルの読者ではなく、目の前のAIに向けて指示を書く

どんな状態か:

# AGENTS.md
Claude, please remember to...

なぜ問題か: AGENTS.mdは複数のツールが読む。「Claude」という名前で呼びかけると、Claudeでないツールが混乱する。またその指示がClaude固有であることを示唆する。それなら、AGENTS.mdに入れるべきでない。

対策: AGENTS.mdの指示は命令形で、特定のツールに向けて書かない。

# AGENTS.md（良い例）
- Run the full test suite before committing
- Do not modify generated files in dist/

# CLAUDE.md（Claude固有でも問題なし）
- When asked to refactor, use plan mode first to outline changes

落とし穴7: AGENTS.mdを静的なドキュメントとして扱う

どんな状態か: プロジェクト作成時にAGENTS.mdをセットアップし、その後一切更新しない。

なぜ問題か: プロジェクトは変わる。コマンドが変わり、新しいパッケージが追加され、規約が変わる。古くなったAGENTS.mdはないよりも悪い。AIが古くなった指示に従い、現在のコードベースと合わない出力を生む。

対策: AGENTS.mdをPRレビューのプロセスに組み込む。コマンドを変更した、パッケージを追加した、規約を変えた、プロジェクト構成が変わったPRはAGENTS.mdの更新を含めるべきだ。PRテンプレートにリマインダーを追加する。

## Checklist
- [ ] Updated AGENTS.md if commands or conventions changed
- [ ] Updated CLAUDE.md if Claude-specific rules changed

FAQ

Q: チームがCursorとClaude Codeの両方を使っている場合、どちらのファイルが優先されますか?

A: 優先の競合は起きない。各ツールが自分のファイルを読む。CursorはAGENTS.mdを読む。Claude CodeはCLAUDE.mdを読む（そして@import経由でAGENTS.mdも参照できる）。2つのファイルは競合しない。異なるツールにサービスを提供している。優先度が問題になるのは、Claude Code自身の階層システムの中だけだ。サブディレクトリのCLAUDE.mdがルートを上書きし、.local.mdがコミット済みファイルを上書きする。

Q: CLAUDE.mdはAGENTS.mdを完全に置き換えられますか?

A: Claude Code内での自分の用途としては、CLAUDE.mdはネイティブフォーマットでAGENTS.mdのすべてに加えてより多くをカバーするので、代替になる。しかしCLAUDE.mdは他のツールのAGENTS.mdを置き換えられない。Cursor、Copilot、Gemini CLI、Aider、その他は基本的にCLAUDE.mdを読まない。チームやコントリビューターの中にClaude Code以外のツールを使う人が1人でもいる場合、AGENTS.mdがなければその人たちは設定を得られない。

Q: 各ファイルの推奨される最大サイズは?

A: 公式の上限はないが、パフォーマンスと信頼性に基づいた実践的なガイドラインがある。

• AGENTS.mdのルート: 400〜500トークンがコミュニティの最適点だ。1,000トークンを超えると、一部のツールが後半のセクションを切り捨てるか優先度を下げ始める。2,500のリアルAGENTS.mdファイルのGitHub分析では中央値が340トークンだった。
• CLAUDE.mdのルート: Claude Codeは200Kトークンのコンテキストウィンドウを持ち、大きなファイルも扱える。しかしそれをすべて使うべきという意味ではない。典型的なプロジェクトでは読み込まれる設定の合計（ルート + サブディレクトリ + インポートファイル）を5,000トークン以下に抑えることを目指してほしい。パス指定ルールを使ってコンテキストを関連するものに絞る。

Q: AGENTS.mdはClaude Codeのサブエージェント機能と連携しますか?

A: 連携する。そしてこれがClaude Code内でのAGENTS.mdの最も強力な機能の一つだ。AGENTS.mdにエージェントエントリー形式のヘッダーを使ってサブエージェントを定義する。

## code-reviewer
description: Reviews code changes for correctness, security, and style consistency.
             Invoke before committing or creating a pull request.
tools: read, bash
model: claude-sonnet-4-5

Claude Codeはこれらのエントリーを読み込み、定義されたサブエージェントに委譲できる。CLAUDE.mdには委譲するタイミングの指示を書ける。

# CLAUDE.md

## Sub-agent Delegation
- Before committing any change touching authentication logic, invoke `code-reviewer`
- For large refactors (>200 lines), break into tasks and use parallel sub-agents

これが両ファイルが本当に必要になるメインケースだ。AGENTS.mdがエージェントを定義し、CLAUDE.mdがオーケストレーションする。

Q: .github/copilot-instructions.mdにはAGENTS.mdとCLAUDE.mdのどちらを使うべきですか?

A: どちらでもない。.github/copilot-instructions.mdはGitHub Copilot独自の設定フォーマットで、AGENTS.mdとCLAUDE.mdの両方とは別物だ。Copilotを使う場合、3つのファイルすべてが必要になるかもしれない。

• AGENTS.md — 共通のプロジェクトコンテキスト
• .github/copilot-instructions.md — Copilot固有の指示
• CLAUDE.md — Claude Code固有の指示

ただし多くのチームは、AGENTS.mdをプライマリソースとしてCopilot固有の追加設定は最小限にする方向で集約している。2026年はCopilotでのAGENTS.mdサポートが大幅に改善されたためだ。

Q: CLAUDE.mdしかなくて誰かがCursorを使ったら何が起きますか?

A: CursorはデフォルトではCLAUDE.mdを読まない。CLAUDE.mdしかないプロジェクトでCursorを使うコントリビューターは、リポジトリからAIの設定を一切得られない。AIはコードそのものからすべてを推測しなければならない。これが複数のコントリビューターがいるプロジェクトでAGENTS.mdを維持する最も強い理由の一つだ。

Q: AGENTS.mdが特定のツールで実際に読まれているか確認する方法は?

A: 万能な方法はないが、主要なツールで有効なアプローチがある。

• Claude Code: AGENTS.mdに特徴的な指示を追加する（例: 「何かをする前に、これからやることを簡潔に要約してから実行してほしい」）。セッションを開始してClaudeが従うか確認する。
• Cursor: Cursorの「Context」パネルで読み込まれているファイルを確認する。AGENTS.mdが表示されていれば読まれている。
• GitHub Copilot: 現在のバージョンのAGENTS.mdサポートをCopilotのドキュメントで確認する。2026年時点でサポートは存在するが、機能によって深さが異なる。
• Gemini CLI: gemini --helpでコンテキスト読み込みのドキュメントを探す。Gemini CLIはプロジェクトルートからAGENTS.mdを読む。

Q: AGENTS.mdをCLAUDE.mdとして使えますか?

A: 技術的には、ユニバーサルなコンテンツとClaude固有のセクションの両方を含むAGENTS.mdというファイルを書き、CLAUDE.mdとしてシンリンクすることはできる。一部のチームがこれをやって単一ファイルを維持している。トレードオフは、Claude固有のセクションがAGENTS.mdを読む他のツールを混乱させること、CLAUDE.mdのインポートシステムとパス指定ルールが使えないこと、ファイルがメンテしにくいほど大きくなる傾向があることだ。よほどシンプルなセットアップでない限り、ファイルを分けるアプローチの方がクリーンだ。

まとめ

AGENTS.md vs CLAUDE.mdの決断は3つの問いに行き着く。

1. 設定を誰が読むか?

• Claude Codeのみ → CLAUDE.mdで十分
• 複数のツール → AGENTS.mdが必要。Claude固有の深みのためにCLAUDE.mdを追加

2. どんな機能が必要か?

• インポート、パス指定ルール、ローカル上書き、パーミッション → CLAUDE.md
• シンプルなコードスタイル、コマンド、境界 → AGENTS.mdで十分

3. チームのツールはどこへ向かっているか?

• Claude Codeに統一していく → CLAUDE.mdの機能に投資
• ツール混在または不確実 → AGENTS.mdのポータビリティに投資

AIの設定を真剣に考えるほとんどのチームにとっての答えは、共通のベースラインをカバーするAGENTS.mdから始め、表現できない機能が必要になったらCLAUDE.mdを追加し、@importで重複なく同期させることだ。

この構成は5人から50人にスケールし、設定を書き直さずに新しいAIツールを追加でき、CLAUDE.md のフル機能を諦めずに誰もが恩恵を受けられる。

関連記事

• AGENTS.md vs CLAUDE.md: 何が違うのか（2026年版） — このガイドが前提とする基礎比較
• 効果的なCLAUDE.mdの書き方 — Claudeが本当に従う指示の書き方
• モノレポでのAGENTS.md: パッケージごとの指示管理 — モノレポのウォークスルーをさらに深掘り
• CLAUDE.mdルール一覧 — OSSプロジェクトの実際のCLAUDE.mdファイル
• AGENTS.mdルール一覧 — プロダクションリポジトリの実際のAGENTS.mdファイル