CLAUDE.md, AGENTS.md and agent instruction files explained

You open a project and find a CLAUDE.md at the top. A teammate's branch adds an AGENTS.md. Someone else commits a GEMINI.md. None of them look like code, and none of them are a README, but they keep turning up.

Each one is an agent instruction file: a plain Markdown file that an AI coding agent reads before it works. It holds the things the agent can't guess from the code alone, like project rules, how to build and test, and the conventions your team follows. If you're new to the format itself, the post on what a .md file is covers the basics.

The files look alike, but each tool reads its own file name, looks in its own places and combines files in its own way.

Agent instruction files at a glance

File name	Read by	Where it goes	How files combine
CLAUDE.md	Claude Code	~/.claude/CLAUDE.md for all your projects; ./CLAUDE.md or ./.claude/CLAUDE.md in a project; ./CLAUDE.local.md for personal project notes	Files in the folders above your working folder load when a session starts; files in subfolders load on demand
AGENTS.md	Codex, and coding agents that follow the AGENTS.md format	Codex: a global file in ~/.codex, plus one file per folder from the project root down to the current folder	Codex joins files root first, and closer files override earlier guidance; the format says the nearest file takes precedence
GEMINI.md	Gemini CLI	~/.gemini/GEMINI.md, plus files in workspace folders and their parent folders, plus files found when a tool touches a folder	All found files are joined and sent with every prompt

Checked against each tool's public docs on 2026-10-19.

CLAUDE.md

Each Claude Code session starts with fresh context. CLAUDE.md files are instructions you write to give Claude persistent context from one session to the next.

There are a few scopes:

• User file at ~/.claude/CLAUDE.md: your preferences for all projects.
• Project file at ./CLAUDE.md or ./.claude/CLAUDE.md: shared with your team through source control.
• Local file at ./CLAUDE.local.md: personal notes for one project. Add it to .gitignore so it stays yours.
• Managed file: an organization can also set one file for everyone.

CLAUDE.md files in the folders above your working folder load when Claude Code starts. Files in subfolders load on demand.

Claude treats these files as context, not as enforced configuration, so a line in CLAUDE.md is guidance rather than a hard rule. A CLAUDE.md can also import another file by putting an @ sign directly before that file's path, and imported files also load at the start of a session.

Source: Claude Code memory docs

AGENTS.md

AGENTS.md describes itself as "a simple, open format for guiding coding agents." The idea is a predictable place for the context and instructions AI coding agents need.

The format draws a clear line between two files. README.md is for humans. AGENTS.md holds the extra context agents need, such as build steps, tests and conventions. There are no required fields. It's standard Markdown, and you can use any headings you like.

Larger repositories can hold nested AGENTS.md files for subprojects. Agents read the nearest file in the folder tree, so the closest one takes precedence. Explicit chat prompts override everything. The format is stewarded under the Linux Foundation.

Source: AGENTS.md format site

How Codex reads AGENTS.md

Codex reads AGENTS.md files before doing any work. It builds its instructions in layers:

1. Global file. In the Codex home folder (~/.codex by default), Codex uses AGENTS.override.md if it exists, and AGENTS.md if not.
2. Project files. From the project root down to your current folder, Codex takes at most one file per folder. In each folder it looks for AGENTS.override.md, then AGENTS.md, then any fallback names you've configured.
3. Joining. Files are joined root first. Files closer to your current folder come later and override earlier guidance.

Empty files are skipped. Codex stops adding files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default. That limit is one more reason to keep each file short.

Source: Codex AGENTS.md guide

GEMINI.md

Gemini CLI calls these context files, and the default name is GEMINI.md. They give project instructions, a persona or style guides.

Gemini CLI loads them in this order:

1. The global file at ~/.gemini/GEMINI.md.
2. GEMINI.md files in your workspace folders and their parent folders.
3. Just-in-time files, found when a tool touches a folder.

All the files it finds are joined and sent with every prompt. To see exactly what the model is getting, /memory show displays the joined content, and /memory reload scans again after you edit a file. Like CLAUDE.md, a GEMINI.md can import other files by putting an @ sign before a relative or absolute path.

Source: Gemini CLI GEMINI.md docs

Using one file for several tools

If your team uses more than one of these tools, you don't have to keep three copies of the same rules in sync. Each tool has a documented way to read a shared AGENTS.md:

• Claude Code can read a repository's AGENTS.md in place of CLAUDE.md, from v2.1.277 on, unless its built-in AGENTS.md support has been turned off. By default it does this only when there is no CLAUDE.md (or CLAUDE.local.md) in the working folder or above it. If your session reads only CLAUDE.md (an older version, that support turned off, or a few other cases the docs list), import the file from a CLAUDE.md instead, as the next item shows.
• Claude Code, with both files. To share one file and still add Claude-specific lines, put a CLAUDE.md next to AGENTS.md. In it, write a line with an @ sign followed by AGENTS.md, which imports the shared file, then add the Claude-specific lines below.
• Gemini CLI can read a different file name. Set context.fileName in settings.json, for example to AGENTS.md.
• Codex can read other file names too. Add them with project_doc_fallback_filenames in ~/.codex/config.toml.

With that in place, AGENTS.md holds the shared rules and each tool reads it, by default or through its own setting.

What to put in one

The tools differ on where the file goes, but some advice on what goes inside applies to all of them. For a longer guide to writing docs an agent can act on, see how to write Markdown docs your AI agent can follow. The short version:

• Keep it short. The Claude Code docs suggest under 200 lines per CLAUDE.md file. Longer files use more context and reduce how closely the agent follows them.
• Use headings and bullets. Group related instructions under Markdown headings, with one instruction per bullet.
• Write the build and test steps. The AGENTS.md format names these as extra context agents need, beyond what a README for humans holds. Give the exact commands.
• State your conventions. Naming, folder layout, the style your team agrees on.
• Remove contradictions. If two lines disagree, the Claude Code docs say the agent may pick one arbitrarily. Read the file top to bottom and settle the conflict yourself.
• Leave out secrets. No passwords, keys or tokens. A project CLAUDE.md is shared with your team through source control.

A small project file might look like this:

## Build and test

- Install: `npm install`
- Run tests: `npm test`

## Conventions

- Use TypeScript for new files.
- Keep components in `src/components/`.

Reading these files

Agent instruction files are plain Markdown, so any Markdown reader shows them. That matters because they change. You edit them, teammates edit them, and agents sometimes edit them too.

When you open one, a good reader should render the headings and lists cleanly, so you can scan the sections instead of reading raw syntax. It should also show you what changed since you last looked, so a new rule added by an agent or a teammate doesn't slip past you. The same habits help with the other files agents leave behind, like an agent handoff file or a plan you want to read without an IDE.

Where Sashmark fits

Sashmark is a Markdown reader and editor for people whose AI agents write Markdown, being built for Mac, Windows and Linux. It is in development and has not been released, and the app has no AI features of its own. Sashmark is being built to treat a CLAUDE.md, AGENTS.md or GEMINI.md as just another Markdown file to show and edit. It has no tie to any of the agent tools on this page.

A good reader should render these files cleanly and show what changed since you last opened them. Sashmark is being built for this; the roadmap shows where it stands. See the planned features for the rest.

Sashmark is in development. See what it is at sashmark.com.