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

Date: 2025-06-10 · Author: Robert Scales · https://guidetoartificialintelligence.com/en/learn/write-agents-md-claude-md-file/

**Answer:** Write a short plain-text Markdown file at the root of your repository that tells a coding agent what the project is, which commands build and test it, and which rules to follow; name it AGENTS.md for OpenAI's Codex or CLAUDE.md for Anthropic's Claude Code. Keep it brief and specific, update it when the agent makes the same mistake twice, and never put passwords or keys in it.

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.

```markdown
# 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.

> **Try it:** Open a project you know and write the "Commands" section only, from memory. Then run each command exactly as written. Any line that fails or needs an extra step is a line an agent would have got wrong too.

## 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.

## Sources

- Claude Code: Best practices for agentic coding: https://www.anthropic.com/engineering/claude-code-best-practices
- Introducing Codex: https://openai.com/index/introducing-codex/
- Best Practices for API Key Safety: https://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety