Miten kirjoittaa hyvä CLAUDE.md-tiedosto

CLAUDE.md on yksittäinen tiedosto, joka vaikuttaa eniten siihen, millaista koodia Claude Code tuottaa projektissasi. Se on kuin briiffi, jonka annat uudelle tiimiläiselle ensimmäisenä päivänään: mitä tämä projekti tekee, miten täällä toimitaan ja mitä saa ja ei saa tehdä.

Ilman CLAUDE.md-tiedostoa Claude Code arvaa. Ja arvaukset johtavat väärin nimettyihin muuttujiin, väärin valittuihin kirjastoihin ja koodiin, joka ei noudata projektisi konventioita. Hyvä CLAUDE.md poistaa arvailun ja korvaa sen selkeillä ohjeilla.

Mitä CLAUDE.md-tiedostoon kirjoitetaan?

CLAUDE.md on Markdown-tiedosto, joka sijoitetaan projektin juureen. Claude Code lukee sen automaattisesti joka kerta, kun aloitat uuden keskustelun. Sen sisältö muodostaa kontekstin, jonka perusteella tekoäly tekee päätöksiä.

Hyvä CLAUDE.md kattaa viisi aluetta:

1. Projektin kuvaus -- mitä tämä sovellus tekee ja kenelle
2. Teknologiapino -- kielet, frameworkit, versiot
3. Konventiot -- nimeämiskäytännöt, tiedostorakenne, tyylit
4. Säilytettävät asiat -- arkkitehtuuripäätökset, joista ei jousteta
5. Kiellot -- asiat, joita tekoälyn ei pidäisi tehdä

Näin yksinkertaista se on. Ei tarvitse kirjoittaa romaania -- riittää, että kerrot oleelliset asiat selkeästi.

Projektin kuvaus

Aloita kertomalla, mitä projekti tekee. Yksi tai kaksi lausetta riittää. Tämä auttaa Claude Codea ymmärtämään kontekstin ja tekemään parempia päätöksiä.

## Projekti

Verkkokauppa-alusta pienyrittäjille. Käyttäjät voivat luoda oman
kaupan, lisätä tuotteita ja vastaanottaa maksuja Stripe-integraation kautta.

Kerro myös kohderyhmä ja projektin vaihe. Onko tämä MVP, tuotannossa oleva sovellus vai sisäinen työkalu? Tämä vaikuttaa siihen, pitääkö tekoälyn priorisoida nopeutta vai laatua.

Teknologiapino

Listaa käyttämäsi teknologiat ja niiden versiot. Tämä estää Claude Codea käyttämästä vanhentuneita API-kutsuja tai vääriä importteja.

## Teknologiapino

- Next.js 15 (App Router)
- React 19
- TypeScript 5.x (strict mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL
- Vitest + React Testing Library

Ole tarkkana versioiden kanssa. Ero Next.js 14:n ja 15:n välillä on merkittävä, ja Claude Code voi tuottaa väärän syntaksin, jos se ei tiedä versiota.

Konventiot ja tiedostorakenne

Tämä on CLAUDE.md:n tärkein osio. Täällä kerrot, miten projektissasi toimitaan.

## Konventiot

- Komponentit: PascalCase, yksi komponentti per tiedosto
- Hookit: `use`-prefiksi, omassa `hooks/`-kansiossa
- API-routet: `src/app/api/[resurssi]/route.ts`
- Tyylit: Tailwind-utilityt, ei CSS-moduleita
- Testit: `__tests__/`-kansio jokaisen moduulin vieressä
- Kielet: TypeScript kaikkialla, ei `.js`-tiedostoja
- Importit: absoluuttiset polut `@/`-prefiksillä

## Tiedostorakenne

src/
  app/           -- Next.js App Router -sivut
  components/    -- Jaetut UI-komponentit
  lib/           -- Apufunktiot ja logiikka
  hooks/         -- Custom React -hookit
  types/         -- Jaetut TypeScript-tyypit

Mitä tarkempi olet, sitä vähemmän joudut korjaamaan. Jos projektissasi kaikkien komponenttien pitää käyttää forwardRef-patternia, kerro se. Jos virheenkäsittely tehdään aina Result-tyypillä, kerro sekin.

Säilytettävät päätökset ja kiellot

Jokaisessa projektissa on päätöksiä, joista ei tingitä. Kirjoita ne ylös, jotta Claude Code ei yritä "parantaa" niitä.

## Tärkeät säännöt

- ÄLÄ koskaan käytä `any`-tyyppiä TypeScriptissä
- ÄLÄ asenna uusia riippuvuuksia kysymättä ensin
- ÄLÄ käytä CSS-in-JS -kirjastoja (ei styled-components, ei Emotion)
- Käytä AINA Server Componentteja oletuksena, "use client" vain tarvittaessa
- Virheviestit AINA suomeksi käyttäjälle, englanniksi lokeissa
- Jokainen uusi API-route vaatii Zod-validoinnin

Kapiteelilla kirjoitetut ÄLÄ ja AINA toimivat hyvin, koska ne erottuvat tekstistä ja Claude Code painottaa niitä.

Kokonainen esimerkki

Tässä täydellinen CLAUDE.md Next.js-projektille:

# CLAUDE.md

## Projekti

Vibekoodaus.fi on suomenkielinen opetussivusto tekoälyavusteisesta koodauksesta.
Kohderyhmä: aloittelijat ja koodauksesta kiinnostuneet. Tuotannossa oleva sivusto.

## Teknologiapino

- Next.js 15 (App Router)
- React 19
- TypeScript (strict)
- Tailwind CSS v4
- MDX blogisisällöille
- Vercel (hosting)

## Tiedostorakenne

src/
  app/           -- Sivut ja routet
  components/    -- UI-komponentit (PascalCase)
  content/blog/  -- MDX-blogiartikkelit
  lib/           -- Apufunktiot, data, SEO
  lib/data/      -- Sisältödatat TypeScript-tiedostoina

## Konventiot

- Kaikki sisältö suomeksi, tekniset termit englanniksi
- Komponentit PascalCase, yksi per tiedosto
- Tailwind-utilityt tyylitykseen, ei CSS-moduleita
- Absoluuttiset importit @/-prefiksillä
- Jokainen sivu tarvitsee metadata-exportin ja JSON-LD-scheman

## Säännöt

- ÄLÄ luo uusia tiedostoja ellei se ole välttämätöntä, muokkaa olemassa olevia
- ÄLÄ käytä emojeja leipätekstissä
- AINA lyhyet kappaleet (2-3 lausetta max)
- AINA sinä-muoto (puhuttele lukijaa suoraan)
- SEO-konfiguraatio keskitetty: src/lib/seo/config.ts
- Päivitä ai-docs/project-status.md merkittävän työn jälkeen

Huomaa, miten koko tiedosto mahtuu yhdelle näytölliselle. Se on tarkoituksellista.

Monitasoinen konfiguraatio

CLAUDE.md ei toimi vain projektin juuressa. Voit käyttää sitä kolmella tasolla:

Globaali taso (~/.claude/CLAUDE.md): Ohjeet, jotka pätevät kaikkiin projekteihin. Tänne sopivat yleiset preferenssisi, kuten "käytä aina TypeScriptiä" tai "kirjoita commit-viestit englanniksi".

Projektitaso (projektin juuressa CLAUDE.md): Projektikohtaiset ohjeet. Tämä on se tiedosto, josta tämä artikkeli puhuu.

Alikansiotaso (esim. src/components/CLAUDE.md): Tiettyyn kansioon rajatut ohjeet. Voit esimerkiksi kertoa komponenttikirjastolle omat konventionsa.

Claude Code yhdistää nämä kaikki. Globaalit ohjeet ovat aina mukana, ja kun työskentelet tietyssä kansiossa, myös sen CLAUDE.md on käytössä. Jos ohjeet ovat ristiriidassa, lähempi tiedosto voittaa.

Käytännössä useimpiin projekteihin riittää yksi CLAUDE.md projektin juuressa. Alikansiotason konfiguraatiosta on hyötyä isommissa monorepo-projekteissa.

Yleisimmät virheet

Liian pitkä tiedosto

Jos CLAUDE.md on satoja rivejä pitkä, Claude Code joutuu painottamaan, mikä on tärkeää ja mikä ei. Pidempi konteksti-ikkuna ei tarkoita, että sinun pitäisi täyttää se. Tavoittele alle 50 riviä. Jos tarvitset enemmän, pohdi voisitko jakaa ohjeet alikansioihin.

Liian yleiset ohjeet

"Kirjoita hyvää koodia" ei kerro mitään. "Käytä aina const eikä let, paitsi jos muuttuja oikeasti muuttuu" kertoo kaiken. Ole konkreettinen.

Ristiriitaiset ohjeet

"Käytä aina Server Componentteja" ja "lisää use client jokaiseen komponenttiin" samassa tiedostossa hajottavat tekoälyn logiikan. Lue CLAUDE.md läpi ja varmista, että ohjeet eivät sodi toisiaan vastaan.

Vanhentunut tieto

CLAUDE.md, joka viittaa projektin vanhaan rakenteeseen tai poistettuihin kirjastoihin, johtaa virheisiin. Pidä se ajan tasalla -- se on elävää dokumentaatiota, ei kertaluontoinen teksti.

Itsestäänselvyyksien toistaminen

Claude Code tietää jo, miten JavaScript, React ja TypeScript toimivat. Sinun ei tarvitse opettaa sille perusasioita. Keskity siihen, mikä on projektillesi uniikkia.

Ylläpito ja parhaat käytännöt

CLAUDE.md on elävää dokumentaatiota. Se kannattaa versioida Gitissä ja päivittää aina, kun projektissa tapahtuu merkittäviä muutoksia.

Päivitä, kun:

• Vaihdat frameworkin tai kirjaston versiota
• Muutat tiedostorakennetta
• Lisäät uuden konvention tai säännön
• Huomaat, että Claude Code tekee toistuvasti saman virheen

Pidä lyhyenä. Jos huomaat, että CLAUDE.md kasvaa yli 80 riviin, kysy itseltäsi: onko kaikki tämä tarpeellista joka keskustelussa? Jos ei, siirrä osa ohjeista alikansiotason tiedostoihin.

Testaa muutokset. Kun päivität CLAUDE.md:tä, kokeile antaa Claude Codelle tyypillinen tehtävä ja katso, noudattaako se uusia ohjeita. Iterointi on nopeaa.

Versiohallinnan arvo. Kun CLAUDE.md on Gitissä, tiimisi jokainen jäsen -- ja jokainen Claude Code -istunto -- työskentelee samojen ohjeiden mukaan. Ei enempää "mulla se toimi eri tavalla" -keskusteluja.

Lue lisää: Tutustu Claude Code -oppaaseen kokonaisvaltaisesti. Syvenny CLAUDE.md-tiedoston yksityiskohtiin tai katso, miten Claude Code eroaa muista työkaluista vertailuartikkelissa.