Skip to content
bits
Sign in
Work with coding agents · Lesson 2 of 7 · 7 min

The file it reads every time

Tutor:

Every Claude Code session starts fresh. It doesn't remember yesterday's chat. What it does read, every single time, is your project's context file: CLAUDE.md at the root of the repo. It's plain markdown, and it goes into the context window before your first message.

Tutor:

Think of it as the note you'd leave a capable new colleague on day one: how to run things, the house rules, and the traps. Not a tour of the codebase; they can read that themselves.

Where it lives (checked November 2026):

  • ./CLAUDE.md in your project, shared with your team through git.

  • ~/.claude/CLAUDE.md for your own habits across every project.

  • ./CLAUDE.local.md for personal notes on one project (add it to .gitignore).

Many tools share a file called AGENTS.md. Claude Code reads it when the project has no CLAUDE.md.

Tutor:

What earns a line? Anthropic's guide keeps it to facts Claude needs every session: build and test commands, conventions, "always do X" rules, and the gotchas it can't work out from the code. Aim for under 200 lines; a long file costs context and gets followed less.

What doesn't: anything Claude can read for itself (folder layouts, dependency lists, an architecture essay), and long step-by-step procedures, which belong in a skill (lesson 4). A good habit, from the docs and from Matt Pocock's AGENTS.md guide: when you correct Claude for the same thing twice, add one line.

Bloated vs Leanillustrative: made-up numbers that show the idea, not output from a real modelcompare

promptPart of a CLAUDE.md for Moon Café's site

Bloated

This is a website for Moon Café, a café that opened in 2019. The src folder contains the source code. The tests folder contains the tests. We use TypeScript, which is a typed superset of JavaScript. Please write good, clean code and follow best practices at all times.

Lean

Use pnpm, never npm. pnpm test runs vitest; run it before you say you're done. Never edit src/generated/: run pnpm codegen instead. Ask before running pnpm deploy.

Tutor:

Every line on the right changes what the agent does. Most lines on the left change nothing, or tell it what it can already see.

Tutor:

You can generate a starting file with /init, which reads your codebase and drafts one, then trim it. To see what's loaded, run /memory.

Your turn. Write a short CLAUDE.md for Moon Café's site from these facts: the project uses pnpm (not npm), pnpm test runs the tests, files in src/generated/ are made by pnpm codegen and must never be edited by hand, and deploys need a human's OK. Then, on the last line, ask what an agent would: how do I run the tests? Claude here answers from your file, the same way Claude Code would.

Your turn

Goal Write a short context file with only what an agent needs every session, and see Claude answer from it

What good looks likeThe coach checks the reply
  • Says to use pnpmnot checked yet
  • Gives the test commandnot checked yet
  • Protects the generated filesnot checked yet
  • Keeps deploys humannot checked yet
  • Asks how to run the testsnot checked yet
  • Ran at 1.0not checked yet
  • Answers with pnpm testnot checked yet
  • Shortnot checked yet
  • Every line is something the agent couldn't see for itself in the codenot checked yet
  • Has no generic advice like “write clean code”nice to have
  • Answers with the pnpm command, not npm or a guessnot checked yet

Run your prompt and the replies land here.

    ~0 tokens

    Turn on JavaScript to run prompts.

    Tutor:

    Now delete the pnpm test line and ask again. What does Claude have to guess this time?

    Down the rabbit hole