Yksi ohjetiedosto Claude Codelle, Codexille ja Cursorille vuonna 2026

Lisätietoja palvelusta on Ailoot-dokumentaatiossa.

Mikä muuttuu, kun käytät Claude Codea, Codexia ja Cursoria yhdessä?#

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.

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

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:

Se, mitä Claude Code tarkalleen lukee, riippuu projektissa olevista tiedostoista:

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:

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

Virallisen dokumentaation minimaalinen toimiva esimerkki:

@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:

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

Dokumentaatiossa symbolinen linkki esitetään näin:

ln -s AGENTS.md CLAUDE.md

Ja heti sen jälkeen annetaan suora varoitus Windowsista:

Vertailutaulukko:

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.

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

Yleiskuva seitsemästä tärkeimmästä työkalusta (perustuu kunkin työkalun viralliseen dokumentaatioon):

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

Anthropic kuvaa /init-komentoa dokumentaatiossaan näin:

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:

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.

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

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

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:

---
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:

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

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

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

Kattava vibe-koodauksen kokoonpano illaksi: AI-klooni + Second Brain + kontekstisuunnittelu.

Tutustu Ailootiin.