You know an instruction file carries your rules into a fresh session. The question this page answers is the one that shows up about a month later, when you have three of them: a personal file with your style preferences, a project file describing the codebase, and a third file inside one subfolder. A rule goes in the wrong one and either never fires or fires on everything.

The idea

Instruction files have scope. A file in your home directory applies to every project on the machine. A file at the root of a repository applies to that project. A file inside a subfolder applies to work Claude Code does on files in that folder. What they do not do is override each other: Anthropic's memory documentation says every file Claude Code finds is added together into the session, outermost first, so a nested rule extends the root file rather than replacing it. Choosing the right file is choosing how often a rule loads and how much of your context budget it spends.

code
  ~/.claude/CLAUDE.md          every project, every session
        │                      "no emojis in my terminal output"
        +  added to
  repo/CLAUDE.md               this project, every session
        │                      "Postgres, not MySQL. Money in integer cents."
        +  added to
  repo/apps/docs/CLAUDE.md     loaded only when a file in apps/docs is read
                               "never publish internal dossiers"

  all of them in context at once, nearest read last ──────────►

How it works

Claude Code reads CLAUDE.md and does not read AGENTS.md. Several other tools, including Cursor and the OpenAI Codex CLI, read AGENTS.md. Both are plain markdown with no required structure, so if you use two tools, put the content in AGENTS.md and make CLAUDE.md a one-line @AGENTS.md import. That is one source of truth with two readers.

What belongs where:

  • Global file: things true of you, not of any codebase. Your preferred answer length. Your operating system. That you want commands handed to you one line at a time. If a rule would be strange advice on someone else's project, it is global.
  • Project file: things true of the repository and stable for months. The stack. Naming conventions. Which folder holds server-only code. The commands that verify a change. Facts that are expensive to rediscover, like "there is no /admin route despite three files referring to one".
  • Folder file: rules that only make sense inside one part of a project that holds several apps, especially hard prohibitions. A content directory with a never-publish rule is the clearest case.

The two upper files load at the start of every session and are paid for on every session. They consume space and, worse, they dilute the rules that matter. Twenty sharp lines get followed. Four hundred lines of aspiration get skimmed the same way you skim a terms-of-service page.

The folder file is the exception, and it is the reason to use one. Claude Code loads it on demand, when it actually reads a file in that directory, so a rule about apps/docs costs nothing on the days you never open apps/docs.

What to do

  1. Before writing a rule, ask how often it is true. Every project, this project, or this folder. Put it in the matching file and nowhere else. Duplicating a rule across two files means you will later fix one of them.
  2. Write rules that can be checked. "Run pnpm check before saying a change is done" is a rule. "Write clean code" is a mood.
  3. Once a month, delete. Any rule describing something the project no longer does is actively harmful, because the model believes it.
  4. Never put a secret, a password, or an API key in any of these files, the global one included. Two separate reasons, and either alone is enough. The project files get committed and pushed. And all of them, committed or not, are sent to the model provider in full, the two upper ones at the start of every session and the folder file the moment anything in that folder is read. All three land in transcripts. Name the variable instead: "the Resend key is in .env.local as RESEND_API_KEY".

Where it breaks

Because the files are added together rather than ranked, two rules that genuinely contradict each other are resolved by the model, in the moment, and it may go either way. The file nearest your working directory is read last, which usually helps and guarantees nothing. When you catch a conflict, fix the files. And when a rule does not seem to be firing at all, check that it loaded before you rewrite it. /context in Claude Code lists the memory files actually in the session, which is how you find out the folder file was never read. /memory lists file locations, including ones that do not exist yet, so it cannot answer that question.

A rule in a file is a strong prior competing with everything else in the session, not a guarantee. Short and concrete rules survive a long session; vague ones lose to whatever was said more recently. For anything where being wrong is expensive, a rule in a file is the weakest available tool. The next page, on checks that run by themselves, covers the stronger option.