AGENTS.md vs CLAUDE.md: A Practical Guide for Developers in 2026

If you are setting up AI coding rules for a project in 2026, you have likely seen both AGENTS.md and CLAUDE.md referenced. They look similar on the surface — both are Markdown files that tell AI agents how to work in your codebase. But they are designed for different audiences, support different features, and excel in different scenarios.

This guide breaks down the real, practical differences between the two formats. No marketing fluff, just what you need to know to make the right choice for your project.

What Is AGENTS.md?

AGENTS.md is an open, tool-agnostic standard for providing instructions to AI coding agents. It emerged from a collaboration between Sourcegraph, OpenAI, Google, Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

The core idea: one file that any AI coding tool can read. Instead of maintaining separate configuration files for each tool your team uses, you write a single AGENTS.md that works across OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, and a growing list of others. It has been adopted by over 60,000 repositories on GitHub, including major projects like n8n (178K stars), awesome-go (167K stars), and LangFlow (145K stars).

The format is straightforward Markdown. There is no formal schema to learn — you write natural language instructions organized under headers.

# AGENTS.md

## Project Overview
E-commerce API built with Go 1.22 and PostgreSQL.

## Coding Standards
- Follow Go idioms: short variable names in small scopes,
  descriptive names for exported functions
- Error wrapping with fmt.Errorf("operation: %w", err)
- Table-driven tests in _test.go files alongside source

## Commands
- Build: go build ./...
- Test: go test ./... -race
- Lint: golangci-lint run

## Boundaries
- Never modify files in migrations/ without explicit approval
- Do not add new dependencies without justification

What Is CLAUDE.md?

CLAUDE.md is Anthropic’s native configuration format for Claude Code. It is a Markdown file (or set of files) that Claude reads at the start of every session, giving it persistent instructions about your project, your conventions, and your preferences.

Where AGENTS.md aims to be universal, CLAUDE.md is purpose-built for one tool and goes deeper because of it. It supports a hierarchical file system, path-scoped rules, user-level overrides, local files that stay out of version control, and an import system that lets you compose configuration from multiple sources.

Major projects that ship CLAUDE.md include Next.js (138K stars), LangChain (128K stars), Excalidraw (118K stars), and Deno (106K stars).

A basic CLAUDE.md looks familiar:

# Project

Next.js 14 monorepo using the App Router, TypeScript, and Drizzle ORM.

## Code Style
- TypeScript strict mode, no `any` types
- Functional components with named exports
- Collocate tests next to source files

## Commands
- pnpm dev — Start dev server
- pnpm test — Run Vitest
- pnpm lint — ESLint + Prettier check

But the real power of CLAUDE.md shows up when you use its Claude-specific features, which we will cover next.

Key Differences

1. Tool Compatibility

This is the most important distinction.

AGENTS.md is read by a wide and growing list of tools:

OpenAI Codex
Cursor
GitHub Copilot
Gemini CLI
Windsurf
Aider
Zed
Warp
RooCode
Factory

CLAUDE.md is read by Claude Code. That is its primary consumer. Other tools could theoretically parse it (it is just Markdown), but they do not look for it by default.

If your team uses multiple AI tools, or you maintain an open-source project where contributors bring their own tools, AGENTS.md gives you the broadest reach.

2. Configuration Hierarchy

CLAUDE.md has a sophisticated layered system that AGENTS.md does not match:

Managed policy (organization-wide, enforced, cannot be excluded)
User global (~/.claude/CLAUDE.md) — personal preferences across all projects
Project root (./CLAUDE.md) — shared with the team, committed to version control
Local project (./CLAUDE.local.md) — personal project-specific settings, not committed
Subdirectory (./packages/api/CLAUDE.md) — package-specific rules in monorepos
Path-scoped rules (.claude/rules/*.md with YAML frontmatter to match file paths)

Claude merges these layers intelligently. A rule in a subdirectory CLAUDE.md overrides the root. A local file overrides the committed one. This gives you fine-grained control that is hard to replicate with a single AGENTS.md.

AGENTS.md does support subdirectory placement — the closest AGENTS.md to the edited file wins — but it does not have user-level, local, or path-scoped equivalents.

3. The Import System

CLAUDE.md supports an @import syntax that lets you compose instructions from multiple files:

# CLAUDE.md

See @docs/api-patterns.md for API conventions.
See @docs/testing-guide.md for test patterns.
See @README.md for project overview.

Claude pulls in the referenced content when relevant. Imports can be recursive — your referenced files can reference other files. This is powerful for large projects where you want to keep documentation in its natural location (next to the code it describes) while still making it available to Claude.

AGENTS.md does not have an equivalent mechanism. You put everything in the file itself, or you split it across subdirectory AGENTS.md files.

4. Path-Scoped Rules

CLAUDE.md supports rules that activate only when Claude is working with specific files:

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

# API Layer Rules

- All handlers must validate input with Zod schemas
- Return standardized error responses using ApiError class
- Log all 5xx errors with request context

Drop this in .claude/rules/api-rules.md and it only loads when Claude edits files matching those paths. When Claude works on a React component in src/components/, this rule does not consume context.

AGENTS.md has no equivalent. All instructions in an AGENTS.md file are loaded regardless of what file the agent is editing (though subdirectory placement provides coarse scoping).

5. Local Overrides

CLAUDE.md has CLAUDE.local.md — a file you add to .gitignore for personal settings that should not be committed. This is useful for:

Local environment paths
Personal style preferences that differ from the team
Debug commands specific to your setup
Notes about your current work-in-progress

AGENTS.md is designed to be committed and shared. There is no built-in mechanism for personal overrides.

6. Content Philosophy

AGENTS.md encourages you to write for the lowest common denominator. Because any tool might read it, you stick to universal instructions: code style, project structure, commands, boundaries. The GitHub Blog analysis of 2,500 repositories recommends covering six core areas: commands, testing, project structure, code style, git workflow, and boundaries.

CLAUDE.md can go further because it targets a single, known consumer. You can use Claude-specific features like sub-agent delegation instructions, permission levels, session management rules, and references to Claude’s capabilities. You lose portability, but you gain precision.

When to Use AGENTS.md

Use AGENTS.md as your primary configuration when:

Your team uses different AI tools. Some developers on Cursor, some on Copilot, some on Claude Code. AGENTS.md is the common ground.
You maintain an open-source project. Contributors bring whatever tool they prefer. AGENTS.md gives everyone a baseline.
You want future-proofing. New AI coding tools almost always add AGENTS.md support early because it is the open standard.
Your rules are straightforward. Code style, commands, project structure, boundaries. If that covers your needs, AGENTS.md handles it well.
You want one source of truth. Instead of syncing three tool-specific files, maintain one AGENTS.md. Some teams symlink their other config files to it.

When to Use CLAUDE.md

Use CLAUDE.md as your primary configuration when:

Your team standardizes on Claude Code. If Claude Code is your primary AI tool, CLAUDE.md unlocks features that AGENTS.md cannot access.
You have a monorepo with complex rules. The hierarchical system (root, subdirectory, path-scoped, local) is designed for this. A monorepo with 10 packages can have targeted rules for each without bloating a single file.
You need personal vs. team separation. The .local.md and user-level config let individuals customize without affecting the shared configuration.
You want to reference existing docs. The @import system means you do not have to duplicate your API guide or testing standards — just point Claude to the existing docs.
Your instructions are Claude-specific. Permission levels, session behavior, agent delegation — these only make sense in Claude Code.

Using Both in the Same Repository

AGENTS.md and CLAUDE.md can coexist. This is not a hack — it is a legitimate and increasingly common pattern. Here is how it works in practice:

my-project/
  AGENTS.md          # Universal rules for any AI tool
  CLAUDE.md          # Claude-specific rules and overrides
  .claude/
    rules/
      api-rules.md   # Path-scoped rules for Claude
  packages/
    api/
      AGENTS.md      # API-specific rules for any tool
      CLAUDE.md      # API-specific Claude additions

The strategy:

AGENTS.md contains the universal rules: code style, commands, project structure, boundaries. These apply regardless of which tool reads them.
CLAUDE.md contains Claude-specific additions: import references, permission levels, session behavior, and any rules that leverage Claude Code features.

Keep the overlap minimal. Do not duplicate your code style rules in both files. Instead, your CLAUDE.md can import AGENTS.md content:

# CLAUDE.md

See @AGENTS.md for project coding standards.

## Claude-Specific Configuration

### Commands
- Use `pnpm test:watch` during development sessions
- Run `pnpm typecheck` before any commit

### Rules
- Prefer editing existing files over creating new ones
- When modifying API routes, check the corresponding test file

This gives Claude Code users the best of both worlds: the universal standards from AGENTS.md plus Claude-specific optimizations from CLAUDE.md. Contributors using other tools still get the AGENTS.md baseline.

Migration Tips

From AGENTS.md to adding CLAUDE.md

If you already have AGENTS.md and want to add Claude-specific features:

Create a CLAUDE.md that imports your AGENTS.md: See @AGENTS.md for base rules.
Add Claude-specific sections: commands, permissions, session management.
If you have a monorepo, create subdirectory CLAUDE.md files for package-specific rules.
Consider adding .claude/rules/ with path-scoped rules for high-traffic areas of the codebase.
Add CLAUDE.local.md to .gitignore so developers can add personal overrides.

From CLAUDE.md to adding AGENTS.md

If you already have CLAUDE.md and want to support other tools:

Extract the tool-agnostic parts of your CLAUDE.md: code style, project overview, commands, boundaries.
Put those in a new AGENTS.md at the repo root.
Trim your CLAUDE.md to only Claude-specific content and add an import reference to AGENTS.md.
If you have subdirectory CLAUDE.md files, decide which rules are universal (move to AGENTS.md) vs. Claude-specific (keep in CLAUDE.md).
Test with at least one other AI tool to verify your AGENTS.md works as expected.

From .cursorrules to both

Create AGENTS.md with the universal content from your .cursorrules — add Markdown headers for structure.
Create CLAUDE.md with See @AGENTS.md for base rules. plus any Claude-specific additions.
Keep .cursorrules if your team still uses Cursor, or check if your Cursor version supports AGENTS.md natively (most current versions do).

Recommendation Summary

Choose AGENTS.md when:

Multiple AI tools are used in your project
You are an open-source maintainer
You want a single, portable configuration
Your rules are straightforward (style, commands, structure)
Future-proofing across tools matters

Choose CLAUDE.md when:

Claude Code is your team’s primary AI tool
You need hierarchical, path-scoped, or layered rules
You have a complex monorepo
You want personal vs. team configuration separation
Your instructions reference Claude-specific capabilities

Use both when:

You want maximum compatibility and maximum Claude Code performance
Your project has both universal rules and Claude-specific needs
You maintain an open-source project with Claude Code power users among contributors

The pragmatic answer for most teams: start with AGENTS.md as your universal baseline, add CLAUDE.md when you need Claude-specific features, and keep the overlap between them minimal. One file for the world, one file for your tool.