Workbranch › Guides

How to write a CLAUDE.md file for Claude Code

Every Claude Code session starts with an empty context, so you end up repeating the same build commands and house rules. A CLAUDE.md file fixes that. This guide covers where it goes, what belongs in it, and how to check that Claude is actually reading it.

Updated 30 October 2026

Locations and commands below were checked against Anthropic's Claude Code documentation as of October 2026. If something is missing in your version, run claude update.

Where CLAUDE.md files live

You can have several files, each with a different reach. Claude Code combines them all instead of letting one replace another; the more specific ones are read last.

Files in the folder you launch from and every folder above it load at startup. A CLAUDE.md inside a subfolder loads later, once Claude reads or edits a file in that subfolder.

Create the file with /init

1. Open a terminal in the project's root folder and start claude.
2. Type /init. Claude looks through the codebase and writes a starter CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting it.
3. Read the draft and delete anything obvious or wrong.
4. Add what Claude can't discover from the code: decisions, environment quirks, "never do X" rules.
5. Commit the file so teammates get the same instructions.

To edit later, run /memory. It lists your CLAUDE.md and CLAUDE.local.md locations for user and project scopes, including ones that don't exist yet, and opens the file you pick in your editor. You can also just say add this to CLAUDE.md.

What to put in it

A simple test: if you have had to tell Claude something twice, it belongs in the file. Typical moments to add a line: Claude repeats a mistake, a code review catches something it should have known, or you type the same correction you typed last session.

• Commands: how to build, test, lint and run the project.
• Layout: where key code lives, such as API handlers are in src/api/handlers/.
• Conventions: naming, formatting, branch and commit rules.
• Hard-won facts: things that would trip up a new teammate.

Write rules you could check. Run npm test before committing works better than test your changes. Group lines under headings and bullets, and remove instructions that contradict each other, because Claude may follow either one. Multi-step procedures or rules that matter for one part of the codebase belong in a skill or a path-scoped rule instead.

Keep it short and organized

• Size: aim for under 200 lines per file. Longer files take more context and are followed less reliably.
• Imports: write @README or @docs/git-instructions.md to pull another file in. Paths are relative to the CLAUDE.md, and imports can nest up to four levels. Imported files still cost context, so this helps organization, not size. The first time a project imports a file from outside the folder, Claude Code asks you to approve it.
• Rules folder: put topic files such as testing.md in .claude/rules/. Add a paths field at the top (for example src/api/**/*.ts) and the rule loads only when Claude works on matching files.
• Audit: on recent versions, /doctor prompt-audit asks Claude to look for outdated or conflicting instructions and propose edits without changing anything until you say so.

CLAUDE.md vs auto memory

Claude Code also keeps notes of its own, called auto memory. You write CLAUDE.md; Claude writes auto memory from your corrections and preferences. It lives per repository at ~/.claude/projects/<project>/memory/, with a MEMORY.md index whose first 200 lines (or 25KB) load into each session. It stays on your machine and isn't shared through git. When you say remember to always use pnpm, that goes to auto memory; turn the feature on or off with the toggle in /memory. Use CLAUDE.md for anything the whole team should get.

Good to know

• Claude Code comes with the Pro and Max plans as part of the same subscription as the Claude apps; Team and Enterprise members have a separate help article.
• CLAUDE.md shapes behavior but doesn't enforce it. Block commands or files with permission rules in settings.
• The CLAUDE.md at the project root is read again from disk after /compact, so rules kept there outlast long sessions, while rules you only typed in chat can be lost. Subfolder files and path-scoped rules come back once Claude touches matching files again.
• Files in folders added with --add-dir are not loaded unless you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

If it doesn't work

• Claude ignores an instruction. Run /context and look under Memory files. If the file isn't listed, Claude can't see it: check the file name and that you started Claude in the right folder.
• Rules are followed some of the time. Make them more specific, remove conflicts with other CLAUDE.md or rule files, and shorten the file.
• An import isn't loading. A path with spaces needs a backslash before each space, a quoted path is not imported, and a path inside backticks stays literal. Imports from outside the project need your one-time approval.
• A subfolder's CLAUDE.md seems missing. It loads only after Claude touches a file in that subfolder.

Keep decisions and to-dos outside the file

CLAUDE.md is for lasting rules, not for the open tasks of this week. The Workbranch plugin for Claude Code covers that part: run /workbranch:save and Claude files the session's tasks, decisions and open questions into a Workbranch project, and when a session starts in a folder linked to a Workbranch project, the plugin shows what's still open there. There is a 3-day free trial at app.workbranch.ai.

Sources

• How Claude remembers your project (Claude Code Docs, checked 2026-10-30)
• Commands (Claude Code Docs, checked 2026-10-30)
• Use Claude Code with your Pro or Max plan (Claude Help Center, checked 2026-10-30)

Frequently asked questions