[{"data":1,"prerenderedAt":323},["ShallowReactive",2],{"content-\u002Fguides\u002Fwriting-claude-md-files":3,"children-\u002Fguides\u002Fwriting-claude-md-files":322},{"id":4,"title":5,"author":6,"body":7,"budget_tier":6,"build_tags":6,"created":305,"description":306,"document_type":307,"extension":308,"game":6,"install":6,"investment_tier":6,"league":6,"meta":309,"navigation":310,"patch":6,"path":311,"plugin":6,"profit_per_hour":6,"ratings":6,"seo":312,"skills_count":6,"status":6,"stem":313,"strategy_tier":6,"tags":314,"updated":305,"version":6,"weight":320,"__hash__":321},"content\u002Fguides\u002Fwriting-claude-md-files.md","CLAUDE.md is project memory, not documentation",null,{"type":8,"value":9,"toc":295},"minimark",[10,14,27,37,40,45,64,78,100,104,107,143,150,154,160,177,191,195,198,201,228,232,242,253,257,260,264],[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],{},"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 prompt content: every line stays in context for the duration of the\nsession and competes with the user's actual task for the model's\nattention. A 50-line file Claude can keep loaded. A 2000-line file Claude\nreads once and effectively forgets — the rules at line 1500 don't fire\nwhen they should.",[15,38,39],{},"So the question is what to put in 50–200 lines that change Claude's\nbehavior on this codebase, and what to leave out because Claude can read\nit from the code itself.",[41,42,44],"h2",{"id":43},"what-belongs-in-claudemd","What belongs in CLAUDE.md",[15,46,47,51,52,55,56,59,60,63],{},[48,49,50],"strong",{},"Rules that aren't derivable from the code.","\n\"Use ",[19,53,54],{},"bun"," instead of ",[19,57,58],{},"npm",".\" \"Never run dev servers.\" \"Commit messages\nare imperative with no ",[19,61,62],{},"feat:"," prefix.\" Claude can't infer house rules\nfrom grepping the codebase.",[15,65,66,69,70,73,74,77],{},[48,67,68],{},"Hidden invariants and rationale.","\n\"The retry loop in ",[19,71,72],{},"worker.go:142"," runs 5x, not 3x, because the upstream\nAPI has a 4s connect-timeout-then-retry on its side — anything less than\n5 and we miss the second-attempt window.\" Context that doesn't exist\nanywhere else, not even in ",[19,75,76],{},"git log",".",[15,79,80,51,83,86,87,90,91,94,95,99],{},[48,81,82],{},"Tool and runtime preferences.",[19,84,85],{},"rg"," for text search, ",[19,88,89],{},"sg"," for AST queries. Type-check with ",[19,92,93],{},"bunx vue-tsc --noEmit"," before declaring done.\" Shapes ",[96,97,98],"em",{},"how"," Claude works on\nthe code, not what it builds.",[41,101,103],{"id":102},"what-does-not-belong","What does NOT belong",[15,105,106],{},"Anything Claude can extract on demand:",[108,109,110,117,123,131,137],"ul",{},[111,112,113,116],"li",{},[48,114,115],{},"File layout"," — Claude can read the directory tree.",[111,118,119,122],{},[48,120,121],{},"Function signatures or API shapes"," — Claude can grep and read.",[111,124,125,128,129,77],{},[48,126,127],{},"Recent git history"," — Claude can run ",[19,130,76],{},[111,132,133,136],{},[48,134,135],{},"General programming practices"," — already in the model's weights.",[111,138,139,142],{},[48,140,141],{},"Ephemeral todo lists or current sprint state"," — those belong in\nTodoWrite or per-task notes, not in the shared CLAUDE.md.",[15,144,145,146,149],{},"The litmus test for any candidate rule: ",[96,147,148],{},"will Claude reliably do this\nwithout it?"," If yes, drop the rule.",[41,151,153],{"id":152},"format","Format",[15,155,156,159],{},[48,157,158],{},"Imperatives, not narration."," \"Use X.\" beats \"We try to use X when\nappropriate.\" Direct directives override softer language in the prompt.",[15,161,162,165,166,169,170,169,173,176],{},[48,163,164],{},"Group by concern."," ",[19,167,168],{},"## Code Style",", ",[19,171,172],{},"## Tools & Runtime",[19,174,175],{},"## Commit Conventions",". One block per topic so Claude can attend to the whole\nsection when one concern is active.",[15,178,179,182,183,186,187,190],{},[48,180,181],{},"Why before what for non-obvious rules."," \"Never use ",[19,184,185],{},"--no-verify"," on\ngit commits. Reason: a previous incident bypassed a pre-commit hook that\ncatches secret leakage; the hook fired but the secret already pushed to\nremote.\" Without the ",[96,188,189],{},"why",", the rule looks arbitrary the next time it\ngets in the way, and the next contributor deletes it.",[41,192,194],{"id":193},"length-and-discipline","Length and discipline",[15,196,197],{},"A 200-line CLAUDE.md is read with attention. A 2000-line one is skimmed.",[15,199,200],{},"If yours is growing past a few hundred lines, look for:",[108,202,203,212,222],{},[111,204,205,208,209,211],{},[48,206,207],{},"Domain expansion"," — split into multiple subdirectory ",[19,210,21],{}," files.\nEach one applies only to its subtree.",[111,213,214,217,218,221],{},[48,215,216],{},"Documentation creep"," — content that's really product documentation, not\nproject memory. Move to ",[19,219,220],{},"docs\u002F"," or a wiki.",[111,223,224,227],{},[48,225,226],{},"Wishful rules"," — things nobody actually enforces. Either bake them into\nCI or delete them.",[41,229,231],{"id":230},"a-useful-skeleton","A useful skeleton",[233,234,240],"pre",{"className":235,"code":237,"language":238,"meta":239},[236],"language-markdown","# CLAUDE.md\n\n## Tone\n\n- Push back when you disagree with evidence. Don't perform agreement.\n- Surface uncertainty explicitly. \"I'm guessing\" beats confident wrong.\n\n## Code style\n\n- 4-space indent in Python, tabs in Go.\n- Tests next to implementation, not in \u002Ftests.\n- Public APIs documented with one sentence + an example.\n\n## Tools\n\n- bun, never npm. rg for search, sg for AST.\n- `bunx vue-tsc --noEmit` before declaring done.\n\n## Commit \u002F PR\n\n- Imperative sentence-case subjects. No type prefix.\n- One concern per commit. Atomic.\n- Co-author Claude when it contributed.\n","markdown","",[19,241,237],{"__ignoreMap":239},[15,243,244,245,248,249,252],{},"That's it for a small project. For a larger one, add ",[19,246,247],{},"## Architecture"," (the\ninvariants Claude must respect) and ",[19,250,251],{},"## Workflows"," (how multi-step tasks are\nexpected to chain).",[41,254,256],{"id":255},"iterating-on-it","Iterating on it",[15,258,259],{},"Treat CLAUDE.md like code. Review it on PRs. When you find yourself\ncorrecting Claude twice on the same thing, add the rule. When a rule\nhasn't fired in three months, remove it. Mature CLAUDE.md files get\nshorter over time, not longer — the team learns which rules the model\nactually needed and which ones were noise.",[41,261,263],{"id":262},"related","Related",[108,265,266,279,286],{},[111,267,268,269,274,275,278],{},"The ",[270,271,273],"a",{"href":272},"\u002Fplugins","plugin catalog"," — ",[19,276,277],{},"aio-claude-toolkit"," includes a skill for\nauditing existing CLAUDE.md files against best practices.",[111,280,281,285],{},[270,282,284],{"href":283},"\u002Fguides\u002Fskills-agents-hooks","Skills, agents, hooks"," — the three primitives\nClaude Code exposes beyond plain prompts.",[111,287,288,294],{},[270,289,293],{"href":290,"rel":291},"https:\u002F\u002Fdocs.anthropic.com\u002Fclaude\u002Fdocs\u002Fclaude-code",[292],"nofollow","Anthropic's Claude Code docs","\nfor the authoritative reference.",{"title":239,"searchDepth":296,"depth":296,"links":297},2,[298,299,300,301,302,303,304],{"id":43,"depth":296,"text":44},{"id":102,"depth":296,"text":103},{"id":152,"depth":296,"text":153},{"id":193,"depth":296,"text":194},{"id":230,"depth":296,"text":231},{"id":255,"depth":296,"text":256},{"id":262,"depth":296,"text":263},"2026-05-25","Claude Code loads CLAUDE.md into the session prompt on every start. That makes it prompt content, not documentation. What to put in 50–200 lines, what to leave out, and why the file should shrink over time.","guide","md",{},true,"\u002Fguides\u002Fwriting-claude-md-files",{"title":5,"description":306},"guides\u002Fwriting-claude-md-files",[315,316,317,318,319],"claude-md","project-memory","claude-code","best-practices","configuration",10,"yS8M1aDe6xi916z7JmRulrvYD6rSJ6gxX8Lky3HdCWY",[],1779702153310]