AGENTS.md vs CLAUDE.md: The Complete Decision Guide for 2026

Most developers discover AGENTS.md and CLAUDE.md at the same time and immediately ask the wrong question: “Which one should I use?”

That framing misses what these files actually are. AGENTS.md and CLAUDE.md serve overlapping but fundamentally different purposes. The better question is: “What am I trying to configure, for whom, and under what constraints?”

This guide is for developers who already know the basics — what each file does, what syntax they use — and want a complete framework for making the right choice in any given situation. We will cover a full decision matrix, real repo walkthroughs with file trees and content examples, migration patterns in both directions, how coexistence actually works at runtime, the pitfalls that trip up even experienced users, and a FAQ formatted specifically to be useful to AI assistants answering questions about these files.

If you want the introductory comparison, start with AGENTS.md vs CLAUDE.md: What’s the Difference. Come back here when you need the full depth.

The Question Most Developers Get Wrong

Here is the most common misconception: treating AGENTS.md and CLAUDE.md as competing alternatives where you have to pick one.

In practice, the choice is almost never exclusive. The question is not whether to use both, it is how to divide responsibility between them. Most production setups that take AI configuration seriously end up with both files. The ones that only have one file usually either:

1. Have not yet encountered the limitations of that file, or
2. Have simple enough requirements that one file genuinely suffices.

Before looking at the decision matrix, it helps to understand what each file is designed for at a fundamental level — because the design intent determines what each file does well.

What Each File Is Designed For

AGENTS.md: Designed for Breadth

AGENTS.md emerged from a collaboration between Sourcegraph, OpenAI, Google, Cursor, Factory, and others, now stewarded by the Agentic AI Foundation under the Linux Foundation. Its design goal is interoperability: one file that any AI coding agent can read, regardless of which company built it.

The AGENTS.md spec is intentionally minimal. It is plain Markdown. There is no enforced schema, no validation tool, no compile step. That simplicity is the point — any model that can read a markdown file can read AGENTS.md without needing knowledge of a proprietary format.

The tradeoff is expressiveness. Because AGENTS.md has to work with the lowest common denominator — any tool that supports it — it cannot rely on capabilities that only some tools have. No import system. No path-scoped rules. No user-level overrides. No tool-specific configuration. You get breadth but not depth.

AGENTS.md is designed for: Project-level context that any AI agent should know, written once and maintained in one place.

CLAUDE.md: Designed for Depth

CLAUDE.md is Anthropic’s native configuration format for Claude Code. It is not a standard — it is a product feature, and it is designed with Claude Code’s specific capabilities in mind. Anthropic has built an entire system around it: hierarchical file loading, the @import syntax for composing from multiple sources, path-scoped rules in .claude/rules/, user-level global files, local override files, and session behavior configuration.

This depth comes at a cost: CLAUDE.md is Claude-specific. Other AI tools do not look for it, do not parse it, and cannot use it. But for teams that run on Claude Code, the expressiveness gap over AGENTS.md is substantial.

CLAUDE.md is designed for: Fine-grained control over Claude Code’s behavior, leveraging Claude-specific features that have no equivalent in the open AGENTS.md standard.

Decision Matrix

The matrix below covers the situations where the choice matters. For each scenario, it answers which file to use and why.

Reading the Matrix

A few patterns jump out from the matrix:

AGENTS.md wins on portability, CLAUDE.md wins on power. Every scenario where AGENTS.md is the primary choice comes down to needing the config to work across multiple tools or having simple enough requirements that portability is free. Every scenario where CLAUDE.md is the primary choice involves features AGENTS.md cannot express.

Most non-trivial teams end up using both. The “mixed tools” and “sub-agent delegation” rows are the most common production situations. The answer in both cases is not a single file — it is a deliberate split between what goes in each.

Solo developers can skip AGENTS.md entirely. If you are the only developer, only use Claude Code, and do not plan to change that, AGENTS.md adds overhead without benefit. CLAUDE.md is the better investment.

Capability Comparison

Before the real-repo walkthrough, here is the full capability comparison. This is what you need to reference when deciding which file can express something.

Real Repo Walkthroughs

Abstract rules become concrete when you see how they apply to actual repository structures. Here are four walkthroughs representing different project types.

Walkthrough 1: Solo Claude Code Developer (TypeScript SPA)

Situation: A solo developer building a React/TypeScript application who uses Claude Code as their only AI tool. Simple requirements.

Recommended file structure:

my-spa/
├── CLAUDE.md
├── CLAUDE.local.md          # gitignored, personal dev preferences
├── .claude/
│   └── rules/
│       └── component-rules.md   # Path-scoped rules for src/components/
├── src/
│   ├── components/
│   ├── hooks/
│   └── lib/

CLAUDE.md content:

# 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 (only loads when editing 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

Why no AGENTS.md? This developer uses only Claude Code. An AGENTS.md would add a file to maintain with zero benefit. If they later onboard a team member who uses Cursor, this becomes the moment to add AGENTS.md.

Walkthrough 2: Mixed-Tool Team (Backend API)

Situation: A five-person team building a Go API. Two developers use Claude Code, two use Cursor, one uses GitHub Copilot. The team wants consistent AI behavior across all tools.

Recommended file structure:

go-api/
├── AGENTS.md              # Universal rules — all tools read this
├── CLAUDE.md              # Claude Code additions only
├── .claude/
│   └── rules/
│       ├── api-handlers.md    # Rules for handlers/ directory
│       └── db-migrations.md   # Rules for migrations/ directory
├── cmd/
├── internal/
│   ├── handlers/
│   ├── models/
│   └── db/
├── migrations/
└── docs/
    ├── api-conventions.md
    └── testing-guide.md

AGENTS.md content:

# 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 content (Claude Code additions):**

```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

Why this split? AGENTS.md carries the universal rules that Cursor, Copilot, and Claude Code all need. CLAUDE.md uses @import to reference the detailed API and testing docs without duplicating them, adds Claude-specific commands, and sets permission boundaries that only Claude Code understands. Cursor users get the AGENTS.md baseline; Claude Code users get that plus the deeper configuration.

Walkthrough 3: Open-Source Library (Python)

Situation: A Python data processing library with 200+ GitHub stars. Contributors use every tool imaginable. Maintainers need AI configuration that works for everyone who opens a PR.

Recommended file structure:

dataprocessor/
├── AGENTS.md             # The only AI config file
├── src/
│   dataprocessor/
│       __init__.py
│       core.py
│       transforms/
│       io/
├── tests/
├── docs/
└── CONTRIBUTING.md

AGENTS.md content:

# 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

**Why no CLAUDE.md?** This is a library where the maintainers have no control over what tools contributors use. AGENTS.md reaches the widest audience. Adding CLAUDE.md would only benefit maintainers who use Claude Code — it would not help the contributor opening a PR from Cursor or Copilot. The marginal benefit does not justify maintaining two files.

---

### Walkthrough 4: Enterprise Monorepo (Multi-Team, Mixed Stack)

**Situation:** A monorepo with 40+ packages spanning React frontends, Go microservices, Python ML pipelines, and infrastructure-as-code. Multiple teams, some standardized on Claude Code. Complex rules that vary by package.

**Recommended file structure:**

monorepo/ ├── AGENTS.md # Universal root rules ├── CLAUDE.md # Root Claude config + imports ├── .claude/ │ └── rules/ │ ├── infra-rules.md # Rules for infra/ tree │ └── ml-pipeline-rules.md # Rules for packages/ml-*/ ├── packages/ │ ├── api-gateway/ │ │ ├── AGENTS.md # Gateway-specific universal rules │ │ └── CLAUDE.md # Gateway Claude additions │ ├── auth-service/ │ │ ├── AGENTS.md │ │ └── CLAUDE.md │ ├── ml-feature-store/ │ │ └── AGENTS.md # ML team uses diverse tools, no CLAUDE.md │ └── web-dashboard/ │ └── CLAUDE.md # Frontend team is all Claude Code ├── infra/ │ ├── AGENTS.md │ └── terraform/ └── docs/ ├── architecture.md ├── api-standards.md └── security-policy.md

**Root AGENTS.md (excerpt):**

```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.

**Root CLAUDE.md (excerpt):**

```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.

The enterprise monorepo pattern shows why neither file alone works at scale. AGENTS.md at the root and per-package level gives every AI tool consistent baseline behavior. CLAUDE.md layers Claude-specific depth on top, including path-scoped rules that activate only in the relevant directory. Teams that have not standardized on Claude Code (like the ML team in this example) skip CLAUDE.md entirely — they get the AGENTS.md baseline and nothing more.

Migration Patterns

Pattern 1: Adding CLAUDE.md to an Existing AGENTS.md Setup

This is the most common migration. You started with AGENTS.md for portability, your team has converged on Claude Code, and you want to unlock the deeper feature set.

Step 1: Create CLAUDE.md that imports AGENTS.md

# CLAUDE.md

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

## Claude-Specific Rules
(add below)

Starting with an @import means you are not duplicating content. Claude Code reads both; other tools still read just AGENTS.md.

Step 2: Move Claude-specific content into CLAUDE.md

Review your AGENTS.md for anything that is Claude-specific and does not benefit other tools — permission levels, session behavior, sub-agent delegation patterns. Move those to CLAUDE.md.

Step 3: Add .claude/rules/ for path-scoped rules

Identify areas of the codebase with complex, conditional rules. For example: “API handlers need input validation,” or “test files should never import production database clients.” These become path-scoped rules:

---
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`.

Step 4: Set up personal overrides

Add CLAUDE.local.md to .gitignore and create your personal file:

# CLAUDE.local.md (not committed)

## 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`

What not to do: Do not copy your entire AGENTS.md content into CLAUDE.md and then modify it. You will end up with two files with overlapping, potentially contradictory content, both of which you need to maintain.

Pattern 2: Adding AGENTS.md to an Existing CLAUDE.md Setup

You have a mature CLAUDE.md with detailed rules. Your team is growing, new contributors use different tools, or you are open-sourcing the project. You want AI configuration that works for everyone.

Step 1: Audit your CLAUDE.md for portable content

Go through your CLAUDE.md and tag each section:

• Universal — applies to any AI tool (code style, commands, project structure, boundaries)
• Claude-specific — uses CLAUDE.md features or references Claude capabilities

Step 2: Extract universal content into AGENTS.md

# AGENTS.md

(Your project overview, universal code style, commands, and boundaries)

Keep this file as tool-agnostic as possible. No mentions of Claude features, permissions, or session behavior.

Step 3: Trim CLAUDE.md to Claude-specific additions

# CLAUDE.md

See @AGENTS.md for project conventions.

## Claude-Specific Configuration
(imports, path-scoped rules, permissions, session behavior)

Step 4: Test with another tool

Run Cursor or Copilot against your AGENTS.md and verify it behaves as expected. This catches cases where you left Claude-specific assumptions in AGENTS.md.

What breaks during this migration: Instructions that referenced Claude’s conversational behavior or used Claude-specific phrasing (“When Claude asks for clarification…”) will not translate to AGENTS.md cleanly. Rewrite them as tool-agnostic behavioral instructions.

Pattern 3: From .cursorrules to Both

If you are migrating from a .cursorrules file (Cursor’s old format) to the newer AGENTS.md standard with optional CLAUDE.md:

Step 1: Create AGENTS.md from the portable content in .cursorrules

Most .cursorrules files contain: project description, code style rules, preferred libraries, naming conventions, and boundaries. All of this translates directly to AGENTS.md. Restructure it with Markdown headers for clarity.

Step 2: Create CLAUDE.md (if you use Claude Code)

# CLAUDE.md

See @AGENTS.md for project conventions.
(Add Claude-specific rules below)

Step 3: Keep .cursorrules for the Cursor team (or migrate)

Recent Cursor versions support AGENTS.md natively. Check your team’s Cursor version: if everyone is on 0.44+, you can delete .cursorrules and rely on AGENTS.md for Cursor as well. If someone is on an older version, keep both during the transition.

Step 4: Do not delete .cursorrules immediately

Wait one sprint. If nobody reports Cursor behaving differently, delete .cursorrules. The gradual rollout catches regressions before they cause real work loss.

The Coexistence Pattern: How It Works at Runtime

When both files exist in the same repository, what actually happens when an AI tool reads them?

For Claude Code:

Claude reads both files. The behavior is additive, not a conflict-resolution problem. At session start, Claude loads:

1. Organization-level managed policy (if configured)
2. User global ~/.claude/CLAUDE.md
3. Project root CLAUDE.md
4. Any subdirectory CLAUDE.md files relevant to the current working context
5. Applicable .claude/rules/*.md files (based on path matching)
6. CLAUDE.local.md (personal overrides, not committed)

AGENTS.md is one of the files that CLAUDE.md can reference via @import, but Claude Code does not automatically merge the two — it reads CLAUDE.md as the primary source. If your CLAUDE.md contains See @AGENTS.md for coding standards, Claude follows the reference and incorporates the content. If CLAUDE.md does not reference AGENTS.md, Claude Code may or may not read it (behavior varies by version).

Practical takeaway: If you have both files, add See @AGENTS.md for project conventions to your CLAUDE.md. This makes the relationship explicit and ensures Claude reads both.

For Cursor, GitHub Copilot, Gemini CLI, and other AGENTS.md-supporting tools:

These tools read AGENTS.md. They do not read CLAUDE.md (unless they happen to parse any markdown in the repo, which some do without understanding it). From the perspective of these tools, CLAUDE.md does not exist.

For tools that support both standards (emerging):

Some newer tools are starting to support both AGENTS.md and CLAUDE.md as configuration sources. Behavior in these tools varies — check the tool’s documentation for precedence rules. When in doubt, assume that AGENTS.md is for cross-tool rules and CLAUDE.md is for the specific tool’s native features.

Runtime conflict resolution:

What if AGENTS.md and CLAUDE.md contain contradictory instructions? For Claude Code, CLAUDE.md wins — it is the native format. If your CLAUDE.md says “use tabs” and your AGENTS.md says “use spaces,” Claude Code will use tabs. This is another reason to avoid duplicating the same instructions in both files: the duplication creates a maintenance burden and a potential conflict surface.

The cleanest runtime setup: CLAUDE.md for Claude-specific rules + a See @AGENTS.md import for universal rules. No duplication, no conflicts.

Common Pitfalls

Pitfall 1: Duplicating Content Across Both Files

What it looks like:

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

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

Why it hurts: When you change the style convention, you have to update two files. If you forget one, the files contradict each other. Over time, the files drift apart.

Fix: Use CLAUDE.md to import AGENTS.md for shared content, then add only Claude-specific rules in CLAUDE.md. Shared rules live in exactly one file.

Pitfall 2: Putting Claude-Specific Features in AGENTS.md

What it looks like:

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

Why it hurts: Other tools reading AGENTS.md will encounter instructions they cannot interpret. At best, they ignore it. At worst, the instructions confuse the model. Claude-specific features do not belong in the cross-tool configuration file.

Fix: AGENTS.md contains only instructions that any AI tool can understand and follow. Claude-specific behavior goes in CLAUDE.md.

Pitfall 3: Not Scoping Large Files with Subdirectory AGENTS.md or Path Rules

What it looks like: A 600-line AGENTS.md at the root that covers every package in a monorepo, with sections for each package, each technology, and each team’s conventions.

Why it hurts: Large files waste context. An AI editing a frontend component does not need the database migration conventions. Every token spent loading irrelevant rules is a token not spent on the actual task. Some tools also have hard limits on AGENTS.md file size.

Fix: For AGENTS.md, split package-specific rules into subdirectory AGENTS.md files. The closest AGENTS.md wins. For CLAUDE.md, use .claude/rules/*.md with path matchers so rules only load when relevant.

Pitfall 4: Using Vague Instructions That Are Not Testable

What it looks like:

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

Why it hurts: “Clean” and “well-structured” mean different things to different developers and to different AI models. These instructions do not actually change behavior — the model already tries to write good code. What you want to express is specifically what “good” means in your codebase.

Fix: Replace abstract instructions with concrete, verifiable ones.

- 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

These are instructions you can test: you can check whether a function is longer than 50 lines, whether it logs before returning.

Pitfall 5: Failing to .gitignore CLAUDE.local.md

What it looks like: A developer commits their CLAUDE.local.md containing local database credentials and personal path overrides.

Why it hurts: Credentials in version control is a security issue. Personal preferences shared with the team cause friction. This file is designed to stay local.

Fix: On day one, add CLAUDE.local.md to .gitignore. If you maintain a template, add CLAUDE.local.md.example to the repo as a starting point.

# Claude Code personal overrides
CLAUDE.local.md

Pitfall 6: Writing Instructions for the Current AI, Not the File’s Audience

What it looks like:

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

Why it hurts: AGENTS.md is read by multiple tools. Addressing “Claude” by name confuses tools that are not Claude. It also implies the instruction is Claude-specific — if so, it does not belong in AGENTS.md.

Fix: Write AGENTS.md instructions in the imperative, addressed to no specific tool.

# AGENTS.md (good)
- Run the full test suite before committing
- Do not modify generated files in dist/

# CLAUDE.md (fine to be Claude-specific)
- When asked to refactor, use plan mode first to outline changes

Pitfall 7: Treating AGENTS.md as Static Documentation

What it looks like: Setting up AGENTS.md once during project creation and never updating it.

Why it hurts: Your project evolves. Commands change, new packages get added, conventions shift. An outdated AGENTS.md is worse than no AGENTS.md — the AI follows stale instructions and produces output that does not match the current codebase.

Fix: Include AGENTS.md in your PR review process. Any PR that changes commands, adds packages, modifies conventions, or changes project structure should include an AGENTS.md update. Add a reminder to your PR template:

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

FAQ

Q: If my team uses both Cursor and Claude Code, which file takes priority?

A: There is no priority conflict — each tool reads its own file. Cursor reads AGENTS.md. Claude Code reads CLAUDE.md (and can also reference AGENTS.md via @import). The two files do not compete; they serve different tools. The only situation where priority matters is within Claude Code’s own layered system, where CLAUDE.md subdirectory files override the root, and .local.md overrides the committed file.

Q: Can CLAUDE.md replace AGENTS.md entirely?

A: For your own use in Claude Code, yes — CLAUDE.md is the native format and covers everything AGENTS.md does plus more. But CLAUDE.md does not replace AGENTS.md for other tools. Cursor, Copilot, Gemini CLI, Aider, and others do not read CLAUDE.md by default. If anyone on your team or in your contributor base uses a tool other than Claude Code, AGENTS.md provides them with configuration they would not otherwise have.

Q: What is the maximum recommended size for each file?

A: There is no official limit, but practical guidelines based on performance and reliability:

• AGENTS.md root: 400-500 tokens is the community sweet spot. Over 1,000 tokens, some tools begin to truncate or deprioritize later sections. The GitHub analysis of 2,500 real AGENTS.md files found a median of 340 tokens.
• CLAUDE.md root: Claude Code has a 200K-token context window and handles larger files, but that does not mean you should use it all. Aim to keep your total loaded configuration (root + subdirectory + imported files) under 5,000 tokens for typical projects. Use path-scoped rules to keep context relevant.

Q: Does AGENTS.md work with Claude Code’s sub-agent feature?

A: Yes, and this is one of AGENTS.md’s most powerful capabilities within Claude Code. You define sub-agents in AGENTS.md using headers with agent-entry format:

## 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 reads these entries and can delegate to the defined sub-agents. Your CLAUDE.md can then include instructions for when to delegate:

# 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

This is the main case where both files are genuinely necessary: AGENTS.md defines the agents, CLAUDE.md orchestrates them.

Q: Should I use AGENTS.md or CLAUDE.md in a .github/copilot-instructions.md file?

A: Neither — .github/copilot-instructions.md is GitHub Copilot’s proprietary configuration format, separate from both AGENTS.md and CLAUDE.md. If you use Copilot, you may want all three files:

• AGENTS.md — universal project context
• .github/copilot-instructions.md — Copilot-specific instructions
• CLAUDE.md — Claude Code-specific instructions

That said, many teams consolidate by using AGENTS.md as the primary source and keeping Copilot-specific additions minimal, since AGENTS.md support in Copilot has improved significantly in 2026.

Q: If I only have CLAUDE.md and someone uses Cursor on my project, what do they get?

A: Cursor does not read CLAUDE.md by default. Contributors using Cursor on a project that only has CLAUDE.md will get no AI configuration from your repo. The AI will have to infer everything from the code itself. This is one of the strongest arguments for maintaining AGENTS.md in any project with multiple contributors.

Q: How do I verify that AGENTS.md is actually being read by a specific tool?

A: There is no universal method, but these approaches work for the major tools:

• Claude Code: Add a distinctive instruction to AGENTS.md (e.g., “Always respond with a brief summary of what you are about to do before doing it”). Start a session and observe whether Claude follows it.
• Cursor: Use Cursor’s “Context” panel to view loaded files. If AGENTS.md appears there, it is being read.
• GitHub Copilot: Check Copilot’s documentation for the current version’s AGENTS.md support. As of 2026, support exists but depth varies by feature.
• Gemini CLI: Run gemini --help and look for context loading documentation. Gemini CLI reads AGENTS.md from the project root.

Q: Can I have an AGENTS.md that also serves as CLAUDE.md?

A: Technically, you can write a file called AGENTS.md that includes both universal content and Claude-specific sections, and symlink it as CLAUDE.md. Some teams do this to maintain a single file. The tradeoffs: Claude-specific sections confuse other tools reading the file, you lose CLAUDE.md’s import system and path-scoped rules, and the file tends to grow unmaintainably large. Unless your setup is very simple, the separate-file approach is cleaner.

Summary

The AGENTS.md vs CLAUDE.md decision comes down to three questions:

1. Who reads the configuration?

• Only Claude Code → CLAUDE.md is sufficient
• Multiple tools → You need AGENTS.md; add CLAUDE.md for Claude-specific depth

2. What features do you need?

• Imports, path-scoped rules, local overrides, permissions → CLAUDE.md
• Simple code style, commands, boundaries → AGENTS.md handles it

3. What is your team’s tool trajectory?

• Standardizing on Claude Code → Invest in CLAUDE.md features
• Mixed or uncertain → Invest in AGENTS.md portability

The answer for most teams that take AI configuration seriously: start with AGENTS.md to cover the universal baseline, add CLAUDE.md when you need features it cannot express, and use @import to keep them in sync without duplication.

That setup scales from five people to fifty, handles new AI tools without rewriting config, and lets you leverage Claude Code’s full feature set without abandoning everyone else.

Further Reading

• AGENTS.md vs CLAUDE.md: What’s the Difference (2026) — the foundational comparison this guide builds on
• Writing Effective CLAUDE.md Files — how to phrase instructions Claude actually follows
• AGENTS.md in Monorepos: Per-Package Instructions Without the Chaos — the monorepo walkthrough expanded further
• CLAUDE.md rules gallery — real CLAUDE.md files from open-source projects
• AGENTS.md rules gallery — real AGENTS.md files from production repositories