CLAUDE.md beste praksis (med kommentert eksempel)

CLAUDE.md er den dyreste filen i repositoryet ditt. Ikke i bytes. I repetisjon. Alt du legger der, leses inn i Claudes kontekst ved starten av hver økt og blir med på hver eneste melding du sender etterpå. En oppblåst CLAUDE.md er en skatt du betaler hundrevis av ganger om dagen uten å merke det.

Vi hos SkillProof tester Claude-oppsett på heltid, og vi har nå lest flere CLAUDE.md-filer enn vi liker å innrømme. De fleste gjør feil på samme måte: de behandler filen som en dumpingplass for alt forfatteren noen gang har villet at Claude skal vite. Kodefilosofi, tonepreferanser, en hel stilguide, tre avsnitt om å være forsiktig. Alt lastet, hele tiden, for hver forespørsel, inkludert den der du ba Claude om å døpe om en variabel.

Denne guiden er vårt forsøk på å fikse det. Hva CLAUDE.md faktisk er til, et komplett kommentert eksempel du kan tilpasse, hva du bør flytte ut i skills, og regnestykket som forklarer hvorfor noe av dette betyr noe.

Hva CLAUDE.md er og når den lastes

CLAUDE.md er Claude Codes prosjektminnefil. Når du starter en økt i en katalog, går Claude Code oppover fra arbeidskatalogen din på jakt etter CLAUDE.md-filer og laster det den finner inn i systemkonteksten. Den globale filen din på ~/.claude/CLAUDE.md lastes også, i alle prosjekter. Filer i underkataloger lastes når Claude jobber med filer der.

Delen folk overser: dette er ikke en engangslesing. Språkmodeller er tilstandsløse, så hele konteksten, inkludert CLAUDE.md-en din, sendes med hver forespørsel i samtalen. Still førti spørsmål i en økt, og filen overføres førti ganger. Prompt caching demper dollarkostnaden, og vi kommer til de faktiske tallene, men ingenting demper oppmerksomhetskostnaden. Hvert token i CLAUDE.md er et token som konkurrerer med den faktiske koden din om modellens fokus.

Det er prisen. Den kjøper deg noe reelt: Claude starter hver økt og kan allerede byggekommandoene dine, arkitekturens rariteter og landminene i kodebasen. Ingen trenger å lime inn «vi bruker pnpm, ikke npm» for niende gang. Spørsmålet er aldri om du skal ha en CLAUDE.md. Det er hva som fortjener en plass i den.

Den gylne regelen: fakta i CLAUDE.md, atferd i skills

Her er tesen for hele denne artikkelen, og det ene filteret som fikser de fleste dårlige filer:

CLAUDE.md er for fakta om dette prosjektet. Skills er for gjenbrukbar atferd.

Et faktum om dette prosjektet: «priser lagres som heltall i cent.» Claude kan ikke gjette det. Ingen mengde generell intelligens henter det ut av løse luften, og å ta feil korrumperer data. Det hører hjemme i CLAUDE.md, permanent lastet, fordi det er relevant for nesten enhver endring som berører penger.

Gjenbrukbar atferd: «ved kodegjennomgang, sjekk feilhåndtering først, så sikkerhet, så navngiving.» Det er ikke et faktum om prosjektet ditt. Det er en prosedyre, den gjelder alle prosjekter du noen gang kommer til å røre, og den er bare relevant når du faktisk gjennomgår kode. Legg den i CLAUDE.md, og du betaler for den under hver commit-melding, hver CSS-justering, hvert «hva gjør denne funksjonen». Legg den i en skill, og den koster deg én linje metadata frem til øyeblikket en gjennomgang faktisk skjer, og da lastes de fulle instruksjonene på forespørsel.

De fleste dytter alt inn i CLAUDE.md fordi det er filen de kjenner til. Den er rett der, den fungerer åpenbart, og kostnaden er usynlig fordi ingen faktura noensinne sier «du betalte for stilguiden din 4 000 ganger denne måneden». Men kostnaden er reell, og fordelingen er nesten mekanisk når du stiller to spørsmål om enhver instruksjon. Er den sann bare for dette prosjektet? Er den relevant for de fleste forespørsler? To ja: CLAUDE.md. Alt annet: en skill, eller søpla.

Det finnes en grunn nummer to for delingen som ikke har noe med tokens å gjøre. Instruksjoner i en fil som alltid lastes, konkurrerer med hverandre. Vi har sett en CLAUDE.md på 2 000 ord der den genuint viktige regelen («aldri kjør db:push mot staging») satt i avsnitt elleve, under en forelesning om ren kode. Claude følger lange instruksjonslister slik mennesker gjør: de skarpe punktene vannes ut av fyllstoffet rundt. Korte filer blir adlydt. Lange filer blir skumlest.

Et kommentert CLAUDE.md-eksempel for en mellomstor webapp

Her er et komplett eksempel for en fiktiv, men realistisk Next.js-nettbutikk. Kommentarene forklarer hvorfor hver seksjon fortjener sin faste plass i konteksten. Det ender på rundt 350 ord, omtrent 500 tokens, og vi vil hevde at ingenting i det kan kuttes.

# 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. -->

Legg merke til hva som mangler. Ingen «skriv ren, vedlikeholdbar kode». Ingen toneinstruksjoner. Ingen forklaring av hva Next.js er. Ingen lint-regler som linteren allerede håndhever mekanisk. Hver linje er enten en kommando Claude kommer til å kjøre, et faktum den ikke kan utlede, eller en grense der overtredelse koster ekte penger eller ekte timer.

Hva du bør flytte ut i skills

Er din nåværende CLAUDE.md på 1 500 ord, faller overskuddet vanligvis i noen gjenkjennelige bøtter, og hver bøtte har et skill-formet hjem. Noen eksempler fra vår egen katalog, alle installert og testet på rene maskiner før vi listet dem:

Git-seremoni. Branch-navngiving, commit-meldingsformat, maler for PR-beskrivelser, når man skal squashe. Dette er atferd, det er identisk på tvers av prosjektene dine, og det er bare relevant når du faktisk committer. git-workflow-skillen vi testet håndterer nøyaktig dette omfanget, og å flytte det ut av CLAUDE.md sparer typisk 200 til 400 ord tekst som ellers alltid lastes.

Gjennomgangssjekklister. «Når jeg ber om review, sjekk X og så Y»-instruksjoner er den klassiske CLAUDE.md-okkupanten. De er lange, de er prosedyriske, og de ligger i dvale 95 % av tiden. code-review-checklist laster sjekklisten sin bare når en gjennomgang faktisk skjer, og det er hele poenget med skill-formatet.

Feilsøkingsdisiplin. Instruksjoner som «reproduser før du fikser, formuler hypotesen din, verifiser etterpå» beskriver en metodikk, ikke prosjektet ditt. systematic-debugging pakker den metodikken og holder seg unna konteksten mens du gjør noe annet enn å jage en bug.

Den generelle regelen: kunne du kopiert avsnittet inn i et annet prosjekts CLAUDE.md uten å redigere det, er det ikke et faktum om prosjektet ditt og hører ikke hjemme der. Trekk det ut. Å skrive din egen skill tar rundt tjue minutter med guiden vår, og det er de mest verdifulle tjue minuttene som finnes for alle med en CLAUDE.md som har rullet forbi én skjerm.

Antimønstre vi stadig ser

Vi gjennomgår mange oppsett, og de samme fem feilene dukker opp på repeat.

Romanen. En CLAUDE.md på 3 000 ord som leses som en ingeniørhåndbok. Noen hadde en dårlig opplevelse, la til et avsnitt, hadde en til, la til ett til, og slettet aldri noe. Filen bare vokser. Utover token-kostnaden begraver slike filer de to reglene som faktisk betyr noe, under tjue som ikke gjør det, og Claudes etterlevelse av alle sammen synker i takt.

Utdaterte kommandoer. Filen sier npm run test:unit, skriptet ble omdøpt til pnpm test for åtte måneder siden, og nå kjører Claude selvsikkert en kommando som feiler, leser feilen, roter rundt i package.json og henter seg inn. Hver økt. Du betaler for feil dokumentasjon og betaler så igjen for at Claude skal rute seg rundt den. En feilaktig CLAUDE.md er verre enn ingen CLAUDE.md, for Claude stoler på den.

Dupliserte lint-regler. «Bruk enkle anførselstegn. Ingen ubrukte variabler. Maks linjelengde 100.» ESLint-konfigen din håndhever allerede dette mekanisk, med bedre dekning enn en LLMs oppmerksomhet noensinne får. Å gjenta maskinhåndhevede regler i prosa er rent sløseri. Det ene unntaket: regler verktøyene ikke kan fange, som «ikke importer fra src/legacy», som genuint må skrives ned.

«Vær hjelpsom»-seksjonen. «Skriv ren kode. Tenk nøye før du gjør endringer. Vær grundig, men konsis.» Vi ser en variant av dette i kanskje halvparten av filene vi gjennomgår, og det gjør ingenting. Claude prøver allerede. Vibbebaserte instruksjoner uten testbart innhold er det første du bør slette, og deres eneste målbare effekt er tokenene de brenner.

Selvbiografien. Lange beskrivelser av hva produktet gjør, hvem brukerne er, selskapets misjon. Av og til betyr ett produktfaktum noe for kodebeslutninger («brukerne våre sitter på trege bygdenett, bundle-størrelse er en reell begrensning»). Behold den ene setningen. Kutt pitch-decket.

Token-regnestykket

La oss gjøre regnestykket folk hopper over, for det er tallene som gjorde oss til minimalister.

En CLAUDE.md på 3 000 ord er omtrent 4 000 tokens. Den blir med hver forespørsel, så en arbeidsøkt på 40 meldinger overfører den 40 ganger: 160 000 tokens input i én økt som er minnefilen din, ikke koden eller samtalen. Jobb fem økter om dagen, og du flytter 800 000 CLAUDE.md-tokens daglig. Over en måned på 22 dager, rundt 17,6 millioner.

Prompt caching redder mesteparten av dollarkostnaden, og det skal vi være ærlige om. Cachet input på Sonnet koster en tidel av grunnprisen, så de 17,6 millioner tokenene koster et par dollar i måneden om cachen holder seg varm, mer som 50 dollar om den ikke gjør det. Irriterende, ikke ruinerende.

Kostnaden caching ikke redder, er kontekst. Claude Codes kontekstvindu er endelig, og lange økter ender allerede i komprimering (compaction), der samtalen oppsummeres og detaljer går tapt. En permanent beboer på 4 000 tokens betyr at du treffer komprimeringen tidligere, hver økt, for alltid. Den forringer også oppmerksomheten før du treffer noen hard grense: modeller følger beviselig instruksjoner bedre når det er færre av dem som konkurrerer. Forskjellen mellom en fil på 500 tokens og en på 4 000 er ikke 3 500 tokens. Den er om modellen fortsatt bryr seg om «aldri rør staging»-regelen din ved melding 35.

Kjør de samme tallene på det trimmede eksempelet over: 500 tokens, 40 meldinger, fem økter, 22 dager. Rundt 2,2 millioner tokens i måneden, en åttedel av den oppblåste versjonen, med de viktige reglene stående i et rom uten trengsel. Vi skrev opp hele playbooken for kostnadskutt i token-kostnadsguiden vår, og CLAUDE.md-trimming er konsekvent den billigste gevinsten i den.

Prosjekt vs. globalt: skillet ~/.claude/CLAUDE.md

Du har to filer, og ting går galt når innhold lander i feil fil.

~/.claude/CLAUDE.md er global. Den lastes i alle prosjekter, så den må bare inneholde ting som er sanne overalt: «jeg bruker pnpm i alle personlige prosjekter», «svar på engelsk selv om promptene mine av og til er russiske», «aldri commit uten å bli bedt om det». Hold den under ti linjer. Hver linje her multipliseres over alt arbeidet ditt, så budsjettet dens bør være det strammeste.

<project>/CLAUDE.md er prosjektfilen, sjekket inn i git, delt med kolleger og CI. Fakta om denne kodebasen, i formen fra eksempelet over. Fordi den deles, hører personlige preferanser ikke hjemme i den; det er det CLAUDE.local.md eller den globale filen er til.

CLAUDE.md-filer i underkataloger er det underbrukte mellomnivået. En packages/api/CLAUDE.md med API-spesifikke fakta lastes bare når Claude rører den pakken. Har rotfilen i monorepoet ditt seksjoner som gjelder ett workspace, er det gratis token-besparelse uten informasjonstap å dytte dem ett nivå ned.

Én misforståelse verdt å avlive: å legge en ting i mer enn én av disse filene får ikke Claude til å følge den hardere. Det gjør filen lengre. Velg ett hjem per faktum.

Hold den fersk

CLAUDE.md råtner raskere enn vanlig dokumentasjon, fordi ingenting knekker synlig når den tar feil. Tester feiler høylytt. En utdatert minnefil villeder bare modellen i stillhet, som stille henter seg inn, og du betaler stille for begge deler.

Ritualet vårt er kjedelig og tar ti minutter i måneden. Åpne filen. For hver kommando, kjør den faktisk. For hvert påstått faktum, spør om det fortsatt er sant og om Claude gjorde noe feil denne måneden på grunn av det. Slett minst én linje; det finnes alltid en linje, og finner du den ikke, har standarden din for «å fortjene en plass» sklidd ut. Sjekk så lengden: én skjerm er målet, to skjermer er taket, og forbi det redigerer du ikke lenger, du ekstraherer til skills.

Den beste triggeren for oppdateringer er likevel ikke kalenderen. Det er øyeblikket Claude gjør noe feil fordi filen villedet den. Fiks filen i samme åndedrag som koden. Behandle CLAUDE.md-bugs som bugs, for de har samme gjentakelsesatferd: ufiksede skjer de igjen neste økt.

FAQ

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

Under 500 ord for de fleste prosjekter, under 1 000 for et genuint komplisert monorepo. Vår arbeidstest: får den ikke plass på én skjerm, er noe i den atferd forkledd som fakta, og det noe hører hjemme i en skill. Eksempelet i denne artikkelen er på rundt 350 ord og dekker en reell mellomstor app.

Hva er forskjellen på CLAUDE.md og en skill?

Lasteatferd. CLAUDE.md lastes i sin helhet, alltid, for hver forespørsel. En skill eksponerer bare en énlinjes beskrivelse til en oppgave matcher den, og lastes så på forespørsel. Så CLAUDE.md bør holde fakta du trenger konstant, og skills bør holde prosedyrer du trenger av og til. Skills-guiden vår dekker mekanikken.

Bør jeg committe CLAUDE.md til git?

Ja. Den er delt dokumentasjon, og kollegaenes Claude-økter nyter godt av de samme faktaene som dine. Hold personlige preferanser i CLAUDE.local.md (gitignorert) eller den globale filen din i stedet for å dytte dem på teamet.

Kan jeg bruke nøstede CLAUDE.md-filer i underkataloger?

Ja, og i monorepoer bør du. Claude Code laster en underkatalogs fil når den jobber med filer der. Rotfilen får fakta som gjelder hele repoet, packages/api/CLAUDE.md får API-fakta, og prosjekter med én pakke kan droppe nøsting helt.

Endrer trimming av CLAUDE.md faktisk Claudes atferd, eller bare kostnaden?

Begge deler, og atferden er den største gevinsten. Instruksjonsfølging forringes etter hvert som antallet instruksjoner vokser; en kort fil med fem skarpe regler blir adlydt mer pålitelig enn en lang med tretti. Token-besparelsen er den målbare delen, og effektivitetsrangeringene våre sporer hvilke skills som hjelper mest der, men forbedringen i etterlevelse er det du merker først.

En siste mening: de beste CLAUDE.md-filene vi har sett, ble alle redigert gjennom sletting. Ingen skriver en god en på dag én. Du skriver en middelmådig en, ser hvor Claude snubler, legger til faktumet som ville forhindret det, og kutter en linje fyll for å betale for det. Seks uker med det slår enhver mal, inkludert vår.