What is CLAUDE.md (and AGENTS.md)?

Claude Code reads CLAUDE.md files from several places: ./CLAUDE.md or ./.claude/CLAUDE.md for the project (committed and shared), ./CLAUDE.local.md for your own uncommitted notes, ~/.claude/CLAUDE.md for every project, and an organisation-wide managed file. Files in your working folder and the folders above it load at launch; files in subfolders load when Claude works there. An @path line imports another file, up to four hops deep.

AGENTS.md, which its site calls “a README for agents”, does the same job for Codex, Cursor, Gemini CLI and others. Since v2.1.277, Claude Code reads AGENTS.md when there’s no CLAUDE.md or CLAUDE.local.md in your working folder or above it. To use both, the documented pattern is a CLAUDE.md that imports it with an @AGENTS.md line.

Claude treats these files as context, not enforced configuration. Anthropic suggests staying under 200 lines per file, because longer files use more context and are followed less reliably.

This file is 126 tokens on OpenAI’s o200k_base tokenizer (Claude’s own tokenizer counts differently). It holds only what Claude can’t work out from the code: the commands, two architecture rules and a security rule.

Because it sits in the context, it goes out with every request: a 40-request session sends it 40 times, about 5,040 tokens, usually at the discounted prompt caching rate. Every line you add is paid for on every turn of every session, which is the best argument for keeping it short.

# Acme web app

Next.js app with a Postgres database. Package manager: pnpm.

## Commands
- `pnpm dev`: start the app on http://localhost:3000
- `pnpm test`: unit tests (Vitest); run them before every commit
- `pnpm lint --fix`: lint and format

## Rules
- Server-only code lives in `src/server/`; never import it from client components.
- Change the database with a new file in `db/migrations/`; never edit an old migration.
- Never commit `.env` files or print secrets in logs.

A good CLAUDE.md saves the turns Claude would spend rediscovering your build commands and conventions, and stops repeated mistakes. A bloated one costs tokens on every request and dilutes the rules that matter. For rules that must always hold, use a hook instead.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, but by default only when there’s no CLAUDE.md or CLAUDE.local.md in your folder or above it. Importing it from a CLAUDE.md with an @AGENTS.md line also works in sessions that can’t read AGENTS.md directly.

CLAUDE.md vs auto memory

You write CLAUDE.md. Auto memory is notes Claude writes for itself in a MEMORY.md file, of which the first 200 lines or 25 KB load each session.

CLAUDE.md vs system prompt

The system prompt is set by the app. CLAUDE.md is your project’s file that Claude Code adds to the context alongside it.

• Free toolCLAUDE.md Generator→Generate a CLAUDE.md and AGENTS.md for your project.
• Free toolAI Token Counter→Count tokens for GPT, Claude, Gemini, DeepSeek, Qwen and more.
• Guide · 12 min readHow to write a good CLAUDE.md, with a complete exampleWhat to put in CLAUDE.md, what to leave out, where Claude Code loads it from, how imports and AGENTS.md work, plus an annotated example and a before and after.
• Guide · 11 min readHow to reduce Claude Code token usage, and what each fix costs youCut Claude Code token use with /clear, /compact, model and effort choice, a lean CLAUDE.md, fewer MCP servers and subagents, and the trade-off of each.

• System promptA system prompt is the set of standing instructions a developer sends with every request to set a model’s role, rules and output format, kept separate from what the user types.
• Context windowA context window is the maximum number of tokens a language model can work with in one request, counting the system prompt, tool definitions, conversation history, documents and the reply it writes.
• Claude Code hooksClaude Code hooks are commands, HTTP calls, MCP tool calls, prompts or subagents that Claude Code runs automatically at fixed points in a session, such as just before a tool call, so a rule is applied every time.
• SubagentA subagent is a separate AI worker that a main agent hands a task to, running in its own context window with its own system prompt, tools and model, and returning only its result to the main conversation.
• Prompt cachingPrompt caching is an API feature that stores the processed start of a prompt, so later requests that begin with exactly the same tokens are billed at a much lower cached-input price and start answering sooner.

All 40 terms in the AI glossary