Lesson 7 of 8 · 12 min · Checked on 6 October 2026

CLAUDE.md and AGENTS.md: giving the agent context

By the end of this lesson you will be able to:

Write a short instructions file: what the project is, how to verify it and what never to do
Tell what should and should not go into that file
Put the file in the right place for Claude Code and for Codex
Use a single instructions file for both tools

At the bakery, the owner leaves a note stuck to the cupboard door for whoever comes to help on Saturday: “The big oven takes 40 minutes to heat up. The orders are on the top shelf. Never touch the till.” Whoever arrives reads the note and starts working without asking everything again.

The agent is the Saturday helper. Do not count on it remembering, from one session to the next, that the page is in European Portuguese, or that the opening hours are not touched without your say-so. Either you repeat everything in every session, or you leave a note on the door.

The concept: a note the agent reads on the way in

The note is a text file in the project folder. By default, the agent reads it on its own at the start of every session. It should answer three questions:

What this project is and which are the main files.
How to verify that it came out right.
What is never done.

Claude Code looks for a file called CLAUDE.md. Codex looks for one called AGENTS.md. The idea is the same; only the name changes. The .md means Markdown: plain text where # marks a heading and - marks an item in a list.

A complete example

Example

The AGENTS.md for the padaria folder, with fifteen lines:

# Padaria do Largo website

## What it is
A one-page site: opening hours, bread of the day and contacts.
Files: index.html (content) and estilo.css (look).

## How to verify
- After each change, show me the diff and tell me what I should see in the browser.
- The page must stay readable in a narrow window, like a phone's.

## Rules
- Always write in European Portuguese.
- Do not change the opening hours or the prices unless I ask.
- Never read or show the .env file.
- Before changing any file, show me the plan and wait for my reply.

What to put in and what to leave out

Put in:

what the project is, in two or three sentences;
the main files and what each one is for;
how to verify that it is right;
concrete rules that can be checked.

Leave out:

secrets (keys, passwords, tokens). The file goes into Git and goes to the provider in every session;
long texts. A page of bakery history takes up space and hides the rules that matter;
things that change every day, such as this week's to-do list;
what the agent finds out on its own by reading the files.

Tip

Start small, with 10 to 20 lines. Add a rule when you catch yourself correcting the agent for the second time on the same thing.

Tip

Write rules that can be checked. “Be clear” cannot be checked. “Answer in European Portuguese” and “show the plan before changing files” can.

Watch out

The instructions file is a request, not a lock. The Claude Code documentation says these instructions are context and not mandatory configuration: the agent almost always follows them, but it can fail. If something really must not happen, such as reading .env, also use a permission rule, as in the previous lesson. The file asks; the permissions decide.

How it is done today: where the files go

This is how it looks on 6 October 2026; your screen may differ. Look for the button with the same name. The ~ sign means your home folder.

Claude Code (official guide: Claude Code memory):

CLAUDE.md in the project root (or .claude/CLAUDE.md): the project's rules, shared with whoever works on it.
~/.claude/CLAUDE.md: your personal preferences, for all projects.
CLAUDE.local.md in the root: personal notes for this project only. Add it to .gitignore.

Codex (official guide: AGENTS.md in Codex):

AGENTS.md in the repository root: the project's rules. There can be others in subfolders, and the one closest to the folder where you work is read last.
~/.codex/AGENTS.md: your personal preferences, for all projects.

Both tools have the /init command, which reads the project and writes a first draft of the file. Review that draft and cut what you do not need.

Both tools on the same project

If you use both, write the rules once, in AGENTS.md. Then create a CLAUDE.md with this line:

@AGENTS.md

The line @AGENTS.md tells Claude Code to import the other file. Below it you can add rules for Claude only. By default, recent versions of Claude Code read AGENTS.md when there is no CLAUDE.md, but if both exist, they read only CLAUDE.md. This depends on the version and the settings; the import solves it regardless of either.

Agents can also keep their own notes between sessions, so-called automatic memory; that waits for Level 2.

Tip

The file is read when the session starts. After you change it, close the session and open another. In Claude Code, the /context command shows which instructions files were loaded.

Exercise

In the padaria folder, create the AGENTS.md from the example. If you use Claude Code, also create CLAUDE.md with the line @AGENTS.md.
Open a new session and ask: “What rules do you have for this project?”
Ask: “Change the colours of the page to autumn colours.”
If you like the result, make a commit of the new files, as in lesson 5.

How I know it worked in step 2, the agent sums up the rules from your file without you having written them in the conversation. In step 3, instead of changing at once, it first shows the plan and waits for your reply, in European Portuguese.

If it didn't work

The agent does not know the rules: check the exact name, with capital letters (AGENTS.md, CLAUDE.md), and that the file is in the folder where you opened the agent.
On Windows the file is called AGENTS.md.txt: turn on the option to show file extensions and change the name.
You created the file with the session open: close the session and open another.
Claude Code ignores AGENTS.md: put the line @AGENTS.md in CLAUDE.md and check with /context.
The agent knows the rule but does not follow it: rewrite it more concretely. If it really matters, add a permission rule.

Videos

**AGENTS.md e CLAUDE.md são Inúteis?**
Waldemar Neto - Dev Lab · 5 min · PT-BR · subtitles · Watch on YouTube
Summarises a study that tested AGENTS.md and CLAUDE.md in real projects: the results, the cost of unnecessary context and how to structure these files.

**The CLAUDE.md file**
Claude · 3 min · EN · subtitles · Watch on YouTube
An official Anthropic video: what to put in CLAUDE.md, how the file hierarchy works and how to keep it effective.

Test what you learned

1. Which of these lines is best to put in the bakery's instructions file? Do a good job and be careful. Before changing any file, show me the plan and wait for my reply. A three-page text about the history of the bakery since 1950.

2. The bakery page is going to use a service with an API key. Where does the key go? In AGENTS.md, so the agent always has it to hand In CLAUDE.md, but at the end of the file, where nobody reads In the .env file, which is in .gitignore; in AGENTS.md goes only the name of the variable

3. You use Claude Code at home and Codex at work, on the same project. How do you organise the instructions? Write everything in AGENTS.md and put the line @AGENTS.md in CLAUDE.md Write two files with different rules, one for each Write none: each agent learns on its own

Corrections to this lesson (1)

6 October 2026: After an external review: it now says «do not count on it remembering»; reading `AGENTS.md` is described as default behaviour that depends on the version and settings; links are named. Quiz options were reordered.