Claude Code CLAUDE.md: Stop Retyping Your Project Rules

Every session, you retype the same context: the stack, the folder layout, how tests run. Claude Code still edits the wrong file, because none of that is written down anywhere it can read. One file fixes it — CLAUDE.md, generated by /init in your repo, loaded before you type a single prompt.

Claude Code is Anthropic's coding agent that runs in your terminal. Official documentation: Claude Code overview.

Run /init in your repo

/init is the first command to run inside a repository. Claude scans the code, then writes CLAUDE.md at the root with the things that matter most:

• the stack
• the folder layout
• the test command

bash
cd your-repo
claude
/init

That output is a draft, not a finished file. It gets you the structure in seconds instead of you writing it from memory.

What belongs in CLAUDE.md

The file is short on purpose. Four kinds of content carry almost all the value:

Stack. Which language, which framework, which package manager. If Claude has to guess between two, it guesses wrong.

Folder layout. Where routes live, where components live, where tests live. This is the difference between a correct edit and a plausible-looking edit in the wrong directory.

Commands. The exact test command, the exact dev command, the exact lint command. Not a description of them — the literal commands you run.

Never touch. The list of files and directories Claude must leave alone: generated output, migrations, vendored code, secrets, lockfiles you manage by hand.

The file loads at the start of every session, so you stop repeating yourself. That is the whole trick.

Use shift+tab for plan mode on big edits

For small changes, let Claude write. For anything large, press shift+tab to switch into plan mode.

In plan mode, Claude reads first, writes nothing, and shows you the steps it intends to take before any code changes. You approve the plan, then it works. This catches the expensive mistake — the one where it refactors three files you never asked it to open — before a single line is written.

The workflow that holds up:

1. shift+tab into plan mode.
2. Describe the change in one or two sentences.
3. Read the plan. Cut what you don't want.
4. Approve, and let it execute.

Plan mode costs you one extra read. It saves you a revert.

Write down what Claude must never touch

The "never touch" list is the part most people skip, and it is the part that prevents the worst outcomes. If a directory is generated, say so. If a config is hand-maintained, say so. If a migration file is frozen, say so.

Be literal about it. Naming the exact paths beats writing a general rule, because a general rule still leaves room for interpretation.

Why it works

CLAUDE.md sits in the repository next to the code it describes. It is versioned with everything else, so when the layout changes, the rules change in the same commit. Every session starts with it already in context, which means the first prompt you type is about the actual task instead of about setting the scene.

The order of operations that matters: write the file once, keep it current, and use plan mode for anything bigger than a single-file edit.

Get the template

The comment keyword on the video is CLAUDE — that gets you the CLAUDE.md template used in the demo. Full reference: Claude Code docs.

Quick recap

• CLAUDE.md is the project rules file Claude Code loads at the start of every session.
• Run /init in your repo — Claude scans the code and writes it: stack, folder layout, test command.
• Keep it to four things: stack, layout, commands, and files it must never touch.
• Press shift+tab for plan mode on big edits — Claude reads first, writes nothing, shows the steps.
• Version the file with the code so the rules stay true when the repo changes.