How do you write an AGENTS.md or CLAUDE.md file?

A coding agent starts every task knowing nothing about your project. It can read the code, but it can't guess that tests run with a particular command, that one folder is generated and must not be edited, or that your team writes commit messages a certain way. An instructions file fixes that. Claude Code automatically loads a file called CLAUDE.md into its context at the start of a session. OpenAI's Codex reads AGENTS.md files in the repository for the same purpose. Think of either one as a README written for the agent rather than for a new colleague.

Neither file has a required format. Anthropic recommends keeping CLAUDE.md concise and readable by humans, and OpenAI describes AGENTS.md as a text file much like a README. Plain Markdown with short headings and bullet points works well for both.

What belongs in it

Anthropic's list of useful content is a good checklist for either file:

• Project overview: two or three sentences on what the code does and how it is laid out.
• Commands: how to install, build, test, lint and type-check, written exactly as you would type them.
• Code style: the conventions that matter and that a linter doesn't already enforce.
• Testing instructions: which tests to run, and when.
• Repository etiquette: branch names, commit messages, pull request descriptions.
• Warnings: anything surprising, such as a slow test, a folder that is generated, or a file that must not change.

A worked example

Here is a complete file for an imaginary small web app, an event calendar for a regional tourism site. Every name and command is illustrative; use your own.

# Project
Event calendar for a regional tourism website. Python 3.12, Flask, SQLite.
- app/        web routes and templates
- app/models  database models
- tests/      pytest tests
- static/gen/ GENERATED by the build script: never edit by hand

# Commands
- Install: pip install -r requirements.txt
- Run locally: flask --app app run
- Test everything: pytest
- Test one file: pytest tests/test_events.py
- Lint: ruff check .

# Rules
- Every page must work in French and English; text goes in app/i18n/, never hard-coded.
- Dates are stored in UTC and shown in local time.
- Write or update a test for every bug fix.
- Don't add new dependencies without asking.

# Before you finish
- Run ruff check . and pytest; both must pass.
- Commit messages: short imperative summary, e.g. "Fix date filter on event list".

# Secrets
- Keys and passwords live in environment variables (see .env.example for the names).
- Never print, log or commit their values.

Save it as AGENTS.md, CLAUDE.md, or both (see below). The "Before you finish" section is worth having: the Codex system message OpenAI published tells the agent that when an AGENTS.md file contains programmatic checks, it must run all of them after making its changes.

Where to put it, and how far it reaches

Both tools let you use more than one file.

• Claude Code reads CLAUDE.md at the root of your repository (commit it so the whole team shares it), files in parent folders, files in subfolders when it works there, and a personal ~/.claude/CLAUDE.md that applies to all your projects. A CLAUDE.local.md, kept out of Git, holds personal notes. The /init command drafts a first version for you, and pressing # during a session adds an instruction to the file.
• Codex follows rules in the published system message: an AGENTS.md file applies to the whole folder tree it sits in, a more deeply nested file wins when instructions conflict, and direct instructions in your prompt take precedence over the file.

To serve both agents from one project, keep a single source. One simple approach: put the full content in AGENTS.md, and make CLAUDE.md a one-line note asking the agent to read and follow AGENTS.md. Test that each tool actually follows it before relying on the arrangement.

Keep it working

Anthropic suggests treating the file like any prompt you use often: refine it, see what improves the agent's behaviour, and cut what doesn't. Its engineers sometimes add emphasis such as "IMPORTANT" to rules that were being ignored. A practical habit: when the agent makes the same mistake twice, add one clear line to the file, and when a line is obsolete, delete it. A short file that is accurate beats a long one that is half out of date.

What should never go in it?

Secrets, first of all. No API keys, passwords, tokens, database connection strings with credentials, or private certificates. The file is meant to be committed to Git, and OpenAI's guidance on key safety notes that committing keys to source code is a common way they leak, especially in public repositories, though private ones can be exposed too. The file is also loaded into the model's context on every task. Name the environment variables the code expects, as in the example, and keep the values out of the repository.

Personal or client data should stay out as well: real customer names, email addresses, phone numbers or extracts from a production database. If the agent needs sample data, point it to a fixtures folder with invented records.

Leave out instructions that weaken safety, such as "always skip permission checks" or "push directly to main." Anthropic warns that letting Claude Code run commands without permission checks risks data loss and attacks hidden in content it reads, and advises doing it only inside a container without internet access. A decision that big belongs in how you launch the tool, not in a file every session reads by default.

Finally, avoid anything you would not want a new teammate to read on their first day. If it would be inappropriate in the README, it is inappropriate here.