Claude CodeLesson

CLAUDE.md

Every session starts knowing nothing about the project. CLAUDE.md is the one file it is sure to read first, so it is where the instructions every session needs belong, and nothing else.

Know CLAUDE.md already? Skip to In Terrarium.

Outside the box · General

The concept

Claude Code loads the CLAUDE.md at a project's root into every session, at the start and again after the conversation is compacted. You write it in plain Markdown: build commands, conventions, where things live, "always do X" rules. Claude reads it as context, not as enforced configuration. It tries to follow each line, and it follows short, concrete, consistent lines best.

So the docs send everything else elsewhere. A procedure, or an instruction that matters for only one part of the code, goes in a or a path-specific . Something that must happen at a fixed point whatever Claude decides, such as checking every shell command before it runs, goes in a hook.

A first CLAUDE.md in your own project's root can be this small:

# CLAUDE.md

- Run `npm test` before you commit.
- API handlers live in `src/api/handlers/`.
- Before you change the database schema, read `docs/migrations.md`.

Full referenceClaude Code docs: How Claude remembers your project

Looking inside

In Terrarium

Every Terrarium session, whether a person started it or a schedule did, begins with CLAUDE.md. It opens with the house style: write the least code and the fewest words that stay exact. Everything after that is short sections of instructions every session needs.

The section that does most of the work names when to read each doc rather than copying the doc in. A trigger binds a doc to an action:

CLAUDE.md ↗19–24as of 1 Nov 2026

19- **Before your first git command** beyond the read-only `status`, `diff`,
20  `show`, `ls-tree`, `cat-file`, `grep` and `ls-files` (commit, fetch, pull,
21  rebase, amend, reset, or `log`/`blame` to draw a conclusion):
22  `docs/agents/git-conventions.md`.
23- **Before your first GitHub operation** (`mcp__github__*` tool or `gh`):
24  `docs/agents/github-integration.md`.

The docs themselves sit in docs/agents/, and only the sessions that reach a trigger read its doc. Rules and Skills stay out of CLAUDE.md, which only points to them. Instructions about particular files are rules in .claude/rules/, which Claude Code loads when an agent reads or edits those files; the summary of each is a rule too. Procedures are Skills in .agents/skills/.

A trigger is still prose, and an agent can act before it notices one. For some triggers, scripts/hooks/read-first-hint.ts is a backstop: at the first matching call it adds a pointer to the doc, beside that call's result. It can't stop the call, and it stays silent once the doc has been read. .claude/settings.json wires it in behind a short shell filter, scripts/hooks/read-first-hint.sh, which runs it only for a call that could match a trigger, such as a git, GitHub or screenshot call.

Why it's built this way

Short on purpose. Every session reads all of CLAUDE.md, often skimming, and it had grown with rules, incident stories and copies of other docs. A cut it to rules that came from a serious problem and have no other home. The cost: an old mistake can return; the later sessions log catch it. ADR-0027 (docs/adr/0027-prune-trials.md).
Triggers, not topics. Agents mostly skipped a read-first list grouped by topic and a line to read every ADR, so edits missed the ADRs that bound them. Each entry is now a trigger tied to an action: "before you do X, read Y". Lines tied to a file became rules, for the reason Path-specific rules gives.
A hint at the first call. Even with triggers, many sessions read the git or GitHub doc just after their first call, one only after a broad search had filled its context, the text the model holds at once. A hook now points to the doc at that call. The cost: it never blocks, so that first call still runs before the doc is read. scripts/hooks/read-first-hint.ts.

What to watch for

Loaded is not obeyed. A line can load and still be skipped. Where a slip is costly, Terrarium backs the line with something that runs: a hint or a guard (a hook that adds advice or refuses a call, see Claude Code hooks), or the .
Each incident tempts a new line. Lines added after every mistake bury the ones that matter. Terrarium tests a line by removing it in a ; the open trials are listed in .agents/prune-trials.yml.
A rule can't order a step. A rule loads only after its file is touched, so it can't say "before you touch it". A "before you do X" instruction stays in CLAUDE.md, however file-bound it looks. ADR-0029 (docs/adr/0029-instructions-load-with-the-files-they-govern.md).

Try it in your project

Find the doc your agent most often forgets. Add one line to your CLAUDE.md that names the action and the doc ("Before you change the schema: read docs/migrations.md"), then delete any paragraph of CLAUDE.md that only repeats that doc.

Where next

Walkthroughs through this Lesson

WalkthroughAsking an agent for a change

Last updated 1 Nov 2026 · Latest source on GitHub ↗