Guide

How to write AGENTS.md and CLAUDE.md: the map that interviews you

Let the coding agent draft it, then let it interview you for the rest. In plan mode in Claude Code or Codex, where the agent plans before it changes anything, type: “Explore this repository. Change nothing. Draft a one-page map. Then ask me what the code could not tell you. One at a time, most important first.” Answer its questions about what is retired, how the team writes code and what is dangerous to touch. Save the map and the answers in the repository root as CLAUDE.md for Claude Code or AGENTS.md for Codex, adding to any file already there. Both agents read the file before they work, but it guides rather than enforces, so tests, hooks and code review stay.

AGENTS.md. AGENTS.md is a markdown file of standing instructions that Codex reads before doing any work, and CLAUDE.md is the file Claude Code reads at the start of every session for the same job.

Written by Tayyeb Mahmud, founder and Principal Architect. Claude Certified Architect – Professional · LinkedIn profile of Tayyeb Mahmud

1AYM is an OpenAI Select Partner.

Checked 11 October 2026. The Claude Code docs on memory, permission modes, the desktop app, hooks and best practices, Anthropic’s prompting guidance, Claude blog and Help Center, OpenAI’s Codex docs on AGENTS.md, customization, memories, prompting, hooks, managed configuration, GitHub code review and codebase onboarding, OpenAI’s Codex best practices guide and the agents.md site were read on this date. Commands, menu names and defaults change between releases.

The map that interviews you · 54 seconds, with captions

The method: five steps to a file every agent reads

Switch to plan mode
Turn on plan mode in Claude Code or Codex, so the first pass researches and plans without editing anything.
Ask for the map, then the questions
Type the prompt word for word: explore, change nothing, draft a one-page map, then ask what the code could not tell it, one question at a time.
Answer with reasons
Answer each question in a sentence or two, give the reason, and say so when you do not know.
Write the page to the instruction file
Have the agent write the map and the answers as one page in CLAUDE.md or AGENTS.md at the repository root, adding to any file already there.
Review it like code
Open a pull request, have the people who gave the answers review it, and give the file an owner.

Five steps for writing an AGENTS.md or CLAUDE.md with the coding agent’s help, and what it looks like when each step is skipped.
Dimension	What it looks like when the step is skipped
Switch to plan mode	The agent starts changing code while it is still learning the repository.
Ask for the map, then the questions	A long page restating what the code already says, and nothing it leaves out.
Answer with reasons	Bare rules the agent cannot apply to a case nobody wrote down.
Write the page to the instruction file	The answers stay in one session, and the next one starts from nothing.
Review it like code	One person’s guesses reach every engineer’s agent unreviewed.

Why the agent built on code you retired

The film on this page opens on a coding agent building on code the team retired two years ago. Nothing in the repository said so. Retired code can still compile, still pass its tests and look like every other folder, so the agent did what any newcomer does with nobody to ask: it followed the pattern in front of it. The decision to retire that code lived in two people’s heads.

Both vendors built an instruction file for exactly this gap. Claude Code reads CLAUDE.md at the start of every session [1], and OpenAI’s documentation opens with the line “Codex reads AGENTS.md files before doing any work” [2]. On what belongs in the file, the two give compatible answers. Anthropic says to keep what Claude cannot guess, such as commands, rules that differ from defaults and gotchas, and to leave out what it can work out by reading the code [3]. OpenAI’s list for a good AGENTS.md is the repository layout, how to run the project, the build, test and lint commands, conventions, do-not rules, and what done means and how to verify it [4].

Writing it is the hard part. Both tools offer /init: in Claude Code it analyses the codebase and writes a starting CLAUDE.md [1], and in Codex it creates a starter AGENTS.md that OpenAI calls a starting point to edit to match how your team builds, tests, reviews and ships [4]. Anthropic’s advice is to run /init, then refine the file with what Claude could not discover for itself [3]. That second step needs the people who hold the knowledge, and it is the easiest one to leave for later. The play in the film puts both steps in one session: the agent draws the map, then it asks.

The prompt: draw the map, then ask

Switch the agent to plan mode first; the steps for each tool are in the table further down. In Claude Code’s terminal you can also start the prompt itself with /plan [5]. Then type the prompt from the film, word for word.

Type this in plan mode

Explore this repository. Change nothing. Draft a one-page map. Then ask me what the code could not tell you. One at a time, most important first.

The agent reads its way round the repository and comes back with a draft map: where things live, how the parts connect, how to build and test. Then it starts asking. Answer each question in a sentence or two and give the reason, because the reason is what lets the agent apply a rule to a case nobody wrote down. Anthropic’s prompting guidance makes the same point: Claude does better with the motivation behind a constraint than with a bare ban [6].

Run it with the people who hold the knowledge at the keyboard, or on a call with whoever does. If a question needs somebody else, say so and move on. The most important questions come first, so a session that ends early still leaves you with the answers that matter.

Why a map and an interview beat a blank file

Each part of the prompt does one job, and where the answers end up matters as much as the questions.

“Change nothing” makes the first pass safe: Plan mode already holds the agent back: Claude Code researches and proposes changes without making them [5], and Codex gathers context, asks clarifying questions and builds a plan before it changes anything [4]. Saying it in the prompt as well costs two words and leaves no doubt about what this session is for.
The map is the part the agent can do alone: Reading a whole repository is slow for a person and quick for an agent. OpenAI’s guidance for unfamiliar code is to have Codex explain the area and trace how it works before you change anything, and to keep asking until the explanation is specific enough that you would trust yourself to make the first edit [7]. That is a fair bar for the map. The one-page limit keeps it to the shape of the system rather than a tour of every file, and a draft gives your engineers something to correct, which is quicker than filling a blank page.
“What the code could not tell you” aims the questions: The phrase points the agent at the one category Anthropic says belongs in the file: what it cannot work out for itself [3]. Both vendors already recommend letting the agent interview you. Anthropic documents it for larger pieces of work, with Claude asking the questions and writing a spec [3], and OpenAI suggests it whenever you have only a rough idea [4]. Here the subject of the interview is the codebase itself.
One at a time, most important first: A single question lets each answer shape the next one, so an answer that a module is retired can lead straight to a question about what replaced it. The order means the session can stop early without losing what matters most.
Written once, read before every job: The film’s sceptic has a point: the team already has documentation for new joiners, and nobody reads it. The instruction file has a reader that opens it every time. Claude Code reads CLAUDE.md at the start of every session [1], Codex reads AGENTS.md before doing any work [2], and the project file is shared through source control [1], so one interview reaches every engineer’s agent.

What the questions should draw out

The film names three things the agent cannot see: what is retired, how the team likes code written and what is dangerous to touch. The vendors’ own lists add two more. This is why the code stays silent on each, and the kind of line each answer becomes.

What the interview should draw out, why the code cannot show it, and an example of the line each answer becomes in the instruction file
Dimension	Why the code cannot tell it	A line it might become
What is retired	Retired code can still compile, pass its tests and look like every other folder. The decision to stop using it was made in a meeting, not in the code.	“src/legacy/billing is retired. Do not import from it or extend it; new work goes in src/billing, because the old module is due to be deleted.”
How the team likes it written	The agent copies the patterns it finds, including the ones the team is moving away from. Anthropic says to keep rules that differ from defaults [3].	“Every new endpoint uses the error helpers in lib/errors. Do not throw raw strings, because the client parses our error shape.”
What is dangerous to touch	Nothing in a file marks the change that cannot be undone. OpenAI lists do-not rules as part of a good AGENTS.md [4].	“Ask before changing anything under db/migrations, because a bad migration cannot be rolled back in production.”
Commands it cannot guess	A build script can hide the one command that works on a laptop. Anthropic says to keep commands Claude cannot guess [3].	“Run make test-fast before you finish. The full suite needs staging credentials and runs in CI.”
What done means	The code shows what exists, not the bar a change has to clear. OpenAI’s list ends with what done means and how to verify it [4].	“A change is done when make test-fast and make lint pass and it has a test of its own.”

The example lines are illustrations, not a template to copy. What they share is that each names something checkable, which is Anthropic’s test for an instruction: “Use 2-space indentation”, not “Format code properly” [1]. Each also carries its reason [6]. Leave out what the agent can work out by reading the code, standard conventions it already knows and anything that changes often [3].

Write the page where every agent will read it

When the questions run out, have the agent write the map and your answers into the instruction file at the repository root: CLAUDE.md for Claude Code, AGENTS.md for Codex. If the file already exists, add to it rather than replace it. In Claude Code, approve the plan and choose to review each edit yourself [5]; in Codex, toggle Plan mode off with /plan or Shift+Tab [4].

Type this when the questions run out

Now write the map and my answers as one page in [CLAUDE.md or AGENTS.md] at the repository root. If the file already exists, add to it and keep what is there. Give the reason with each rule, and make every rule concrete enough to check.

Then treat the file like code. Open a pull request, ask the people who gave the answers to review it, and name an owner for later changes, which is Anthropic’s advice for any shared instruction file [8]. Keep it short. Anthropic’s target is under 200 lines per file, because longer files use more context and reduce adherence [1], and OpenAI’s advice is to keep AGENTS.md short and accurate [4].

From then on the file should grow from real mistakes rather than guesses. Anthropic says to add an instruction when Claude makes the same mistake a second time, or when a new teammate would need the same context [1]. OpenAI says to correct the agent when it gets something wrong and tell it to update AGENTS.md, so the fix carries into future sessions [4].

Variation: the repository already has a file

An old instruction file can do more harm than none, because it tells every agent with confidence how the code used to work. Point the same play at the gap between the file and the code.

Type this when a file already exists

Compare our instruction file with this repository. Change nothing. List what the file gets wrong, what is out of date and what it leaves out. Then ask me what neither the file nor the code could tell you. One at a time, most important first.

Make the corrections in the same pull request as the new answers. In Claude Code, running /init on a repository that already has a CLAUDE.md suggests improvements instead of overwriting it [1], which makes a useful second opinion beside this prompt.

Variation: one service in a large repository

In a large repository one page cannot map everything, and it should not try. Run the play on the folder a team owns and give that folder its own file.

Type this for one folder

Explore the [folder name] folder of this repository. Change nothing. Draft a one-page map of that folder only. Then ask me what the code could not tell you about it. One at a time, most important first.

Both agents read folder-level files. In Codex, AGENTS.md files in subfolders add local rules, and guidance closer to the folder you are working in wins [9]. Claude Code loads a CLAUDE.md in a subfolder once Claude reads, writes or edits a file there, and larger projects can split instructions into .claude/rules/ files that load only when Claude works on matching files [1]. Keep the root file for what applies everywhere.

Where it lives in Claude Code and Codex

The play needs two things from a tool: a plan mode for the first pass, and an instruction file the agent reads before it works. Claude Code and Codex both have both. Which of the two a team should standardise on is a separate question, which our guide to choosing between Claude Code and Codex answers.

Plan mode, the instruction file and its layers in Claude Code and Codex, as Anthropic and OpenAI document them
Dimension	Claude Code	Codex
Turn on plan mode	In the terminal, press Shift+Tab or start the prompt with /plan. In the desktop app’s Code tab, choose Plan in the mode selector next to the send button. Claude researches and proposes changes without making them [5, 10].	Type /plan or press Shift+Tab; OpenAI documents /plan in the desktop app, the Codex CLI and the IDE extension. Codex gathers context, asks clarifying questions and builds a plan before it changes anything [4, 11].
When the questions are done	Choose how the plan runs: approve it and continue in auto mode, approve it and review each edit yourself, or keep planning [5]. Reviewing each edit suits a file every agent will read.	Toggle Plan mode off with /plan or Shift+Tab, then ask Codex to write the file [4].
Where the page goes	CLAUDE.md in the repository root, shared through source control. Claude Code reads it at the start of every session [1].	AGENTS.md in the repository root, which sets team rules. Codex reads AGENTS.md files before doing any work [2, 9].
A starter file	/init analyses the codebase and writes a starting CLAUDE.md; if one exists, it suggests improvements instead of overwriting [1].	/init creates a starter AGENTS.md, which OpenAI calls a starting point to edit to match how your team builds, tests, reviews and ships [4].
Personal and organisation layers	~/.claude/CLAUDE.md for you across projects, CLAUDE.local.md for you in one project, and an organisation file deployed by IT. The layers are added together rather than overriding each other [1].	~/.codex/AGENTS.md for you. OpenAI documents no organisation-wide AGENTS.md; administrators use managed configuration, whose requirements users cannot override [9, 12].
One team, both agents	If a repository has an AGENTS.md and no CLAUDE.md, current Claude Code reads the AGENTS.md as its project instructions [1].	AGENTS.md is the default name, and a team can configure other file names for Codex to treat as instruction files [2].

Every row was checked on Anthropic’s or OpenAI’s own documentation on 11 October 2026. Commands and defaults change between releases, so check them against the version your engineers run.

Plan mode belongs to the coding agents. In Claude Cowork, Claude creates a plan when a task starts that you review and steer, and plan mode by that name is a Claude Code feature [5, 13]. For ChatGPT Work on the web, OpenAI’s advice is to ask for a plan in the prompt [11]. The play is built for Claude Code and Codex, because they are the tools that read the instruction file.

What goes wrong, and the honest limits

The play gets the knowledge out of two people’s heads and in front of every agent. It does not make the agent obey it, and it brings a few risks of its own, each with a simple counter.

It guides; it does not enforce: Anthropic treats CLAUDE.md as context rather than enforced configuration, with no promise of strict compliance [1]. OpenAI says to pair AGENTS.md with things that enforce it, such as pre-commit hooks, linters and type checkers, because written guidance guides rather than guarantees [9]. Write the dangerous-to-touch answers into the file, then back the ones that must hold every time with a hook or a permission, which Anthropic calls the real guardrails [8]. Code review stays.
Plan mode stops edits, not exploration: In plan mode Claude Code reads files and runs shell commands to explore, and writes its plan without editing your source [5]. That is what lets it draw the map, and it is why the prompt says “Change nothing” as well. Run the play on a clean branch, so anything a command changes in the repository is easy to throw away.
Long files get partly ignored: Anthropic’s target is under 200 lines, and if Claude keeps breaking a written rule, the file is probably too long and the rule is getting lost [1, 3]. Codex stops adding instruction files once their combined size reaches 32 KiB by default [2]. Test every line by asking whether removing it would cause mistakes, and cut it if not [3].
The map goes stale: Code moves faster than the file about it. Leave out anything that changes often [3], add a rule when the agent makes the same mistake twice [1], and have the file’s owner reread it whenever a module is retired or replaced.
An answer is only as good as the person giving it: The interview records what the person at the keyboard believes. If they guess, every engineer’s agent inherits the guess. Put the questions to the people who actually hold the knowledge, mark anything uncertain as uncertain, and have them review the pull request.
Nothing secret goes on the page: The file sits in the repository, so everyone with access to the code can read it, and so does every agent. No keys, passwords, customer data or names of people. Run the play in the Claude Code or Codex account your company administers rather than a personal one, because drawing the map means the agent reads your code.

Where 1AYM fits

Rolling out AI coding tools to engineering teams is core 1AYM work, and the shared AGENTS.md and review rules are part of it. On a rollout we would run this interview with the people who hold the knowledge, have the file reviewed like any other change, and turn the answers that must hold every time, such as what is dangerous to touch, into hooks, permissions and CI checks the system enforces. We sell it as AI Engineering Transformation, our AI harness and platform engineering work. The closest documented case is engagement file D-01: at a large international marketing agency we hold the lead architect role on its AI platform and contribute engineering to its internal Claude Code skill platform.

It can start small. 1AYM takes fixed-scope statements of work as well as larger builds, and fixed-scope work can start within a day of the scope being signed. If a second pair of eyes on your instruction files would help, book a call or email enquiries@1aym.com.

For engineers: how each agent loads the file, plan mode in detail and where enforcement lives

The loading rules behind the advice above, from Anthropic’s and OpenAI’s documentation as checked on 11 October 2026. Paths, limits and defaults move between releases.

How Claude Code loads CLAUDE.md: Four layers: an organisation file deployed by IT, ~/.claude/CLAUDE.md for you across projects, the project file in source control and CLAUDE.local.md for you alone. They are concatenated from the repository root down to the working directory, and a CLAUDE.md in a subfolder loads once Claude reads, writes or edits a file there. Files in .claude/rules/ load only for matching paths, and @path imports go up to four hops deep without reducing the context they cost [1].
How Codex finds AGENTS.md: Codex reads a global file from its home directory, ~/.codex unless CODEX_HOME is set, then walks from the project root, usually the Git root, down to the working directory, taking at most one file per folder: AGENTS.override.md, then AGENTS.md, then any configured fallback names. Files are joined root first, so closer guidance comes later and wins, and joining stops at project_doc_max_bytes, 32 KiB by default. The chain is built once per run, which in the terminal usually means once per session, so start a new session after the file changes [2].
One file for both agents: Current Claude Code reads AGENTS.md as the project instructions only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above [1], so one engineer’s CLAUDE.local.md switches the shared AGENTS.md off for them by default. CLAUDE.md can import other files with @path [1], which lets a team that also needs a CLAUDE.md pull the AGENTS.md in rather than copy it. Codex can treat other file names as instruction files through project_doc_fallback_filenames [2].
Plan mode, precisely: In Claude Code’s plan mode, Claude reads files, runs shell commands to explore and writes a plan without editing your source; claude --permission-mode plan starts a session in it [5]. In the desktop Code tab Shift+Tab does not cycle modes, so use the mode selector [10]. In Codex, /plan or Shift+Tab toggles Plan mode. OpenAI documents /plan in the desktop app, the CLI and the IDE extension, and calls Plan mode the easiest and most effective option for most users on difficult tasks [4, 11].
The interview pattern at full size: Anthropic’s best practices describe the larger version: Claude interviews you, writes a spec to a file, and a fresh session carries it out [3]. The play on this page is the same move aimed at the instruction file rather than one feature. Correct the map and the answers while they are still a plan, before anything is written to the file.
Enforce the dangerous-to-touch answers: Anthropic’s line is that anything that must happen every time belongs in a hook, because instruction files are advisory and hooks are deterministic [3]. In Claude Code a PreToolUse hook runs before a tool call and can block it, even in bypass-permissions mode, and a project’s .claude/settings.json can be committed so the team gets its hooks [14]. Codex hooks can also run before a tool is used, hooks delivered by an organisation are trusted by policy and cannot be switched off by the user, and OpenAI warns that a hook error or timeout can fail without blocking the action, so test the failure path [15].
Organisation-wide guidance: Claude Code supports an organisation-wide CLAUDE.md deployed by IT, which cannot be excluded, and Anthropic’s split is settings for technical enforcement and CLAUDE.md for behavioural guidance [1]. OpenAI documents no organisation-wide AGENTS.md. Codex administrators use managed configuration, whose requirements users cannot override, including managed developer instructions [9, 12].
Review rules live in the same file: Codex code review on GitHub follows a ## Code Review Rules section in the AGENTS.md closest to the code the rules govern, and OpenAI says those rules guide Codex and do not replace tests, branch protections or required approvals [16].
Memory is not the file: Claude Code’s auto memory is separate from CLAUDE.md, on by default in local sessions and stored on one machine; asking Claude Code to remember something saves it there, so ask for CLAUDE.md by name when a rule belongs to the team [1]. Codex Memories are off by default and stored locally, and OpenAI says to keep required team guidance in AGENTS.md and treat memories as a recall layer [17].

Sources

Questions engineering leads ask about AGENTS.md

What is AGENTS.md?

AGENTS.md is a markdown file of standing instructions for a coding agent, kept in the repository. Codex reads AGENTS.md files before doing any work, and OpenAI describes the format as an open-format README for agents. Its official site, agents.md, is stewarded by the Agentic AI Foundation under the Linux Foundation. Claude Code’s own file is CLAUDE.md.

What should an AGENTS.md or CLAUDE.md file include?

What the agent cannot learn from the code. OpenAI’s list for a good AGENTS.md is the repository layout, how to run the project, the build, test and lint commands, conventions, do-not rules, and what done means and how to verify it. Anthropic says to keep commands Claude cannot guess, rules that differ from defaults and gotchas, and to leave out what it can work out by reading the code, standard conventions and anything that changes often.

Does Claude Code read AGENTS.md?

Yes, when the repository has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. Anthropic’s docs say current Claude Code then reads AGENTS.md as the project instructions. A team using both Claude Code and Codex can keep one AGENTS.md, or keep a CLAUDE.md that imports it, because CLAUDE.md can import other files with @path.

Should I use /init to create AGENTS.md or CLAUDE.md?

Use it as a start, not the finish. In Claude Code, /init analyses the codebase and writes a starting CLAUDE.md, or suggests improvements if one exists. In Codex, /init creates a starter AGENTS.md that OpenAI says to edit to match how your team builds, tests, reviews and ships. Anthropic’s advice is to refine the result with what Claude could not discover for itself, which is what the interview prompt on this page collects.

How long should AGENTS.md or CLAUDE.md be?

Short. Anthropic’s target for CLAUDE.md is under 200 lines per file, because longer files use more context and reduce adherence. OpenAI says to keep AGENTS.md short and accurate, and by default Codex stops adding instruction files once they reach 32 KiB combined. The play on this page aims for one page: a map plus the answers the code could not give.

Will a coding agent always follow AGENTS.md?

No. Anthropic calls CLAUDE.md context rather than enforced configuration, with no promise of strict compliance, and OpenAI says written guidance on its own guides rather than guarantees. Rules that must hold every time belong in hooks, permissions, linters, tests or managed settings, with the instruction file explaining them.

What is plan mode in Claude Code and Codex?

A mode in which the agent researches and plans before it changes anything. In Claude Code you enter it with Shift+Tab or by starting a prompt with /plan in the terminal, or by choosing Plan in the desktop app’s Code tab. In Codex you toggle it with /plan or Shift+Tab, and OpenAI calls it the easiest and most effective option for most users on difficult tasks.

Where does AGENTS.md go in a monorepo?

One at the root for rules that apply everywhere, and one in each subfolder that needs its own. Codex reads them from the root down, and guidance closer to the folder you are working in wins. Claude Code loads a subfolder’s CLAUDE.md once it reads, writes or edits a file there, and can also load path-specific rules from .claude/rules/.