[{"data":1,"prerenderedAt":56},["ShallowReactive",2],{"blog-claude-md-guide":3,"blog-related-claude-md-guide":39},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-md-guide","How to write a CLAUDE.md that Claude Code follows","What goes in a CLAUDE.md, where the files live, how imports and .claude\u002Frules work, and the writing habits that make Claude Code follow your instructions.","Getting started","getting-started","claude.md","2026-11-17",5,"A `CLAUDE.md` is a Markdown file Claude Code reads at the start of every session: your build commands, conventions and rules, written once instead of re-typed each time. Claude treats it as context, not as enforced configuration, so how you write it decides how well it is followed. Short, concrete, verifiable instructions win; long essays get ignored.\n\n## What is a CLAUDE.md, and where does it go?\n\nEach session starts with a fresh context window. CLAUDE.md files are one of two ways knowledge survives between sessions (the other is auto memory, notes Claude writes about your corrections). Claude Code reads these files:\n\n| Scope | Location | Shared with |\n| --- | --- | --- |\n| Organization (managed) | `\u002FLibrary\u002FApplication Support\u002FClaudeCode\u002FCLAUDE.md` on macOS, `\u002Fetc\u002Fclaude-code\u002FCLAUDE.md` on Linux | Everyone on the machine |\n| You, all projects | `~\u002F.claude\u002FCLAUDE.md` | Only you |\n| Project | `.\u002FCLAUDE.md` or `.\u002F.claude\u002FCLAUDE.md` | The team, via git |\n| You, this project | `.\u002FCLAUDE.local.md` (add it to `.gitignore`) | Only you |\n\nFiles are concatenated, not overridden: Claude Code loads the ones in your working directory and every directory above it, from the root down, so the file closest to where you launched is read last. CLAUDE.md files in subdirectories load on demand, when Claude reads or edits a file there. That makes a `packages\u002Fapi\u002FCLAUDE.md` a good place for rules that only matter in that package.\n\n## How do you generate a first one?\n\nRun `\u002Finit` inside a session. Claude scans the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If one already exists, it suggests improvements instead of overwriting it.\n\nTreat the output as a draft. Delete anything Claude could work out by reading the code, and add what it could not: the reason behind an odd convention, the command that actually runs your integration tests, the directory nobody should touch.\n\nTo confirm a file loaded, run `\u002Fcontext all` and look at the list of memory files. `\u002Fmemory` opens the files for editing.\n\n## What should go in it?\n\nWrite down what you would otherwise re-explain. The official guidance is to add a line when Claude makes the same mistake twice, when a code review catches something it should have known, or when you type the same correction as last session.\n\nA solid project file usually has four short blocks:\n\n```md\n# Commands\n- Install: `pnpm install`\n- Test one file: `pnpm vitest run path\u002Fto\u002Ffile.test.ts`\n- Lint and typecheck before finishing: `pnpm lint && pnpm typecheck`\n\n# Layout\n- API handlers live in `src\u002Fapi\u002Fhandlers\u002F`, one file per route\n- Shared types in `src\u002Ftypes\u002F`; never import from `src\u002Flegacy\u002F`\n\n# Conventions\n- TypeScript strict; no `any` without a comment saying why\n- Use the `Result` helper in `src\u002Flib\u002Fresult.ts`, do not throw in handlers\n\n# Don't\n- Don't edit files under `generated\u002F`; run `pnpm codegen` instead\n- Don't commit directly to `main`\n```\n\n## How do you write instructions it actually follows?\n\n**Make each line verifiable.** The docs give the contrast: \"Use 2-space indentation\" beats \"Format code properly\"; \"Run `npm test` before committing\" beats \"Test your changes\"; \"API handlers live in `src\u002Fapi\u002Fhandlers\u002F`\" beats \"Keep files organized\". If you could not check a line in a code review, Claude cannot reliably follow it either.\n\n**Keep it short.** The target is under 200 lines per file. Longer files use more context and adherence drops. If you cannot cut, move material elsewhere (see below).\n\n**Structure it.** Headers and bullets are easier to follow than paragraphs.\n\n**Remove contradictions.** If two lines disagree, Claude may pick either. This is easy to cause with a user file, a project file and a rules folder all saying slightly different things. `\u002Fdoctor prompt-audit` asks Claude to look for outdated or conflicting instructions across your instruction files and proposes edits without applying them.\n\n**Do not use it as a lock.** A CLAUDE.md line like \"never run `rm -rf`\" is a request. For anything that must never happen, use a permission deny rule or a PreToolUse hook; see [permission modes](\u002Fblog\u002Fclaude-code-permission-modes).\n\n## How do imports and rules keep the file small?\n\nReference other files with `@` and Claude Code loads them alongside:\n\n```md\nSee @README for the project overview and @package.json for npm scripts.\n\n# Git workflow\n@docs\u002Fgit-instructions.md\n```\n\nRelative paths resolve from the file that contains the import, and imports can nest four levels deep. Note that imports organize a long file but do not reduce its context cost: imported content is loaded too. To mention a path without importing it, wrap it in backticks.\n\nFor real savings, split by topic into `.claude\u002Frules\u002F`. Each Markdown file there is loaded at launch, unless it declares paths:\n\n```md\n---\npaths:\n  - \"src\u002Fapi\u002F**\u002F*.ts\"\n---\n\n# API rules\n- Validate every input with the shared schema\n- Return errors in the standard envelope\n```\n\nA rule with `paths` only loads when Claude touches a matching file. Personal rules for every project go in `~\u002F.claude\u002Frules\u002F`.\n\nA related choice: if a block is a multi-step procedure (how to cut a release, how to add a migration), it belongs in a [skill](\u002Fblog\u002Fclaude-code-skills), which loads only when needed, not in a file that is read every time.\n\n## What about notes for humans and several folders?\n\nBlock-level HTML comments (`\u003C!-- note for maintainers -->`) are stripped before the content reaches Claude, so you can leave notes without spending context.\n\nBy default, CLAUDE.md files from folders you add with `--add-dir` are not loaded. Set `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` and they are, which matters for a project split over several repositories.\n\nIf your repository uses an `AGENTS.md` for other tools, Claude Code can read it in place of CLAUDE.md; the docs describe how the two combine.\n\n## A quick checklist\n\n- Under 200 lines, headers and bullets\n- Commands to build, test and lint are written out in full\n- Every rule is checkable\n- No duplicates between user, project and rules files\n- Hard guarantees live in settings or hooks, not prose\n- Big procedures moved to skills, area-specific rules to `.claude\u002Frules\u002F`\n- Revisit it whenever Claude repeats a mistake\n\nNew to the tool? Start with the [beginner's guide](\u002Fblog\u002Fclaude-code-beginners-guide).\n\n## In Relais\n\nIn Relais a group is one project made of several folders. The first folder is where Claude starts and the others are added as extra directories, and Relais sets `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` so the CLAUDE.md of every folder loads. That suits a project spread over a frontend, a backend and a shared repo. See [features](\u002Ffeatures).","\u003Cp>A \u003Ccode>CLAUDE.md\u003C\u002Fcode> is a Markdown file Claude Code reads at the start of every session: your build commands, conventions and rules, written once instead of re-typed each time. Claude treats it as context, not as enforced configuration, so how you write it decides how well it is followed. Short, concrete, verifiable instructions win; long essays get ignored.\u003C\u002Fp>\n\u003Ch2 id=\"what-is-a-claude-md-and-where-does-it-go\">\u003Ca class=\"anchor\" href=\"#what-is-a-claude-md-and-where-does-it-go\" aria-label=\"Link to this section\">#\u003C\u002Fa>What is a CLAUDE.md, and where does it go?\u003C\u002Fh2>\n\u003Cp>Each session starts with a fresh context window. CLAUDE.md files are one of two ways knowledge survives between sessions (the other is auto memory, notes Claude writes about your corrections). Claude Code reads these files:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>Scope\u003C\u002Fth>\u003Cth>Location\u003C\u002Fth>\u003Cth>Shared with\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>Organization (managed)\u003C\u002Ftd>\u003Ctd>\u003Ccode>\u002FLibrary\u002FApplication Support\u002FClaudeCode\u002FCLAUDE.md\u003C\u002Fcode> on macOS, \u003Ccode>\u002Fetc\u002Fclaude-code\u002FCLAUDE.md\u003C\u002Fcode> on Linux\u003C\u002Ftd>\u003Ctd>Everyone on the machine\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>You, all projects\u003C\u002Ftd>\u003Ctd>\u003Ccode>~\u002F.claude\u002FCLAUDE.md\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Only you\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Project\u003C\u002Ftd>\u003Ctd>\u003Ccode>.\u002FCLAUDE.md\u003C\u002Fcode> or \u003Ccode>.\u002F.claude\u002FCLAUDE.md\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>The team, via git\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>You, this project\u003C\u002Ftd>\u003Ctd>\u003Ccode>.\u002FCLAUDE.local.md\u003C\u002Fcode> (add it to \u003Ccode>.gitignore\u003C\u002Fcode>)\u003C\u002Ftd>\u003Ctd>Only you\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>Files are concatenated, not overridden: Claude Code loads the ones in your working directory and every directory above it, from the root down, so the file closest to where you launched is read last. CLAUDE.md files in subdirectories load on demand, when Claude reads or edits a file there. That makes a \u003Ccode>packages\u002Fapi\u002FCLAUDE.md\u003C\u002Fcode> a good place for rules that only matter in that package.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-generate-a-first-one\">\u003Ca class=\"anchor\" href=\"#how-do-you-generate-a-first-one\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you generate a first one?\u003C\u002Fh2>\n\u003Cp>Run \u003Ccode>\u002Finit\u003C\u002Fcode> inside a session. Claude scans the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If one already exists, it suggests improvements instead of overwriting it.\u003C\u002Fp>\n\u003Cp>Treat the output as a draft. Delete anything Claude could work out by reading the code, and add what it could not: the reason behind an odd convention, the command that actually runs your integration tests, the directory nobody should touch.\u003C\u002Fp>\n\u003Cp>To confirm a file loaded, run \u003Ccode>\u002Fcontext all\u003C\u002Fcode> and look at the list of memory files. \u003Ccode>\u002Fmemory\u003C\u002Fcode> opens the files for editing.\u003C\u002Fp>\n\u003Ch2 id=\"what-should-go-in-it\">\u003Ca class=\"anchor\" href=\"#what-should-go-in-it\" aria-label=\"Link to this section\">#\u003C\u002Fa>What should go in it?\u003C\u002Fh2>\n\u003Cp>Write down what you would otherwise re-explain. The official guidance is to add a line when Claude makes the same mistake twice, when a code review catches something it should have known, or when you type the same correction as last session.\u003C\u002Fp>\n\u003Cp>A solid project file usually has four short blocks:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"md\">\u003Ccode># Commands\n- Install: `pnpm install`\n- Test one file: `pnpm vitest run path\u002Fto\u002Ffile.test.ts`\n- Lint and typecheck before finishing: `pnpm lint &amp;&amp; pnpm typecheck`\n\n# Layout\n- API handlers live in `src\u002Fapi\u002Fhandlers\u002F`, one file per route\n- Shared types in `src\u002Ftypes\u002F`; never import from `src\u002Flegacy\u002F`\n\n# Conventions\n- TypeScript strict; no `any` without a comment saying why\n- Use the `Result` helper in `src\u002Flib\u002Fresult.ts`, do not throw in handlers\n\n# Don't\n- Don't edit files under `generated\u002F`; run `pnpm codegen` instead\n- Don't commit directly to `main`\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2 id=\"how-do-you-write-instructions-it-actually-follows\">\u003Ca class=\"anchor\" href=\"#how-do-you-write-instructions-it-actually-follows\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you write instructions it actually follows?\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>Make each line verifiable.\u003C\u002Fstrong> The docs give the contrast: &quot;Use 2-space indentation&quot; beats &quot;Format code properly&quot;; &quot;Run \u003Ccode>npm test\u003C\u002Fcode> before committing&quot; beats &quot;Test your changes&quot;; &quot;API handlers live in \u003Ccode>src\u002Fapi\u002Fhandlers\u002F\u003C\u002Fcode>&quot; beats &quot;Keep files organized&quot;. If you could not check a line in a code review, Claude cannot reliably follow it either.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Keep it short.\u003C\u002Fstrong> The target is under 200 lines per file. Longer files use more context and adherence drops. If you cannot cut, move material elsewhere (see below).\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Structure it.\u003C\u002Fstrong> Headers and bullets are easier to follow than paragraphs.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Remove contradictions.\u003C\u002Fstrong> If two lines disagree, Claude may pick either. This is easy to cause with a user file, a project file and a rules folder all saying slightly different things. \u003Ccode>\u002Fdoctor prompt-audit\u003C\u002Fcode> asks Claude to look for outdated or conflicting instructions across your instruction files and proposes edits without applying them.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Do not use it as a lock.\u003C\u002Fstrong> A CLAUDE.md line like &quot;never run \u003Ccode>rm -rf\u003C\u002Fcode>&quot; is a request. For anything that must never happen, use a permission deny rule or a PreToolUse hook; see \u003Ca href=\"\u002Fblog\u002Fclaude-code-permission-modes\">permission modes\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-imports-and-rules-keep-the-file-small\">\u003Ca class=\"anchor\" href=\"#how-do-imports-and-rules-keep-the-file-small\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do imports and rules keep the file small?\u003C\u002Fh2>\n\u003Cp>Reference other files with \u003Ccode>@\u003C\u002Fcode> and Claude Code loads them alongside:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"md\">\u003Ccode>See @README for the project overview and @package.json for npm scripts.\n\n# Git workflow\n@docs\u002Fgit-instructions.md\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Relative paths resolve from the file that contains the import, and imports can nest four levels deep. Note that imports organize a long file but do not reduce its context cost: imported content is loaded too. To mention a path without importing it, wrap it in backticks.\u003C\u002Fp>\n\u003Cp>For real savings, split by topic into \u003Ccode>.claude\u002Frules\u002F\u003C\u002Fcode>. Each Markdown file there is loaded at launch, unless it declares paths:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"md\">\u003Ccode>---\npaths:\n  - &quot;src\u002Fapi\u002F**\u002F*.ts&quot;\n---\n\n# API rules\n- Validate every input with the shared schema\n- Return errors in the standard envelope\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>A rule with \u003Ccode>paths\u003C\u002Fcode> only loads when Claude touches a matching file. Personal rules for every project go in \u003Ccode>~\u002F.claude\u002Frules\u002F\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>A related choice: if a block is a multi-step procedure (how to cut a release, how to add a migration), it belongs in a \u003Ca href=\"\u002Fblog\u002Fclaude-code-skills\">skill\u003C\u002Fa>, which loads only when needed, not in a file that is read every time.\u003C\u002Fp>\n\u003Ch2 id=\"what-about-notes-for-humans-and-several-folders\">\u003Ca class=\"anchor\" href=\"#what-about-notes-for-humans-and-several-folders\" aria-label=\"Link to this section\">#\u003C\u002Fa>What about notes for humans and several folders?\u003C\u002Fh2>\n\u003Cp>Block-level HTML comments (\u003Ccode>&lt;!-- note for maintainers --&gt;\u003C\u002Fcode>) are stripped before the content reaches Claude, so you can leave notes without spending context.\u003C\u002Fp>\n\u003Cp>By default, CLAUDE.md files from folders you add with \u003Ccode>--add-dir\u003C\u002Fcode> are not loaded. Set \u003Ccode>CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1\u003C\u002Fcode> and they are, which matters for a project split over several repositories.\u003C\u002Fp>\n\u003Cp>If your repository uses an \u003Ccode>AGENTS.md\u003C\u002Fcode> for other tools, Claude Code can read it in place of CLAUDE.md; the docs describe how the two combine.\u003C\u002Fp>\n\u003Ch2 id=\"a-quick-checklist\">\u003Ca class=\"anchor\" href=\"#a-quick-checklist\" aria-label=\"Link to this section\">#\u003C\u002Fa>A quick checklist\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>Under 200 lines, headers and bullets\u003C\u002Fli>\n\u003Cli>Commands to build, test and lint are written out in full\u003C\u002Fli>\n\u003Cli>Every rule is checkable\u003C\u002Fli>\n\u003Cli>No duplicates between user, project and rules files\u003C\u002Fli>\n\u003Cli>Hard guarantees live in settings or hooks, not prose\u003C\u002Fli>\n\u003Cli>Big procedures moved to skills, area-specific rules to \u003Ccode>.claude\u002Frules\u002F\u003C\u002Fcode>\u003C\u002Fli>\n\u003Cli>Revisit it whenever Claude repeats a mistake\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>New to the tool? Start with the \u003Ca href=\"\u002Fblog\u002Fclaude-code-beginners-guide\">beginner&#39;s guide\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>In Relais a group is one project made of several folders. The first folder is where Claude starts and the others are added as extra directories, and Relais sets \u003Ccode>CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1\u003C\u002Fcode> so the CLAUDE.md of every folder loads. That suits a project spread over a frontend, a backend and a shared repo. See \u003Ca href=\"\u002Ffeatures\">features\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33,36],{"id":16,"text":17},"what-is-a-claude-md-and-where-does-it-go","What is a CLAUDE.md, and where does it go?",{"id":19,"text":20},"how-do-you-generate-a-first-one","How do you generate a first one?",{"id":22,"text":23},"what-should-go-in-it","What should go in it?",{"id":25,"text":26},"how-do-you-write-instructions-it-actually-follows","How do you write instructions it actually follows?",{"id":28,"text":29},"how-do-imports-and-rules-keep-the-file-small","How do imports and rules keep the file small?",{"id":31,"text":32},"what-about-notes-for-humans-and-several-folders","What about notes for humans and several folders?",{"id":34,"text":35},"a-quick-checklist","A quick checklist",{"id":37,"text":38},"in-relais","In Relais",[40,45,51],{"slug":41,"title":42,"description":43,"category":7,"categoryId":8,"keyword":44,"date":10,"minutes":11},"claude-code-beginners-guide","Claude Code for beginners: install, first session, habits","Install Claude Code, run your first session and learn the habits that matter: specific prompts, plan before edit, CLAUDE.md, small commits, a clean context.","claude code for beginners",{"slug":46,"title":47,"description":48,"category":7,"categoryId":8,"keyword":49,"date":10,"minutes":50},"claude-code-hooks","Claude Code hooks: run a script on every tool call","Claude Code hooks run your own script before or after a tool call. Learn the config format, exit codes and three working examples you can paste today.","claude code hooks",6,{"slug":52,"title":53,"description":54,"category":7,"categoryId":8,"keyword":55,"date":10,"minutes":11},"claude-code-permission-modes","Claude Code permission modes explained (and when to use each)","Default, acceptEdits, plan, auto, dontAsk and bypassPermissions: what each Claude Code permission mode allows, how to switch, and which one fits which job.","claude code permission modes",1794931098788]