CLAUDE.md best practices — med komplett kommenterat exempel

CLAUDE.md är den dyraste filen i ditt repository. Inte i bytes. I upprepning. Allt du lägger där läses in i Claudes context i början av varje session och åker med i varje enskilt meddelande du skickar därefter. En uppsvälld CLAUDE.md är en skatt du betalar hundratals gånger om dagen utan att märka det.

Vi testar Claude-setups på heltid på SkillProof, och vi har vid det här laget läst fler CLAUDE.md-filer än vi vill erkänna. De flesta gör fel på samma sätt: de behandlar filen som en avstjälpningsplats för allt författaren någonsin velat att Claude ska veta. Kodfilosofi, tonpreferenser, en komplett stilguide, tre stycken om att vara försiktig. Allt inläst, hela tiden, för varje förfrågan inklusive den där du bad Claude byta namn på en variabel.

Den här guiden är vårt försök att fixa det. Vad CLAUDE.md faktiskt är till för, ett komplett kommenterat exempel du kan anpassa, vad du bör flytta ut till skills, och matematiken som förklarar varför något av det här spelar roll.

Vad CLAUDE.md är och när den laddas

CLAUDE.md är Claude Codes minnesfil för projekt. När du startar en session i en katalog vandrar Claude Code uppåt från din arbetskatalog och letar efter CLAUDE.md-filer och laddar det den hittar in i systemkontexten. Din globala fil i ~/.claude/CLAUDE.md laddas också, i varje projekt. Filer i underkataloger laddas när Claude arbetar med filer i de underkatalogerna.

Delen folk missar: det här är inte en engångsläsning. Språkmodeller är tillståndslösa, så hela contexten, inklusive din CLAUDE.md, skickas med varje förfrågan i konversationen. Ställ fyrtio frågor i en session och filen överförs fyrtio gånger. Prompt caching mildrar dollarkostnaden, och vi kommer till de faktiska siffrorna, men inget mildrar uppmärksamhetskostnaden. Varje token i CLAUDE.md är en token som konkurrerar med din faktiska kod om modellens fokus.

Det är priset. Det köper dig något verkligt: Claude börjar varje session med att redan känna till dina byggkommandon, dina arkitekturegenheter och minorna i din kodbas. Ingen behöver klistra in "vi använder pnpm, inte npm" för nionde gången. Frågan är aldrig om du ska ha en CLAUDE.md. Det är vad som förtjänar en plats i den.

Gyllene regeln: fakta i CLAUDE.md, beteende i skills

Här är tesen för hela den här artikeln, och det enda filter som lagar de flesta dåliga filer:

CLAUDE.md är för fakta om det här projektet. Skills är för återanvändbart beteende.

Ett faktum om det här projektet: "priser lagras som heltal i cent." Claude kan inte gissa det. Ingen mängd allmän intelligens plockar fram det ur tomma luften, och att få det fel korrumperar data. Det hör hemma i CLAUDE.md, permanent inläst, eftersom det är relevant för nästan varje ändring som rör pengar.

Återanvändbart beteende: "vid kodgranskning, kolla felhantering först, sedan säkerhet, sedan namngivning." Det är inte ett faktum om ditt projekt. Det är en procedur, den gäller varje projekt du någonsin kommer att röra, och den är bara relevant när du faktiskt granskar kod. Lägg den i CLAUDE.md och du betalar för den under varje commit-meddelande, varje CSS-justering, varje "vad gör den här funktionen". Lägg den i en skill och den kostar dig en rad metadata fram till ögonblicket då en granskning faktiskt sker, varpå de fullständiga instruktionerna laddas vid behov.

De flesta trycker in allt i CLAUDE.md för att det är filen de känner till. Den ligger där, den fungerar uppenbarligen, och kostnaden är osynlig eftersom ingen faktura någonsin säger "du betalade för din stilguide 4 000 gånger den här månaden". Men kostnaden är verklig, och uppdelningen är nästan mekanisk när du ställer två frågor om varje instruktion. Är den bara sann för det här projektet? Är den relevant för de flesta förfrågningar? Två ja: CLAUDE.md. Allt annat: en skill, eller papperskorgen.

Det finns ett andra skäl till uppdelningen som inte har något med tokens att göra. Instruktioner i en alltid inläst fil konkurrerar med varandra. Vi har sett en CLAUDE.md på 2 000 ord där den genuint viktiga regeln ("kör aldrig db:push mot staging") satt i stycke elva, under en föreläsning om ren kod. Claude följer långa instruktionslistor på samma sätt som människor gör: de vassa punkterna späds ut av utfyllnaden runt dem. Korta filer blir åtlydda. Långa filer blir skummade.

Ett kommenterat CLAUDE.md-exempel för en medelstor webbapp

Här är ett komplett exempel för en fiktiv men realistisk Next.js-butik. Kommentarerna förklarar varför varje sektion förtjänar sin permanenta plats i contexten. Det landar på ungefär 350 ord, cirka 500 tokens, och vi skulle hävda att inget i det går att stryka.

# Acme Storefront

Next.js 14 (App Router) + TypeScript. Postgres via Prisma. Deployed on Vercel.
<!-- One line of stack. Claude infers most of this from package.json anyway;
     this just saves it the lookup. Do not write paragraphs here. -->

## Commands
- `pnpm dev` — local server on :3000 (needs `docker compose up db` first)
- `pnpm test` — unit tests (Vitest). Integration: `pnpm test:int` (slow, needs db)
- `pnpm lint && pnpm typecheck` — run both before calling any task done
- Migrations go through `pnpm db:migrate`. NEVER `db:push` outside local.
<!-- Commands earn their place because Claude runs them dozens of times per
     session, and a wrong guess (npm vs pnpm) wastes a round-trip every time.
     The db:push line is here because the failure is irreversible. -->

## Architecture facts you can't guess
- `src/app` is routes only. All logic lives in `src/modules/<domain>`.
- API routes are thin wrappers over `src/modules/*/service.ts`. No logic in routes.
- Auth is Clerk, but `userId` in services is OUR internal id, not Clerk's.
  Map with `getInternalUser()`.
- Prices are integer cents everywhere. Formatting lives in `lib/money.ts`.
- Feature flags come from `flags.ts`, not env vars.
<!-- The test for this section: would a skilled new hire get it wrong on
     day one? The Clerk id mismatch has caused real bugs; that is exactly
     the kind of fact worth paying for on every request. -->

## Conventions that differ from defaults
- Named exports only. Legacy violations exist in `src/legacy`; don't add new ones.
- Server components by default. `"use client"` needs a comment saying why.
- Zod schemas live next to services; infer types from them, never hand-write both.
<!-- Only conventions that DIFFER from what Claude would do anyway.
     "Use TypeScript strict mode" when tsconfig already says so is a wasted line. -->

## Gotchas
- `src/legacy/*` is frozen. Don't refactor it or import from it in new code.
- CI runs Node 20. `pnpm test:int` fails on 22; use `nvm use` first.
<!-- Each line here represents an hour someone actually lost. -->

## Definition of done
Lint, typecheck, and unit tests pass, and you state which of them you ran.
<!-- One sentence. Not a philosophy of quality. -->

Lägg märke till vad som saknas. Inget "skriv ren, underhållbar kod". Inga toninstruktioner. Ingen förklaring av vad Next.js är. Inga lintregler som lintern redan upprätthåller mekaniskt. Varje rad är antingen ett kommando Claude kommer att köra, ett faktum den inte kan härleda, eller en gräns där en överträdelse kostar riktiga pengar eller riktiga timmar.

Vad du bör flytta ut till skills

Om din nuvarande CLAUDE.md är 1 500 ord faller överskottet oftast i några igenkännbara högar, och varje hög har ett skill-format hem. Några exempel från vår egen katalog, alla installerade och testade på rena maskiner innan vi listade dem:

Git-ceremonier. Branch-namngivning, commit-meddelandeformat, PR-beskrivningsmallar, när man ska squasha. Det här är beteende, det är identiskt över alla dina projekt, och det är bara relevant när du faktiskt committar. Skillen git-workflow som vi testade hanterar exakt det här omfånget, och att flytta ut det ur CLAUDE.md sparar typiskt 200 till 400 ord alltid-inläst text.

Granskningschecklistor. Instruktioner i stil med "när jag ber om en review, kolla X och sedan Y" är den klassiska CLAUDE.md-ockupanten. De är långa, de är procedurella och de ligger i dvala 95 % av tiden. code-review-checklist laddar sin checklista bara när en granskning faktiskt pågår, vilket är hela poängen med skill-formatet.

Felsökningsdisciplin. Instruktioner som "reproducera innan du fixar, formulera din hypotes, verifiera efteråt" beskriver en metodik, inte ditt projekt. systematic-debugging paketerar den metodiken och håller sig utanför contexten medan du gör något annat än att jaga en bugg.

Den generella regeln: om du kan kopiera stycket in i ett annat projekts CLAUDE.md utan att redigera det, är det inte ett faktum om ditt projekt och det ska inte bo där. Extrahera det. Att skriva en egen skill tar ungefär tjugo minuter med vår guide, och det är de tjugo minuter med högst hävstång som finns tillgängliga för alla vars CLAUDE.md har rullat förbi en skärm.

Antimönster vi ser om och om igen

Vi granskar många setups, och samma fem misslyckanden dyker upp på repeat.

Romanen. En CLAUDE.md på 3 000 ord som läses som en ingenjörshandbok. Någon hade en dålig upplevelse, la till ett stycke, hade en till, la till ett till, och raderade aldrig något. Filen bara växer. Utöver tokenkostnaden begraver sådana filer de två regler som faktiskt spelar roll under tjugo som inte gör det, och Claudes efterlevnad av allihop sjunker tillsammans.

Inaktuella kommandon. Filen säger npm run test:unit, skriptet döptes om till pnpm test för åtta månader sedan, och nu kör Claude självsäkert ett kommando som fallerar, läser felet, rotar runt i package.json och återhämtar sig. Varje session. Du betalar för fel dokumentation och betalar sedan igen för att Claude ska ta sig runt den. En felaktig CLAUDE.md är värre än ingen CLAUDE.md, för Claude litar på den.

Duplicerade lintregler. "Använd enkla citattecken. Inga oanvända variabler. Max radlängd 100." Din ESLint-konfiguration upprätthåller redan detta mekaniskt, med bättre täckning än en LLM:s uppmärksamhet någonsin kommer att ha. Att upprepa maskinupprätthållna regler i prosa är rent slöseri. Det enda undantaget: regler verktygen inte kan fånga, som "importera inte från src/legacy", vilka genuint behöver skrivas ned.

"Var hjälpsam"-sektionen. "Skriv ren kod. Tänk noga innan du gör ändringar. Var grundlig men koncis." Vi ser någon variant av detta i kanske hälften av filerna vi granskar, och det gör ingenting. Claude försöker redan. Vibbaserade instruktioner utan testbart innehåll är det första du ska radera, och deras enda mätbara effekt är de tokens de bränner.

Självbiografin. Långa beskrivningar av vad produkten gör, vilka användarna är, företagets mission. Ibland spelar ett enda produktfaktum roll för kodbeslut ("våra användare sitter på långsamma landsbygdsuppkopplingar, bundle-storlek är en verklig begränsning"). Behåll den meningen. Stryk pitchdecken.

Tokenmatematiken

Låt oss göra aritmetiken folk hoppar över, för det var siffrorna som gjorde oss till minimalister.

En CLAUDE.md på 3 000 ord är ungefär 4 000 tokens. Den åker med varje förfrågan, så en arbetssession på 40 meddelanden överför den 40 gånger: 160 000 tokens input under en session som är din minnesfil, inte din kod eller din konversation. Jobba fem sessioner om dagen och du flyttar 800 000 CLAUDE.md-tokens dagligen. Under en månad med 22 arbetsdagar, cirka 17,6 miljoner.

Prompt caching räddar det mesta av dollarkostnaden, och vi ska vara ärliga med det. Cachad input på Sonnet kostar en tiondel av baspriset, så de där 17,6 miljonerna tokens kostar ett par dollar i månaden om cachen hålls varm, snarare 50 dollar om den inte gör det. Irriterande, inte ruinerande.

Kostnaden som caching inte räddar är context. Claude Codes context-fönster är ändligt, och långa sessioner slutar redan i kompaktering, där konversationen sammanfattas och detaljer går förlorade. En permanent hyresgäst på 4 000 tokens betyder att du når kompaktering tidigare, varje session, för alltid. Det försämrar också uppmärksamheten långt innan du når någon hård gräns: modeller följer bevisligen instruktioner bättre när färre av dem konkurrerar. Skillnaden mellan en fil på 500 tokens och en på 4 000 tokens är inte 3 500 tokens. Det är huruvida modellen fortfarande bryr sig om din "rör aldrig staging"-regel vid meddelande 35.

Kör samma siffror på det bantade exemplet ovan: 500 tokens, 40 meddelanden, fem sessioner, 22 dagar. Cirka 2,2 miljoner tokens i månaden, en åttondel av den uppsvällda versionen, med de viktiga reglerna stående i ett rum utan trängsel. Vi har skrivit ihop den bredare kostnadssänkningsplaybooken i vår guide om tokenkostnader, och CLAUDE.md-bantning är konsekvent den billigaste vinsten i den.

Projekt vs globalt: uppdelningen med ~/.claude/CLAUDE.md

Du har två filer, och det går snett när innehåll hamnar i fel.

~/.claude/CLAUDE.md är global. Den laddas i varje projekt, så den får bara innehålla saker som är sanna överallt: "jag använder pnpm i alla personliga projekt", "svara på engelska även om mina promptar ibland är på ryska", "committa aldrig utan att bli ombedd". Håll den under tio rader. Varje rad här multipliceras över allt ditt arbete, så dess budget ska vara den stramaste.

<project>/CLAUDE.md är projektfilen, incheckad i git, delad med kollegor och CI. Fakta om den här kodbasen, i samma form som exemplet ovan. Eftersom den är delad hör personliga preferenser inte hemma i den; det är vad CLAUDE.local.md eller den globala filen är till för.

CLAUDE.md-filer i underkataloger är den underutnyttjade mellannivån. En packages/api/CLAUDE.md med API-specifika fakta laddas bara när Claude rör det paketet. Om ditt monorepos rotfil har sektioner som gäller ett enda workspace är det gratis tokenbesparing utan informationsförlust att trycka ned dem en nivå.

En missuppfattning värd att avliva: att lägga en sak i mer än en av dessa filer får inte Claude att följa den hårdare. Det gör filen längre. Välj ett hem per faktum.

Håll den färsk

CLAUDE.md ruttnar snabbare än vanlig dokumentation eftersom inget går sönder synligt när den är fel. Tester fallerar högljutt. En inaktuell minnesfil vilseleder bara tyst modellen, som tyst återhämtar sig, och du betalar tyst för bådadera.

Vår ritual är tråkig och tar tio minuter i månaden. Öppna filen. Kör faktiskt varje kommando. Fråga för varje påstått faktum om det fortfarande är sant och om Claude gjorde något fel den här månaden på grund av det. Radera minst en rad; det finns alltid en rad, och om du inte hittar den har dina krav för att "förtjäna en plats" halkat. Kolla sedan längden: en skärm är målet, två skärmar är taket, och bortom det redigerar du inte längre, du extraherar till skills.

Den bästa triggern för uppdateringar är dock inte kalendern. Det är ögonblicket när Claude gör något fel för att filen vilseledde den. Fixa filen i samma andetag som koden. Behandla CLAUDE.md-buggar som buggar, för de har samma återkomstbeteende: ofixade händer de igen nästa session.

Vanliga frågor

Hur lång bör en CLAUDE.md vara?

Under 500 ord för de flesta projekt, under 1 000 för ett genuint komplicerat monorepo. Vårt arbetstest: om den inte får plats på en skärm är något i den beteende utklätt till fakta, och det något hör hemma i en skill. Exemplet i den här artikeln är ungefär 350 ord och täcker en verklig medelstor app.

Vad är skillnaden mellan CLAUDE.md och en skill?

Laddningsbeteendet. CLAUDE.md laddas i sin helhet, alltid, för varje förfrågan. En skill exponerar bara en enrads beskrivning tills en uppgift matchar den, och laddas sedan vid behov. Så CLAUDE.md ska hålla fakta du behöver konstant, och skills ska hålla procedurer du behöver ibland. Vår skills-guide täcker mekaniken.

Ska jag committa CLAUDE.md till git?

Ja. Det är delad dokumentation, och dina kollegors Claude-sessioner drar nytta av samma fakta som dina. Håll personliga preferenser i CLAUDE.local.md (gitignorerad) eller din globala fil i stället för att trycka dem på teamet.

Kan jag använda nästlade CLAUDE.md-filer i underkataloger?

Ja, och i monorepos bör du. Claude Code laddar en underkatalogs fil när den arbetar med filer där. Rotfilen får repo-övergripande fakta, packages/api/CLAUDE.md får API-fakta, och enkelpaketsprojekt kan hoppa över nästling helt.

Ändrar CLAUDE.md-bantning faktiskt Claudes beteende, eller bara kostnaden?

Bådadera, och beteendet är den större vinsten. Instruktionsföljandet försämras när antalet instruktioner växer; en kort fil med fem vassa regler blir mer pålitligt åtlydd än en lång med trettio. Tokenbesparingen är den mätbara delen, och våra effektivitetsrankningar följer vilka skills som hjälper mest där, men efterlevnadsförbättringen är vad du märker först.

En sista åsikt: de bästa CLAUDE.md-filer vi har sett var alla redigerade genom radering. Ingen skriver en fantastisk fil dag ett. Du skriver en medioker, ser var Claude snubblar, lägger till faktumet som hade förhindrat det, och stryker en rad utfyllnad för att betala för det. Sex veckor av det slår vilken mall som helst, inklusive vår.