What Is CLAUDE.md, and Why Does Claude Ignore Half of It?

Short answer: CLAUDE.md is a plain markdown file of instructions that Claude Code loads at the start of every session [1]. It works when it is short and specific. Past about 200 lines, Anthropic's own docs say Claude follows it less reliably [1].

Where CLAUDE.md lives

Claude Code looks for it in several places and loads all of them together, broadest first [1]:

  • Your user file, ~/.claude/CLAUDE.md, for preferences across every project.
  • The project file, ./CLAUDE.md, shared with your team through source control.
  • A local file, ./CLAUDE.local.md, for personal notes you don't commit.
  • A managed policy file, set by your company's admin.

Run /init to have Claude draft one from your codebase, and /memory to see which files loaded [1].

Why Claude ignores it

Two reasons, both in Anthropic's docs:

  1. It's context, not configuration. CLAUDE.md is delivered as a message after the system prompt, so there's no guarantee of strict compliance, especially for vague or conflicting lines [1].
  2. It got too long. Anthropic's target is under 200 lines per file; longer files "consume more context and reduce adherence" [1]. Their best-practices page puts it bluntly: if a line is getting lost, the file needs to be shorter [2].

Adding "IMPORTANT" in capitals doesn't fix it. If a rule truly can't be broken, Anthropic recommends a hook instead [2].

What to put in, and what to leave out

Put in what you'd otherwise re-explain [1]: build and test commands, conventions, decisions that aren't written down anywhere else, and anything you've had to correct twice [2].

Leave out what Claude can find by reading the repo [2], long procedures (make those a skill), and anything about your business that isn't about this codebase.

That last point is where most setups go wrong. Your pricing, your customers and your brand voice don't belong in one repo's CLAUDE.md. They belong in one company folder that every Claude session reads, in Code, in Cowork and in chat. Then CLAUDE.md can stay short: one line pointing at the folder, plus the rules for this repo. Our own index file is 39 lines.

Do it yourself, or have it done

Chet sets up that company folder (we call it Start) from your own documents, grades your Claude setup, and fixes what breaks. $99 a month, cancel anytime.

Maximize Claude with Chet: https://www.coworkers.global/get-chet?utm_source=blog&utm_medium=internal&utm_campaign=chet&utm_content=what-to-put-in-claude-md-cta

FAQ

Is CLAUDE.md the same as Claude's memory? No. CLAUDE.md is what you write. Claude Code also keeps an auto memory it writes itself, and loads the first 200 lines or 25KB of its index at the start of each session [1].

Does a long CLAUDE.md cost more? It's loaded in full every session regardless of length [1], so yes: every line takes context in every session.

Can one CLAUDE.md import another file? Yes, with @path/to/file, up to four hops deep [1].

Sources

  1. Claude Code docs, how Claude remembers your project: https://code.claude.com/docs/en/memory
  2. Claude Code docs, best practices: https://code.claude.com/docs/en/best-practices

Regards,

Charles Stack
Founder, Coworkers.Global

Coworkers.Global is not affiliated with Anthropic. Claude is a trademark of Anthropic, PBC.

Coworkers.Global is an AI staffing agency. We place managed agents into organizations that need dedicated expert knowledge work. A managed agent is an AI specialist provisioned for a specific role, trained on your context, supervised by a person, and accountable for its output. The first, Alex, evaluates startup business plans for fundability, informed by human expertise and research, and calibrated against real investor decisions. We are early-stage with paying clients, and we still lead with the quality of our judgment rather than customer logos. The managed AI staffing agency.
Get new posts by email

What we're learning building a startup with managed agents, plus notes on raising. Weekly newsletter, no spam.

Want more out of Claude today? Chet is available now, $99 a month. Every other role is on the waitlist.