CLAUDE.md:n parhaat käytännöt: 9 sääntöä, jotka estävät Claudea ignoroimasta sinua (2026)

CLAUDE.md:n parhaat käytännöt: 9 sääntöä, jotka estävät Claudea ignoroimasta sinua (2026)

Useimmat CLAUDE.md:n parhaat käytännöt -artikkelit antavat sinulle mallipohjan ja julistavat asian valmiiksi, mutta viime viikolla kirjoittamasi tiedosto on luultavasti jo jätetty huomiotta, etkä tiedä miksi. Korjaus on harvoin "lisää enemmän sääntöjä". Usein se on päinvastoin. Olemme ottaneet Claude Coden käyttöön jokaisessa tuoreessa asiakasprojektissa, ja nämä 9 sääntöä ovat ne, jotka todella vaikuttavat tuloksiin: hierarkia, joka vastaa tapaa, jolla Claude lataa tiedostot, ohjeiden budjetti, jota et voi rikkoa, AGENTS.md-päätös ja kuusi syytä, miksi Claude hiljaisesti pudottaa tiedostosi kesken istunnon.

Keskeiset havainnot

• CLAUDE.md on projektimuistia, joka ladataan Claude Coden kontekstiin; pidä se alle 200 rivin pituisena, tai säännöt alkavat pudota pois.
• Tiedostot latautuvat ylhäältä alas: globaali, projektin juurihakemisto, alihakemisto (laiska lataus) ja CLAUDE.local.md (henkilökohtainen, gitignore-listalla).
• Käytä AGENTS.md:ää, jos käytät myös Cursoria tai Copilotia; luo symbolinen linkki CLAUDE.md:stä AGENTS.md:hen kohdistaaksesi molemmat.
• Jos Claude ignoroi tiedostoasi, 90 % ajasta syynä on pituus, epämääräisyys tai puuttuva "miksi".

Mitä CLAUDE.md todella tekee (ja miksi sillä on väliä)

Lyhyesti: CLAUDE.md on markdown-tiedosto, jonka Claude Code lukee projektimuistina jokaisen istunnon alussa. Se ei ole system prompt, koukku (hook) tai taito (skill), vaan neuvoa-antava konteksti, joka ohjaa Claudea tiimisi konventioiden suuntaan. Ajattele sitä vähemmän dokumentaationa ja enemmän konfigurointitiedostona, jonka AI-pariohjelmoijasi todella lukee.

Monet tiimit kirjoittavat CLAUDE.md:n kuin README-tiedoston. Tämä on ensimmäinen virhe. README selittää projektin ihmisille, jotka voivat silmäillä ja ohittaa kohtia. Claude Code kuluttaa CLAUDE.md:n kokonaisuudessaan istunnon alussa, jolloin jokainen rivi maksaa tokeneita ja vaatii noudattamista. Se on paljon lähempänä konfigurointitiedostoa tai testifixturejä kuin dokumentaatiota.

Se ei myöskään ole ainoa tapa ohjata Claudea. Koukut (Hooks) suorittavat deterministisiä toimintoja (muotoilu, commitien estäminen). Taidot (Skills) kokoavat uudelleenkäytettäviä työnkulkuja. CLAUDE.md istuu näiden välissä neuvoa-antavana kontekstina; Claude arvioi sen, joskus ohittaa sen ja unohtaa siitä osia varmasti, jos kirjoitat liikaa. Tämä ero on kaiken alla olevan perusta, ja siksi CLAUDE.md on yksi työkalu laajemmassa kontekstitekniikan käytännössä, ei hopealuoti.

Sääntö #1: Käsittele sitä kuin koodia, ei dokumentaatiota. Versioi se. Arvioi se pull requesteissa. Karsi sitä kuten refaktoroisit turhan paisunutta moduulia. Anthropicin CLAUDE.md-oppaan mukaan tiedosto ladataan samalla prioriteetilla kuin mikä tahansa järjestelmäohje, mikä tarkoittaa, että vanhentunut sääntö kuuden takaa muokkaa edelleen aktiivisesti jokaista vastausta tänään.

Miten CLAUDE.md latautuu: 4-tason hierarkia

Lyhyesti: Claude Code lataa CLAUDE.md:n neljästä tasosta: globaali (~/.claude/CLAUDE.md), projektin juurihakemisto, CLAUDE.local.md henkilökohtaisia ohituksia varten ja alihakemistotiedostot, jotka latautuvat laiskasti vain, kun Claude lukee tiedostoja kyseisessä hakemistossa. Sisarhakemistot eivät koskaan näe toistensa CLAUDE.md-tiedostoja, mikä pitää claude code -muistin tarkasti rajattuna.

Hierarkia on CLAUDE.md:n väärinymmärretyin osa, ja se on kohta, jossa 0 viidestä parhaasta hakutuloksesta menee syvällisesti aiheeseen. Tässä on mitä todella tapahtuu kulissien takana:

Kaksi termiä, jotka kannattaa kiinnittää mieleen: laiska lataus ja sisareristys.

Laiska lataus tarkoittaa, että alihakemiston CLAUDE.md ei tule Clauen kontekstiin ennen kuin Claude todella avaa tiedoston kyseisessä hakemistossa. Jos kysyt "korjaa kirjautumisbugi" ja Claude koskee vain backend/-hakemistoa, frontend/CLAUDE.md ei koskaan lataudu. Tämä on hyvä asia, se pitää konteksti-ikkunan puhtaana, mutta se puree tiimejä, jotka laittavat kriittisiä sääntöjä alihakemistoihin odottaen niiden pätevän aina.

Sisareristys on seuraus: frontend/CLAUDE.md ja backend/CLAUDE.md eivät koskaan lataa toisiaan. Ne jakavat vain sen, mikä on projektin juuritiedostossa. Joten jos frontend-sääntösi ovat ristiriidassa backend-sääntöjesi kanssa, se on ok. Jos niiden täytyy jakaa konventio, pushaa se ylös juuritiedostoon.

CLAUDE.local.md on hätäpoistumistie. Se ladataan, mutta sitä ei commitoida, mikä on täydellistä tyylille "minä suosin pnpm:ää, mutta tiimi on standardoinut npm:n". Koukku: sitä ei automaattisesti lisätä gitignoreen. Sinun täytyy lisätä se itse. Unohda tämä, ja commitoit henkilökohtaiset sääntösi tiimisi repoon.

Sääntö #4: Sovita ohjeet siihen, missä Claude todella lukee ne. React-komponenttien tyylisäännöt kuuluvat frontend/CLAUDE.md:hen, ei juureen. Tietokantamigraatiosäännöt kuuluvat backend/:iin. Anthropicin Memory-dokumentaatio (päivitetty marraskuussa 2025) vahvistaa tämän; laiskan latauksen käyttäytyminen on tarkoituksellista ja kantava rakenteellinen osa.

Mitä CLAUDE.md:n sisälle laitetaan (ja mitä jätetään pois)

Lyhyesti: CLAUDE.md:n sisälle kuuluu kaikki, mitä Claude ei voi päätellä koodistasi: build-komennot, nimeämiskonventiot, anti-patternit, joissa tiimisi on polttanut sormensa, ja miksi jokaisen säännön takana. Poissa on kaikki, mikä on README:ssä, kaikki, mikä on package.json:ssa, ja kaikki säännöt, jotka muuttuvat viikoittain. claude code -ohjeiden tulee olla testattavia ja spesifejä.

Tässä on minimaalinen CLAUDE.md, joka todella kantaa kortensa kekoon:

# Project: techsy-app

## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)

## Conventions
- Server components by default. Add `'use client'` only when truly needed.
  Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
  Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.

## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.

## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`

Vertaa tätä nyt anti-pattern-versioon, jonka useimmat tiimit toimittavat:

# Project Rules

- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.

Toinen tiedosto ei ole väärä. Se on vain hyödytön. Claude haluaa jo kirjoittaa siistiä koodia. "Ole johdonmukainen" ei kerro Claudelle, minkä patternin kanssa olla johdonmukainen. Anthropicin insinööri Boris Chernyn julkiset esimerkit nojaavat vahvasti ensimmäiseen tyyliin: konkreettiset komennot, nimetyt työkalut ja päätösten miksi, jotka eivät ole ilmeisiä pelkästä koodikannasta.

Sääntö #2: Ole spesifi, ei aspiratiivinen. "Kirjoita siistiä koodia" on aspiratiivista. "Palvelinkomponentit oletuksena; lisää 'use client' vain kun todella tarvitaan" on testattavissa. Sama disciplina underpinnoi hyvää prompt engineeringia: spesifit, testattavat ohjeet voittavat epämääräiset haaveet, olivatpa ne promptissa tai CLAUDE.md:ssä.

Sääntö #3: Selitä, miksi jokainen sääntö on tärkeä. "Miksi" ei ole fluffia, se on tapa, jolla Claude päättää reunatapauksista. Sääntö, jolla on peruste ("saimme 8s LCP:n liiallisesta client-puolen käytöstä"), yleistyy samanlaisiin tilanteisiin. Sääntö ilman perustetta jätetään huomiotta heti, kun konteksti muuttuu. Patterni on dokumentoitu myös Builder.io:n CLAUDE.md-oppaassa.

Miksi Claude ignoroi CLAUDE.md:täsi? Ohjeiden budjetti

Lyhyesti: Claude ei ole pahantahtoinen, siltä loppuu vain huomio. Noin 80 rivin jälkeen huomaat sääntöjen putoavan pois; yli 200 rivin jälkeen suuret lohkot jätetään kokonaan huomiotta; yli 500 sanan tiheiden sääntöjen jälkeen noudattaminen romahtaa. Korjaus on ohjeiden budjetti. Käsittele jokaista riviä kustannuksena claude code -muistille ja sääntökohtaiselle noudattamiselle.

Tuore tutkimus vahvistaa sen, mitä tuotantokäyttäjät jatkuvasti löytävät: ohjeiden noudattaminen heikkenee epälineaarisesti sääntömäärän kasvaessa. arxiv-paperi 2507.11538 ohjeiden noudattamiskapasiteetista osoittaa, että noudattaminen per sääntö laskee, kun niitä pinotaan enemmän, ja HumanLayerin analyysi CLAUDE.md:stä tuotannossa kaiku samaa havaintoa.

Käännös: jokainen lisäämäsi sääntö tekee jokaisesta muusta säännöstä hieman epätodennäköisemmän noudattaa. Joten 400-rivinen CLAUDE.md ei ole 4x niin tehokas kuin 100-rivinen. Se on usein vähemmän tehokas, koska säännöt, joista välität, laimenevat niiden sääntöjen joukossa, jotka kirjoitit perjantaina kolme kuukautta sitten etkä koskaan poistanut.

CLAUDE.md-tiedostoissamme kaikki linjan 150 jälkeen alkaa näkyvästi menettää noudattamista. Linjalla 250 olemme nähneet Clauen ohittavan kokonaisia osioita. Joten me asetamme katon.

wc -l CLAUDE.md

Siinä koko työkalu. Aja se. Jos olet yli 200:ssä, olet yli budjetin. Kovaa sääntöä, jonka toimitamme asiakkaille:

Käsittele CLAUDE.md:tä 200 rivin budjettina. Jokainen rivi maksaa noudattamista. Käytä sitä siellä, missä sillä on väliä.

Sääntö #1 vahvistettuna: Pidä se lyhyenä. Alle 200 riviä. Alle 500 sanaa tiheitä sääntöjä. Jos huomaat haluavasi lisätä automaatiosääntöjä ("aja aina prettier muokkausten jälkeen"), ne kuuluvat todennäköisesti Claude Code -koukkuihin sen sijaan; koukut ovat deterministisiä eivätkä maksa ohje-budjetin tokeneita.

Pitäisikö käyttää CLAUDE.md:tä, AGENTS.md:tä, .cursorrulesia vai copilot-instructionsia?

Lyhyesti: Jos käytät vain Claude Codea, CLAUDE.md on ok. Jos käytät kahta tai useampaa agentti-CLI:tä (Codex, Cursor, Copilot, Sourcegraph), vaihda AGENTS.md:hen ja luo symbolinen linkki CLAUDE.md:stä AGENTS.md:hen. AGENTS.md nousi esiin vuoden 2025 lopulla cross-tool-standardina, useimmat modernit agentit palautuvat siihen, joten yksi tiedosto syöttää koko ekosysteemiä.

Tämä on kysymys, johon 0 viidestä parhaasta tuloksesta todella vastaa. Tässä matriisi:

Kaksoiskohdistustemppu on yksi rivi:

ln -s AGENTS.md CLAUDE.md

Siinä kaikki. Nyt Claude Code, Codex ja mikä tahansa AGENTS.md-tietoinen työkalu lukevat samaa tiedostoa. Päivitä kerran, jokainen agentti poimii sen. AGENTS.md-spesifikaatio on avoin ja tarkoituksellisen minimaalinen, se on vain markdownia tavanomaisilla osioilla.

Kaksi todellisen maailman mutkaa. Ensinnäkin: jos tiimilläsi on Cursor-power-user, Cursorin .cursorrules ottaa erilaisen lähestymistavan, yksittäinen tiedosto, ei hierarkiaa, jäykempi formaatti. Jotkut tiimit pitävät molempia: AGENTS.md jaetut säännöt varten, .cursorrules Cursor-spesifejä erikoisuuksia varten. Toiseksi: Copilotin .github/copilot-instructions.md ei palaudu AGENTS.md:hen, joten Copilot-painotteiset tiimit tarvitsevat erillisen tiedoston.

Jos valitset agenttipinon tyhjästä, Claude Code vs Cursor vs Copilot -erittelymme kattaa kompromissit käyttötasolla. Lyhyt versio: Claude Coden hierarkia on tehokkain monorepoille, Cursorin UX voittaa soolotyössä, Copilotin IDE-integraatio on edelleen sulavin asteittaiseen adoptioon.

Sääntö #9: Käytä AGENTS.md:tä, jos ajat enemmän kuin yhtä agentti-CLI:tä. Älä ylläpidä kahta tiedostoa, jotka sanovat samaa asiaa. Valitse tiedosto, jota suurin osa pinostasi lukee, ja linkitä loput siihen.

CLAUDE.md vs Koukut vs Taidot: Päätöskolmio

Lyhyesti: CLAUDE.md = neuvoa-antava konteksti. Koukut = deterministiset toiminnot. Taidot = niputetut kyvykkyydet. Valitse väärä, ja poltat ohje-budjettia johonkin, mitä koukun pitäisi hoitaa, tai kirjoitat CLAUDE.md-säännön johonkin, mitä vain taito voi tuottaa. Kolmio on halvin tapa pitää CLAUDE.md kevyenä.

Kolme työkalua, kolme tehtävää. Virhe, jonka näemme useimmin: "aja aina prettier muokkauksen jälkeen" -säännön laittaminen CLAUDE.md:hen. Claude lukee sen. Claude joskus ajaa prettierin. Olet turhautunut. Korjaus on siirtää tuo rivi pois CLAUDE.md:stä ja koukkuun, koska koukut laukeavat deterministisesti joka kerta, ilman neuvoa-antavaa liikkumavaraa.

Jos säännön täytyy aina lauetta, se kuuluu koukkuun. Jos se on tyylimieltymys, jonka Claude voi arvioida kontekstia vastaan, se kuuluu CLAUDE.md:hen. Jos se on monivaiheinen työnkulku niputetuine varoineen (mallipohjat, skriptit, promptit), se kuuluu taitoon.

Sääntö #8: Valitse CLAUDE.md vs koukut vs taidot oikein, koukun laittaminen CLAUDE.md:hen on yleisin ohje-budjetin tuhlaus. Konfiguroi deterministiset toiminnot Claude Code -koukuilla ja pakkaa uudelleenkäytettävät työnkulut Claude-taidoiksi. CLAUDE.md:si lyhenee, suojakaiteesi vahvistuvat, ja Claude lakkaa "unohtamasta" sääntöjä, joilla on väliä.

Monorepo-patternit: Sisäkkäiset CLAUDE.md-tiedostot, @imports ja .claude/rules/

Lyhyesti: Monorepossa pidä juuren CLAUDE.md pienenä, vain osoittimet ja jaetut konventiot. Pushaa spesifisyydet apps/*/CLAUDE.md:hen, jotta jokaisella alipuulla on rajatut säännöt. Käytä @imports-syntaksia jakamaan modulaarisia sääntötiedostoja .claude/rules/:n kautta. Tämä on progressiivista paljastamista, Claude hakee jokaisen palasen vain kun se on relevantti.

Tyypillinen monorepo CLAUDE.md -puu:

.
├── CLAUDE.md                        # 30 lines — points to subdirs and shared rules
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Next.js-specific rules
│   └── api/
│       └── CLAUDE.md                # Fastify-specific rules
└── packages/
    └── shared/
        └── CLAUDE.md                # Library author rules

@import-syntaksi antaa juuritiedoston hakea jaettuja sääntöpaloja ilman, että niitä tarvitsee toistaa:

# Root CLAUDE.md

This is a Turborepo. See subdir CLAUDE.md for app-specific rules.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md

## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test script

Tämä on progressiivista paljastamista käytännössä. Juuritiedosto on 30-rivinen osoitin. Jokainen alihakemiston CLAUDE.md lisää 50–80 riviä fokusoituja sääntöjä. .claude/rules/-tiedostot sisältävät konventiopaloja, joita useat alihakemistot voivat hakea. Mitään ei duplikoida, mitään ei unohdeta, eikä mikään yksittäinen tiedosto ylitä ohje-budjettia.

Aiempi laiskan latauksen sääntö on vielä tärkeämpi tässä: kun Claude työskentelee apps/web/Button.tsx:n kanssa, se näkee juuritiedoston plus apps/web/CLAUDE.md:n plus @import-tuodut sääntötiedostot. Se ei näe apps/api/CLAUDE.md:tä. Siinä koko pointti, backend-konventiot eivät saastuta frontend-kontekstia, ja konteksti-ikkunasi pysyy käyttökelpoisena.

Sääntö #6: Käytä @importsia pitämään juuritiedosto alle 200 rivin. Anthropicin parhaat käytännöt Claude Codelle -opas käsittelee tätä standardina monorepo-patternina. Subagentit perivät myös parent CLAUDE.md -kontekstin, mikä on hyvä tietää, jos sisäkkäistät työnkulkuja, katso kontekstitekniikka siitä, miten tämä vuorovaikuttaa subagenttien suunnittelun kanssa.

6 syytä, miksi Claude ignoroi tiedostoasi (ja korjaus kuhunkin)

Lyhyesti: Kun Claude ignoroi CLAUDE.md:tä, se on lähes aina yksi kuudesta syystä: tiedosto liian pitkä, epämääräinen formulointi, puuttuva "miksi", kontekstin tiivistäminen, ristiriitainen parent-tiedosto tai väärä tiedostonimi. Jokaisella on 60 sekunnin korjaus. Testaa tuoreessa istunnossa jokaisen muutoksen jälkeen, se on Sääntö #7.

1. Tiedosto liian pitkä (>200 riviä / >500 sanaa)

Aja wc -l CLAUDE.md. Jos se on yli 200, karsi aggressiivisesti. Siirrä automaatiosäännöt koukkuihin. Siirrä työnkulut taitoihin. Jaa jaetut palaset .claude/rules/:ään ja hae ne @import:illa. Yleisin syy, miksi Claude "lakkaa noudattamasta" sääntöjäsi, on se, että tiedosto on kasvanut liian pitkäksi ajan myötä ja noudattaminen on hiljaa romahduttu.

2. Epämääräinen formulointi ("kirjoita siistiä koodia")

Korvaa jokainen aspiratiivinen sääntö spesifillä, testattavalla säännöllä. "Ole johdonmukainen" on näkymätön Claudelle. "Käytä palvelinkomponentteja oletuksena; lisää 'use client' vain lomakkeisiin tai interaktiiviseen UI:hun" on jotain, mitä Claude voi todella soveltaa.

3. Puuttuva "miksi"

Säännöt ilman perusteita eivät yleistetä. Claude ei voi päätellä, milloin taivuttaa sääntöä, koska se ei tiedä, mitä sääntö suojelee. Jokainen ei-ilmeinen sääntö saa yhden rivin: "käytämme unknown emmekä any, koska meillä oli kolme runtime-crashia typed-as-any API-vastauksista viime kvartaalilla."

4. Kontekstin tiivistäminen hylkäsi sen

Pitkät istunnot laukaisevat tiivistämisen, Claude tiivistää aikaisempaa kontekstia mahtuakseen ikkunaan, ja CLAUDE.md:n sisältö joskus tiivistetään olemattomiin. Korjaus: /clear suurten kontekstin polttojen jälkeen, tai käynnistä istunto kokonaan uudelleen. Tämä on täsmälleen se, mitä GitHub Issue #17530 jatkuvaan nostaa esiin.

5. Ristiriitainen parent CLAUDE.md

Globaali sanoo "käytä 4 välilyöntiä." Projektin juuri sanoo "käytä 2 välilyöntiä." Alihakemisto ei sano mitään. Claude valitsee yhden, joskus väärän. Auditoi ~/.claude/CLAUDE.md ja projektin juuri ristiriitojen varalta. Sen, joka on spesifimpi, pitäisi voittaa, mutta vain jos teet siitä eksplisiittisen.

6. Väärä tiedostosijainti tai tiedostonimen kirjainkoko

Claude.md ja CLAUDE.md ovat eri tiedostoja Linuxissa ja macOS:ssä. Samoin claude.md ja CLAUDE.md. Varmista, että polku on tarkalleen ./CLAUDE.md (isoilla kirjaimilla), ja varmista, että Claude Code käynnistetään hakemistosta, joka sisältää sen. GitHub Issue #668 on täynnä tapauksia, joissa tiedosto oli olemassa, mutta Claude ei nähnyt sitä polkuongelmien vuoksi.

Sääntö #7: Testaa tuoreessa istunnossa. Minkä tahansa CLAUDE.md-muutoksen jälkeen avaa uusi istunto ja pyydä Claudea "tiivistämään CLAUDE.md:n säännöt". Jos tiivistelmästä puuttuu jotain, tiedosto ei tee työtään.

Ensimmäinen CLAUDE.md:si 10 minuutissa: 5-vaiheinen aloitus

Lyhyesti: Aja /init luonnoksen siementämiseksi, karsi se 6–10 todelliseksi säännöksi perusteineen, lisää 3 komentoa, jotka Clauen pitäisi tuntea, lisää 2 anti-patternia, joissa tiimisi on kompastunut, ja testaa sitten tuoreessa istunnossa pyytämällä Claudea tiivistämään tiedosto. Kokonaisaika: noin 10 minuuttia. 5-vaiheinen resepti on se, mitä käytämme päivänä 1 jokaisessa uudessa repossa.

1. Aja /init luonnoksen siementämiseksi. Claude Coden /init-komento skannaa reposi ja kirjoittaa aloitus-CLAUDE.md:n. Älä toimita sitä, mitä se kirjoittaa. /init-tuloste on lähtökohta, ei valmis tiedosto, ja rehellisesti sanottuna, suurin osa sen generoimasta sisällöstä voidaan poistaa.

2. Karsi se 6–10 riviksi todellisia sääntöjä perusteineen. Poista kaikki yleiset asiat. Poista kaikki, mikä on README:ssä. Pidä vain säännöt, joita Claude ei voi päätellä itse koodista.

3. Lisää 3 komentoa, jotka Clauen pitäisi tuntea. Build, test, lint. Sisällytä tarkka komento ja kaikki ei-ilmeiset flagit. Jos käytät Vitestiä etkä Jestia, sano se.

4. Lisää 2 anti-patternia, joissa tämä tiimi on kompastunut. Todellisia. "Älä käytä any:tä, koska meillä oli kolme runtime-crashia" voittaa "käytä TypeScriptia oikein" joka kerta.

5. Avaa tuore istunto ja varmista. Pyydä Claudea "tiivistämään CLAUDE.md:n säännöt". Jos se jättää jotain huomiotta, tiedosto on liian pitkä, liian epämääräinen tai siitä puuttuu "miksi". Korjaa ja toista.

Sääntö #5: Älä automaattigeneroi pelkästään /init:stä. /init on lähtökohta, ei valmis tiedosto. Ne 8 minuuttia, jotka käytät sen karsimiseen, ovat se, missä arvo on.

FAQ

Mikä on CLAUDE.md-tiedosto?

CLAUDE.md-tiedosto on markdown-tiedosto, jonka Claude Code lukee projektimuistina jokaisen istunnon alussa. Se kertoo Claudelle konventiosi, komentosi ja anti-patternisi, jotta sen ei tarvitse arvata. Se toimii neljällä tasolla: globaali, projektin juuri, alihakemisto (laiskasti ladattu) ja henkilökohtainen CLAUDE.local.md, jonka pidät gitignore-listalla.

Kuinka pitkä CLAUDE.md-tiedoston pitäisi olla?

Alle 200 riviä ja alle 500 sanaa tiheitä sääntöjä. Näiden kynnysten ylittyessä Clauen ohjeiden noudattaminen heikkenee, jokainen lisäämäsi sääntö tekee jokaisesta muusta säännöstä hieman epätodennäköisemmän noudattaa. Käsittele sitä kiinteänä budjettina. Jos tarvitset enemmän, jaa alihakemisto CLAUDE.md -tiedostoihin ja käytä @import:ia jaettuihin palasiin.

Minne CLAUDE.md pitäisi laittaa?

Pääasiallinen menee projektin juureen (./CLAUDE.md) ja se commitoidaan. Lisää alihakemisto CLAUDE.md -tiedostoja app-spesifejä sääntöjä varten monorepoissa. Laita projektien väliset mieltymykset ~/.claude/CLAUDE.md:hen. Käytä CLAUDE.local.md:tä henkilökohtaisiin ohituksiin, joita et halua commitoida, mutta muista lisätä se manuaalisesti gitignoreen.

Miksi Claude ignoroi CLAUDE.md:täni?

90 % ajasta se on yksi kolmesta asiasta: tiedosto on liian pitkä (yli 200 riviä), säännöt ovat epämääräisiä ("kirjoita siistiä koodia") tai säännöistä puuttuu "miksi", jota Claude voi käyttää niiden soveltamiseen. Aja wc -l CLAUDE.md, auditoi sitten spesifisyyden varalta. Testaa muutokset tuoreessa istunnossa pyytämällä Claudea tiivistämään tiedosto.

Pitäisikö käyttää CLAUDE.md:tä vai AGENTS.md:tä?

Jos tiimisi käyttää vain Claude Codea, pysy CLAUDE.md:ssä. Jos käytät kahta tai useampaa agentti-CLI:tä (Codex, Cursor, Sourcegraph), vaihda AGENTS.md:hen ja luo symbolinen linkki CLAUDE.md:stä siihen: ln -s AGENTS.md CLAUDE.md. Useimmat modernit agentti-CLIt palautuvat AGENTS.md:hen, joten yksi tiedosto syöttää jokaista työkalua.

Pitäisikö ajaa /init generoidakseen CLAUDE.md?

Kyllä, luonnoksena. Ei, valmiina tiedostona. /init skannaa reposi ja tuottaa aloituksen, mutta se on verbose ja yleinen. Sekä Anthropic että HumanLayer suosittelevat aggressiivista karsimista /init:n ajamisen jälkeen. Ne 8 minuuttia, jotka käytät leikkaamiseen ja "miksi"-rivien lisäämiseen, ovat se, missä tiedostosta tulee todella hyödyllinen.

Miten CLAUDE.md-tiedostot toimivat monorepossa?

Juuritason CLAUDE.md pysyy pienenä, vain osoittimet ja jaetut säännöt. Jokaisella appilla on oma apps/*/CLAUDE.md rajatuilla konventioilla. Alihakemistotiedostot latautuvat laiskasti vain, kun Claude lukee tiedostoja kyseisessä alipuussa, joten sisaret pysyvät eristettyinä. Käytä @import .claude/rules/style.md:tä jakamaan modulaarisia sääntöpaloja ilman, että niitä duplikoidaan appien välillä.

Mikä on ero CLAUDE.md:n, koukkujen ja taitojen välillä?

CLAUDE.md on neuvoa-antava konteksti, Claude lukee sen ja yleensä noudattaa sitä. Koukut ovat deterministisiä toimintoja, jotka laukeavat aina (muotoilu, commitien estäminen). Taidot ovat niputettuja kyvykkyyksiä uudelleenkäytettäviin työnkulkuihin varoineen. Käytä CLAUDE.md:tä tyiliohjaukseen, koukkuja koviin sääntöihin ja taitoja monivaiheisiin töihin, jotka toistat projekteissa.

Miten Techsy lähestyy tätä

Techsyllä jokaisessa Claude Code -projektissa, jonka toimitamme, on alle 150-rivinen CLAUDE.md ja AGENTS.md-symbolinen linkki. Käsittelemme tiedostoa kuin koodia, versioimme sen, arvioimme muutokset PR:eissä ja testaamme uudelleen tuoreissa istunnoissa ennen mergeä. Tarvitsetko apua AI-agenttien kytkemisessä dev-workflow'hun? Hanki ilmainen konsultaatio.