[{"data":1,"prerenderedAt":649},["ShallowReactive",2],{"content-\u002Fguides\u002Fwriting-claude-md-files":3,"children-\u002Fguides\u002Fwriting-claude-md-files":648},{"id":4,"title":5,"author":6,"body":7,"budget_tier":6,"build_tags":6,"created":631,"description":632,"document_type":633,"extension":634,"game":6,"install":6,"investment_tier":6,"league":6,"meta":635,"navigation":636,"patch":6,"path":637,"plugin":6,"profit_per_hour":6,"ratings":6,"seo":638,"skills_count":6,"status":6,"stem":639,"strategy_tier":6,"tags":640,"updated":631,"version":6,"weight":646,"__hash__":647},"content\u002Fguides\u002Fwriting-claude-md-files.md","CLAUDE.md is project memory, not documentation",null,{"type":8,"value":9,"toc":608},"minimark",[10,14,27,42,53,68,73,76,81,84,114,121,125,128,183,190,193,201,204,208,215,222,226,229,265,272,276,280,301,305,314,317,321,336,340,351,355,362,377,383,392,396,407,411,414,417,453,460,464,467,477,484,488,491,497,503,506,510,521,524,568,575,579],[11,12,5],"h1",{"id":13},"claudemd-is-project-memory-not-documentation",[15,16,17,18,22,23,26],"p",{},"Claude Code looks for ",[19,20,21],"code",{},"CLAUDE.md"," in three places when a session starts:\nthe user's home directory (",[19,24,25],{},"~\u002F.claude\u002FCLAUDE.md","), the project root, and\nthe working subdirectory. Whatever it finds is concatenated into the\nsession prompt before the user's first message.",[15,28,29,30,33,34,36,37,41],{},"That's what makes it different from ",[19,31,32],{},"README.md",". A README is documentation\nwritten for a human reader who can scroll, skim, and reread. ",[19,35,21],{},"\nis ",[38,39,40],"strong",{},"prompt content",": every line stays in context for the duration of\nthe session and competes with the user's actual task for the model's\nattention. A short, dense file gets read. A long one gets skimmed.",[15,43,44,45,49,50],{},"So the real question isn't ",[46,47,48],"em",{},"\"what should I tell Claude about this\nproject?\""," — that road leads to a CLAUDE.md the size of a wiki. The\nquestion is ",[46,51,52],{},"\"what's the smallest set of lines that changes the model's\nbehavior in the directions my project actually needs?\"",[15,54,55,56,59,60,67],{},"This guide is about how to think about that question. It does not\nprescribe the rules themselves — those depend on your team, your\ncodebase, and what you care about. It describes the ",[46,57,58],{},"shape"," of content\nthat fires reliably, and the failure modes that produce CLAUDE.md files\nnobody benefits from. A full real-world example lives on a companion\npage: ",[61,62,64],"a",{"href":63},"\u002Fguides\u002Fmy-claude",[38,65,66],{},"My CLAUDE.md",".",[69,70,72],"h2",{"id":71},"what-earns-a-line","What earns a line",[15,74,75],{},"Three broad categories of content earn space in CLAUDE.md. The mix\nvaries by project — most files lean heavily on one or two.",[77,78,80],"h3",{"id":79},"_1-facts-the-model-cant-derive-from-the-code","1. Facts the model can't derive from the code",[15,82,83],{},"The classic case. Conventions, tool preferences, and invariants that\ndon't show up in the source itself.",[85,86,87,98,104],"ul",{},[88,89,90,93,94,97],"li",{},[38,91,92],{},"Tool preferences"," — which package manager, which test runner, which\nformatter. The codebase doesn't say ",[46,95,96],{},"\"never use yarn\"","; CLAUDE.md does.",[88,99,100,103],{},[38,101,102],{},"Process conventions"," — commit message style, branch naming, when\nto ask before pushing.",[88,105,106,109,110,113],{},[38,107,108],{},"Hidden invariants with rationale"," — a magic number with a reason\n(",[46,111,112],{},"\"the retry count is 5 because the upstream API does its own retry on\n4s timeout\"","), an ordering constraint that isn't enforced by types,\na workaround whose context lives only in a slack thread.",[15,115,116,117,120],{},"The litmus test: ",[46,118,119],{},"if I delete this rule, will Claude reliably do the\nright thing anyway?"," If yes, the rule is noise.",[77,122,124],{"id":123},"_2-behavioral-defaults-you-want-corrected","2. Behavioral defaults you want corrected",[15,126,127],{},"Claude ships with defaults tuned for a broad audience. Your project may\nwant different defaults. The categories of behavior teams most often\nadjust:",[85,129,130,137,144,151,169,176],{},[88,131,132,133,136],{},"How the model balances ",[38,134,135],{},"agreement vs. pushback"," on the user's ideas.",[88,138,139,140,143],{},"How the model handles ",[38,141,142],{},"uncertainty"," — silent guess vs. flagged\nhunch vs. refusal to claim until verified.",[88,145,146,147,150],{},"How aggressively the model ",[38,148,149],{},"roots-causes"," vs. patches symptoms.",[88,152,153,154,157,158,161,162,165,166,168],{},"How the model treats ",[38,155,156],{},"proxies"," — does ",[46,159,160],{},"tests pass"," mean ",[46,163,164],{},"feature\nworks",", or only ",[46,167,160],{},"?",[88,170,171,172,175],{},"How the model ",[38,173,174],{},"estimates effort"," — by a single human, or by what an\nAI session can actually do.",[88,177,178,179,182],{},"How ",[38,180,181],{},"verbose"," end-of-turn summaries should be, and what they must\ninclude.",[15,184,185,186,189],{},"You don't need an opinion on every dimension. Write down only the\ncorrections that actually matter for your project. A team shipping\ncritical infrastructure wants different defaults than a team prototyping\nUX. The point of the section is to declare ",[46,187,188],{},"where your defaults differ\nfrom the model's",", not to recite every preference you have.",[15,191,192],{},"The shape that fires reliably:",[194,195,196],"blockquote",{},[15,197,198],{},[46,199,200],{},"\"By default, do X. Reason: Y.\"",[15,202,203],{},"A reason makes the rule durable across edge cases. A rule without one\ngets deleted the first time it gets in the way.",[77,205,207],{"id":206},"_3-engineering-principles-you-want-held-in-attention-mid-task","3. Engineering principles you want held in attention mid-task",[15,209,210,211,214],{},"Principles you want Claude to apply ",[46,212,213],{},"while writing code",", not just at\nreview time. These are the highest-stakes lines in the file because\nthey shape every commit, but also the easiest to over-include — every\nteam has favorite principles, and most of them are already in the\nmodel's training.",[15,216,217,218,221],{},"A principle earns its line only when it changes the output. Usually\nthat's when it cuts against a default the model would otherwise make:\npreferring co-located code over a deep package hierarchy, preferring\nexplicit error returns over panics, preferring duplication over a\nshaky abstraction. If the principle is ",[46,219,220],{},"\"write good code,\""," drop it.",[69,223,225],{"id":224},"what-lives-elsewhere","What lives elsewhere",[15,227,228],{},"Anything Claude can extract on demand belongs outside CLAUDE.md:",[85,230,231,237,243,253,259],{},[88,232,233,236],{},[38,234,235],{},"File layout"," — the directory tree exists already.",[88,238,239,242],{},[38,240,241],{},"Function signatures and APIs"," — grep and read.",[88,244,245,248,249,252],{},[38,246,247],{},"Recent git history"," — ",[19,250,251],{},"git log"," is authoritative.",[88,254,255,258],{},[38,256,257],{},"General programming practices"," — already in the model's weights.",[88,260,261,264],{},[38,262,263],{},"Ephemeral state"," (current sprint, today's todo, in-progress\nfeature) — lives in TodoWrite or per-task notes, not in a file every\nsession loads.",[15,266,267,268,271],{},"When in doubt: ",[46,269,270],{},"will the model reliably do this without the rule?"," If\nyes, drop it.",[69,273,275],{"id":274},"format-heuristics","Format heuristics",[77,277,279],{"id":278},"imperatives-over-narration","Imperatives over narration",[15,281,282,285,286,289,290,293,294,293,297,300],{},[46,283,284],{},"\"Use X.\""," beats ",[46,287,288],{},"\"We try to use X when appropriate.\""," Direct directives\nfire as directives. Softeners — ",[46,291,292],{},"sometimes",", ",[46,295,296],{},"generally",[46,298,299],{},"try to"," —\ngive the model permission to skip the rule under perceived pressure.",[77,302,304],{"id":303},"why-before-what-when-the-rule-isnt-obvious","Why before what, when the rule isn't obvious",[15,306,307],{},[46,308,309,310,313],{},"\"Never use ",[19,311,312],{},"--no-verify"," on commits. Reason: a previous incident\nbypassed a secret-scan hook and pushed a token to remote.\"",[15,315,316],{},"A rule whose rationale lives in someone's head is one re-org away from\ngone. The next contributor reads it, can't explain it, and deletes it.",[77,318,320],{"id":319},"group-by-concern","Group by concern",[15,322,323,293,326,293,329,293,332,335],{},[19,324,325],{},"## Code style",[19,327,328],{},"## Tools",[19,330,331],{},"## Workflow",[19,333,334],{},"## Behavior",". One block per\ntopic so the model can attend to the relevant section when that concern\nis active. Long flat lists of mixed rules fade in attention.",[77,337,339],{"id":338},"one-example-per-rule-with-edge-cases","One example per rule with edge cases",[15,341,342,343,346,347,350],{},"A rule like ",[46,344,345],{},"\"prefer colocation\""," without an example collapses under\ninterpretation. A single concrete ",[46,348,349],{},"\"e.g. handlers + their queries in\none file, not split into a Services\u002F folder\""," anchors the intent.",[77,352,354],{"id":353},"replace-dont-accumulate","Replace, don't accumulate",[15,356,357,358,361],{},"When you change your mind on a rule, delete the old version completely.\nDon't leave residue like ",[46,359,360],{},"\"we used to do X, now we do Y\""," in the\nforward-looking sections of the file. The old phrasing keeps the\ndiscarded approach in attention, and the next contributor reads it as\nstill-relevant context.",[15,363,364,365,368,369,372,373,376],{},"Negative rules belong only where there was never a positive alternative\n(",[46,366,367],{},"\"never commit secrets\"","). If you're tempted to write ",[46,370,371],{},"\"don't use the\nold X\"",", the cleaner move is to write ",[46,374,375],{},"\"use Y\""," and let the old X\ndisappear from the file entirely.",[15,378,379,380,382],{},"History lives in ",[19,381,251],{}," or an ADR. The current rules file is\nforward-looking only.",[15,384,385],{},[46,386,387,388,391],{},"(Research note: psychologists call this the ironic-process effect —\n",[46,389,390],{},"don't think about X"," still activates X in the reader's attention.\nThe same pattern shows up in prompts.)",[77,393,395],{"id":394},"state-how-uncertainty-should-be-expressed","State how uncertainty should be expressed",[15,397,398,399,402,403,406],{},"The model's default is uniform confident prose, which makes verified\nfacts and unverified hunches look identical. If you want them\ndistinguishable, say how — explicit confidence labels, a ",[46,400,401],{},"\"I'm\nguessing\""," prefix, a rule against claiming ",[46,404,405],{},"\"done\""," without a\nverification step. The mechanism matters less than declaring one.",[69,408,410],{"id":409},"length-and-discipline","Length and discipline",[15,412,413],{},"A short CLAUDE.md is read with attention. A long one is skimmed. The\ncrossover point varies, but a file past a few hundred lines is almost\ncertainly past it.",[15,415,416],{},"Common shapes of bloat, and what to do about them:",[85,418,419,428,441,447],{},[88,420,421,424,425,427],{},[38,422,423],{},"Domain expansion"," — the file accumulates rules for unrelated parts\nof the codebase. Split into subdirectory ",[19,426,21],{}," files, one per\narea. The model loads them based on the working directory.",[88,429,430,433,434,293,437,440],{},[38,431,432],{},"Documentation creep"," — content that's really product or onboarding\ndocumentation. Move to ",[19,435,436],{},"docs\u002F",[19,438,439],{},"CONTRIBUTING.md",", or a wiki.",[88,442,443,446],{},[38,444,445],{},"Wishful rules"," — things nobody enforces. Either bake into CI (lint\nrule, pre-commit hook, GitHub Action) or delete. CLAUDE.md is not a\nwish list.",[88,448,449,452],{},[38,450,451],{},"Stale rules"," — the old framework is gone but its rule remains.\nPrune.",[15,454,455,456,459],{},"The healthy long-term trajectory is ",[46,457,458],{},"shorter over time",", not longer.\nThe team learns which rules the model actually needed and which were\nnoise; the noise gets cut.",[69,461,463],{"id":462},"a-starting-skeleton","A starting skeleton",[15,465,466],{},"Project-specific content varies, but most useful files share a similar\nbackbone. Use this as a starting point — add the sections you need,\ndelete the ones you don't.",[468,469,475],"pre",{"className":470,"code":472,"language":473,"meta":474},[471],"language-markdown","# CLAUDE.md\n\n## Tools and workflow\n\n- [your package manager \u002F test runner \u002F formatter]\n- [conditions for running which commands]\n- [what counts as \"ready to commit\"]\n\n## Code style\n\n- [conventions not enforced by lint]\n- [naming, file layout, test placement]\n- [an example or two for anything genre-defining]\n\n## Behavior\n\n- [pushback vs. agreement preference]\n- [how uncertainty should be flagged]\n- [what counts as \"done\" — verification expectations]\n\n## Architecture invariants\n\n- [things that look optional but aren't]\n- [why each invariant exists]\n\n## Commit and PR\n\n- [commit message style]\n- [PR size \u002F scope conventions]\n","markdown","",[19,476,472],{"__ignoreMap":474},[15,478,479,480,483],{},"A small project may only need the first two sections. A larger one may\nsplit ",[19,481,482],{},"Architecture invariants"," into a per-subdirectory file. The\nstructure is a starting frame, not a target.",[69,485,487],{"id":486},"iterating-on-the-file","Iterating on the file",[15,489,490],{},"Treat CLAUDE.md like code. Review it on PRs. Two failure modes to\nwatch for:",[15,492,493,496],{},[38,494,495],{},"Under-correction."," The same correction comes up twice in a week.\nAdd the rule. One line in the prompt costs less than repeated\ninterventions.",[15,498,499,502],{},[38,500,501],{},"Over-accumulation."," Rules pile up that haven't fired in months.\nRemove them. The model's attention is finite; an unused rule consumes\nattention the load-bearing rules need.",[15,504,505],{},"A mature CLAUDE.md is shorter than its first draft, not longer. The\nrules that became muscle memory got promoted into automation. The\nrules that turned out to be noise got cut. What's left is the small\nset of things the model would otherwise get wrong on this codebase,\nstated in the form most likely to fire.",[69,507,509],{"id":508},"a-real-world-example","A real-world example",[15,511,512,513,515,516,520],{},"The author's own ",[19,514,25],{}," is published as a companion\npage: ",[61,517,518],{"href":63},[38,519,66],{},". It is one team's working\nconfiguration, not a template — the voice is personal (Vietnamese–\nEnglish code-switching included), the specific rules reflect this\nauthor's projects and tools, and the choices won't all transfer. Read\nit as an artifact: a concrete instance of the categories described\nabove, sized and shaped for one engineer's actual work.",[15,522,523],{},"A few things worth noticing when you read it:",[85,525,526,546,556,562],{},[88,527,528,531,532,293,535,293,538,541,542,545],{},[38,529,530],{},"Where it differs from the model's defaults."," Sections like\n",[46,533,534],{},"Proactive Conviction",[46,536,537],{},"Confidence Labels",[46,539,540],{},"Goal-Driven Execution",",\nand ",[46,543,544],{},"Positive Framing"," are explicit corrections to behaviors the\nauthor wanted different from out-of-the-box Claude.",[88,547,548,551,552,555],{},[38,549,550],{},"How each rule carries its reason."," Most non-obvious rules include\na ",[46,553,554],{},"\"Reason:\""," or a research citation. Rules that survive months of\nuse almost always have one; rules that don't, don't.",[88,557,558,561],{},[38,559,560],{},"What it leaves out."," No file tree, no API list, no recent commit\nhistory. Anything Claude can grep is missing on purpose.",[88,563,564,567],{},[38,565,566],{},"The shape of bloat that's still there."," Even this file has lines\nthe author would probably cut on the next pass. CLAUDE.md is never\nfinished, only currently good enough.",[15,569,570,571],{},"→ Open the example: ",[61,572,573],{"href":63},[38,574,66],{},[69,576,578],{"id":577},"related","Related",[85,580,581,592,599],{},[88,582,583,584,248,588,591],{},"The ",[61,585,587],{"href":586},"\u002Fplugins","plugin catalog",[19,589,590],{},"aio-claude-toolkit"," includes a\nskill for auditing CLAUDE.md files against best practices.",[88,593,594,598],{},[61,595,597],{"href":596},"\u002Fguides\u002Fskills-agents-hooks","Skills, agents, hooks"," — the three\nprimitives Claude Code exposes beyond plain prompts.",[88,600,601,607],{},[61,602,606],{"href":603,"rel":604},"https:\u002F\u002Fdocs.anthropic.com\u002Fclaude\u002Fdocs\u002Fclaude-code",[605],"nofollow","Anthropic's Claude Code docs","\nfor the authoritative reference on file loading and precedence.",{"title":474,"searchDepth":609,"depth":609,"links":610},2,[611,617,618,626,627,628,629,630],{"id":71,"depth":609,"text":72,"children":612},[613,615,616],{"id":79,"depth":614,"text":80},3,{"id":123,"depth":614,"text":124},{"id":206,"depth":614,"text":207},{"id":224,"depth":609,"text":225},{"id":274,"depth":609,"text":275,"children":619},[620,621,622,623,624,625],{"id":278,"depth":614,"text":279},{"id":303,"depth":614,"text":304},{"id":319,"depth":614,"text":320},{"id":338,"depth":614,"text":339},{"id":353,"depth":614,"text":354},{"id":394,"depth":614,"text":395},{"id":409,"depth":609,"text":410},{"id":462,"depth":609,"text":463},{"id":486,"depth":609,"text":487},{"id":508,"depth":609,"text":509},{"id":577,"depth":609,"text":578},"2026-05-25","Claude Code loads CLAUDE.md into the session prompt on every start. That makes it prompt content, not documentation. Categories of content that earn a line, format heuristics that make rules fire, with a companion page linking to a real-world example.","guide","md",{},true,"\u002Fguides\u002Fwriting-claude-md-files",{"title":5,"description":632},"guides\u002Fwriting-claude-md-files",[641,642,643,644,645],"claude-md","project-memory","claude-code","best-practices","configuration",10,"dgYBf3uAgs_DpkBHK9D7FxBdf_ACPorPOpnrQllQzEs",[],1779707415457]