CLAUDE.md — the questions everyone asks.

CLAUDE.md is a markdown file named exactly CLAUDE.md that Claude reads at the start of every conversation. It carries the concrete context that should not have to be re-explained each session — your role, your workflow, your voice, your output rules. Without it, Claude treats every chat as a stranger: generic tone, generic defaults, generic examples. With a good CLAUDE.md, your message-one defaults are already correct — Claude matches your domain, your style, and your output format before you type a word.

The canonical location is a file named CLAUDE.md at the root of your repository — Claude Code picks it up automatically on every session in that repo. For subproject rules (a packages/api/ folder with its own conventions, a frontend/ folder with component patterns) drop a CLAUDE.md in that subfolder and Claude will load it when work in that subfolder is in scope. For defaults that should apply across every project you work on — your role, your voice, your general output rules — put a CLAUDE.md in your home directory at ~/.claude/CLAUDE.md.

No — they have different readers. A README is for humans browsing the repo: how to install, how to run the tests, what each module is for. CLAUDE.md is loaded into the model's context window on every conversation, so it should contain the rules Claude needs to behave correctly: tone, output format, what to never do, what to always do, project-specific gotchas. The README should link to CLAUDE.md and can summarize the most important rules, but it cannot replace it — humans skim, Claude reads every word.

Yes — Claude Code reads a repo-root CLAUDE.md on every session, deterministically, before any user message. Claude on the web and cowork use uploaded project versions of CLAUDE.md the same way. The catch is specificity: vague rules get ignored. "Be concise" will be forgotten by turn 3; "always end every reply with a one-line summary" sticks. CoworKit's Optimizer scores your file against actual readability signals and pinpoints which rules are too vague to survive — paste your existing CLAUDE.md into the Optimize tab to see the diagnostic.

Schedule a quarterly review tied to a real workflow change — a new repo, a new client type, a new tooling decision. In that review: trim rules that no longer match how you actually work, and rewrite rules that drift into vagueness. The Optimizer scores against fresh signals on every run, so re-running it after each quarter is the easiest audit. Add a one-line last_reviewed: 2026-08-02 header at the top of the file so the next review surfaces in your calendar. Stale CLAUDE.md files are silent — they keep getting read, but they stop being right.