AGENTS.md and CLAUDE.md: Leave a Project Manual for AI
Prerequisite reading: Advanced Handbook: Make AI Understand Your Project Better
AGENTS.md is a project manual placed in the project root directory: Claude Code, Codex, and OpenCode all read it automatically before starting work, so you don't have to verbally explain the tech stack and rules every time.
Claude Code's memory file is called CLAUDE.md—same mechanism, different filename. This page sets up both files together so all three tools read the same content.
What You'll Be Able to Do
- Write an
AGENTS.mdplaced in the project root directory that all three AI coding agents will read automatically - Explain which four blocks of content AGENTS.md should contain, and why it shouldn't be a long essay
- Set up
CLAUDE.mdfor Claude Code, and make sure the two files never conflict - Open a new session to verify: the AI can answer how to start the project and what conventions to follow without you explaining
Your Current Struggles
- Every new session, you have to explain again: "We use pnpm, not npm" and "Run
pnpm testfor tests." - Rules agreed upon in the previous session are completely forgotten by the AI in this one, and it goes right back to running
npm installand installing things all over the place. - Project conventions exist only in your head: switch sessions, switch tools, or bring in a teammate, and you have to explain everything all over again.
When to Use This Technique
When you need to:
- Let the AI automatically know the project's tech stack, common commands, and code conventions in every new session
- Commit the rules to git so everyone on the team and every AI shares the same copy
- Use Claude Code today, switch to Codex or OpenCode tomorrow—the manual still works
And you don't want to:
- Paste a huge block of "project background" into the chat before starting every session
- Configure the same set of rules separately in three tools, each time differently
🎒 Preparation Before You Start
- Finish the prerequisite course Advanced Handbook: Make AI Understand Your Project Better
- Have a project directory—an empty project just getting started is fine
- Have any AI coding agent installed: Claude Code, Codex, or OpenCode. Not installed yet? First read Install Claude Code: Ready in 10 Minutes
- Set aside 10 minutes
Core Idea
The "manual mechanism" of the three tools looks very similar; the differences lie in the filename and how it is located:
| Tool | Which File It Reads | Where the Project-Level File Goes | Global File (Personal Preferences) |
|---|---|---|---|
| Claude Code | CLAUDE.md; without it, it can also read AGENTS.md directly (requires v2.1.277+) | Project root directory ./CLAUDE.md or ./.claude/CLAUDE.md | ~/.claude/CLAUDE.md |
| Codex | AGENTS.md, read before starting work | Project root directory | ~/.codex/AGENTS.md |
| OpenCode | AGENTS.md; starting from v2.3.1, when AGENTS.md is absent from the directory, it reads CLAUDE.md | the project root directory | ~/.config/opencode/AGENTS.md (falling back to ~/.claude/CLAUDE.md if missing) |
The idea in one sentence: make AGENTS.md the single source of truth. Codex and OpenCode read it directly; Claude Code uses a CLAUDE.md that references its content, plus Claude-specific notes. Change the rules in one place, and all three tools update in sync.
CLAUDE.md itself also has scopes: enterprise level (managed uniformly by the organization), user level (~/.claude/CLAUDE.md, holds personal preferences, applies to all your projects), and project level (version-controlled, shared with the team). This page mainly covers the project level.
Follow Along
Step 1: Create AGENTS.md in the Project Root Directory
Why: The more specific the manual, the less the AI has to guess. The examples in the Codex official guide are also directly executable instructions, one per line, rather than vague statements like "the code should be clean."
Create AGENTS.md in the project root directory (at the same level as README) and write four blocks of content:
# Project Overview
- One sentence: what this project does (e.g., a course booking website)
- Tech stack: Next.js + TypeScript, package management with pnpm
- Common commands: pnpm install / pnpm dev / pnpm test / pnpm build
- Code conventions: components go in src/components, run pnpm test before committing, do not directly modify build-generated filesWrite every rule as a verifiable instruction: "Indent with 2 spaces" is better than "keep the formatting clean," and "run pnpm test before committing" is better than "remember to test."
You should see: the file sitting in the root directory, within a few dozen lines, one rule per line.
- Quick check: have someone unfamiliar with your project look at it for 30 seconds—they should be able to say what tech stack the project uses and how to start it
Step 2: Put the Manual in the Right Place
Why: The three tools look for the instruction file differently, but all of them recognize the project root—Codex searches from the project root down to the subdirectory you're in; OpenCode reads the global file first, then collects from the current directory upward level by level; Claude Code reads CLAUDE.md in the current directory and above. Put it in the root, and all three lookup methods will hit it.
Steps:
- Confirm that
AGENTS.mdis in the project root—don't stuff it into subdirectories likesrc/, and don't leave it on the desktop. - Commit it to git. The OpenCode documentation explicitly recommends committing the project instruction file to the repository so every collaborator gets the same set of instructions.
- Don't put personal preferences (such as "reply in Chinese") into the project instruction file—put them in each tool's global prompt file: Codex uses
~/.codex/AGENTS.md, OpenCode uses~/.config/opencode/AGENTS.md, Claude Code uses~/.claude/CLAUDE.md.
You should see: git status shows AGENTS.md is tracked; ls in the root directory shows it side by side with README. After that, no matter whether you launch the agent from the root directory or a subdirectory, it will find this instruction file.
Step 3: Set up a CLAUDE.md for Claude Code
Why: Claude Code reads CLAUDE.md by default. As long as there is a project-level CLAUDE.md in the working directory or above, it stops reading AGENTS.md—if you don't connect the two files, Claude Code will "not see" your instruction file.
Option A (recommended): CLAUDE.md imports AGENTS.md
Create CLAUDE.md in the root directory:
@AGENTS.md
## Exclusive to Claude Code
- (Optional) Extra instructions written only for Claude@AGENTS.md is Claude Code's import syntax: the contents of AGENTS.md get expanded and loaded, and Claude-specific instructions go below the import. The rules are maintained in only one place.
Option B: Symlink
ln -s AGENTS.md CLAUDE.mdOne command, and the two files stay in sync forever—there's no output on success. But creating symlinks on Windows requires administrator privileges or developer mode, and Git may check it out as plain text—if anyone on your team uses Windows, choose Option A.
Option C: Copy the content over
Copy the contents of AGENTS.md into CLAUDE.md. The most straightforward, at the cost of having to edit two places when changing the rules; when the two disagree, the AI may just pick one at random to believe.
You should see: Run claude in the project directory, enter /context, and CLAUDE.md appears in the Memory files list, with the imported AGENTS.md content loaded along with it.
- Quick check: CLAUDE.md is in the Memory files of
/context
💡 What happens if you don't create a CLAUDE.md?
New versions of Claude Code (since v2.1.277) read AGENTS.md directly when there's no CLAUDE.md, and a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md appears at the start of the session. But some sessions don't support this (for example, the first session after upgrading from an old version), so setting up a CLAUDE.md is the safest bet.
Step 4: Open a new session to verify the instruction file takes effect
Why: All three tools read the instruction file at the start of a session—Claude Code loads memory files at the start of each session, Codex builds an instruction chain on each run, and OpenCode also requires a new session for changes to nested instruction files to take effect. If you test in an old session, you're testing the old rules.
Steps:
- Open a brand-new session: for Claude Code run
claudein the project directory, for Codex runcodex. - Just ask: "How do I start this project? What code conventions does it have?"
- Codex users can run the verification command given in the official guide:
codex --ask-for-approval never "Summarize the current instructions."You should see: The AI can answer with the startup commands and conventions written in the file without any extra explanation from you; Codex will recite the instructions from the global and project files in loading order.
- Quick check: switch to a subdirectory and launch again—the AI can still find the instruction file
Checkpoint ✅
AGENTS.mdis in the project root and contains four sections: project overview, tech stack, common commands, and code conventions- The file is committed to git, so anyone who clones the repository gets the same set of instructions
- Run
/contextin a Claude Code session, and the Memory files list CLAUDE.md - Open a new session and ask "how do I start the project"—the AI answers correctly without you explaining
- AGENTS.md and CLAUDE.md have consistent content (imported or synced), with no contradictory rules
Pitfall warnings
❌ Writing a long-winded essay
The longer the instruction file, the harder it is for the AI to grasp the key points. Claude Code officially recommends keeping each CLAUDE.md within 200 lines: too long eats up context and reduces adherence. Codex also has a total cap there—loading stops once multiple instruction files add up to 32 KiB (the default).
The right approach: only write facts the AI can't guess (commands, conventions, taboos), one per line, keeping it to a few dozen lines.
❌ Writing only principles, no commands
"Keep the code clean" is empty talk—the AI can't execute it.
The right approach: write verifiable instructions—"start with pnpm dev, test with pnpm test" "put API handlers in src/api/handlers/".
❌ Claude Code can't see AGENTS.md
Common causes: there's a project-level CLAUDE.md (or CLAUDE.local.md) in the working directory or above, so Claude Code reads only CLAUDE.md—the user-level ~/.claude/CLAUDE.md doesn't count; or the version is below v2.1.277.
The correct approach: claude --version to confirm the version; /context to see which files are actually loaded, and /memory to list the locations of memory files everywhere; then follow step 3 and use @AGENTS.md to import and connect them. Also note: OpenCode v2.3.1 (since 2026-11-18) reads CLAUDE.md again, but only as a fallback when there is no AGENTS.md in the directory; setting the environment variables OPENCODE_DISABLE_CLAUDE_CODE or OPENCODE_DISABLE_CLAUDE_CODE_PROMPT skips all CLAUDE.md. So AGENTS.md still takes precedence, and configuring both files is the safest.
❌ Verifying in an old session
After editing the instruction file, if you immediately ask the AI in the current session, it still answers with the old rules.
The right approach: after editing the file, open a new session to test; in Claude Code you can also run /context directly to confirm the file is loaded.
Advanced tips
- Let the AI write the first draft for you: Run
/initin Claude Code, and it will analyze the codebase and automatically generate a starter CLAUDE.md containing build commands, test instructions, and project conventions; if the file already exists, it gives improvement suggestions instead of overwriting it. - Give your rules a health check: Available since Claude Code v2.1.283,
/doctor prompt-audithas Claude check the instruction file for outdated content, contradictions, and references to nonexistent files. - Directory-level overrides (Codex): Put
AGENTS.override.mdin a subdirectory, and Codex reads it first; if the repository already has files likeTEAM_GUIDE.md, you can register them as fallback filenames in theproject_doc_fallback_filenamesof~/.codex/config.toml. - Hook up more instructions (OpenCode): Append files, globs, or URLs to the
instructionsarray inopencode.jsonc, and they load together with AGENTS.md. - Project preferences that belong only to you: Claude Code supports
CLAUDE.local.md, which holds your personal project preferences—remember to add it to.gitignore.
Lesson Summary
✅ By this point, you have already:
- Written an
AGENTS.md: four sections, one line each, placed in the project root and committed to git - Configured Claude Code with a
CLAUDE.mdthat references it, so three tools read the same set of rules - Verified with a new session: without you saying anything, the AI knows how the project starts and what conventions to follow
Key files recap:
| File | Recommended location | Purpose |
|---|---|---|
AGENTS.md | Project root | The single source of truth, read directly by Codex and OpenCode |
CLAUDE.md | Project root | Claude Code's memory file; use @AGENTS.md to import the shared content |
~/.claude/CLAUDE.md | User home directory | Personal preferences, effective for all your projects |
~/.codex/AGENTS.md | Codex home directory | Codex global guidance, inherited by all repositories |
~/.config/opencode/AGENTS.md | OpenCode config directory | OpenCode global guidance; put rules that apply everywhere here |
Remember it in one sentence: AGENTS.md is the project manual for the AI—write it concretely, put it in the root, keep it the only one.
Next Lesson Preview
The manual has helped the AI understand your project; in the next lesson, it will gain more capabilities: Vercel × AI Coding Agents: The Plugin, Skills, and MCP Trio.
You will learn:
- What the Plugin, Skills, and MCP trio that Vercel provides for AI coding agents are, respectively
- How to connect them to your agent using the official commands
- Once connected, what the AI can do with your Vercel project
If you want to think through "what to write" first, review Plan Before You Act: Turning a One-Sentence Idea into a Requirements List; for the basics of Claude Code, see Claude Code Usage: An AI Coding Agent in the Terminal.