{"componentChunkName":"component---src-templates-blog-post-js","path":"/claude-md-best-practices/","result":{"data":{"site":{"siteMetadata":{"title":"Catwomaniya"}},"mdx":{"id":"a7a02e30-ee54-5df5-aca2-1be5b6099285","excerpt":"Most people using Claude Code either ignore CLAUDE.md or auto-generate it and never touch it again. Not great practices.\nCLAUDE.md is the only persistent memory…","body":"function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }\n\nfunction _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }\n\nfunction _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }\n\n/* @jsx mdx */\nvar _frontmatter = {\n  \"title\": \"CLAUDE.md: how to use Claude Code effectively (best practices)\",\n  \"date\": \"2026-04-22\",\n  \"description\": \"A concise guide to structuring CLAUDE.md for better context and performance in Claude Code\"\n};\nvar layoutProps = {\n  _frontmatter: _frontmatter\n};\nvar MDXLayout = \"wrapper\";\nreturn function MDXContent(_ref) {\n  var components = _ref.components,\n      props = _objectWithoutProperties(_ref, [\"components\"]);\n\n  return mdx(MDXLayout, _extends({}, layoutProps, props, {\n    components: components,\n    mdxType: \"MDXLayout\"\n  }), mdx(\"p\", null, \"Most people using Claude Code either ignore CLAUDE.md or auto-generate it and never touch it again. Not great practices.\\nCLAUDE.md is the only persistent memory Claude has about your project. Every new session, Claude starts completely fresh, no memory of your stack, your folder structure, your preferences or that weird workaround you put in last week. CLAUDE.md is the fix for that.\\nIf you\\u2019re using Claude Code seriously, this is the one file that determines whether it feels like a helpful collaborator or a confused intern.\"), mdx(\"h2\", null, \"What it actually is\"), mdx(\"p\", null, \"CLAUDE.md is a markdown file that Claude Code reads at the start of every session.\\nThis file gets loaded into Claude\\u2019s working context at the start of each session.\\nThink of it as a briefing doc Claude reads before it starts working.\\nThe catch: Anthropic actually wraps your file in a note that says something like \\u201Cthis may or may not be relevant to your tasks.\\u201D Which means Claude can decide to filter parts of it if they don\\u2019t seem related to what you\\u2019re currently doing, especially if it\\u2019s a longer file. \"), mdx(\"p\", null, \"Where to put it:\"), mdx(\"p\", null, mdx(\"code\", _extends({\n    parentName: \"p\"\n  }, {\n    \"className\": \"language-text\"\n  }), \" ~/.claude/CLAUDE.md - global file, loads for every project on your machine\\n ./CLAUDE.md in your project root - project-specific, goes into git\\n ./CLAUDE.local.md - personal notes for a project, gitignored (more on this later)\")), mdx(\"h2\", null, \"Why shorter is actually better\"), mdx(\"p\", null, \"Frontier AI models can reliably follow somewhere around 150\\u2013200 instructions before things start breaking down.Claude\\u2019s system prompt already uses ~50, leaving ~100-150 effective instructions.\"), mdx(\"p\", null, \"In practice:\"), mdx(\"p\", null, \"  <200 lines recommended\"), mdx(\"blockquote\", null, mdx(\"p\", {\n    parentName: \"blockquote\"\n  }, \"300 lines = noticeable drop in adherence\")), mdx(\"p\", null, \"The test for every line you write: \\u201CIf I deleted this, would Claude actually make a mistake?\\u201D If the answer is no, cut it.\"), mdx(\"h2\", null, \"The structure that works\"), mdx(\"p\", null, \"Think of it like onboarding a smart new person on your team on day one. You wouldn\\u2019t hand them a 50-page manual. You\\u2019d give them the essentials and tell them where to look when they need more.\\nStart with one line about what the project is.\\nNot a paragraph. One sentence.\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"List your commands in a code block\")), mdx(\"p\", null, \"| ------- | ----------- |\\n| pnpm test | Run tests |\\n| pnpm typecheck | Type check |\"), mdx(\"p\", null, \"Commands in code blocks get treated as commands. Commands buried in sentences get treated as suggestions.\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Add a shallow directory map\"), \"\\nNot every file. Just the top level with one-line descriptions. Claude can open files itself - you don\\u2019t need to describe them all.\"), mdx(\"p\", null, \"| --------- | ----------- |\\n| app/ | Screens and navigation |\\n| components/ | Reusable UI |\\n| services/ | API and third-party calls |\\n| lib/ | Business logic (no external calls here) |\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Add version numbers to your tech stack\"), \"\\nClaude cannot guess that you\\u2019re using React Native 0.74 not 0.73. Be explicit.\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Conventions - only the non-obvious ones\"), \"\\nSkip anything your linter already enforces. Skip standard language patterns. Only write down the things that are specific to how your project works.\\nGood examples:\\n\\u201CExpo Router for navigation. Not React Navigation.\\u201D\\n\\u201CAll API calls go through services. Never make fetch calls directly in components.\\u201D\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Hard rules\"), \"\\nEvery \\u201Cnever do X\\u201D should come with \\u201Cdo Y instead\\u201D and a quick explanation. The reason matters because it lets Claude generalize the rule to situations you didn\\u2019t anticipate.\"), mdx(\"h2\", null, \"How to keep the file short without losing information\"), mdx(\"p\", null, \"The trick is progressive disclosure.\\nDon\\u2019t dump everything into CLAUDE.md. Point to where details live.\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Scoped rule files\"), \" in .claude/rules/ load automatically at session start. You can even scope them to specific parts of your codebase, so they only activate when Claude is working in those areas - not burning context the rest of the time.\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Skills\"), \" in .claude/skills/ are on-demand. Claude loads a skill when the task matches the description. Good for things that matter on specific tasks but would be noise otherwise.\\nExternal docs with \\u201CRead when\\u201D triggers in your CLAUDE.md:\"), mdx(\"h2\", null, \"Reference docs\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Navigation structure - docs/navigation.md\")), mdx(\"p\", null, \"Read when: Adding new screens or changing routing.\"), mdx(\"p\", null, mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"API integration - docs/api.md\")), mdx(\"p\", null, \"Read when: Adding or modifying anything in services/.\"), mdx(\"p\", null, \"This tells Claude when to actually get it. The result: your main file stays lean.\"), mdx(\"h2\", null, \"What to leave out\"), mdx(\"p\", null, \"As said earlier, don\\u2019t include too much.\\nCut:\"), mdx(\"ul\", null, mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"Standard coding practices (Claude already knows them)\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"File-by-file explanations\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"Full documentation pasted inline\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"Generic advice like \\u201Cwrite clean code\\u201D\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"Task-specific instructions (move them to skills)\")), mdx(\"h2\", null, \"Treat it like code\"), mdx(\"p\", null, \"The most common failure mode: after every frustrating session, you add a new rule. Nobody ever removes old ones. Eventually the file is long enough that Claude starts filtering it, which makes things worse, which leads to more rules.\\nTwo signs your file needs pruning:\"), mdx(\"ol\", null, mdx(\"li\", {\n    parentName: \"ol\"\n  }, \"Claude apologizes for missing an instruction that\\u2019s clearly already there. Rewrite that line - the phrasing is ambiguous.\"), mdx(\"li\", {\n    parentName: \"ol\"\n  }, \"The same mistake keeps happening across sessions. The file is probably too long. Cut before you add.\\nOnly add a rule after a real mistake happened. Not speculatively.\")), mdx(\"h2\", null, \"Takeaway\"), mdx(\"p\", null, \"The goal isn\\u2019t to tell Claude everything about your project. It\\u2019s to tell Claude the things it genuinely cannot figure out on its own, as concisely as possible so the rest of the budget goes toward actually building.\\nKeep it short, keep it specific, update it when reality changes.\"));\n}\n;\nMDXContent.isMDXComponent = true;","frontmatter":{"title":"CLAUDE.md: how to use Claude Code effectively (best practices)","date":"Apr 22, 2026","description":"A concise guide to structuring CLAUDE.md for better context and performance in Claude Code"}}},"pageContext":{"slug":"/claude-md-best-practices/","previous":{"fields":{"collection":"blog","slug":"/tiktok-growth-strategy/"},"frontmatter":{"title":"TikTok Growth Strategy: How founders are scaling UGC to millions of views"}},"next":null}}}