Näin otat CLAUDE.md:n käyttöön vuonna 2026: malli ja 6 sääntöä

Kehote: Täytä projektini CLAUDE.md-tiedosto

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

Pyri pitämään valmis CLAUDE.md alle 200 rivissä. Jos se on pidempi, tarkista toisto ja siirrä yksityiskohtaiset menettelyt linkitettyihin tiedostoihin. Säilytä olennaiset suunnittelu-, loppupohdinta- ja repositoriosäännöt ja testaa ne sitten edustavilla tehtävillä.

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

Jos sinulla ei vielä ole about-me/- ja business/-kansioita, se ei haittaa. Claude kysyy tarkentavia kysymyksiä ja kokoaa saatavilla olevien tietojen pohjalta vähimmäis-CLAUDE.md-tiedoston. Voit luoda kansiot myöhemmin, kun tiedät, mitä niihin laitetaan.

Mitkä 6 sääntöä tekevät CLAUDE.md-tiedostosta elävän dokumentin?#

Sääntö 1. Tavoittele tiivistä, alle 200 rivin tiedostoa

Anthropic ilmaisee asian ytimekkäästi virallisessa dokumentaatiossaan:

Pitkä CLAUDE.md toimii itseään vastaan kahdella tavalla. Ensinnäkin se kuluttaa tokeneita. 800-rivinen ohjetiedosto ladataan jokaiseen ikkunaan, ja se käyttää jokaisessa istunnossa useita tuhansia tokeneita budjetistasi. Pro-tilauksessa, jossa on päivittäinen raja, se vähentää huomattavasti käytettävissä olevien istuntojen määrää. Toiseksi malli alkaa sivuuttaa sääntöjä.

Dokumentaatio suosittelee tavoittelemaan alle 200 riviä kontekstikulutuksen vähentämiseksi ja ohjeiden noudattamisen parantamiseksi. Se ei määritä jyrkkää epäonnistumisrajaa riville 201. Tarkista olennaisuus, ristiriidat, ladattu tokenimäärä ja todelliset tehtävätulokset ennen kuin päätät, mitä siirrät pois.

Sääntö 2. Päätä jokainen istunto loppupohdintaan

Kirjoita CLAUDE.md-tiedostoon: ”Kirjaa jokaisen istunnon lopuksi, mitä teit ja opit tiedostoon retrospectives/YYYY-MM-DD_*.md.” Kun lisäät tämän rivin, Claude alkaa itsenäisesti päättää jokaisen istunnon loppupohdintaan; sinun ei tarvitse pyytää sitä.

Miksi loppupohdinta kannattaa tehdä:

• Kahden viikon päästä voit avata vanhan loppupohdinnan ja muistaa, miksi valitsit kyseisen tavan.
• Kun palaat projektiin kuukauden kuluttua, sinulla on valmiina kartta viimeaikaisista päätöksistä.
• Jos työskentelet tiimissä, kumppani voi lukea loppupohdinnan ja ymmärtää nykytilanteen kahdessa minuutissa ilman puhelua.

Sääntö 3. Tee commit jokaisen valmiin tehtävän jälkeen

Omaan CLAUDE.md-tiedostooni on kirjoitettu: ”Luo jokaisen valmiin tehtävän jälkeen git-commit kuvaavalla viestillä.” Claude alkaa jakaa työn itsenäisesti pieniin committeihin.

Tästä on kaksi hyötyä. Ensinnäkin, jos jokin rikkoutuu, voit palauttaa yhden toiminnon etkä ”kaikkea, mitä tänään tein”. Toiseksi commit-historiasta tulee työloki, josta näkee, mitä muuttui ja missä järjestyksessä.

Sääntö 4. Tutustu aina business/-kansioon

Kaikissa asiakkaisiin, tuotteisiin tai teksteihin liittyvissä tehtävissä agentin pitäisi ensin avata business/INDEX.md ja sieltä asiaankuuluva tiedosto. CLAUDE.md-tiedostossani sanotaan nimenomaisesti: ”Kun työskentelet käyttöliittymän tai tekstien parissa, tarkista ensin business/audience/avatar.md ja business/assets/brand-guidelines.md.”

Ilman tätä sääntöä Claude kirjoittaa tekstejä ”laadukkaan verkkosivuston yleisellä tyylillä”. Sen avulla teksti on sinun tyylistäsi, asiakkaallesi ja ilman kieltämiäsi sanoja.

Sääntö 5. Lisää sääntö jokaisen agentin virheen jälkeen

Tämä on tärkein sääntö, joka pitää CLAUDE.md-tiedoston ajan tasalla.

Esimerkkejä omaan CLAUDE.md-tiedostooni lisätyistä säännöistä, jotka lisättiin tiettyjen virheiden jälkeen:

• ”Älä koskaan commitoi toisen keskeneräisiä WIP-tiedostoja komennolla git add . - lisää tiedostot staging-alueelle nimeltä.”
• ”Tarkista ennen main-haaraan työntämistä komennolla git log origin/main..main --oneline - jos tulos ei ole tyhjä, älä puske.”
• ”Älä keksi arvoja - hae ne .env-tiedostosta tai koodista. Erityisesti URL-osoitteet, käyttäjätunnukset ja tokenit.”

Jokainen näistä riveistä kertoo tietystä tilanteesta. Kerran agentti commitoi kumppanin keskeneräisen haaran. Kerran sisällytin jonkun toisen työntämättömät commitit. Kerran agentti keksi URL-osoitteen, jota ei ollut olemassa. Jokaisesta virheestä tulee sääntö, eikä samaa itse aiheutettua vahinkoa pääse sattumaan uudelleen.

Sääntö 6. Sijoita tietoturvasäännöt tiedostoon .claude/settings.json, älä CLAUDE.md-tiedostoon

CLAUDE.md-tiedostoon voit kirjoittaa ”älä koske .env-tiedostoon”, mutta se on pyyntö; Claude voi rikkoa sitä, koska CLAUDE.md ladataan käyttäjäviestinä eikä lakina. Kriittisessä tietoturvassa käytä tiedostoa .claude/settings.json, jossa voit estää tietyt komennot tiukasti.

Lisään jokaiseen uuteen projektiin seuraavan estolistan:

• rm -rf (tiedostojen rekursiivinen poistaminen).
• Koko .env-tiedoston lukeminen (Read .env).
• export ja curl samassa komennossa (salaisuuksien ulkopuolelle vuotamisen malli).
• git push --force ilman nimenomaista hyväksyntää.

Löydät muita oppaita Ailoot-sivustolta.

Millainen CLAUDE.md on aktiivisessa yrityksessä (280-rivisen tiedoston anatomia)?#

Useimmat CLAUDE.md-esimerkit verkossa ovat kehittäjille tarkoitettuja teknisiä malleja: ”Käytä TypeScriptiä”, ”Älä kirjoita yli 50-rivisiä testejä.” Yrittäjälle tällainen CLAUDE.md on hyödytön - siinä ei käsitellä liiketoimintaa.

Alla on toimivan CLAUDE.md-tiedostoni rakenne. Olen poistanut yksittäiset säännöt ja polut, koska ne kuvaavat sisäisiä toimintatapojani. Osioiden rakennetta ja logiikkaa voi kuitenkin soveltaa mihin tahansa projektiin: lisää omat olosuhteesi, niin saat toimivan tiedoston.

1. Lyhyt projektikuvaus (15 riviä). Mitä teemme, kenelle, mitä tuotteita tarjoamme. Ei markkinointisivuston yhteenvetoa, vaan agentille tarkoitettu tiivistelmä, jotta se ymmärtää, ”mihin olemme menossa”.

2. Tietoa minusta (10 riviä). Linkki about-me/-kansioon, joka sisältää digitaalisen kuvauksen siitä, miten ajattelen. Sävy, arvot, periaatteet ja kielletyt sanat. Kun Claude kirjoittaa tekstiä ”minuna”, se lukee ensin tämän kansion, jotta ääneni säilyy.

3. Tietovaraston rakenne (20 riviä). Kommentoitu hakemistopuu: missä koodi on, missä liiketoiminnan konteksti sijaitsee sekä mistä löytyvät suunnitelmat ja loppupohdinnat. Ilman tätä karttaa Claude etsii tiedostoja sokkona joka kerta.

4. ”Mistä asiat löytyvät” -taulukko (25 riviä). Reititys kysymyksestä tiedostoon. Kiinteistönvälitystoimistolle voisi esimerkiksi olla ohje ”tarvitsetko asuntolainan ehtoja → business/products/mortgage.md” tai ”tarvitsetko julkaisujen äänensävyä → business/assets/voice.md”. Korvaa nämä omilla tiedostoillasi. Tämä taulukko on CLAUDE.md-tiedoston ydin. Ilman sitä agentti arvaa, mistä tiedostosta vastaus löytyy. Sen avulla se menee suoraan lähteelle.

5. Projektin keskeiset periaatteet (40 riviä, 10–15 kohtaa). Tämä osio karttuu hitaasti ja vaatii eniten vaivaa. Jokainen kohta kertoo tietystä virheestä. Verkkokaupalle sääntöjä voisivat esimerkiksi olla: ”älä koskaan kovakoodaa hintoja tai toimitusaikoja”, ”älä julkaise tuotetta ilman nimenomaista komentoa” ja ”tarkista tyyli brändisanastoa vasten ennen tuotetekstin julkaisemista”. Tämä osio on ”projektin perustuslaki”.

6. Operatiivinen suunnittelu (20 riviä). Laukaisintaulukko, joka yhdistää käyttäjän ilmauksen toimintoon. Esimerkiksi: ”Kun sanon ’suunnittele viikko’, avaa ops/monthly.md ja luo viikon tiedosto.” Tämä muuttaa Clauden operatiiviseksi avustajaksi, joka ymmärtää komentojen kontekstin.

7. Työkalut (5 riviä). Teknologiat. Lyhyesti ja ilman täytettä.

8. Julkaiseminen (15 riviä). Tuotantoon tehtävien muutosten julkaisuprosessi vaihe vaiheelta: mitä komentoja ajetaan, missä järjestyksessä ja mitä tarkistetaan. Ennen selitin sen joka kerta. Nyt Claude tietää.

9–12. Tietoturva (35 riviä). Neljä erillistä alajaksoa: .env-tiedoston käytön säännöt, tuotantotietokannan käyttöoikeudet, turvalliset komennot esittelyjä varten (näytöntallenteet, striimit, kuvakaappaukset, jotta tokenit eivät paljastu vahingossa) ja salaisuuksien kierrättämistä koskevat säännöt.

13. plans/-kansio (10 riviä). Suunnitelmien standardi: tiedostonimi, vaiheiden rakenne ja yhteenvetolohkon sisältö.

14. retrospectives/-kansio (5 riviä). Loppupohdinnan standardi: malli, tiedostonimi ja sen sisältö.

15. Reaaliaikaiset tietokantatiedot (15 riviä). Sääntö ”tuoreen datan” merkitsemiseksi: kun tiedostossa sanotaan, että lukujen on oltava ajan tasalla, agentti hakee ne lähteestä vanhojen lukujen käyttämisen sijaan. Näin vältetään riski, että Claude käyttää eilisiä lukuja.

16. Kieli (3 riviä). ”Vastaa aina käyttäjän suosimalla kielellä. Käytä vain yhdysmerkkejä, älä ajatusviivoja.”

Yhteensä noin 280 riviä. Se ylittää tiiviystavoitteen, mutta ei tee tiedostosta virheellistä. Tässä esimerkissä se pysyi hyödyllisenä. Sen säilyttämisen pitää perustua mitattuun kontekstikäyttöön ja edustaviin tehtävätesteihin. Taulukot eivät ole automaattisesti proosaa halvempia tokeneina.

Mitä /init-komento tekee, ja miksi se ei riitä?#

Anthropic kuvaa komentoa dokumentaatiossaan näin:

Mihin /init on hyvä:

• Tunnistaa työkalut tiedostoista package.json, Cargo.toml ja pyproject.toml.
• Listaa koonti- ja testikomennot.
• Poimii käytäntöjä olemassa olevista tiedostoista (.eslintrc, .prettierrc).
• Huomaa Cursorin olemassa olevat säännöt (.cursorrules, .cursor/rules/) ja Copilotin säännöt sekä sisällyttää niistä olennaiset osat. Se poimii AGENTS.md-tiedoston, kun käytössä on tila CLAUDE_CODE_NEW_INIT=1.

Mihin /init ei pysty:

• Se ei tiedä, kuka asiakkaasi on.
• Se ei sisällytä teksteille kieltämiäsi sanoja.
• Se ei lisää sääntöjä agentin virheistä, koska niitä ei vielä ole tapahtunut.
• Se ei luo ”mistä asiat löytyvät” -taulukkoa yrityksesi rakenteesta.

Oikea työnkulku on siis seuraava:

1. Suorita /init Claude Codessa

   Saat 30–50-rivisen aloitus-CLAUDE.md-tiedoston, jossa on työkaluja ja komentoja. Se on tekninen perusta.

2. Lisää tämän artikkelin malli sen päälle

   Käytä osiota ”Vähimmäis-CLAUDE.md 5 minuutissa”. Lisää navigointia, reititystä ja periaatteita käsittelevät osiot.

3. Täytä hakasulkeissa olevat kentät

   Anna Claudelle kehote: ”lue projektini ja täytä malli”. Jos business/- ja about-me/-kansioita ei vielä ole, Claude esittää tarkentavia kysymyksiä.

4. Tee rasituskoe

   Sano Claudelle: ”Lue CLAUDE.md-tiedostoni ja etsi 10 kohtaa, jotka saattavat saada sinut agenttina ymmärtämään ohjeen väärin.” Saat korjausehdotusten listan.

5. Elä sitten tiedoston kanssa

   Lisää rivi jokaisen agentin virheen jälkeen. Kuukaudessa saat CLAUDE.md-tiedoston, joka on elävä ja räätälöity yrityksellesi.

Neljännen vaiheen kehote:

Minulla on CLAUDE.md-tiedosto. Huomenna rakennan sen pohjalta toiminnon.

Tehtäväsi on tehdä sille rasituskoe. Etsi 10 syytä, joiden vuoksi työ saattaisi epäonnistua:

missä CLAUDE.md on monitulkintainen ja sinä agenttina saatat ymmärtää sen väärin

missä on aukkoja, jotka pakottaisivat sinut keksimään asioita

missä säännöt ovat ristiriidassa keskenään

missä yliarvioin sen, kuinka paljon yhdessä päivässä voidaan tehdä

missä aliarvioin asioita (tämä on vielä pahempaa)

Älä säästele. Arvostele sitä ankarasti. Haluan löytää nämä ongelmat nyt, en tuotantovaiheessa.
Anna lopuksi lista konkreettisista muutoksista: mitä pitää muuttaa ja miten, jotta nämä ongelmat eivät toistu.

CLAUDE.md vs AGENTS.md vs MEMORY.md: kuka lukee mitä vuonna 2026?#

Tärkein tulokkaita hämmentävä kysymys on: lukeeko Claude Code tiedostoa AGENTS.md? Ennen syyskuuta 2026 vastaus oli ”ei”: Anthropicin dokumentaatio neuvoi luomaan CLAUDE.md-tiedoston, joka tuo AGENTS.md-tiedoston mukaan. Versiosta 2.1.277 alkaen (julkaistu 18. syyskuuta 2026) Claude Code lukee itse AGENTS.md-tiedoston, mutta vain, jos työkansiossa tai sen yläpuolella ei ole tiedostoa CLAUDE.md, .claude/CLAUDE.md tai CLAUDE.local.md.

Jos projektissa on CLAUDE.md-tiedosto, Claude Code lukee oletusarvoisesti vain sen ja ohittaa AGENTS.md-tiedoston. Tätä voi muuttaa kohdassa /config, Project instructions -asetuksen alta: esimerkiksi claude-md-and-agents-md-asetus saa sen lukemaan molemmat tiedostot. Toinen tapa toimii kaikissa versioissa: lisää CLAUDE.md-tiedostoon tuonti:

@AGENTS.md

## Claude Code

Lisäsääntöjä Claude Codelle, joita muut agentit eivät tarvitse.

Syntaksi @filename tuo toisen tiedoston mukaan. Claude lukee sen ja lataa sen kontekstiin yhdessä CLAUDE.md-tiedoston kanssa. Tuonti ei aiheuta sitä, että tiedosto luettaisiin kahdesti, vaikka Claude Code pystyisi lukemaan AGENTS.md-tiedoston itse.

Milloin tarvitset AGENTS.md-tiedoston. Jos työskentelet rinnakkain Claude Coden ja Codex CLI:n, Cursorin tai Copilotin kanssa, luo AGENTS.md yhteiseksi totuuden lähteeksi, lisää CLAUDE.md-tiedostoon @AGENTS.md ja lisää sen päälle mahdolliset Claude-kohtaiset säännöt. Jos tällaisia sääntöjä ei ole, CLAUDE.md-tiedostoa ei tarvitse luoda: versiosta 2.1.277 alkaen Claude Code lukee itse AGENTS.md-tiedoston. Jos käytät vain Claude Codea, et tarvitse AGENTS.md-tiedostoa; käytä vain yhtä CLAUDE.md-tiedostoa. Kaikki vaihtoehdot vaihe vaiheelta löytyvät oppaasta AGENTS.md:n ja CLAUDE.md:n käyttö samassa projektissa.

Mikä on MEMORY.md? Äskettäisestä päivityksestä lähtien Claude Code tallentaa automaattisesti tietoja sinusta polkuun ~/.claude/projects/<project-name>/memory/MEMORY.md. Näihin kuuluvat keskustelutavoitteet (”käyttäjä pitää lyhyistä vastauksista”), toistuvat ilmaukset (”kielsi emojit koodissa”) ja toimintatapoja koskevat havainnot (”käyttää macOS:ää ja zsh:ää”).

Tämä on erillinen muistijärjestelmä, ei CLAUDE.md. Et kirjoita sitä käsin, vaan Claude tekee sen keskustelujenne perusteella. Jos MEMORY.md sisältää jotain, josta pitäisi tulla sääntö, siirrä se CLAUDE.md-tiedostoon. Jos siinä on jotain tarpeetonta tai virheellistä, voit poistaa sen käsin; se on tekstitiedosto.

Mikä on hyödyllinen CLAUDE.md-tiedoston koko ja miten pitkä tiedosto tarkistetaan?#

Jokaisessa Claude Code -ikkunassa ladataan kontekstiin useita tasoja: Anthropicin järjestelmäkehote (arviolta kymmeniätuhansia tokeneita), CLAUDE.md-tiedostosi, @-merkillä tuodut tiedostot, MEMORY.md, nykyisen keskustelun historia ja Clauden avaamien tiedostojen sisältö. Kaiken tämän on mahduttava mallin kontekstiin (Sonnetilla 200K tokenia, Opuksella 1M).

Mitä suuremmaksi CLAUDE.md kasvaa, sitä vähemmän tilaa jää nykyiselle työlle. 1 000-rivisessä tiedostossa on noin 8 000 tokenia, ja se toistuu jokaisessa istunnossa. Pro-tilauksessa (oman kokemukseni mukaan noin 10–12 ”raskasta” kehotetta päivässä) tämä leikkaa kapasiteettiasi neljänneksellä.

Kustannukset ovat vain yksi huoli. Ohjeiden noudattaminen voi heiketä, kun ne ovat pitkiä, epäolennaisia tai ristiriitaisia. Luotettavasti noudatettaville ohjeille ei ole yleispätevää lukumäärää. Testaa muutama edustava tehtävä, joissa kriittisiä sääntöjä tarvitaan, kirjaa epäonnistumiset ja vertaa toimintaa kohdennetun muokkauksen jälkeen.

Tässä on siis nyrkkisääntö tiedoston koolle:

• 80–120 riviä - kätevä aloitusalue tiiviille projektikartalle, ei taattu ohjeiden noudattamispistemäärä.
• 150–200 riviä - hyödyllinen muistutus tarkistaa olennaisuus ja siirtää yksityiskohtaiset menettelyt linkitettyihin tiedostoihin.
• 200–300 riviä - tarkista tokenimäärä, toisto ja tehtävätulokset. Edellä kuvattu 280-rivinen yritysesimerkki voi silti toimia hyvin.
• 400+ riviä - vahva syy kohdennettuun tarkistukseen, ei todiste käyttökelvottomuudesta. Säilytä olennaiset rajat ja siirrä yksityiskohtia vasta linkkien ja sääntöjen toimivuuden tarkistamisen jälkeen.

Pelkkä rivimäärä ei todista onnistumista tai epäonnistumista. Toista muokkauksen jälkeen samat edustavat tehtävät ja varmista tärkeät säännöt keksityn noudattamisprosentin sijaan.

Anthropic antaa dokumentaatiossaan suoran testin:

Sovella tätä jokaiseen riviin. Jos vastaus on ”se tekisi tämän silti oikein”, poista rivi. CLAUDE.md ei ole paikka dokumentaatiolle, päätöshistorialle tai filosofialle. Se on tarkoitettu vain säännöille, joita agentti tarvitsee välttääkseen virheet.

Mitkä 7 virhettä tekevät CLAUDE.md-tiedostosta hyödyttömän?#

Virhe 1. ”Ole hyvä insinööri”

Yleisin virhe. Ihmiset kirjoittavat CLAUDE.md-tiedostoon yleisiä toiveita: ”kirjoita siistiä koodia”, ”käytä parhaita käytäntöjä”, ”ajattele kuin kokenut insinööri”.

Nämä sanat eivät tarkoita mitään. Claude kirjoittaa jo valmiiksi ”siistiä koodia” yleisessä mielessä. Tällaiset rivit kuluttavat kontekstia vaikuttamatta yhteenkään päätökseen.

Korvaa ”kirjoita siistiä koodia” ohjeella ”käytä 2 välilyönnin sisennystä”, ”älä käytä any-tyyppiä TypeScriptissä” tai ”funktio saa olla enintään 30 riviä pitkä”. Ne ovat täsmällisiä ja todennettavia.

Virhe 2. Clauden jo tietämien asioiden toistaminen

Kuvaukset kielten yleisistä käytännöistä (”JavaScriptissä funktiot ovat ensimmäisen luokan kansalaisia”, ”TypeScriptissä on staattinen tyypitys”). Selitykset siitä, miten npm, git tai docker toimivat.

Claude oppi tämän kaiken koulutuksensa aikana. Sen toistaminen CLAUDE.md-tiedostossa ei lisää mitään, vaan vie tilaa kontekstista.

Virhe 3. Pitkät vaiheittaiset ohjeet CLAUDE.md-tiedostossa

Pitkät ohjeet aiheista ”kuinka projekti otetaan käyttöön”, ”kuinka tietokantamigraatio kirjoitetaan” tai ”kuinka uusi komponentti asetetaan”. Kymmenittäin vaihe vaiheelta eteneviä rivejä.

Tämä ei ole paikka pitkille vaiheittaisille ohjeille. Se on tarkoitettu yhden rivin säännöille. Sijoita pitkät ohjeet skills/-kansioon (erillinen Claude Code -mekanismi, joka ladataan tarvittaessa) tai docs/-kansioon. Käytä CLAUDE.md-tiedostossa yhden rivin linkkiä: ”Kun luot uuden migraation, avaa docs/migrations.md.”

Virhe 4. Säännöt, joita automaattinen koodianalysaattori jo valvoo

”Käytä puolipisteitä”, ”älä jätä käyttämättömiä importteja”, ”älä käytä var-määrettä”. ESLint, Prettier ja Biome havaitsevat nämä kaikki; ne ovat linttereitä (automaattisia koodintarkistustyökaluja).

Linteri on deterministinen: se suoritetaan, löytää virheen ja korjaa sen. CLAUDE.md-sääntö on todennäköisyyksiin perustuva; agentti voi unohtaa sen. Sitä ei tarvitse toistaa - linteri on helpompi määrittää.

Virhe 5. Salaisuudet CLAUDE.md-tiedostossa

Olen nähnyt testitilien salasanoja, testiympäristön API-tokeneita sekä linkkejä todennettuihin ylläpitopaneeleihin. Kaikki oli git-tietovarastoon tallennetussa tiedostossa, joka ladattiin Anthropicin mallin kontekstiin.

Ei koskaan. Salaisuudet kuuluvat .env-tiedostoon, joka on .gitignore-tiedostossa. CLAUDE.md-tiedostossa voi korkeintaan lukea: ”Älä lue koko .env-tiedostoa; hae yksittäinen muuttuja grep-komennolla.”

Virhe 6. Yli 500-rivinen kaatopaikka, jota ei ole siivottu kuuteen kuukauteen

CLAUDE.md on kasvanut, kopioi puolet docs/-kansiosta, on monessa kohdassa ristiriitainen, eikä kukaan muista sen sisältöä. Agentti alkaa sivuuttaa suurinta osaa siitä. Tiimi valittaa, ettei ”Claude noudata ohjeita”, ja lisää uusia sääntöjä, mikä pahentaa tilannetta.

Laiminlyödyn CLAUDE.md:n merkkejä ovat yli 300 riviä, eri osioissa toistuvat säännöt, linkit vanhentuneisiin tai olemattomiin tiedostoihin sekä ”historialliset” muistiinpanot, kuten ”vuonna 2024 päätimme tehdä asian näin, mutta muutimme sitten mielemme”.

Ratkaisu: pyydä Claudea tarkistamaan tiedosto kahden viikon välein Anthropicin testillä: ”Tekisikö agentti virheen, jos tämä rivi poistettaisiin?” Poista kaikki, joihin vastaus on ”ei”.

Virhe 7. CLAUDE.md luodaan ja unohdetaan

Tämä on edellisen virheen vastakohta. Tiedosto koottiin kerran kaksi kuukautta sitten, eikä siihen ole koskettu sen jälkeen. Sillä välin työkalut ovat vaihtuneet, uusia kansioita on lisätty ja uusia agenttivirheitä on ilmennyt. CLAUDE.md ei tiedä näistä mitään, koska kukaan ei ole päivittänyt sitä.

Selvä merkki tästä on se, että toistat saman ohjeen jokaisessa istunnossa. ”Älä tee X:ää”, ”älä koske Y:hyn”, ”muista Z”. Jos olet toistanut sen yli kaksi kertaa, sääntö kuuluu CLAUDE.md-tiedostoon, ei päähäsi.

Miten saat CLAUDE.md-tiedoston oppimaan itse ”päivitä istunnon lopussa” -säännöllä?#

CLAUDE.md-tiedostossani on lyhyt osio:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

Kun tämä osio lisättiin CLAUDE.md-tiedostoon, Claude alkoi kysyä jokaisen istunnon lopussa: ”Oliko jotain uutta, joka kannattaisi kirjata muistiin?” Jos oli, se ehdotti luonnosta säännöksi, minä selvensin sitä ja tiedosto luotiin.

Kahden kuukauden työskentelyn jälkeen minulla on yli kaksi tusinaa tiedostoa about-me/feedback/-kansiossa - niihin on kirjattu tietyistä virheistä opitut säännöt. Kukin tiedosto on yksi sivu Muoto → Syy → Soveltaminen -rakenteella. Kansio kasvoi ”toiseksi muistiksi”, johon on kirjattu henkilökohtaiset mieltymykseni ja tabuni.

Yhtäkään virhettä ei toisteta, koska siitä tulee sääntö, ja säännöt kertyvät ja vahvistavat toisiaan. Kuuden kuukauden jälkeen Claude tuntee projektini paremmin kuin minä kuukauden mittaisen tauon jälkeen muistan sen.

Miten lisäät CLAUDE.md-tiedostoon oikeudellisia sääntöjä, markkinointia ja operatiivisia käytäntöjä?#

Useimmille tiimeille CLAUDE.md on puhtaasti tekninen asiakirja: työkaluja, koontikomentoja ja koodauskäytäntöjä. Siitä on hyötyä, mutta se tuo vain kolmasosan arvosta.

Kun yrittäjä ylläpitää CLAUDE.md-tiedostoa, siihen kannattaa lisätä liiketoimintaa käsitteleviä osioita. Kolme niistä on tärkeimpiä:

Oikeudelliset säännöt (säännellyillä markkinoilla)

Jos julkaiset tekstejä säännellyllä alalla (rahoitus, lääketiede, lääkemainonta tai lasten tuotteet), kielletyillä sanoilla on oikeudellista merkitystä, ja ne kuuluvat CLAUDE.md-tiedostoon nimenomaisina sääntöinä. Ei jonkun mieleen tai toimittajan kuvakaappaukseen, vaan tiedostoon, jonka agentti näkee jokaisessa istunnossa.

Esimerkki fintech-projektille, jolla ei ole pankkitoimilupaa:

Toimituksellinen huomautus: Seuraava esimerkki näyttää tiettyä projektia koskevan sisäisen säännön muodon. Se ei anna yleistä lupaa käyttää lueteltuja termejä: väitteen hyväksyttävyys riippuu sovellettavasta lainsäädännöstä ja yrityksen asemasta.

🚨 KRIITTISTÄ - taloudellisiin palveluihin liittyvä sanamuoto on kielletty. Älä käytä asiakkaille suunnatuissa materiaaleissa sanoja ”talletus”, ”taattu tuotto” tai ”sijoitustuote”. Käytä niiden sijaan ilmauksia ”säästötili”, ”odotettu tuotto” ja ”vaihtuvakorkoinen tuote”. Syynä ovat tätä projektia koskevat rahoituspalvelujen mainontaan sovellettavat lakivaatimukset.

Tämä CLAUDE.md-tiedoston lohko tekee yhden yksinkertaisen asian: aina kun pyydät Claudea kirjoittamaan asiakkaille suunnattua tekstiä, agentti tarkistaa sen näiden kieltojen varalta. Ilman sääntöä kiellettyjä sanoja ilmestyy joka kolmanteen kampanjaan. Sen kanssa unohdat niiden olemassaolon.

Sama lähestymistapa toimii seuraavissa:

• Lääketieteelliset projektit (vältä väitteitä, että jokin ”hoitaa” tai ”parantaa”).
• Lääkemainonta (ei väitteitä ”tehokkaimmasta” hoidosta; vaaditut varoitukset).
• Kaikki säännellyt toimialat, joilla on omat mainontasääntönsä.

Markkinointityyli ja tekstien muoto

Jos julkaiset tekstejä säännöllisesti (sosiaalisessa mediassa, uutiskirjeissä tai verkkosivustoilla), niiden muoto kannattaa dokumentoida yhdessä kappaleessa CLAUDE.md-tiedostossa. Tässä on esimerkki viestintäkanavaa ylläpitävän vaikuttajan tai toimiston ohjeesta:

Kun kirjoitat kanavaan julkaisuja, tutustu tiedostoon style/posts.md. Käytä kanavan sallimia muotoilumerkkejä ja vältä ”vaarallisia” erikoismerkkejä. Päätä julkaisu toimintakehotukseen, jossa on tämän käytännön mukaiset UTM-tunnisteet: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Claude kirjoitti ennen julkaisuja ”markkinointisivuston yleisellä tyylillä”. Nyt se noudattaa muotoasi, käyttää UTM-tunnisteitasi eikä paljasta tekstien olevan tekoälyn kirjoittamia.

Operatiiviset käytännöt

Laukaisintaulukot. Kun sanot tietyn ilmauksen, agentti tietää, mitä tiedostoja avata ja mitä tehdä. Tässä on esimerkki tiimille, joka suunnittelee viikoittain:

”Suunnittele viikko” → avaa ops/monthly.md, luo samaan kansioon YYYY-WNN.md ja siirrä tehtävät tiedostosta ops/backlog.md sopivien päivien alle. ”Mitä tehtäviä on työjonossa?” → lue ops/backlog.md ja näytä sisältö listana. ”Päätä viikko” → täytä nykyisen viikon tiedoston ”Viikon yhteenveto” -osio.

Tällaisilla taulukoilla Claude siirtyy ”koodia kirjoittavasta apurista” ”operaattoriksi”, joka tuntee yrityksesi rutiinit. Joka maanantai sanon: ”Suunnitellaan viikko”, ja Claude avaa oikeat tiedostot, lukee kuukauden tavoitteet ja ehdottaa, miten tehtävät voisi jakaa.

Miten tarkistat CLAUDE.md-tiedoston 12 kohdan tarkistuslistalla 5 minuutissa?#

1. Koko. Onko tiedosto tiivis ja noin 200 riviä tarkistustavoite eikä hyväksymisen tai hylkäämisen yläraja?
2. Nimi. Onko nimi täsmälleen CLAUDE.md isoilla kirjaimilla kirjoitettuna, ei claude.md?
3. Sijainti. Onko tiedosto projektin juuressa tai polussa ./.claude/CLAUDE.md?
4. Projektin kuvaus. Käykö viidestä ensimmäisestä rivistä ilmi, mikä projekti on ja kenelle se on tarkoitettu?
5. Työkalut. Onko teknologiat lueteltu nimenomaisesti ja ilman täytettä?
6. Rakenne. Onko mukana tietovaraston kaavio selityksineen?
7. Reititys. Onko mukana taulukko, joka kertoo, mistä vastaukset löytyvät?
8. Periaatteet. Onko mukana osio, jonka sääntöjen alussa on ”älä koskaan” ja ”aina”?
9. Täsmällisyys. Onko jokainen sääntö todennettavissa? (”Käytä 2 välilyöntiä”, ei ”kirjoita kauniisti”.)
10. Itsepäivitys. Onko mukana sääntö, joka kehottaa tarkistamaan istunnon lopuksi, mitä pitäisi lisätä?
11. Loppupohdinta. Onko mukana sääntö, joka kehottaa ”kirjaamaan istunnon yhteenvedon retrospectives/-kansioon”?
12. Tietoturva. Sisältyvätkö kriittiset kiellot (.env, rm -rf) myös tiedostoon .claude/settings.json?

Jos vastasit ”ei” useammin kuin viisi kertaa, avaa Claude ja anna sille tämä kehote:

Lue CLAUDE.md-tiedostoni ja vertaa sitä alla olevaan tarkistuslistaan. Kerro jokaisesta kohdasta: kyllä / ei / osittain ja mitä pitäisi täsmälleen korjata.

Tarkistuslista:

Tehtävään riittävän tiivis; tarkista noin 200 rivin kohdalla käsittelemättä sitä ehdottomana rajana

Projektin kuvaus viidellä ensimmäisellä rivillä

Työkalut lueteltu nimenomaisesti

Mukana tietovaraston rakennekaavio

Mukana ”kysymys → tiedosto” -taulukko

Mukana periaatteiden osio sääntöineen

Jokainen sääntö on täsmällinen ja todennettavissa

Mukana ”päivitä istunnon lopussa” -sääntö

Mukana ”tee loppupohdinta istunnon lopussa” -sääntö

Kriittiset kiellot sisältyvät tiedostoon .claude/settings.json

Sama sääntö ei toistu useassa osiossa

Ei linkkejä tiedostoihin, joita ei enää ole olemassa

Anna tarkastuksen jälkeen lista konkreettisista muutoksista, joilla tiedostosta saadaan elävä.

Mitä CLAUDE.md-tiedoston jälkeen kannattaa käyttää: Plan Modea, Skillsiä vai aliagentteja?#

CLAUDE.md on perusta. Kun se toimii, voit lisätä kolme Claude Code -mekanismia, jotka vahvistavat toisiaan.

Plan Mode. Tila, jossa Claude laatii ensin muutosuunnitelman, odottaa hyväksyntääsi ja ryhtyy vasta sitten töihin. Ota se käyttöön näppäinyhdistelmällä Shift+Tab tai komennolla /plan. Se ratkaisee vibekoodauksen suurimman kipupisteen: ”Pyysin Claudea korjaamaan yhden asian, ja se kirjoitti puolet projektista uusiksi.” Näin ei tapahdu Plan Modessa: näet suunnitelman ennen kuin agentti koskee yhteenkään tiedostoon.

Skills. Erillisiä .md-tiedostoja .claude/skills/-kansiossa. Ne sisältävät tietoa tietyntyyppistä tehtävää varten. Esimerkiksi ”kuinka tietokantamigraatio kirjoitetaan” -taito sisältää tietyn menettelyn, mallin ja esimerkkejä. Tieto ei ole CLAUDE.md-tiedostossa, koska sitä on liikaa. Kun Claude kohtaa esimerkiksi tehtävän ”kirjoita migraatio”, se lataa asiaankuuluvan taidon ja noudattaa sitä.

Aliagentit. Kun tehtävä vaatii paljon kontekstia (esimerkiksi suuren toiminnon tarkastaminen), Claude voi käynnistää erillisen aliagentin, jolla on oma puhdas kontekstinsa. Aliagentti tekee työn ja palauttaa tuloksen täyttämättä keskustelun pääkontekstia.

Kaikki kolme mekanismia käyttävät CLAUDE.md-tiedostoa lähtökohtanaan: ne lukevat sen työnsä alussa ymmärtääkseen projektin kontekstin. Siksi nämäkin ominaisuudet toimivat huonosti ilman ajan tasalla olevaa CLAUDE.md-tiedostoa. Ensin perusta, sitten sen päälle tulevat tasot.

Seuraava vaihe. Luo projektin juureen CLAUDE.md-tiedosto, kopioi tämän artikkelin alussa oleva malli ja täytä hakasulkeissa olevat kentät apukehotteen avulla. Käytä sitten tiedostoa: muuta jokainen agentin virhe yhdeksi uudeksi riviksi. Kahden tai kolmen viikon jälkeen CLAUDE.md lakkaa olemasta ”asiakirja, jonka kirjoitimme ja unohdimme”, ja siitä tulee jotain, mitä Claude todella käyttää jokaisessa istunnossa.

Jos haluat rakentaa täydellisen viitekehyksen CLAUDE.md-tiedoston ympärille - business/-kansion toiseksi aivoksi, about-me/-kansion digitaaliseksi kuvaukseksi sinusta, perustaidot ja määritetyn Plan Moden - käytä tämän artikkelin vaiheita ja esimerkkejä. Ailoot-oppaat.

Jatka Ailoot-sivustolle.