What should I put in a CLAUDE.md file?

Start with three things: one line on what the project is and what it is built with, the few commands used daily for building, testing and linting, and caveats that are not obvious from the code. Keep detail that applies only to some tasks in separate files referenced from CLAUDE.md or in path-scoped rules.

How long should CLAUDE.md be?

As short as you can make it. The video suggests staying under 300 lines and ideally far less, because every line loads into every session and models follow instructions less reliably as their number grows. Cutting a vague line is usually worth more than adding a new one.

Should I put code style rules in CLAUDE.md?

Generally no. A linter or formatter enforces style deterministically and costs no context. Name the tool or command in CLAUDE.md, or add a PostToolUse hook that runs the formatter after each edit so Claude's changes always match.

All video notes

Video notes · Claude Code memory

Stop Writing Bad CLAUDE.md Files

Video by camelCase on YouTube · 15 min · uploaded February 2026

Notes and analysis by BrainTube, written from the video. Not affiliated with camelCase. Watch on YouTube

In short

The video argues that every line in CLAUDE.md costs instruction-following quality on every prompt, so the file should be short and hand-written. It recommends three sections (a one-line project summary, key commands and caveats) and moves everything else into referenced docs, path-scoped rules and hooks. The advice is sound; the numbers behind it are rough, and the case against /init is stronger than it needs to be.

The argument

Claude starts every session knowing nothing about your project, and CLAUDE.md is the only thing it reads every time. That makes it powerful and dangerous. A bad line in code breaks one place, but a bad line in CLAUDE.md affects every action Claude takes, for every developer on the team. Models can only follow so many instructions before all of them get followed worse, so the file should hold only what applies to most tasks. Anything else should load only when relevant, through referenced files, rules scoped to paths, or deterministic tools such as linters and hooks. The creator adds that most of this applies equally to AGENTS.md for Codex, Cursor and similar agents.

Key ideas, with timestamps

1:06
An instruction budget
He says top models follow roughly 150 to 200 instructions with reasonable consistency, smaller models fewer, and that Claude Code's own system prompt already uses about 50. Company-managed instructions eat more. His point is that going over the budget does not drop the extra rules cleanly; quality falls across all of them. He suggests under 300 lines, ideally much less.
2:43
Do not let AI write it
He advises against /init and AI-generated CLAUDE.md files because they come out long, vague and sometimes wrong. A frequent offender is code style, which /init likes to add. The underlying rule applies to anything you write by hand too: each line is paid for on every prompt.
4:56
Linters, not style rules
Telling Claude to use two-space indents and single quotes turns it into an expensive, unreliable linter, and CI will still fail on small slips. Claude usually copies existing style anyway. Instead, name the tool (Biome, or npm run lint before a commit) or, better, add a PostToolUse hook in the .claude settings file that runs the formatter after every edit.
6:01
Three sections that belong in every file
Start with one line on what the project is, such as a customer-facing payment portal built with Next.js. Then the few commands used daily for build, test, lint and type check, so Claude can check its own work. Then caveats that are not obvious from the code, such as never editing schema.prisma directly or a webhook route that needs the raw body.
8:47
Progressive disclosure
Detail that matters only sometimes, such as a database schema, goes in its own file like docs/schema.md, with one line in CLAUDE.md saying when to read it. He admits Claude may read it when it does not need to, or skip it when it should.
9:19
Path-scoped rules
Files in a rules folder inside .claude are always read, which helps organisation but not context size. Adding a path pattern at the top of a rule file, such as one matching spec.ts files, makes Claude load it only when working on matching files. This is the most useful feature in the video for keeping context small.
10:27
Why Claude still ignores instructions
Claude Code wraps CLAUDE.md in a system reminder saying "this context may or may not be relevant to your tasks", as he reads it. Models also weight the start and end of the input more than the middle. So put the most important lines first, and use emphasis such as IMPORTANT or MUST sparingly.
11:32
A living file, and where it lives
Update CLAUDE.md the moment you catch a wrong assumption, for example tagging Claude in a pull request review to add a rule, and audit it monthly. From 12:38 he covers locations: parent folders are read for monorepos, subfolder files load when Claude works there, a gitignored local file holds personal settings, and a file under the home .claude folder applies everywhere.

What it gets right

The main argument is right and often ignored. CLAUDE.md is a cost paid on every turn, so it should be written like a config file, not like documentation. The three-section template of summary, commands and caveats is a good default, and the caveat examples are exactly the kind of local knowledge a model cannot infer from code.

Moving style rules to linters and hooks is the strongest practical tip. It replaces a probabilistic instruction with a deterministic tool, saves context, and stops CI failures that come from the model drifting. The same reasoning applies to any rule a script can check.

Path-scoped rules are the right answer to the obvious objection, which is that real projects have real detail. Detail tied to a part of the codebase can load only when Claude is working there.

What it leaves out or overstates

The numbers are rough. The 150 to 200 instruction figure and the count for Claude Code's system prompt are given without a source in the video. Treat them as orders of magnitude, not limits. The direction is well supported; the exact cutoff is not. Line counts are a weak proxy too, since one dense line can hold several rules.
/init is a fine first draft. Running it and then deleting most of the output is faster than starting from nothing, and it often finds the build and test commands correctly. The real rule is to prune hard and never ship it unread.
No way to test. The video never checks whether a change helped. A simple method is to pick a few tasks Claude got wrong, change one line, and re-run them.
Personal versus shared memory. It does not mention Claude Code's auto memory, which writes notes on its own, or how to keep those from piling up into the same bloat. File locations and the local-file option are as of the February 2026 upload and have changed between versions, so check the current docs.
Emphasis wears out. Capitals and MUST help a little, but a file full of them is back to everything weighted the same.

How this applies to memory across AI tools

The video treats CLAUDE.md as memory, and the lesson generalises. Memory that is always loaded must be tiny, and everything else should be fetched when relevant. That is the same split as persistent memory versus the context window: a small working set in context, a larger store searched on demand.

CLAUDE.md is per project and per client. Knowledge that is not about a codebase, such as notes on talks, articles or docs you have read, does not belong in it at all. BrainTube saves YouTube videos with their transcripts, articles, PDFs and podcasts into one compiled knowledge base and exposes it as an MCP server, so Claude, ChatGPT, Cursor and other MCP clients can search it when a task calls for it instead of carrying it in every prompt. For local tools that manage Claude Code memory, see Claude Code memory tools.

Who should watch it

Watch it if you use Claude Code, Codex or Cursor on a real codebase and your CLAUDE.md or AGENTS.md has grown past a page. The core is short: 1:06 for the instruction budget, 6:01 for the three sections, and 8:47 to 10:27 for progressive disclosure and path-scoped rules. Skip 3:49 to 4:56, which is a sponsor segment. If you already use rules folders and hooks, the only new material may be the point at 10:27 about where in the file instructions land.

Frequently asked

What should I put in a CLAUDE.md file?: Start with three things: one line on what the project is and what it is built with, the few commands used daily for building, testing and linting, and caveats that are not obvious from the code. Keep detail that applies only to some tasks in separate files referenced from CLAUDE.md or in path-scoped rules.
How long should CLAUDE.md be?: As short as you can make it. The video suggests staying under 300 lines and ideally far less, because every line loads into every session and models follow instructions less reliably as their number grows. Cutting a vague line is usually worth more than adding a new one.
Should I put code style rules in CLAUDE.md?: Generally no. A linter or formatter enforces style deterministically and costs no context. Name the tool or command in CLAUDE.md, or add a PostToolUse hook that runs the formatter after each edit so Claude's changes always match.

Keep videos like this one searchable

BrainTube saves YouTube videos with their transcripts into one compiled knowledge base that Claude, ChatGPT, Cursor and other MCP clients can search.

Start free

Stop Writing Bad CLAUDE.md Files

In short

The argument

Key ideas, with timestamps

An instruction budget

Do not let AI write it

Linters, not style rules

Three sections that belong in every file

Progressive disclosure

Path-scoped rules

Why Claude still ignores instructions

A living file, and where it lives