Keep CLAUDE.md under about 200 lines. Past that it eats context windowThe maximum amount of text a model can consider at once — its working memory for the current conversation or task.Full definition → and, the guide claims, Claude's adherence to the instructions actually drops — so a longer file buys you less compliance, not more.
The content test is specificity: build/test/lint commands, architecture decisions, non-obvious gotchas, naming and error conventions. Leave out anything a linter config should own, documentation you can link to, and paragraphs of theory.
Rule files take a YAML frontmatter 'paths' field. A rule scoped to src/api/ never loads while Claude edits a React component; rules without a paths field load every session, unconditionally.
Hooks exist because CLAUDE.md is a suggestion. The model follows written instructions most of the time, not every time — a agent hookA script the harness runs automatically at a fixed point in an agent's loop — before a tool call, after an edit, on session start.Full definition → is a shell script bound to a workflow event, so the linter or the notification fires without exception.
The two .claude folders serve different owners: the project one is committed team config, the home one holds personal preferences plus machine-local state like session history and memory.
Terms in this piece · Glossary
context window — The maximum amount of text a model can consider at once — its working memory for the current conversation or task.
agent hook — A script the harness runs automatically at a fixed point in an agent's loop — before a tool call, after an edit, on session start.
Why it matters
The reference for everything that lives in .claude — CLAUDE.md, custom commands, permissions, project setup — in one place. The fastest way to turn a default Claude Code install into one tuned to how you actually work.
Key quotes
“The .claude folder is the control center for how Claude behaves in your project.”
“Keep CLAUDE.md under 200 lines. Files longer than that start eating too much context, and Claude's instruction adherence actually drops.”
“CLAUDE.md instructions are good. But they're suggestions. Claude follows them most of the time, not all of the time.”
