One AGENTS.md, every tool

Verified against Claude Code 2.1.263, Codex CLI 0.153.4 · Updated

Most developers I’ve talked to maintain multiple config files for their AI coding tools. A CLAUDE.md for Claude Code, a .cursor/rules/ directory for Cursor, maybe a codex.md or AGENTS.md for Codex. Same project conventions written in three places.

The thing is, you probably don’t need to do that. AGENTS.md works natively in Codex and Cursor. Claude Code needs a one-line bridge file. That’s it. One file, three tools.

The problem with multiple config files

If you’ve ever switched between AI coding tools mid-project, you’ve felt this. Cursor knows you use vitest. Claude Code thinks you’re still on jest because nobody updated CLAUDE.md when you migrated. Codex has no config at all because you forgot it reads from AGENTS.md, not the other two.

It gets worse on teams. One developer sets up Cursor rules, another writes CLAUDE.md, a third adds AGENTS.md for Codex. Within a week, they’ve diverged. The Cursor rules say “use Prisma for database access.” The CLAUDE.md says “use Drizzle” because someone refactored last Tuesday. Nobody updated the other files.

There’s a simpler answer.

What each tool actually reads

In Claude Code

Claude Code reads CLAUDE.md, not AGENTS.md. Anthropic’s memory docs say that in one sentence, then show the supported bridge: a CLAUDE.md whose first line is @AGENTS.md. A symlink (ln -s AGENTS.md CLAUDE.md) also works if you have nothing Claude-specific to add. On Windows, use the import. You still need that one-line file.

In Codex

Codex reads AGENTS.md natively. It checks ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md for global config, then walks from the project root down to the current working directory, taking at most one file per directory (AGENTS.override.md first, then AGENTS.md).

In Cursor

Cursor reads AGENTS.md natively, in the project root and in nested directories, alongside .cursor/rules/*.mdc files. AGENTS.md is plain markdown with no frontmatter. The .mdc files add conditional rules (description, globs, alwaysApply). For most project-wide conventions, AGENTS.md is enough.

The Claude Code bridge

Create a CLAUDE.md file in your project root with this single line:

@AGENTS.md

That’s the entire file. Claude Code’s @ import syntax pulls in the full contents of AGENTS.md and injects it into context automatically. No symlinks, no build scripts. When you update AGENTS.md, Claude Code picks up the changes immediately.

If you also have global conventions in ~/.claude/CLAUDE.md, you can add the @ import there too:

@AGENTS.md

# Global preferences
- Always use TypeScript strict mode
- Prefer functional patterns

The @ import merges with any other content in the file. Your AGENTS.md handles the project-level config, and anything tool-specific goes below.

Writing your AGENTS.md

Here’s a real AGENTS.md for a Next.js + TypeScript project. Every section has a reason.

# AGENTS.md

## Setup
- Install deps: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Run all tests: `pnpm test`
- Run single test: `pnpm vitest run -t "test name"`
- Type check: `pnpm tsc --noEmit`
- Lint: `pnpm lint`

## Stack
- Next.js 15 (App Router)
- TypeScript 5.7 (strict mode)
- Tailwind CSS 4
- Drizzle ORM + Postgres
- Vitest + Testing Library

## Code style
- Single quotes, no semicolons
- Named exports over default exports
- Server components by default, 'use client' only when needed
- Collocate tests next to source files (Button.test.tsx beside Button.tsx)
- Use cn() helper from lib/utils for conditional class names

## Database
- Migrations in drizzle/migrations/
- Generate migration: `pnpm drizzle-kit generate`
- Apply migrations: `pnpm drizzle-kit migrate`
- Schema files in src/db/schema/
- Always use prepared statements, never raw SQL strings

## Architecture
- Feature folders in src/features/ (each has components/, hooks/, actions/)
- Shared UI in src/components/ui/
- Server actions in actions.ts files, validated with Zod
- Environment variables: src/env.ts (validated at build time)

## PR conventions
- Branch format: feature/short-description or fix/short-description
- Commit messages: imperative mood ("add login page" not "added login page")
- Run pnpm test and pnpm lint before committing
- One concern per PR

A few things to notice. The setup section has exact commands, not descriptions. “Run pnpm vitest run -t "test name"” is more useful to an AI agent than “use vitest for testing.” Same for the database section: the actual migration commands, not “we use Drizzle.”

The architecture section tells the agent where things live. Without this, every AI tool will ask you where to put a new component, or worse, guess wrong and create files in random locations.

If you’re working in Python, Rust, or Go, the structure is the same. Swap the commands and stack, keep the sections.

What can’t go in AGENTS.md

AGENTS.md covers 90% of what you need. But each tool has features that AGENTS.md doesn’t support. Here’s what’s left out and whether it matters.

Cursor’s .mdc metadata

Cursor’s .cursor/rules/*.mdc files support frontmatter that AGENTS.md can’t replicate:

---
globs: ["*.test.tsx", "*.spec.ts"]
alwaysApply: false
---
When writing tests, always use describe/it blocks (not test).
Mock external services with MSW, never with jest.mock.

The globs field makes this rule activate only when editing test files. The alwaysApply: false means Cursor only loads it when relevant. AGENTS.md rules are always loaded.

Does this matter? For most projects, no. Putting your testing conventions in AGENTS.md works fine. The agent sees them on every request, but that’s a few extra tokens, not a real cost. Conditional loading matters more in large monorepos where you have hundreds of context-specific rules.

If you do need it: keep your AGENTS.md as the primary config, and add a thin .cursor/rules/ directory for the few rules that genuinely need file-pattern triggering.

Codex’s override files

Codex supports AGENTS.override.md for local overrides that aren’t committed to git. Useful for personal preferences that shouldn’t be shared with the team (your preferred debugger, local database connection strings, etc). AGENTS.md doesn’t have this concept, but it doesn’t need to. Just add AGENTS.override.md alongside your AGENTS.md and Codex picks it up.

Claude Code’s @-imports

Claude Code’s CLAUDE.md supports importing multiple files with @ syntax:

@AGENTS.md
@docs/api-reference.md
@docs/deployment-guide.md

This lets you pull in additional context beyond your AGENTS.md. Useful when you have detailed docs that the agent should reference but don’t belong in your project conventions file. AGENTS.md itself doesn’t support imports (it’s just a markdown file), so this stays Claude Code-specific.

The pattern

Think of it as layers:

  1. AGENTS.md (committed, cross-tool): your project conventions, setup commands, architecture decisions, coding style. Every tool reads this.
  2. CLAUDE.md (committed, Claude Code only): @AGENTS.md import plus any Claude-specific context imports.
  3. .cursor/rules/ (committed, Cursor only): conditional rules that need file-pattern triggering. Only if you actually need them.
  4. AGENTS.override.md (gitignored, Codex only): personal local overrides.

Most projects need layers 1 and 2. Layer 2 is one line. Layers 3 and 4 are optional and situational.

AGENTS.md is the standard

AGENTS.md isn’t just a convention that caught on. The Agentic AI Foundation hosts it as an open project, next to MCP and A2A.

Claude Code still does not read AGENTS.md on its own. The one-line @AGENTS.md import is the documented way to share one file. I use that.

Write your conventions once. Put them in AGENTS.md. Let every tool read the same source of truth.

Sources