# Yksi ohjetiedosto Claude Codelle, Codexille ja Cursorille vuonna 2026
> Yksi totuuden lähde Claude Codelle, Codexille ja Cursorille vuonna 2026: milloin Claude Code lukee AGENTS.md-tiedoston itse, miten @AGENTS.md tuodaan CLAUDE.md-tiedostoon, symbolinen linkki ja /init.
Source: https://ailoot.ai/blog/fi/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/fi/agents-md-claude-md-one-instruction-file/
Language: fi
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-7b9ec274af7665ecc078b63a302cb1e8dc6e8472de49884408e3a6d2b0f57871
Lisätietoja palvelusta on [Ailoot-dokumentaatiossa](https://ailoot.ai/docs/).
## Mikä muuttuu, kun käytät Claude Codea, Codexia ja Cursoria yhdessä?
Keskeinen huomio
Vuonna 2026 tyypillisen vibe-koodaajan työkalukokoonpanoon ei kuulu yksi työkalu vaan 3–5. Claude Code on päätyökalu, Codex sopii pitkiin itsenäisiin tehtäviin ja Cursor nopeisiin muokkauksiin IDE:ssä. Jokaisella on oma ohjetiedostonsa: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Jos pidät ne synkronoituina käsin, muokkaat yhtä riviä viidessä paikassa, unohdat päivittää Cursorin, ja viikon päästä Claude ja Codex antavat eri tulokset samaan kehotteeseen.
Kuvatussa esimerkissä Claude Code on päätyökalu, kun taas Codexia ja Cursoria käytetään tiettyihin tehtäviin. `CLAUDE.md`-tiedostossani on noin 250 riviä ohjeita: mitä luetaan ja missä järjestyksessä, mihin ei saa koskea, mitä komentoja käytetään käyttöönottoon ja millaisia commit-muotoilusääntöjä noudatetaan. Kun kokeilin Codex CLI:tä projektissa ensimmäisen kerran, se ei tuntenut mitään säännöistä: se suoritti `git push --force` -komennon, penkoi `.env`-tiedostoa ja nimesi tiedostoja huolimattomasti uudelleen.
Kopioin ensin `CLAUDE.md`-tiedoston käsin nimelle `AGENTS.md`. Kaksi viikkoa myöhemmin huomasin, että projektissa oli jo neljä versiota samoista ohjeista: tiedostoissa `CLAUDE.md`, `AGENTS.md`, `.cursorrules` ja `.windsurf/rules/`. Ne kaikki poikkesivat toisistaan hieman. Tämä ei ole Claude- tai Cursor-ongelma, vaan useiden totuuden lähteiden järjestelmän perusongelma. Käsittelen tätä ongelmaa tarkemmin [moniagenttityön oppaassa](https://ailoot.ai/blog/fi/claude-code-codex-together/).
Kesäkuussa 2026 Anthropicin Claude Code -muistidokumentaatio tarjosi yhden vastauksen: yhteinen tiedosto ja siihen tehty tuonti. Syyskuusta 2026 lähtien Claude Code lukee `AGENTS.md`-tiedoston itse, jos projektissa ei ole `CLAUDE.md`-tiedostoa. Tuontia tarvitaan silloin, kun sinulla on nimenomaan Claudea koskevia sääntöjä. Alla selitän, milloin yksi `AGENTS.md` riittää, miten tuonti määritetään ja miten yhteiset säännöt erotetaan Claude-kohtaisista säännöistä.
## Lukeeko Claude Code itse AGENTS.md-tiedoston?
Keskeinen huomio
Kyllä, versiosta 2.1.277 lähtien. Se julkaistiin 18. syyskuuta 2026, mutta tiedosto luetaan itse vain, jos työhakemistossa tai sen yläpuolella ei ole tiedostoa `CLAUDE.md`, `.claude/CLAUDE.md` tai `CLAUDE.local.md`. Jos `CLAUDE.md` on olemassa, Claude Code lukee oletuksena vain sen, ja `AGENTS.md` sisällytetään lisäämällä rivi `@AGENTS.md` tiedostoon `CLAUDE.md` tai luomalla symbolinen linkki. Toimintaa voi muuttaa kohdassa `/config`, Project instructions -asetuksissa. Ennen syyskuuta Claude Code ei lukenut `AGENTS.md`-tiedostoa lainkaan, ja tuonti oli ainoa tapa.
Ennen syyskuuta 2026 vastaus oli ”ei”. Issue \#6235, jossa pyydettiin AGENTS.md-tukea, oli ollut avoinna elokuusta 2025 lähtien, ja se suljettiin 17. elokuuta 2026. Muistidokumentaatio oli koko ajan osoittanut yhden ratkaisun: luo CLAUDE.md ja sisällytä siihen `AGENTS.md` tuontina. Versiosta 2.1.277 lähtien dokumentaatio sanoo jotain muuta:
Claude Code voi lukea AGENTS.md-tiedoston projektin ohjeina, joten muille agenteille jo määritetty repository toimii ilman CLAUDE.md-tiedostoa, tuontia tai määrityksiä.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Se, mitä Claude Code tarkalleen lukee, riippuu projektissa olevista tiedostoista:
| Projektin tiedostot | Mitä Claude Code lukee |
|----|----|
| `AGENTS.md`, eikä työhakemistossa tai sen yläpuolella ole tiedostoa `CLAUDE.md` tai `CLAUDE.local.md` | `AGENTS.md` |
| `AGENTS.md` ja `CLAUDE.md` (tai `CLAUDE.local.md`) työhakemistossa tai sen yläpuolella | Vain `CLAUDE.md` |
| `CLAUDE.md`, jossa on rivi `@AGENTS.md` | `CLAUDE.md` sekä sen sisällä `AGENTS.md` tuonnin kautta |
Tässä tarkistuksessa työhakemiston ja kaikkien sen yläpuolisten hakemistojen tiedostot `CLAUDE.md`, `.claude/CLAUDE.md` ja `CLAUDE.local.md` lasketaan mukaan. Henkilökohtaista tiedostoa `~/.claude/CLAUDE.md`, yrityksen hallinnoimaa tiedostoa tai `.claude/rules/`-hakemiston sääntöjä ei lasketa: ne ladataan `AGENTS.md`-tiedoston rinnalla.
Kun `CLAUDE.md`-tiedostoa ei ole, Claude Code lukee käynnistyksen yhteydessä kaikki työhakemiston ja sen yläpuolisten hakemistojen `AGENTS.md`- ja `.claude/AGENTS.md`-tiedostot. Se lukee alihakemiston `AGENTS.md`-tiedoston, kun se avaa tiedoston kyseisessä alihakemistossa. Myös `AGENTS.md`-tiedoston sisäiset `@path`-tuonnit toimivat. Claude Code ei lue tiedostoja `AGENTS.local.md` tai `AGENTS.override.md` eikä `.agents/`-hakemiston sisältöä.
Ongelmana on, että myös henkilökohtainen `CLAUDE.local.md` lasketaan mukaan. Luo sellainen keskeneräisiä sääntöjäsi varten, niin Claude Code lakkaa huomaamatta lukemasta `AGENTS.md`-tiedostoa. Alla mainittu asetus ratkaisee ongelman.
Toimintaa voi muuttaa kohdassa `/config`, Project instructions -asetuksissa:
| Asetus | Mitä Claude Code lukee |
|----|----|
| `claude-md-or-agents-md` (oletus) | `CLAUDE.md` tai, jos sitä tai `CLAUDE.local.md`-tiedostoa ei ole, `AGENTS.md` |
| `claude-md-and-agents-md` | Molemmat tiedostot: kussakin hakemistossa ensin `CLAUDE.md`, sitten `AGENTS.md` |
| `claude-md` | Vain `CLAUDE.md` |
| `managed-only` | Vain yrityksen hallinnoima `CLAUDE.md` ja automaattinen muisti |
Jos haluat säilyttää `CLAUDE.local.md`-tiedoston menettämättä `AGENTS.md`-tiedostoa, valitse `claude-md-and-agents-md`. Tiedostoa ei lueta kahdesti: jos `AGENTS.md` sisältyy jo `@AGENTS.md`-rivin tai symbolisen linkin kautta, Claude Code ei lataa sitä toistamiseen asetuksesta riippumatta.
Voit tarkistaa `/memory`-komennolla, onko tiedosto otettu mukaan: versiosta 2.1.280 lähtien `AGENTS.md`-tiedoston polku näkyy luettelossa. Ennen versiota 2.1.277 ja istunnoissa, joissa sisäänrakennettu `agents-md`-laajennus on poistettu käytöstä, Claude Code lukee vain `CLAUDE.md`-tiedoston, eikä `/config`-valikossa ole Project instructions -kohtaa. Ennen versiota 2.1.281 Amazon Bedrockin kautta toimivat istunnot ja istunnot, joissa telemetria oli poistettu käytöstä, toimivat samalla tavalla. Ensimmäisessä istunnossa vanhemmasta versiosta päivittämisen jälkeen `AGENTS.md`-tiedostoa ei välttämättä myöskään oteta mukaan; se toimii seuraavasta istunnosta alkaen.
Mitä tämä merkitsee yhden tiedoston kokoonpanolle? Jos sinulla ei ole vain Claudea koskevia sääntöjä, voit jättää `CLAUDE.md`-tiedoston pois: `AGENTS.md` riittää, ja Claude Code, Codex ja Cursor lukevat sen. Jos tällaisia sääntöjä on (plan mode riskialttiille hakemistoille, skills, hooks), tarvitset `CLAUDE.md`-tiedoston, jolloin Claude Code lakkaa lukemasta `AGENTS.md`-tiedostoa itse. Lisää silloin `AGENTS.md` `CLAUDE.md`-tiedostoon rivillä `@AGENTS.md`; tämä kokoonpano toimii kuten ennen syyskuuta. Se toimii myös Claude Coden vanhemmissa versioissa. Selitän tämän tarkemmin alla.
## Miten tuot @AGENTS.md-tiedoston CLAUDE.md-tiedostoon?
Keskeinen huomio
Tuontia tarvitaan, kun projektissa on `CLAUDE.md`: sen ollessa olemassa Claude Code ei oletuksena lue `AGENTS.md`-tiedostoa itse. Määritä tuonti kirjoittamalla rivi `@AGENTS.md` `CLAUDE.md`-tiedoston alkuun. Kun Claude Code käynnistää istunnon, se korvaa kyseisen rivin `AGENTS.md`-tiedoston sisällöllä ja lukee tuloksen yhtenä tekstinä. Tuonnin jälkeen voit lisätä osion nimeltä ”Claude Code”, joka sisältää vain Claudea koskevia sääntöjä. Tuonnit toimivat suhteellisilla ja absoluuttisilla poluilla, ja ne voidaan sisäkkäistää enintään neljän tason syvyyteen.
Virallisen dokumentaation minimaalinen toimiva esimerkki:
```markdown
@AGENTS.md
## Claude Code
Käytä plan modea muutoksiin hakemistossa `src/billing/`.
```
Näin se toimii. Ensimmäinen rivi, `@AGENTS.md`, on tuontidirektiivi. Kun Claude Code jäsentää `CLAUDE.md`-tiedoston istunnon alussa, se löytää tuonnin ja lisää sen kohdalle `AGENTS.md`-tiedoston koko sisällön. Seuraavana on otsikko `## Claude Code`: se on pelkkää markdownia, mutta toimii ”Claude-kohtaisten lisäysten” osiona. Sen alla on sääntö, joka koskee vain Claude Codea: käytä plan modea laskutushakemiston muutoksiin. Codex CLI tai Cursor ei avaa tätä tiedostoa lainkaan, vaan ne käyttävät tavallista `AGENTS.md`-tiedostoa.
Lainaus dokumentaatiosta, jossa kuvataan tuontien toimintaa:
CLAUDE.md-tiedostot voivat tuoda muita tiedostoja lisää käyttämällä syntaksia @path/to/import. Tuodut tiedostot laajennetaan ja ladataan kontekstiin istunnon alussa yhdessä niihin viittaavan CLAUDE.md-tiedoston kanssa.
— Anthropic, https://code.claude.com/docs/en/memory
Muutamia käytännön yksityiskohtia:
- **Suhteelliset ja absoluuttiset polut.** `@AGENTS.md` on suhteessa tuonnin sisältävään tiedostoon. `@/Users/me/shared/rules.md` tai `@~/.claude/personal.md` ovat absoluuttisia polkuja. Käytän polkua `@~/.claude/personal.md` henkilökohtaisille mieltymyksille, joita en halua lisätä repositoryyn.
- **Neljän tason syvyys.** `AGENTS.md` voi tuoda tiedoston `@docs/coding-style.md`, joka puolestaan voi tuoda toisen tiedoston, enintään neljän tason syvyyteen asti. Se riittää kaikkiin käytännön rakenteisiin.
- **Takamerkit estävät tuonnit.** Jos tekstissä lukee `` `@README` ``, kyseessä on vain nimen maininta, ei tuonti. Tästä on hyötyä, kun lukijoille selitetään tuontien toimintaa käynnistämättä tuontia.
- **Ulkopuolisten tiedostojen hyväksyntä.** Jos tuonti osoittaa työhakemiston ulkopuolelle, kuten `@~/.claude/personal.md`, Claude Code näyttää ensimmäisellä kerralla valintaikkunan, jossa tiedostot luetellaan. Jos kieltäydyt, ulkoiset tuonnit pysyvät poissa käytöstä eikä valintaikkunaa näytetä uudelleen. Projektin juuressa oleva `@AGENTS.md` ei käynnistä valintaikkunaa. Tämä suojaa sinua lataamasta vahingossa asiaankuulumatonta tiedostoa kontekstiin.
Kun siirryin tähän kokoonpanoon kuvaamassani projektissa, `CLAUDE.md` lyheni 250 rivistä 60:een: mukana oli `@AGENTS.md` sekä viidestä seitsemään sääntöä, jotka koskivat vain Claude Codea (plan mode riskialttiille hakemistoille, mitä hallinta-alueella ei saa muuttaa ja miten commitit muotoillaan). Kaikki yhteinen sisältö on `AGENTS.md`-tiedostossa, jota Codex ja Cursor lukevat.
## Milloin kannattaa valita symbolinen linkki ja milloin tuonti?
Keskeinen huomio
Anthropic tarjoaa kaksi tapaa: tuonnin `@AGENTS.md` tai symbolisen linkin `ln -s AGENTS.md CLAUDE.md`. Symbolinen linkki on yksinkertaisempi – se on vain alias eikä vaadi tiedostomuutoksia. Siinä on kuitenkin kolme haittaa: Windowsissa tarvitaan järjestelmänvalvojan oikeudet, `CLAUDE.md`-tiedostoon ei voi lisätä Claude-kohtaisia sääntöjä, ja Git näyttää joskus symbolisen linkin diffissä roska-arvona. Tuonti on yleiskäyttöinen tapa. Jos sinulla ei ole vain Claudea koskevia sääntöjä, et versiosta 2.1.277 alkaen tarvitse kumpaakaan: Claude Code lukee `AGENTS.md`-tiedoston itse.
Dokumentaatiossa symbolinen linkki esitetään näin:
```bash
ln -s AGENTS.md CLAUDE.md
```
Ja heti sen jälkeen annetaan suora varoitus Windowsista:
Jos sinä tai joku muu repositoryn kloonaava henkilö käyttää Windowsia, käytä `@AGENTS.md`-tuontia. Symbolisen linkin luominen edellyttää siellä järjestelmänvalvojan oikeuksia tai Developer Mode -tilaa, ja Git ilman käytössä olevaa core.symlinks-asetusta hakee commitoidun linkin tavallisena tekstitiedostona. Tällöin saat yhden rivin `CLAUDE.md`-tiedoston, etkä kyseisen kopion ohjeita.
— Anthropic, https://code.claude.com/docs/en/memory
Vertailutaulukko:
| Kriteeri | `@AGENTS.md`-tuonti | Symbolinen linkki `ln -s` |
|----|----|----|
| **Toimii Windowsissa ilman järjestelmänvalvojan oikeuksia** | kyllä | ei (Developer Mode vaaditaan) |
| **Vain Claudea koskevien sääntöjen lisääminen onnistuu** | kyllä, tuonnin jälkeen | ei, tiedosto on sama |
| **Näkyy Gitissä tavallisena markdownina** | kyllä | linkkinä (riippuu asetuksesta `core.symlinks`) |
| **Useita tiedostoja voi tuoda** | kyllä, enintään neljä tasoa | ei, yksi yhteen |
| **Välimuisti ja mitätöinti Claude Codessa** | tavallinen CLAUDE.md-tiedostolle | toimii, mutta symboleihin liittyy metatason ongelmia |
| **Oletusvalinta** | sopii kaikille | vain jos alustojen välinen käyttö ei ole tärkeää |
Käytän kuvatussa projektissa tuonteja. Syyt:
1. **Tiimissä käytetään eri alustoja.** Käytän Macia; esimerkin tiimissä Windows- ja Mac-käyttäjiä on suunnilleen yhtä paljon. Jos repositoryssa on symbolinen linkki, se haetaan Windows-käyttäjille ilman Developer Modea tavallisena tekstitiedostona, jonka ainoa rivi on `AGENTS.md`. Tämä aiheuttaa outoja virheitä: joskus säännöt toimivat ja joskus eivät, eikä syy ole selvä.
2. **Haluan Claude-kohtaisia sääntöjä.** `@AGENTS.md`-tuonnin alla `CLAUDE.md`-tiedostossani on ”Claude Code” -osio, jossa on sääntöjä: käytä `--effort high` -asetusta arkkitehtuuritehtävissä, suorita `npm run build` ennen `git push` -komentoa äläkä kutsu `/api/v1/deploy`-rajapintaa käsin. Codex ei ymmärrä näitä komentoja.
3. **Virheiden jäljittäminen on helpompaa.** Kun jokin menee pieleen, avaan `CLAUDE.md`-tiedoston ja näen tuonnin sekä tekemäni ohitusmääritykset. Symbolisessa linkissä ei näy, että ”tämä lisättiin tähän”. Lisätietoja Claude Code -asetusten virheiden jäljittämisestä on [turvatilan oppaassa](https://ailoot.ai/blog/fi/claude-code-safe-mode-recovery/).
Jos sinulla ei ole Claude-kohtaisia sääntöjä, symbolista linkkiä ei enää tarvita versiosta 2.1.277 lähtien: poista `CLAUDE.md`, niin Claude Code lukee `AGENTS.md`-tiedoston itse. Säilytä symbolinen linkki vain, jos joku tiimissä käyttää versiota, joka on vanhempi kuin 2.1.277, eikä voi päivittää. Jos sinulla on Claude-kohtaisia sääntöjä, tuonti on kätevämpi yhdeksässä tapauksessa kymmenestä.
## Mitä Codex, Cursor, Copilot, Windsurf ja Gemini CLI lukevat?
Keskeinen huomio
Jokainen työkalu lukee omat tiedostonsa, joskus useamman kuin yhden. Claude Code lukee `CLAUDE.md`-tiedoston ja on syyskuusta 2026 lähtien lukenut myös `AGENTS.md`-tiedoston, jos projektissa ei ole `CLAUDE.md`-tiedostoa. Codex CLI lukee `AGENTS.md`-tiedoston sekä `AGENTS.override.md`-tiedoston. Cursor lukee vanhaa `.cursorrules`-muotoa tai uudempaa `.cursor/rules/*.mdc`-muotoa, ja kesästä 2026 lähtien myös `AGENTS.md`-tiedostoa. Copilot lukee `.github/copilot-instructions.md`-tiedoston tai `.github/instructions/*.instructions.md`-tiedostoja. Windsurf lukee vanhaa `.windsurfrules`-tiedostoa tai uudempaa `.windsurf/rules/`-hakemistoa. Gemini CLI lukee `GEMINI.md`-tiedoston. Aider ja Cline ovat jo ottaneet `AGENTS.md`-tiedoston käyttöön.
Yleiskuva seitsemästä tärkeimmästä työkalusta (perustuu kunkin työkalun viralliseen dokumentaatioon):
| Työkalu | Ensisijainen ohjetiedosto | Vaihtoehdot | Lukeeko AGENTS.md-tiedoston? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, hallittu käytäntö | kyllä, jos projektissa ei ole `CLAUDE.md`-tiedostoa (versiosta 2.1.277 lähtien), muutoin tuonnin kautta |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | kyllä (natiivisti) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (vanhentunut) | kyllä |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | laajennusten kautta |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (vanhentunut) | kyllä |
| **Gemini CLI** | `GEMINI.md` | \- | ei |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | kyllä (natiivisti) |
Mitä tästä seuraa? Jos repositoryssa on `AGENTS.md` (sekä tuonnin sisältävä `CLAUDE.md`, kun Claude-kohtaisia sääntöjä tarvitaan), viisi seitsemästä työkalusta saa ohjeet automaattisesti ajan tasalle. Cursorin ja Windsurfin omat natiivitiedostot voi jättää ennalleen (`AGENTS.md` tulee luetuksi myös niissä), tai niihin voi lisätä `@AGENTS.md`-tuonnin – niiden syntaksi kuitenkin eroaa toisistaan, eikä sitä aina tueta.
Yksinkertaisin toimintatapa uuteen projektiin:
1. **Sijoita kaikki yhteiset säännöt tiedostoon `AGENTS.md`** – 95 % säännöistä kuuluu sinne.
2. **Luo `CLAUDE.md`, jos tarvitset vain Claudea koskevia sääntöjä:** kirjoita ensimmäiselle riville `@AGENTS.md` ja lisää sen alle Claude-kohtaisten sääntöjen osio. Jos tällaisia sääntöjä ei ole, `CLAUDE.md`-tiedostoa ei tarvita; Claude Code on lukenut `AGENTS.md`-tiedoston itse versiosta 2.1.277 lähtien.
3. **Säilytä Cursorille `.cursor/rules/`** harvinaisia Cursor-kohtaisia tarpeita varten (sen `@Codebase`- ja `@Docs`-komennot).
4. **Toimi samoin Windsurfissa:** unohda vanha `.windsurfrules` ja käytä uutta `.windsurf/rules/`-hakemistoa vain silloin, kun tarvitset sen syntaksille tarkoitettuja malleja.
Tällä tavalla saat 80 % hyödystä 20 %:lla työstä. Kokemukseni mukaan useamman kuin kahden totuuden lähteen (yhteiset säännöt ja Claude-kohtaiset säännöt) ylläpito muuttuu hankalaksi, kun järjestelin eri työkalujen käyttäjiä ”Antigravity”-projektissa. Jos joku tiimissä lisää säännön `.cursorrules`-tiedostoon ja unohtaa `AGENTS.md`-tiedoston, Cursor ja Codex ovat viikon päästä eri mieltä.
## Miten Claude Coden /init ottaa olemassa olevan AGENTS.md-tiedoston huomioon?
Keskeinen huomio
`/init` muodostaa `CLAUDE.md`-tiedoston repositoryssa jo olevien tietojen pohjalta ja säästää 20–30 minuuttia käsityötä. Oletuksena se ottaa mukaan Cursor-säännöt (`.cursor/rules/`, `.cursorrules`) ja Copilot-säännöt (`.github/copilot-instructions.md`), kun taas `AGENTS.md`, `.windsurfrules` ja `.clinerules` luetaan tilassa `CLAUDE_CODE_NEW_INIT=1`. Tämä sama tila käynnistää vuorovaikutteisen monivaiheisen työnkulun: se esittää kysymyksiä, tutkii koodia aliagentin avulla ja ehdottaa suunnitelmaa ennen kirjoittamista. Syyskuusta 2026 lähtien `/init`-komennolla on haittapuoli projekteissa, joissa on `AGENTS.md`: uusi `CLAUDE.md` estää `AGENTS.md`-tiedoston suoran lukemisen, jolloin säännöt päätyvät kahteen tiedostoon.
Anthropic kuvaa `/init`-komentoa dokumentaatiossaan näin:
/init-komennon suorittaminen lukee muiden työkalujen ohjetiedostot ja siirtää olennaiset osat luotuun CLAUDE.md-tiedostoon: Cursor-säännöt hakemistoista .cursor/rules/ tai tiedostosta .cursorrules, Copilot-säännöt tiedostosta .github/copilot-instructions.md ja, kun käytössä on CLAUDE_CODE_NEW_INIT=1, lisäksi AGENTS.md, .devin/rules/, .windsurf/rules/ tai .windsurfrules sekä .clinerules.
— Anthropic, https://code.claude.com/docs/en/memory
Mitä tämä tarkoittaa käytännössä? Kuvaamassani repositoryssa oli Cursorin kokeilusta jäänyt `.cursorrules` (noin 80 riviä) ja `AGENTS.md` (120 riviä, koottu käsin). Kun suoritin `claude /init` -komennon, se otti molemmat tiedostot, poisti samankaltaisten sääntöjen toistot ja kokosi siistin `CLAUDE.md`-tiedoston minuutissa. Tarkistin sen jälkeen tiedoston ja tein pieniä muokkauksia – poistin vanhentuneita kohtia ja lisäsin otsikoilla jäsennellyn rakenteen. Se oli nopeampaa kuin kaiken kirjoittaminen uudestaan alusta.
Vuorovaikutteinen tila, jossa `/init` lukee myös `AGENTS.md`-tiedoston, otetaan käyttöön ympäristömuuttujalla:
```bash
CLAUDE_CODE_NEW_INIT=1 claude
```
Kun `/init` käynnistyy, Claude esittää joukon tarkentavia kysymyksiä: mitä artefakteja määritetään (`CLAUDE.md`, skills, hooks), mitä teknologiapinoa projekti käyttää ja mitä komentoja testeissä käytetään. Sitten aliagentti tutkii koodikantaa – lukee `package.json`-, `README.md`- ja määritystiedostoja – ja täydentää puuttuvat osat. Lopuksi se näyttää ehdotuksen, jota voit muokata ennen tallentamista. Lue lisää Claude Coden määrittämisestä projektin alussa [erillisestä oppaasta](https://ailoot.ai/blog/fi/spec-kit-claude-code-spec-driven-development/).
Sitten huonot puolet. Jos projektissa on jo aktiivinen `AGENTS.md`, `/init` luo sen rinnalle `CLAUDE.md`-tiedoston, joka sisältää kopion sen säännöistä. Sen jälkeen Claude Code lukee oletuksena vain `CLAUDE.md`-tiedoston, jolloin totuuden lähteitä on taas kaksi: sinä päivität `AGENTS.md`-tiedostoa, mutta Claude jatkaa työskentelyä vanhan kopion pohjalta. `/import`-komento tekee jotain samankaltaista: se lisää `CLAUDE.md`-tiedostoon kertaluonteisen kopion `AGENTS.md`-tiedostosta. Säilytä yksi totuuden lähde lisäämällä `@AGENTS.md`-tuonti `CLAUDE.md`-tiedoston ensimmäiseksi riviksi `/init`-komennon jälkeen ja poistamalla `CLAUDE.md`-tiedostosta kaikki, mikä toistaa `AGENTS.md`-tiedoston sisältöä.
`/init` on hyvä lähtökohta uudelle projektille tai projektille, jonka siirrät Cursorista tai Copilotista. ”Parasta CLAUDE.md-mallia” ei tarvitse etsiä verkosta – Anthropic huomioi jo repositoryn sisällön. Jos projektissa on jo aktiivinen `AGENTS.md` eikä Claude-kohtaisia sääntöjä ole, `/init` on tarpeeton: Claude Code lukee `AGENTS.md`-tiedoston itse.
## Miten erotat yhteiset ja Claude-kohtaiset ohjeet toisistaan?
Keskeinen huomio
Sijoita kaikkien AI-agenttien ymmärrettävät säännöt tiedostoon `AGENTS.md`: mihin ei saa koskea, miten haarat nimetään, että `.env` sisältää salaisuuden ja mitä komentoja testeissä käytetään. Sijoita Claude Codea koskevat säännöt tiedostoon `CLAUDE.md` (tuonnin alle): plan mode, skills, hooks, skill-viittaukset ja mallinimet version mukaan. Ero on yksinkertainen: jos sääntö alkaa sanoilla ”Clauden pitäisi”, sen paikka on `CLAUDE.md`-tiedostossa. Jos se alkaa sanoilla ”työkalun pitäisi”, sen paikka on `AGENTS.md`-tiedostossa.
Erottelen ne tämän periaatteen mukaan. Yhteiset säännöt, jotka kuuluvat tiedostoon `AGENTS.md`:
- **Mihin koodissa ei saa koskea.** Hakemistot `.env`, `node_modules`, `prisma/migrations` (vain komennolla `prisma migrate`), `.next/`, `.git/`.
- **Miten asiat nimetään.** Haarat: `feat/`, `fix/`, `chore/`. Commitit: etuliitteet `feat:`, `fix:`, `docs:` sekä lyhyt kuvaus. Komponenttitiedostojen nimet `kebab-case`-muodossa.
- **Testi- ja lint-komennot.** `npm run build`, `npm run lint`, `npm test`. Komento, joka suoritetaan ennen `git push` -komentoa.
- **Arkkitehtuuriperiaatteet.** Mitä sijoitetaan hakemistoon `src/lib/`, mitä hakemistoon `src/components/`, missä liiketoimintalogiikka on ja missä käyttöliittymä sijaitsee.
- **Tietoturva.** Älä koskaan commitoi salaisuuksia. Käytä tuotantotietokantaa vain komennon `prod-psql` kautta. Käytä tuotantoympäristöön yhdistämisessä SSH:ta vain aliasin `prod` kautta, älä osoitetta `root@IP`.
Claude-kohtaiset säännöt, jotka kuuluvat tiedostoon `CLAUDE.md` (`@AGENTS.md`-tuonnin alle):
- **Plan mode.** Käytä `plan modea` muutoksiin riskialttiissa hakemistoissa (esimerkiksi `src/billing/`).
- **Vaativuustaso.** Käytä arkkitehtuuritehtävissä asetusta `--effort high` ja rutiinityössä asetusta `medium`.
- **Skills.** Mitä AI-agentteja ja skills-ominaisuuksia käytetään eri tilanteissa. Esimerkiksi: ”käytä opasta työstäessä skill-ominaisuutta `build-masterskaya-guide`”.
- **Claude-muisti.** Mitä tallennetaan automaattiseen muistiin ja mitä `CLAUDE.local.md`-tiedostoon. Lisätietoja Claude-muistista on [Memory- ja CLAUDE.md-oppaassa](https://ailoot.ai/blog/fi/claude-memory-claude-md-auto-memory/).
- **Hooks.** Jos `.claude/settings.json`-tiedostossa on hookeja, kuvaile `CLAUDE.md`-tiedostossa, mitä ne tekevät (Codex ja Cursor eivät tunne niitä, eikä niiden tarvitsekaan).
- **Skills ja komennot.** Luettelo usein käyttämistäni kauttaviivakomennoista (`/init`, `/cd`, `/memory`, `/plan`).
Raja ei ole aina selvä. Esimerkiksi ”älä koskaan suorita `git push --force` -komentoa haaraan `main`” on selvästi yhteinen sääntö, joten se kuuluu tiedostoon `AGENTS.md`. Mutta ”käytä plan modea, kun suoritat `git push` -komennon hot-haaraan” koskee vain Claude Codea, joten se kuuluu tiedostoon `CLAUDE.md`. Testaa asia kysymällä: ”Jos poistaisin Claude Coden huomenna ja pitäisin vain Codexin, olisiko tämä sääntö edelleen voimassa?” Jos olisi, sijoita se tiedostoon `AGENTS.md`. Jos ei, sijoita se tiedostoon `CLAUDE.md`.
## Mitkä säännöt kuuluvat AGENTS.md-tiedostoon ja mitkä CLAUDE.md-tiedostoon tai .claude/rules-hakemistoon?
Keskeinen huomio
Suuressa projektissa yksi `AGENTS.md` ei riitä – se kasvaa liian suureksi, ja jokainen agentti saa kontekstiinsa tarpeetonta sisältöä. Ratkaisu on `.claude/rules/`-hakemisto, jossa on erilliset tiedostot aiheittain sekä YAML-etumääre `paths:` polkupohjaisia käynnistimiä varten. Esimerkiksi API-sääntö pätee vain, kun Claude työskentelee hakemistossa `src/api/`. Tämä säästää paljon konteksti-ikkunan tilaa. Cursorin vastaava hakemisto on `.cursor/rules/` ja Windsurfin `.windsurf/rules/`.
Jos sääntöjä on yli 200 riviä, ne kannattaa jakaa. Anthropicin dokumentaatio suosittelee tavoittelemaan 200 riviä tiedostoa kohden, koska pitkien `CLAUDE.md`-tiedostojen noudattaminen alkaa jäädä huomaamatta heikommaksi: Claude näyttää lukevan niitä, mutta noudattaa niitä harvemmin.
Minulle toimiva suuren projektin rakenne:
```
my-project/
├── AGENTS.md # 100-150 lines, shared
├── CLAUDE.md # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
├── CLAUDE.md # alternative to root file, same file
└── rules/
├── api.md # with paths: ['src/api/**']
├── components.md # with paths: ['src/components/**']
├── testing.md # without paths, always active
└── security.md # without paths, always active
```
Jokaisessa `.claude/rules/`-hakemiston tiedostossa voi olla etumääre:
```markdown
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required
```
Claude lataa nämä säännöt vain, kun se käsittelee tiedostoja, jotka vastaavat tätä mallia. Jos se muokkaa tiedostoa `src/components/Button.tsx`, API-sääntöjä ei lisätä kontekstiin. Näin konteksti-ikkunassa käytetään tilaa vain olennaiseen. `.claude/rules/`-hakemisto toimii myös ilman `CLAUDE.md`-tiedostoa: jos projekti sisältää vain `AGENTS.md`-tiedoston, sen säännöt ladataan sen rinnalla, eikä tämä estä `AGENTS.md`-tiedoston lukemista suoraan.
Cursor ja Windsurf tukevat samaa lähestymistapaa hakemistojen `.cursor/rules/` ja `.windsurf/rules/` kautta. AGENTS.md-standardi voi viitata näihin hakemistoihin, mutta eri työkalujen syntaksit eivät ole vielä täysin vakiintuneet. On turvallisempaa pitää yhteiset säännöt tiedostossa `AGENTS.md` ja kopioida polkukohtaiset säännöt hakemistoihin `.claude/rules/` ja `.cursor/rules/` – nämä ovat harvinaisia erityistapauksia, eivät sääntöjen pääosa.
Hyödylliset CLAUDE.md-tiedoston sijainnit laajimmasta suppeimpaan:
| Taso | Sijainti | Tarkoitus |
|----|----|----|
| **Hallittu käytäntö** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Yrityssäännöt, IT/DevOps |
| **Käyttäjä** | `~/.claude/CLAUDE.md` | Henkilökohtaiset asetukset kaikissa projekteissa |
| **Projekti** | `./CLAUDE.md` tai `./.claude/CLAUDE.md` | Projektitiimin säännöt |
| **Paikallinen** | `./CLAUDE.local.md` (`.gitignore`-tiedostossa) | Henkilökohtaiset asetukset tiettyä projektia varten |
Esimerkki `~/.claude/CLAUDE.md`-tiedostosta voisi sisältää kaksi sääntöä: ”vastaa käyttäjän haluamalla kielellä” ja ”kirjoita Ailoot täsmälleen näin”. Nämä säännöt pätevät joka projektissa, joten niitä ei tarvitse kopioida jokaiseen repositoryyn.
Näistä neljästä tasosta vain projektitason `CLAUDE.md` ja `CLAUDE.local.md` estävät `AGENTS.md`-tiedoston lukemisen suoraan. Henkilökohtainen `~/.claude/CLAUDE.md` ja hallittu käytäntö eivät estä sitä; Claude Code lukee ne `AGENTS.md`-tiedoston rinnalla.
## Mitä tehdä, jos AGENTS.md on projektissasi jo vanhentunut?
Keskeinen huomio
Jos `AGENTS.md` koottiin jo vuonna 2025 Codexia tai Aideria varten eikä sitä ole sen jälkeen muokattu, avaa projekti Claude Codessa ja pyydä Claudea muokkaamaan tiedostoa. AGENTS.md on elävä dokumentti; Linux Foundationin määritystä päivitetään. Tärkein sääntö sen pitämiseksi ajan tasalla: jokaisen säännön on vastattava kysymykseen ”Mitä olen kyllästynyt toistamaan Claudelle/Codexille?” Jos se ei vastaa tähän, arkistoi sääntö.
Kuvaamassani projektissa minulla oli toukokuulta 2025 peräisin oleva `AGENTS.md` – 180 riviä, joista moni oli vanhentunut (se mainitsi sittemmin muuttuneita Anthropicin API-päätepisteitä, esimerkkejä syntaksista `claude --tools`, jota ei enää ole, sekä vanhentuneeseen rakenteeseen perustuvia sääntöjä hakemistosta `~/.claude/projects/`).
Käyttämäni päivityssuunnitelma:
1. **Tarkista se `claudella` plan modessa.** Avasin repositoryn, suoritin `claude --safe-mode` ja kysyin: ”Lue `AGENTS.md` uudelleen ja ehdota luetteloa vanhentuneista tai toistuvista kohdista. Älä muokkaa sitä; luettele vain kohdat.” Sain kahdessa minuutissa luettelon 23 tarkistettavasta kohdasta.
2. **Poista selvästi vanhentuneet kohdat.** Näistä 23 kohdasta 9 oli selvästi vanhentuneita – komentojen syntaksi, päätepisteet ja lippujen nimet. Poistin nämä rivit.
3. **Yhdistä päällekkäisyydet.** Toiset 6 kohtaa toistivat saman asian eri sanoin (”älä tee force-pushia”, ”älä koskaan käytä `--force`-valitsinta”, ”vältä komentoa `git push -f`”). Yhdistin ne yhdeksi riviksi.
4. **Lisää uusia kohtia.** Lisäsin asioita, jotka olin huomannut Clauden/Codexin tekevän säännöllisesti väärin viimeisen kuukauden aikana periaatteella ”yksi rivi kutakin virhetyyppiä kohti”. Uusia kohtia tuli 8.
5. **Pyydä aliagenttia tarkistamaan lopputulos.** Pyysin Claudea tarkistamaan tiedoston ja ”etsimään ristiriitoja, epäselvyyksiä ja päällekkäisyyksiä”. Se löysi kolme kohtaa, joiden muotoilua olisi voinut selkeyttää. Korjasin ne.
Tunnin kuluttua `AGENTS.md` oli 110-rivinen ja ajan tasalla, ja tunsin kaikki rivit. Sen pohjalta oli helppo laatia 30-rivinen `CLAUDE.md`. Myös Codexista tuli sen jälkeen selvästi huolellisempi testien suhteen – epäilen, että osa sen ”oudoista” ratkaisuista johtui vanhentuneista ohjeista, joita se oli hyvää tarkoittaen noudattanut.
Elävän `AGENTS.md`-tiedoston pääperiaatteet:
- **Jokainen sääntö vastaa toistuvaan virheeseen.** Jos yksikään tilanne ei saanut minua kuukauden aikana muistamaan jotakin sääntöä, sitä ei kannata säilyttää.
- **Kirjoita käskyjä, älä teoriaa.** ”Käytä kahta välilyöntiä” on sääntö. ”Koodityylin pitäisi olla siisti” ei ole.
- **Täsmällisyys voittaa yleisluontoisuuden.** ”Suorita `npm run build` ennen `git push` -komentoa” on sääntö. ”Testaa muutokset” ei ole.
## Mikä tässä kokoonpanossa EI varmasti toimi?
Keskeinen huomio
`@AGENTS.md`-tiedoston tuonti ei saa eri työkaluja käyttäytymään samalla tavalla. Jokaisella on omat erikoisuutensa: Codex CLI ei tunne `.claude/rules/`-hakemistoa eikä hookeja. Cursorilla on oma automaattisen täydennyksen moottori, joka ei lue CLAUDE.md-tiedostoa tekstiä täydentäessään. Copilot noudattaa tiedostoa `.github/copilot-instructions.md`, eivätkä pelkästään AGENTS.md-tiedoston säännöt riitä sille. Kyse ei ole siitä, että ”yksi tiedosto = yksi toimintatapa”, vaan siitä, että ”yksi lähde perussäännöille ja sen jälkeen kunkin työkalun omat lisäykset”.
Muutamia asioita, jotka opin kantapään kautta työskenneltyäni tämän kokoonpanon kanssa kuusi kuukautta:
**1. Cursorin automaattinen täydennys ei käytä AGENTS.md-tiedostoa.** Kun Cursor ehdottaa editorissa rivin täydentämistä, se ei lue `AGENTS.md`-tiedostoa reaaliajassa – taustalla toimii erillinen nopea moottori. AGENTS.md-tiedoston säännöillä on merkitystä vain silloin, kun lähetät chat-pyynnön Cursorissa. Siksi AGENTS.md-tiedostoon kirjoitettu sääntö ”älä käytä `var`-muuttujaa, käytä `const`-muuttujaa” ei vaikuta automaattiseen täydennykseen; tämä pitää määrittää ESLintin tai TypeScript-asetusten avulla.
**2. Claude Code -hookit AGENTS.md-tiedostossa eivät toimi Codexille.** Jos `.claude/settings.json`-tiedostossa on PreToolUse-hook, joka on määritetty estämään jokin toiminto, tieto on hyödyllinen vain Claudelle. Codex ei tunne hookeja; sen näkökulmasta ”työkalu päättää itse”. Kannattaa kirjoittaa `AGENTS.md`-tiedostoon ”älä tee X” ja tuonnin alle `CLAUDE.md`-tiedostoon ”hook estää X:n fyysisesti”.
**3. Copilot ja `.github/copilot-instructions.md`.** GitHub Copilot lukee omaa tiedostoaan eikä edelleenkään lue AGENTS.md-tiedostoa kovin hyvin. Jos tiimisi käyttää Copilotia aktiivisesti, lisää erillinen `.github/copilot-instructions.md`, jossa on lyhennetty versio säännöistä, tai käytä [Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions) -laajennuksia, jotka tuntevat AGENTS.md-tiedoston. Tilanne muuttuu nopeasti, joten kuva voi olla erilainen kolmen tai kuuden kuukauden päästä.
**4. Git ei seuraa symbolista linkkiä CLAUDE.md-muutoksena.** Jos suoritat `ln -s AGENTS.md CLAUDE.md` ja päivität `AGENTS.md`-tiedoston viikon päästä, Git näyttää diffissä vain `AGENTS.md`-tiedoston muutokset. Se on normaalia, mutta PR:ää tarkistava kollega ei ehkä huomaa, että myös `CLAUDE.md` on päivittynyt (symbolisen linkin kautta). Ratkaisu: kirjoita PR-kuvaukseen nimenomaisesti: ”päivitin `AGENTS.md`-tiedoston; Claude Code näkee saman tiedoston symbolisen linkin kautta”.
**5. Syviä tuontiketjuja on vaikea jäljittää.** Jos `AGENTS.md` tuo tiedoston `@docs/coding-style.md`, joka tuo tiedoston `@docs/typescript.md`, ja jokin sääntö on ristiriidassa toisen kanssa, ongelman jäljittäminen on vaikeaa. Rajoitan tuonnit yhteen tasoon (`CLAUDE.md` → `AGENTS.md`) enkä sisäkkäistä niitä syvemmälle. Anthropic tarjoaa `InstructionsLoaded`-hookin, joka kirjaa, mitkä tiedostot ladattiin – se auttaa kerroksittaisten kokoonpanojen virheiden jäljittämisessä. Huomautus: hook käynnistyy `AGENTS.md`-tiedostolle, joka sisältyy tuonnin tai symbolisen linkin kautta, mutta ei tiedostolle, jonka Claude Code luki itse.
### Lähteet
- [Claude Code -muistidokumentaatio – AGENTS.md-osio](https://code.claude.com/docs/en/memory#agents-md) – milloin Claude Code lukee AGENTS.md-tiedoston itse, Project instructions -asetukset, tuonnit ja symboliset linkit sekä `/init`-toiminta.
- [Claude Code -muistidokumentaatio – lisätiedostojen tuonti](https://code.claude.com/docs/en/memory#import-additional-files) – `@path/to/file`-syntaksi, neljän tason syvyys sekä suhteelliset ja absoluuttiset polut.
- [agents.md – Linux Foundationin standardi](https://agents.md/) – virallinen AGENTS.md-standardi ja luettelo sitä tukevista työkaluista.
- [Cursor Rules -dokumentaatio](https://docs.cursor.com/context/rules-for-ai) – mitä Cursor lukee (`.cursor/rules/*.mdc`, AGENTS.md).
- [GitHub Copilotin mukautetut ohjeet](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) – `.github/copilot-instructions.md`-tiedoston muoto.
- [AGENTS.md-määritys Linux Foundationin sivustolla](https://aaif.io/projects/agents-md/) – jatkuvasti kehittyvä määritys.
Kattava vibe-koodauksen kokoonpano illaksi: **AI-klooni + Second Brain + kontekstisuunnittelu**.
Tutustu [Ailootiin](https://ailoot.ai/).
## Kysymyksiä tästä oppaasta: Yksi ohjetiedosto Claude Codelle, Codexille ja Cursorille vuonna 2026
### Milloin @AGENTS.md-tuonti on symlinkkiä parempi?
Lisää @AGENTS.md CLAUDE.md-tiedostoon, jos tarvitset yhteisten ohjeiden lisäksi Claude-kohtaisia ohjeita tai tiimissä käytetään Windowsia. Symlinkki jakaa saman sisällön eikä mahdollista erillistä Claude-kohtaista osiota.
### Miten varmistan yhteisten ohjeiden latautumisen?
Katso /memory-komennolla luetellut tiedostot. Jos CLAUDE.md tai CLAUDE.local.md estää AGENTS.md:n suoran löytymisen, lisää tuonti tai asetus molempien lataamiseen ja tarkista tulos uudessa istunnossa.
## Ailoot · Yritys ja sen projektisalkku
Ailoot perustuu kertyneeseen toimintakokemukseen, laajaan asiakaskuntaan, vakaaseen palveluun ja jatkuvaan KPI-seurantaan.
Yritys ja sen projektisalkku: miljoonia asiakkaita; kuukausittainen myynti miljardiluokassa.
Ailoot hyödyntää tätä toimintakokemusta tarjotessaan API-yhteyden tekoälytoimintoihin asiakkaiden tuotteissa, agenteissa, sovelluksissa ja automaatioissa.