CLAUDE.md vs CONVENTIONS.md vs AGENTS.md: The Definitive 2026 Comparison

Three files. Same job on the surface — tell AI tools how your codebase works. But pick the wrong one, or conflate them, and you end up with agents ignoring your rules, duplicate config flying out of sync, or instructions that only one of your three AI tools ever reads.

This is the definitive comparison of CLAUDE.md, CONVENTIONS.md, and AGENTS.md as they exist in 2026. We cover what each format actually does, which tools respect it, where each one falls apart, and how to migrate between them.

Quick Reference

What Is CLAUDE.md?

CLAUDE.md is Anthropic’s native configuration format for Claude Code. It is a Markdown file placed at the root of your repo (and optionally in subdirectories) that Claude reads at the start of every session. Think of it as a persistent system prompt for your codebase — it shapes everything Claude does, from how it names variables to which directories it will not touch.

The format is intentionally simple. Standard Markdown, no required schema, organized under headings. But Claude Code layers several advanced features on top of that simplicity:

Hierarchical loading. Place a CLAUDE.md in your repo root, another in src/frontend/, another in packages/api/. Claude loads and merges them based on where it is working. A rule in packages/api/CLAUDE.md overrides the root for that subtree.

Import system. The @path/to/file syntax lets you pull in content from other files. This is significant for monorepos: a root CLAUDE.md can import from @packages/frontend/conventions.md and @packages/backend/rules.md rather than duplicating content.

# Project

This is a monorepo with three packages.

@packages/frontend/CLAUDE.md
@packages/backend/CLAUDE.md
@packages/infra/CLAUDE.md

User-level and local overrides. ~/.claude/CLAUDE.md sets user-wide preferences. CLAUDE.local.md is gitignored by default — machine-specific rules that stay off version control. You can set a personal preference for test verbosity or logging format without polluting the shared config.

Named subagent definitions. Within CLAUDE.md (or AGENTS.md), you can define named agents — specialized Claude instances with their own system prompts, tool permissions, and model configurations.

## agents

### code-reviewer
prompt: |
  You are a code reviewer focused on security and performance.
  Flag any use of eval(), innerHTML assignment, or unparameterized SQL.
  Respond only with specific, actionable comments.
tools: [read_file, search_files]
model: claude-opus-4-5

The result: when Claude delegates to code-reviewer, it gets a separate instance with its own context and constraints.

CLAUDE.md Strengths

• Deepest integration with Claude Code — leverages every advanced feature
• Import system prevents config drift in large repos
• Hierarchical loading makes monorepo config surgical
• Local overrides separate personal preferences from team standards
• Well-documented with extensive real-world adoption (Next.js, Deno, LangChain all ship CLAUDE.md)

CLAUDE.md Weaknesses

• Claude Code only. Cursor reads it partially but does not honor all features. Other tools ignore it entirely.
• Import syntax is Anthropic-specific — it does not transfer to other tools
• No official linting or validation tooling
• Teams using multiple AI coding tools need additional config files

What Is CONVENTIONS.md?

CONVENTIONS.md emerged from Windsurf’s Cascade AI. It is the native configuration file for Windsurf, playing roughly the same role as CLAUDE.md for Claude Code — a persistent context file that Cascade reads to understand project conventions.

The format is nearly identical to CLAUDE.md: plain Markdown with no enforced schema, organized under headings. The main structural difference is that CONVENTIONS.md is typically a single file without a hierarchical loading system.

A typical CONVENTIONS.md:

# Project Conventions

## Tech Stack
- Framework: SvelteKit with TypeScript
- Styling: CSS Modules (no Tailwind)
- Testing: Vitest + Playwright
- Package manager: pnpm

## Naming Conventions
- Components: PascalCase (Button.svelte, not button.svelte)
- Utilities: camelCase files (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE
- Stores: suffix with Store (cartStore.ts)

## Git Conventions
- Branch format: type/short-description
- Commit: conventional commits (feat:, fix:, chore:)

## Off-Limits
- Do not modify src/lib/generated/ (auto-generated by prisma)
- Do not change tsconfig.json strictness settings

CONVENTIONS.md Strengths

• Purpose-built for Windsurf/Cascade — best results in that ecosystem
• Familiar format — trivial to write if you already know CLAUDE.md
• Clean single-file structure works well for most projects
• Windsurf users report better rule adherence compared to generic AGENTS.md

CONVENTIONS.md Weaknesses

• Windsurf/Cascade only. Claude Code and OpenAI Codex ignore it.
• No hierarchical loading, no imports
• No subagent support
• Relatively small community (8K repos) compared to alternatives
• No official documentation from Windsurf on the expected structure

When CONVENTIONS.md Makes Sense

If your team is all-in on Windsurf and has no plans to adopt other AI coding tools, CONVENTIONS.md gives you slightly better Cascade performance. That said, most Windsurf users also maintain an AGENTS.md for cross-tool compatibility. Running both is low-overhead and the safe move.

What Is AGENTS.md?

AGENTS.md is an open, tool-agnostic standard stewarded by the Agentic AI Foundation under the Linux Foundation. The goal: one file any AI coding tool can read, so teams do not maintain separate config for each tool.

The format is standard Markdown. The top-level content describes the project for any tool that reads it — build commands, conventions, off-limits directories. Named sections define subagents for tools that support them (Claude Code, OpenCode).

# AGENTS.md

## Project Overview
Go 1.22 REST API backed by PostgreSQL 16. Authentication via JWT.

## Commands
- Build: `go build ./...`
- Test: `go test ./... -race -cover`
- Lint: `golangci-lint run --fix`
- DB migrate: `atlas migrate apply --env dev`

## Coding Standards
- Prefer table-driven tests in _test.go files alongside the source
- Error wrapping: `fmt.Errorf("context: %w", err)`
- Exported functions: godoc-style comments
- No direct calls to `os.Exit` outside main()

## Boundaries
- Do not modify `migrations/` — use Atlas migrations exclusively
- Do not add dependencies without a brief justification comment in the PR
- `vendor/` is committed — run `go mod vendor` after dependency changes

## Security
- No hardcoded credentials or tokens
- All SQL via `database/sql` with parameterized queries

Tool support as of 2026:

AGENTS.md Strengths

• Broadest tool coverage — one file serves multiple AI tools
• Open standard with Linux Foundation backing — not vendor lock-in
• 60,000+ repos have adopted it: battle-tested patterns are available
• Named subagent sections work in Claude Code and OpenCode
• The pragmatic default for teams using heterogeneous AI tooling

AGENTS.md Weaknesses

• No hierarchical loading (Claude Code only honors this through its own CLAUDE.md)
• Tool support is uneven — “supports AGENTS.md” means different things to different tools
• No import system, so large configs get unwieldy
• Claude Code prefers CLAUDE.md when both are present — AGENTS.md is a fallback

The Real-World Decision Matrix

Use CLAUDE.md when

Your team uses Claude Code exclusively and wants to leverage its full feature set. The import system, hierarchical loading, and local overrides provide capabilities that justify the tool-specific format. Any project where team members use different machines with different personal preferences benefits from the user-level and local override mechanisms.

Projects with complex directory structures particularly benefit: a monorepo with 6 packages can have surgical per-package rules instead of one sprawling root config.

Use AGENTS.md when

Your team uses multiple AI coding tools. A team where some developers use Claude Code, others use Cursor, and your CI pipeline uses OpenAI Codex needs a format all three can read. AGENTS.md is the answer.

Also the right choice if tool flexibility matters: you want to switch from Claude Code to another tool in the future without rewriting your AI config. AGENTS.md keeps you portable.

Use CONVENTIONS.md when

Your team is standardized on Windsurf/Cascade and wants the best Cascade performance. Pair it with AGENTS.md for other tools.

Use all three when

Multi-tool shop with Windsurf users on the team. Maintain AGENTS.md as the canonical source, with CLAUDE.md for Claude Code specifics and CONVENTIONS.md for Windsurf specifics. This sounds like duplication, but in practice the common sections (build commands, off-limits directories) are copy-pasted across all three, and tool-specific sections (Claude subagents, CLAUDE.md imports) live only in the relevant file.

A .claude/ directory with CONVENTIONS.md → AGENTS.md cross-references keeps documentation coherent.

Migration Patterns

Migrating CLAUDE.md to AGENTS.md

Most CLAUDE.md content transfers directly. The sections that do not:

1. Import statements (@path/to/file) — inline the content or drop the dependency
2. Hierarchical CLAUDE.md in subdirectories — consolidate to one AGENTS.md at root, or maintain separate AGENTS.md files per directory
3. User-level preferences — move to .cursorrules, a personal dotfile, or just document them separately

# Before (CLAUDE.md)
@packages/frontend/CLAUDE.md
@packages/backend/CLAUDE.md

## Global Rules
- Use conventional commits

# After (AGENTS.md)
## Frontend
[contents of packages/frontend/CLAUDE.md inlined]

## Backend
[contents of packages/backend/CLAUDE.md inlined]

## Global Rules
- Use conventional commits

Migrating AGENTS.md to CLAUDE.md

All AGENTS.md content transfers without modification. Claude Code reads AGENTS.md natively. The migration adds, not removes: you gain the opportunity to leverage imports, hierarchical rules, and user-level overrides.

Step 1: Copy AGENTS.md to CLAUDE.md verbatim. Step 2: Move per-directory rules to subdirectory CLAUDE.md files. Step 3: Extract personal preferences to CLAUDE.local.md (gitignored). Step 4: Set up imports to keep packages from duplicating global rules.

Running CLAUDE.md and AGENTS.md in parallel

If your team uses Claude Code plus other tools, you need both. The maintenance burden is manageable with a clear convention: AGENTS.md is the shared source of truth, CLAUDE.md adds Claude Code-specific features.

Use a comment in CLAUDE.md:

# CLAUDE.md
# Claude Code-specific config. Core rules are in AGENTS.md (read that first).
# This file adds Claude-specific features: imports, subagent definitions, local path scoping.

@AGENTS.md

## Claude-Specific Configuration

### Subagents
[Claude subagent definitions...]

### Path Scoping
[Directory-specific overrides...]

This way, AGENTS.md changes are always the source of truth and get imported into CLAUDE.md.

Anti-Patterns to Avoid

Maintaining three independent files with duplicate content. If CLAUDE.md, AGENTS.md, and CONVENTIONS.md all have different versions of your build commands, agents will get different information depending on which tool they use. Use the import-from-AGENTS.md pattern to keep one source.

Using CLAUDE.md import syntax in AGENTS.md. The @path/to/file syntax is Claude Code-specific. Tools reading AGENTS.md will output it literally. Stick to standard Markdown in AGENTS.md.

Putting user preferences in the committed CLAUDE.md. Log verbosity, test output format, and personal code style preferences belong in CLAUDE.local.md. Committing them forces them on the whole team.

Empty or stub files. An empty AGENTS.md is worse than no AGENTS.md — tools read it and get no useful information, often leading to worse behavior than the default.

Conflicting rules across formats. If AGENTS.md says “use Jest” and CLAUDE.md says “use Vitest”, Claude Code will resolve the conflict in unpredictable ways. The import-from-AGENTS.md pattern prevents this.

Tool-Specific Behavior Notes

Claude Code Priority

When both CLAUDE.md and AGENTS.md are present, Claude Code loads CLAUDE.md first. AGENTS.md content is accessible through the import mechanism (@AGENTS.md in CLAUDE.md). If CLAUDE.md imports AGENTS.md, the combined content is used. If neither imports the other, CLAUDE.md takes precedence.

OpenAI Codex

Codex reads AGENTS.md by spec. It does not read CLAUDE.md or CONVENTIONS.md. The format spec is documented on the OpenAI platform.

Cursor

Cursor prefers .cursor/rules/ (formerly .cursorrules). It reads AGENTS.md and applies the project-level instructions, but ignores Claude-specific features. See our cursorrules vs CLAUDE.md comparison for full details.

Summary

If you are starting from scratch in 2026, the pragmatic defaults are:

• Single AI tool (Claude Code): CLAUDE.md only, leverage the full feature set
• Single AI tool (Windsurf): CONVENTIONS.md for Cascade + AGENTS.md for portability
• Multiple AI tools: AGENTS.md as canonical source, CLAUDE.md importing from it for Claude Code extras
• Migrating from an existing format: AGENTS.md → CLAUDE.md is trivial; CLAUDE.md → AGENTS.md requires inlining imports

The format decision matters less than the content quality. A thorough AGENTS.md beats a half-baked CLAUDE.md every time.

For related reading: AGENTS.md vs CLAUDE.md covers the core two-way comparison, and 10 CLAUDE.md templates gives you copy-paste starting points for the CLAUDE.md approach.