CLAUDE.md best practices (med fuldt annoteret eksempel)

CLAUDE.md er den dyreste fil i dit repository. Ikke i bytes. I gentagelse. Alt, hvad du lægger der, læses ind i Claudes kontekst ved starten af hver session og følger med i hver eneste besked, du sender bagefter. En oppustet CLAUDE.md er en skat, du betaler hundredvis af gange om dagen uden at lægge mærke til det.

Vi tester Claude-setups som levevej hos SkillProof, og vi har efterhånden læst flere CLAUDE.md-filer, end vi bryder os om at indrømme. De fleste af dem gør det forkert på samme måde: de behandler filen som en losseplads for alt, hvad forfatteren nogensinde har villet have Claude til at vide. Kodefilosofi, tonepræferencer, en hel style guide, tre afsnit om at være forsigtig. Alt sammen indlæst, hele tiden, for hver forespørgsel, inklusive den, hvor du bad Claude om at omdøbe en variabel.

Denne guide er vores forsøg på at rette op på det. Hvad CLAUDE.md egentlig er til, et komplet annoteret eksempel du kan tilpasse, hvad du bør flytte ud i skills, og regnestykket der forklarer, hvorfor noget af det overhovedet betyder noget.

Hvad CLAUDE.md er, og hvornår den indlæses

CLAUDE.md er Claude Codes projekt-hukommelsesfil. Når du starter en session i en mappe, går Claude Code opad fra din arbejdsmappe, leder efter CLAUDE.md-filer og indlæser, hvad den finder, i systemkonteksten. Din globale fil i ~/.claude/CLAUDE.md indlæses også, i alle projekter. Filer i undermapper indlæses, når Claude arbejder med filer i de undermapper.

Det, folk overser: det er ikke en engangslæsning. Sprogmodeller er stateless, så hele konteksten, inklusive din CLAUDE.md, sendes med hver forespørgsel i samtalen. Stil fyrre spørgsmål i en session, og filen transmitteres fyrre gange. Prompt caching mildner dollaromkostningen, og vi kommer til de faktiske tal, men intet mildner opmærksomhedsomkostningen. Hver token i CLAUDE.md er en token, der konkurrerer med din faktiske kode om modellens fokus.

Det er prisen. Til gengæld får du noget reelt: Claude starter hver session med på forhånd at kende dine build-kommandoer, dine arkitektur-særheder og landminerne i din kodebase. Ingen skal indsætte "vi bruger pnpm, ikke npm" for niende gang. Spørgsmålet er aldrig, om du skal have en CLAUDE.md. Det er, hvad der gør sig fortjent til en plads i den.

Den gyldne regel: fakta i CLAUDE.md, adfærd i skills

Her er tesen for hele denne artikel og det ene filter, der fikser de fleste dårlige filer:

CLAUDE.md er til fakta om dette projekt. Skills er til genbrugelig adfærd.

Et faktum om dette projekt: "priser gemmes som heltal i cent." Claude kan ikke gætte det. Ingen mængde generel intelligens henter det ud af den blå luft, og at tage fejl korrumperer data. Det hører hjemme i CLAUDE.md, permanent indlæst, fordi det er relevant for stort set enhver ændring, der rører ved penge.

Genbrugelig adfærd: "ved code review, tjek fejlhåndtering først, så sikkerhed, så navngivning." Det er ikke et faktum om dit projekt. Det er en procedure, den gælder for hvert projekt, du nogensinde rører, og den er kun relevant, når du rent faktisk laver review. Læg den i CLAUDE.md, og du betaler for den under hver commit-besked, hver CSS-justering, hvert "hvad gør den her funktion". Læg den i en skill, og den koster dig én linje metadata indtil det øjeblik, et review faktisk finder sted — og så indlæses de fulde instruktioner on demand.

De fleste propper alt i CLAUDE.md, fordi det er den fil, de kender. Den ligger lige der, den virker åbenlyst, og omkostningen er usynlig, fordi ingen faktura nogensinde skriver "du betalte for din style guide 4.000 gange denne måned". Men omkostningen er reel, og opdelingen er næsten mekanisk, når du stiller to spørgsmål til enhver instruktion. Gælder den kun for dette projekt? Er den relevant for de fleste forespørgsler? To ja'er: CLAUDE.md. Alt andet: en skill, eller skraldespanden.

Der er en anden grund til opdelingen, som intet har med tokens at gøre. Instruktioner i en altid-indlæst fil konkurrerer med hinanden. Vi har set en CLAUDE.md på 2.000 ord, hvor den virkelig vigtige regel ("kør aldrig db:push mod staging") lå i afsnit elleve, under en forelæsning om clean code. Claude følger lange instruktionslister på samme måde som mennesker: de skarpe punkter udvandes af fyldet omkring dem. Korte filer bliver adlydt. Lange filer bliver skimmet.

Et annoteret CLAUDE.md-eksempel til en mellemstor webapp

Her er et komplet eksempel til en fiktiv men realistisk Next.js-webshop. Annoteringerne forklarer, hvorfor hver sektion gør sig fortjent til sin permanente plads i konteksten. Det lander på omkring 350 ord, cirka 500 tokens, og vi vil påstå, at intet i det kan skæres væk.

# 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æg mærke til, hvad der mangler. Intet "skriv ren, vedligeholdelsesvenlig kode". Ingen tone-instruktioner. Ingen forklaring på, hvad Next.js er. Ingen lint-regler, som linteren allerede håndhæver mekanisk. Hver linje er enten en kommando, Claude vil køre, et faktum, den ikke kan udlede, eller en grænse, hvor en overskridelse koster rigtige penge eller rigtige timer.

Hvad du bør flytte ud i skills

Er din nuværende CLAUDE.md på 1.500 ord, falder overskuddet som regel i nogle få genkendelige bunker, og hver bunke har et skill-formet hjem. Nogle eksempler fra vores eget katalog, alle installeret og testet på rene maskiner, før vi listede dem:

Git-ceremoni. Branch-navngivning, commit-beskedformat, PR-beskrivelsesskabeloner, hvornår man squasher. Det er adfærd, det er identisk på tværs af dine projekter, og det er kun relevant, når du faktisk committer. git-workflow-skillen, vi testede, håndterer præcis det scope, og at flytte det ud af CLAUDE.md sparer typisk 200 til 400 ord altid-indlæst tekst.

Review-tjeklister. "Når jeg beder om et review, tjek X og så Y"-instruktioner er den klassiske CLAUDE.md-husbesætter. De er lange, de er procedurelle, og de ligger i dvale 95 % af tiden. code-review-checklist indlæser kun sin tjekliste, når et review faktisk finder sted, hvilket er hele pointen med skill-formatet.

Debugging-disciplin. Instruktioner som "reproducér før du fikser, formuler din hypotese, verificér bagefter" beskriver en metode, ikke dit projekt. systematic-debugging pakker den metode og holder sig ude af konteksten, mens du laver alt andet end at jagte en bug.

Den generelle regel: kunne du kopiere afsnittet ind i et andet projekts CLAUDE.md uden at redigere det, er det ikke et faktum om dit projekt, og så skal det ikke bo der. Træk det ud. At skrive din egen skill tager omkring tyve minutter med vores guide, og det er de mest værdifulde tyve minutter, der findes for alle, hvis CLAUDE.md er rullet forbi én skærm.

Anti-mønstre vi bliver ved med at se

Vi gennemgår mange setups, og de samme fem fejl dukker op igen og igen.

Romanen. En CLAUDE.md på 3.000 ord, der læser som en engineering-håndbog. Nogen havde en dårlig oplevelse, tilføjede et afsnit, havde en til, tilføjede et til og slettede aldrig noget. Filen vokser kun. Ud over token-omkostningen begraver filer som denne de to regler, der faktisk betyder noget, under tyve, der ikke gør, og Claudes efterlevelse af dem alle falder samlet.

Forældede kommandoer. Filen siger npm run test:unit, scriptet blev omdøbt til pnpm test for otte måneder siden, og nu kører Claude selvsikkert en kommando, der fejler, læser fejlen, roder rundt i package.json og finder til sidst ud af det. Hver session. Du betaler for den forkerte dokumentation og betaler så igen for, at Claude navigerer uden om den. En forkert CLAUDE.md er værre end ingen CLAUDE.md, for Claude stoler på den.

Duplikerede lint-regler. "Brug enkelt-anførselstegn. Ingen ubrugte variabler. Maks. linjelængde 100." Din ESLint-config håndhæver allerede det mekanisk, med bedre dækning end en LLM's opmærksomhed nogensinde får. At gentage maskinhåndhævede regler i prosa er rent spild. Den ene undtagelse: regler, værktøjet ikke kan fange, som "importér ikke fra src/legacy", der reelt skal skrives ned.

"Vær hjælpsom"-sektionen. "Skriv ren kode. Tænk dig godt om, før du ændrer noget. Vær grundig men kortfattet." Vi ser en variation af det i måske halvdelen af de filer, vi gennemgår, og det gør ingenting. Claude prøver allerede. Vibe-baserede instruktioner uden testbart indhold er det første, der skal slettes, og deres eneste målbare effekt er de tokens, de brænder.

Selvbiografien. Lange beskrivelser af, hvad produktet gør, hvem brugerne er, virksomhedens mission. Ind imellem betyder ét produktfaktum noget for kodebeslutninger ("vores brugere sidder på langsomme landforbindelser, bundle-størrelse er en reel begrænsning"). Behold den ene sætning. Skær pitch-decket væk.

Token-regnestykket

Lad os lave det regnestykke, folk springer over, for det var tallene, der gjorde os til minimalister.

En CLAUDE.md på 3.000 ord er cirka 4.000 tokens. Den følger med hver forespørgsel, så en arbejdssession på 40 beskeder transmitterer den 40 gange: 160.000 input-tokens i én session, som er din hukommelsesfil, ikke din kode eller din samtale. Arbejd fem sessioner om dagen, og du flytter 800.000 CLAUDE.md-tokens dagligt. Over en måned med 22 arbejdsdage: omkring 17,6 millioner.

Prompt caching redder det meste af dollaromkostningen, og det skal vi være ærlige om. Cachet input på Sonnet koster en tiendedel af basisprisen, så de 17,6 mio. tokens koster et par dollars om måneden, hvis cachen holdes varm, snarere $50 hvis ikke. Irriterende, ikke ruinerende.

Omkostningen, som caching ikke redder, er kontekst. Claude Codes kontekstvindue er endeligt, og lange sessioner ender allerede i compaction, hvor samtalen opsummeres og detaljer går tabt. En permanent beboer på 4.000 tokens betyder, at du rammer compaction tidligere, hver session, for altid. Den forringer også opmærksomheden, før du rammer nogen hård grænse: modeller følger beviseligt instruktioner bedre, når der er færre af dem, der konkurrerer. Forskellen mellem en fil på 500 tokens og en på 4.000 er ikke 3.500 tokens. Det er, om modellen stadig bekymrer sig om din "rør aldrig staging"-regel ved besked 35.

Kør samme tal på det trimmede eksempel ovenfor: 500 tokens, 40 beskeder, fem sessioner, 22 dage. Omkring 2,2 mio. tokens om måneden, en ottendedel af den oppustede version, med de vigtige regler stående i et rum uden trængsel. Vi har skrevet den bredere spare-playbook i vores token-omkostningsguide, og CLAUDE.md-trimning er konsekvent den billigste gevinst i den.

Projekt vs. global: opdelingen med ~/.claude/CLAUDE.md

Du har to filer, og det går galt, når indhold lander i den forkerte.

~/.claude/CLAUDE.md er global. Den indlæses i alle projekter, så den må kun indeholde ting, der er sande alle steder: "jeg bruger pnpm i alle personlige projekter", "svar på engelsk, selvom mine prompts nogle gange er på russisk", "commit aldrig uden at blive bedt om det". Hold den under ti linjer. Hver linje her ganges op på tværs af alt dit arbejde, så dens budget skal være det strammeste.

<project>/CLAUDE.md er projektfilen, checket ind i git, delt med kolleger og CI. Fakta om denne kodebase, i samme form som eksemplet ovenfor. Fordi den er delt, hører personlige præferencer ikke hjemme i den; det er det, CLAUDE.local.md eller den globale fil er til.

CLAUDE.md-filer i undermapper er det underudnyttede mellemlag. En packages/api/CLAUDE.md med API-specifikke fakta indlæses kun, når Claude rører den pakke. Har din monorepos rodfil sektioner, der kun gælder ét workspace, er det gratis token-besparelse uden informationstab at skubbe dem et niveau ned.

En misforståelse, der fortjener at dø: at lægge en ting i mere end én af disse filer får ikke Claude til at følge den hårdere. Det gør bare filen længere. Vælg ét hjem pr. faktum.

Hold den frisk

CLAUDE.md rådner hurtigere end almindelig dokumentation, fordi intet går synligt i stykker, når den er forkert. Tests fejler højlydt. En forældet hukommelsesfil vildleder bare stille modellen, som stille retter op, og du betaler stille for begge dele.

Vores ritual er kedeligt og tager ti minutter om måneden. Åbn filen. Kør faktisk hver kommando. Spørg for hvert påstået faktum, om det stadig er sandt, og om Claude tog fejl af noget denne måned på grund af det. Slet mindst én linje; der er altid en linje, og kan du ikke finde den, er dine krav til "at gøre sig fortjent til en plads" skredet. Tjek så længden: én skærm er målet, to skærme er loftet, og forbi det redigerer du ikke længere, du udtrækker til skills.

Den bedste trigger for opdateringer er dog ikke kalenderen. Det er øjeblikket, hvor Claude gør noget forkert, fordi filen vildledte den. Fiks filen i samme åndedrag som koden. Behandl CLAUDE.md-bugs som bugs, for de har samme tilbagefaldsmønster: ufiksede sker de igen næste session.

FAQ

Hvor lang bør en CLAUDE.md være?

Under 500 ord for de fleste projekter, under 1.000 for en reelt kompliceret monorepo. Vores arbejdstest: passer den ikke på én skærm, er noget i den adfærd forklædt som fakta, og det noget hører hjemme i en skill. Eksemplet i denne artikel er på cirka 350 ord og dækker en rigtig mellemstor app.

Hvad er forskellen på CLAUDE.md og en skill?

Indlæsningsadfærd. CLAUDE.md indlæses i sin helhed, altid, for hver forespørgsel. En skill eksponerer kun en beskrivelse på én linje, indtil en opgave matcher den, og indlæses så on demand. Så CLAUDE.md skal rumme fakta, du konstant har brug for, og skills skal rumme procedurer, du har brug for af og til. Vores skills-guide dækker mekanikken.

Skal jeg committe CLAUDE.md til git?

Ja. Det er delt dokumentation, og dine kollegers Claude-sessioner nyder godt af de samme fakta som dine. Hold personlige præferencer i CLAUDE.local.md (gitignoret) eller din globale fil i stedet for at trække dem ned over teamet.

Kan jeg bruge indlejrede CLAUDE.md-filer i undermapper?

Ja, og i monorepos bør du. Claude Code indlæser en undermappes fil, når den arbejder med filer dér. Rodfilen får repo-brede fakta, packages/api/CLAUDE.md får API-fakta, og enkelt-pakke-projekter kan springe indlejring helt over.

Ændrer trimning af CLAUDE.md faktisk Claudes adfærd, eller kun omkostningen?

Begge dele, og adfærden er den største gevinst. Instruktionsefterlevelse forringes, når antallet af instruktioner vokser; en kort fil med fem skarpe regler bliver adlydt mere pålideligt end en lang med tredive. Token-besparelsen er den målbare del, og vores effektivitets-ranglister følger, hvilke skills der hjælper mest dér, men forbedringen i efterlevelse er det, du bemærker først.

En sidste holdning: de bedste CLAUDE.md-filer, vi har set, blev alle redigeret ved sletning. Ingen skriver en fantastisk en på dag ét. Du skriver en middelmådig, ser hvor Claude snubler, tilføjer det faktum, der ville have forhindret det, og skærer en linje fyld for at betale for det. Seks uger af det slår enhver skabelon, inklusive vores.