One AGENTS.md, every tool

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.

This isn’t a hypothetical. There are active threads on r/ClaudeAI and r/cursor from developers trying to figure out how to keep their configs in sync across tools. The common answer is symlinks, copy scripts, or just accepting the drift.

There’s a simpler answer.

What each tool actually reads

Here’s the current state as of March 2026:

Codex reads AGENTS.md natively. It walks from your project root down to the current working directory, checking each level. It also reads ~/.codex/AGENTS.md for global config that applies to every project.

Cursor reads AGENTS.md natively, alongside .cursor/rules/*.mdc files. AGENTS.md content is always included. The .mdc files add conditional rules (triggered by file patterns or specific contexts), but for most project-wide conventions, AGENTS.md is enough.

Claude Code reads CLAUDE.md. It does not read AGENTS.md natively yet. This is an open feature request with strong community support, and a second request filed as recently as March 2026. But you don’t have to wait for Anthropic to ship it.

The bridge is one line.

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:

AGENTS.md (committed, cross-tool): your project conventions, setup commands, architecture decisions, coding style. Every tool reads this.
CLAUDE.md (committed, Claude Code only): @AGENTS.md import plus any Claude-specific context imports.
.cursor/rules/ (committed, Cursor only): conditional rules that need file-pattern triggering. Only if you actually need them.
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. It’s now maintained by the Agentic AI Foundation under the Linux Foundation, with backing from OpenAI, Google, Cursor, Amp, and Factory. Over 60,000 open-source projects already use it.

Claude Code is the last major holdout for native support, and with two open feature requests and strong community demand, it’s a matter of when, not if. In the meantime, the one-line bridge works perfectly.

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