The six-line project CLAUDE.md (with the real file)

Six load-bearing lines

A global inventory tells Claude what exists on the machine — and Claude will still reach for the wrong tool, because nothing tells it what this project demands. In a static-HTML practice repo it will happily suggest npm install, since npm really is on the shelf. The fix isn't paragraphs of guidance; it's a short file at the project root where every line earns its place. Six lines, written well, beat six hundred written hopefully.

A project CLAUDE.md lives at ./CLAUDE.md (or ./.claude/CLAUDE.md) and loads into every session you start inside that project — after the global inventory file, so the most specific instructions are the last thing Claude reads. Where the global file catalogs, this file commands. The template has six slots:

1. 01Stack lock — what this project is built with, and what it is not
2. 02Package manager — the one allowed install command
3. 03Test gate — what must pass before anything is called done
4. 04Style rule — the convention that protects the design system
5. 05Banned thing — the one mistake you never want to see again
6. 06Tone rule — how the words should read

A real project CLAUDE.md example

Here's the whole rulebook for studio-demo, a practice folder holding a three-file static site — it fits in one cat:

# studio-demo

- Stack: static HTML + CSS only. No frameworks, no build step, no JavaScript.
- Package manager: pnpm only — never npm install or yarn add.
- Before claiming done: open index.html in a browser and check it renders.
- Styling: use the CSS variables in style.css — no inline style attributes.
- Banned: emojis anywhere in markup or copy.
- Tone: plain English copy, no marketing superlatives.

Writing yours takes five minutes, and proving it works takes two more:

1. 01Create CLAUDE.md at the project root — next to index.html, not in a subfolder. Claude finds it by walking up from wherever you launch.
2. 02Fill the six slots, adapting each line to the project. Be concrete enough to verify — the docs' own example of a good instruction is "use 2-space indentation", not "format code properly".
3. 03Trip a constraint on purpose: claude -p "I was about to run npm install date-fns in this project. Anything wrong with that? Two sentences max." — then watch which lines fire.

Same question, two answers

Both answers below are verbatim from two runs of that exact question — same model, identical copies of the project, except one copy has the CLAUDE.md deleted. First, the control:

Nothing wrong with the install itself — there's no lockfile yet, so npm is
as good a choice as any and it'll just create package-lock.json. The real
catch is that this project is plain static HTML/CSS with no bundler, so the
installed package won't be importable from index.html without adding a
build tool...

Yes, two problems: this project's CLAUDE.md mandates pnpm only (never npm
install), and it's a static HTML + CSS project with no JavaScript or build
step, so date-fns can't be used here anyway. If you need date formatting,
write the dates into the HTML directly.

Claude doesn't grumble vaguely — it cites the pnpm mandate and the stack lock, then proposes the compliant path instead. Six lines changed the answer; that's the deletion test passing in public. The same demonstration fits in a card deck at the six-line project CLAUDE.md.

Why short files win

The failure mode of project CLAUDE.md files is length. These files are context, not configuration — Claude weighs them the way you weigh a long brief, which means a 600-line file gets skimmed, and your one critical rule sits in paragraph forty hoping to be noticed. The docs put a number on it: past roughly 200 lines, adherence measurably drops. Every line you cut makes the survivors louder.

Knowing what to leave out is half the craft. Secrets never go in — the file ships with the repo. Multi-step procedures don't belong either; a deploy runbook is a skill, loaded only when invoked instead of taxing every session. And anything that must happen every time — formatting after each edit, a check before each commit — eventually graduates from instruction to hook, because an instruction is a request and a hook is a guarantee. What remains in CLAUDE.md is the judgment layer: the constraints Claude must hold in mind while it works.

The scoping logic cuts the other way too. Want Claude to stop suggesting npm install in one specific repo? The line goes here, not in the global file — put it in ~/.claude/CLAUDE.md and it poisons every repo where npm is fine. The global file states facts that hold everywhere; the project file states the commands and constraints this codebase demands. That division — global says what exists, project says what to use — is the entire two-file system.

When a project genuinely needs more than six lines, the answer is still not prose — it's structure. The grown-up version of this pattern steers a production monorepo, and it scales by adding sections of locks, not paragraphs of advice:

## Stack constraints (locked)

- **Framework:** Next.js 16 App Router. No mixing with Astro/SvelteKit/Vite.
- **Package manager:** pnpm 10.x. No `npm install` or `yarn add`.

## Test before shipping

- `pnpm --filter=<app> typecheck` clean before any commit
- Don't claim "fixed" without verifying — type-check ≠ feature works

Same six slots, scaled up: locks, gates, bans. Still scannable in one screen, still passing the deletion test line by line.

Two pointers before you write yours. /init will draft a starting CLAUDE.md by analyzing an existing codebase — a reasonable seed, which you then cut down with the deletion test. And for personal notes that shouldn't ship to teammates, CLAUDE.local.md loads alongside the project file and belongs in .gitignore. Load order across the directory tree, the 200-line guidance, and path-scoped rules in .claude/rules/ are all in the memory docs.