Appearance

Language

Mastering AI agents

How to Write AGENTS.md and CLAUDE.md: One Rules File for Every AI Coding Tool (2026)

CLAUDE.md is the rules file Claude Code reads at the start of every session; AGENTS.md is the one Codex reads. Where each tool looks, how `@` imports work, what to put in and leave out, and how to make one file serve both, with templates to copy.

Kelvin Wang · · 11 min read

Key points

  1. Codex reads AGENTS.md; Claude Code reads CLAUDE.md, and reads AGENTS.md directly when a repo has no CLAUDE.md.
  2. To share rules, write them in AGENTS.md and make CLAUDE.md a single @AGENTS.md line plus any Claude-only rules.
  3. Write only what the code can't tell the AI: test commands, misleading spots, decisions already made, mistakes corrected twice.
  4. Rules that can never be broken don't belong only here; use a hook, a permission rule or a test.

AI coding tools start every session blank. “Run the tests with this command”, “that folder looks unused but don’t delete it”: whatever you told it last time is gone unless it’s written in the file the tool reads on startup. I run two of these tools side by side every day. This post pulls together their official docs (checked November 16, 2026) and how I get both tools to read the same rules.

How do CLAUDE.md and AGENTS.md differ?

Both are plain Markdown with the same job: project notes and rules written for the AI. The difference is which tool reads them and from where.

ItemCodexClaude Code
File it readsAGENTS.md (or AGENTS.override.md when one sits in the same folder)CLAUDE.md; reads AGENTS.md directly when there's no CLAUDE.md
Personal, all projects~/.codex/AGENTS.md (moved with CODEX_HOME)~/.claude/CLAUDE.md
ProjectFrom the project root (usually the Git root) down to the current folder, at most one file per folderCLAUDE.md in the current folder and every folder above; subfolder files load when Claude works there
Personal, one projectNot mentioned in the docsCLAUDE.local.md, added to .gitignore
When rules conflictFiles closer to the current folder come later and winAll files are concatenated; the closest is read last
Importing other filesNo import syntax in the docs@path/to/file, up to four hops
Size32 KiB combined by default; files past that are droppedUnder 200 lines per file recommended
First draft/init/init

Sources: Codex AGENTS.md docs [3], Codex slash commands [5], Claude Code memory docs [1].

Both tools have /init. Claude Code’s analyzes the project and writes a first CLAUDE.md, or suggests improvements if one already exists instead of overwriting it 1. Codex’s creates an AGENTS.md scaffold in the current folder 5, and its docs suggest editing the result to match how your team really works 4.

Claude Code also has an organization-wide location (managed policy) that IT pushes to everyone in a company; individuals don’t need it 1.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277. What it reads depends on whether there’s a CLAUDE.md in your working folder or above it 1:

Your repo hasClaude Code reads
Only AGENTS.mdAGENTS.md
AGENTS.md and CLAUDE.md (or CLAUDE.local.md)CLAUDE.md only
A CLAUDE.md containing @AGENTS.mdCLAUDE.md, with AGENTS.md pulled in by the import

Watch out for CLAUDE.local.md: it counts. In a project that relies on AGENTS.md, adding a CLAUDE.local.md for your own notes makes Claude Code stop reading AGENTS.md. Your global ~/.claude/CLAUDE.md doesn’t count, and loads alongside AGENTS.md 1.

You can change the default under Project instructions in /config, for example to read both files. The setup that depends least on versions and settings is the one the docs describe: write the rules in AGENTS.md, import it on the first line of a CLAUDE.md next to it, and add Claude-only rules below 1.

@AGENTS.md

## Claude Code

- Use plan mode for changes under src/billing/.

If you have no Claude-only rules, a symlink works too: ln -s AGENTS.md CLAUDE.md. The docs flag two things. Claude’s Edit tool won’t write through a symlink and edits AGENTS.md instead. And if anyone on the team uses Windows, use the import, because creating a symlink there needs admin rights or Developer Mode, and Git may check it out as a plain one-line text file 1.

Where should the files go?

I use three layers:

  1. Global: rules for every project. How to communicate, read the latest version before editing a file, commit only your own changes. Codex: ~/.codex/AGENTS.md; Claude Code: ~/.claude/CLAUDE.md.
  2. Project root: this repo’s build and test commands, folder conventions, decisions made. Committed and shared with the team.
  3. Subfolders: rules only one area needs, like a payments module with its own test command. They live in that folder and get read when the AI works there.

Both tools support the subfolder layer, in different ways. Codex reads from the root down to the current folder, with closer files coming later and winning; to replace the rules above entirely at some level, put an AGENTS.override.md there 3. Claude Code loads a subfolder’s CLAUDE.md when Claude reads or writes files in that folder. It also has .claude/rules/, where each rule file can carry paths so it only loads when Claude touches matching files, say src/api/**/*.ts 1.

How do @ imports work?

In Claude Code, @ plus a path in a CLAUDE.md loads that file’s contents too 1:

  • Relative paths resolve from the file containing the import, not from your current folder. Absolute paths and ~ paths work too.
  • Imported files can import more files, up to four hops deep.
  • Backticks stop an import. To mention a path without loading it, write `@README`.
  • A project CLAUDE.md importing a file outside the project triggers an approval dialog the first time. It’s there so a file someone else committed can’t quietly read things on your machine. Imports in your own ~/.claude/CLAUDE.md normally need no approval.

Imports help with organization, not context: imported text loads with the CLAUDE.md and costs the same 1.

Codex’s AGENTS.md docs don’t mention any import syntax 3, so a shared AGENTS.md shouldn’t depend on @ imports. Codex’s advice is to keep the main file short and point from it to separate Markdown files for task-specific detail 4. Claude-only imports go in CLAUDE.md.

What should go in the rules file?

Both vendors’ docs say roughly the same thing: what the AI can’t learn from the code but needs every time 2 4.

  • Commands that confirm the work. How to run tests, type checks and lint, and how to run a single test file. Claude Code’s docs say that if your repo has tests, the single most useful line in the file is the command that runs them 2.
  • Places where the code misleads. An old pattern that’s everywhere but new code mustn’t copy; a folder that looks unused but isn’t.
  • Decisions that aren’t in the repo. The error-handling approach the team picked, how deploys work, which changes need a human review.
  • Anything corrected twice. Codex’s guide: when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md 4.
  • Actions that need a human first. For example, confirm before adding a production dependency.

Make each rule specific enough to check. “Run npm test before committing” beats “test your changes”; “API handlers live in src/api/handlers/” beats “keep files organized” 1. When two rules contradict each other, the model may pick either, so prune stale and conflicting rules from time to time.

What should you leave out?

  • Architecture and file layout. Claude Code’s docs say Claude reads the repo itself 2. Codex’s checklist does include repo layout 4. My compromise is one line saying which file to start reading, not a tour of the folders.
  • Multi-step procedures. Deploy steps or a publishing routine go in a skill, which loads only when a task needs it 1.
  • Rules for one area only. Put them in a subfolder’s rules file, or a Claude Code rule with paths.
  • Rules that can never be broken. A rules file is context, and the model may decide a rule doesn’t apply this time. “Never read .env” or “don’t touch the migrations folder” belong in a hook or a permission rule 2; formatting and lint belong in CI 3.
  • Personal preferences. Use the global file or CLAUDE.local.md, not the shared team file.
  • Keys, tokens, accounts. The file goes into version control and into the model, whole.

If you keep adding “IMPORTANT” to a rule and it still gets ignored, tone isn’t the problem. Either the file is long enough that the line gets lost, or it’s a rule with no exceptions that belongs in a hook 2.

Go deeper What Is an AI Harness? 7 Parts That Keep AI Agents Reliable (2026) Beyond the rules file: rules as tests, skills, MCP, memory, subagents and verification.

How do I make one rules file work for Codex and Claude Code?

I used to have three global instruction files, and their contents had already started to diverge. I moved the shared rules into ~/ai-config/AGENTS.md and pointed both tools at that file. The directory is a Git repository, so I can look up each change in its commit history.

  • Codex: ~/.codex/AGENTS.md is a symlink to that file.
  • Claude Code: ~/.claude/CLAUDE.md is one line, @~/ai-config/AGENTS.md.
  • Skills: a setup.sh script in the same repo symlinks each skill into both tools’ skill folders.

I harness Codex and Claude Code at the same time. For both to have the same memory of a project, the rules have to be one file.

Besides the skills, setup.sh --check checks three things and reports an error if any is off:

  1. ~/.codex/AGENTS.md is a symlink to the source, not a copied file.
  2. ~/.claude/CLAUDE.md contains only that one import. If an installer appended something, it gets flagged.
  3. There’s no ~/AGENTS.md in the home folder. If there were, starting a tool from the home folder could load the same rules twice, once as global and once as project.

Beyond the usual rules, the source file has a section about both tools running at the same time:

  • Read the latest version before editing, change only the part you need, and never overwrite the whole file from an old copy.
  • If an edit fails, re-read instead of forcing it.
  • Check the staging area before committing and commit only this task’s changes, never another AI’s work.

There’s also a project index: one line per project with its name, aliases, a one-line purpose and the entry document. When I mention a project, the AI knows where to read the details, and the details stay out of the global file.

On 12 October 2026 I deleted a whole “write routing” table: where each of seven kinds of content goes, and whether to ask me first. What’s left is one sentence: a new project gets one line in the index, and its details live in that project’s own repo. The same day, Claude Code’s CLAUDE.md shrank to a single import line.

For each project, do the same: rules in the project’s AGENTS.md, and a CLAUDE.md that imports it with @AGENTS.md. Two similar files maintained side by side in one project will drift apart sooner or later.

Templates you can copy

Global rules, saved as ~/ai-config/AGENTS.md (choose your own path):

# Global rules

## Communication
- Answer in English.
- Say when you're unsure; don't make things up.

## Editing files
- Read the latest version before editing; change only what's needed, never overwrite the whole file.
- Check the staging area before committing; commit only this task's changes.
- Ask me before pushing, deleting data, or touching production.

## Definition of done
- Before saying it's done, run the tests and tell me which command ran and what it printed.

## Project index
- <project id> | <name> | <one-line purpose> | <entry document path>

Hook it up to both tools (if ~/.codex/AGENTS.md or ~/.claude/CLAUDE.md already exists, move its contents into the source file and delete the old one first):

mkdir -p ~/.codex ~/.claude
ln -s ~/ai-config/AGENTS.md ~/.codex/AGENTS.md
echo '@~/ai-config/AGENTS.md' > ~/.claude/CLAUDE.md

Project rules, saved as AGENTS.md at the repo root:

# <project name>

## Commands
- Install: npm install
- Test: npx vitest run
- One test file: npx vitest run tests/<name>.test.ts
- Build: npm run build

## Conventions
- Read DESIGN.md before changing anything visible.
- src/legacy/ is still live, but don't copy its patterns into new code.

## Ask first
- Before applying a database migration to production.
- Before pushing to main (a push deploys).

And CLAUDE.md next to it:

@AGENTS.md

## Claude Code
- Rules only Claude Code needs go here.

How do you check the tool actually loaded it?

  • Claude Code: run /context all in a session and look under Memory files. If your file isn’t listed, Claude can’t see it 1.
  • Codex: from the repo root, run codex --ask-for-approval never "Summarize the current instructions." and check that it repeats your rules; for subfolder rules, run it again with codex --cd <subfolder> 3. Codex rebuilds the instructions on every run, so a restart picks up changes.

FAQ

Is a longer CLAUDE.md better?

No. Every line takes a little attention on every task, relevant or not. Claude Code recommends under 200 lines per file 1, and Codex stops loading AGENTS.md content past 32 KiB combined by default 3.

Can I leave notes for humans in the rules file?

Claude Code strips block-level HTML comments (<!-- … -->) before loading, so they work as maintainer notes that cost no context 1. Codex’s docs don’t mention this, so don’t lean on it in a shared AGENTS.md.

Will one tool misread the other tool’s file?

When Claude Code reads AGENTS.md, @ imports still expand 1; Codex’s docs don’t mention imports, so to Codex an @ line is just text. Write the shared file so it makes sense without imports, and keep tool-specific parts in each tool’s own file.

Go deeper Claude Code Tutorial 2026: Install, CLAUDE.md, Skills, and Your First Website From installing and a first CLAUDE.md to skills, hooks and MCP.

Sources

  1. 1. How Claude remembers your project · Claude Code Docs · checked 2026-11-16
  2. 2. Best practices for Claude Code · Claude Code Docs · checked 2026-11-16
  3. 3. Custom instructions with AGENTS.md · OpenAI Codex Docs · checked 2026-11-16
  4. 4. Codex best practices · OpenAI Codex Docs · checked 2026-11-16
  5. 5. Slash commands in Codex CLI · OpenAI Codex Docs · checked 2026-11-16

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me