Mikä AGENTS.md on ja miten kirjoitat oman tiedostosi 30 minuutissa

Käytännön materiaalia vibe codingista ja agenttien kanssa työskentelystä: Ailoot-dokumentaatio.

AGENTS.md yhdessä kappaleessa#

Seuraavassa tiedostomuotoa tarkastellaan agents.md-sivuston, OpenAI Codexin dokumentaation, JetBrains Junien, Cursor Rules Docsin, GitHub Copilot Coding Agentin muutoslokin sekä Linux Foundationin Agentic AI Foundationia koskevan lehdistötiedotteen pohjalta. Kaikki luvut ja ominaisuudet ovat tilanteen mukaisia 30. toukokuuta 2026, ja Claude Coden AGENTS.md-tukea käsitellään Anthropicin dokumentaation sekä 24. syyskuuta 2026 tehdyn päivityksen perusteella.

Jos et tiedä, mitä tämä markkinoiden työkalusirkus on tai miksi ne tarvitsevat yhteisen tiedoston, lue ensin opas ”Millä koodata vuonna 2026: 8 AI-työkalua Claude Codesta Antigravityyn”. Tämä artikkeli keskittyy nimenomaan AGENTS.md-tiedostomuotoon ja siihen, miten kirjoitat oman tiedostosi 30 minuutissa.

Mikä AGENTS.md on ja mistä se sai alkunsa?#

Aiemmin jokaisella AI-työkalulla oli oma sääntötiedostonsa: Anthropicilla oli CLAUDE.md, Cursorilla .cursorrules, GitHubilla .github/copilot-instructions.md, Aiderilla .aider.conf.yml ja JetBrainsilla .junie/guidelines.md. Jos tiimilläsi oli kolme eri agenttia, se tarkoitti kolmea rinnakkaista tiedostoa, joissa oli sama sisältö ja jotka alkoivat erota toisistaan viikon kuluessa.

OpenAI kyllästyi tähän ensimmäisenä. Elokuussa 2025 se julkaisi Codex CLI:n ja käynnisti samalla avoimen agents.md-tiedostomuodon. Sivustolta:

”Ajattele AGENTS.md-tiedostoa agenttien README-tiedostona.”

(agents.md, käännetty englannista)

Pääasia on, että AGENTS.md täydentää README-tiedostoa. README on kirjoitettu ihmisille: ”mikä projekti on, miten sitä ajetaan paikallisesti ja miten siihen voi osallistua”. AGENTS.md on kirjoitettu agentille: tarkat komentotulkin komennot, todennettavat ”valmis”-kriteerit ja rajat, kuten ”älä koske tähän koskaan”.

Sivustolta:

”AGENTS.md täydentää README-tiedostoa: se sisältää lisäkontekstia, joskus yksityiskohtaista, jota agentti tarvitsee – rakennusvaiheet, testit ja käytännöt, jotka kuormittaisivat README-tiedostoa tai joita ihmiskäyttäjät eivät yksinkertaisesti tarvitse.”

(agents.md, käännetty englannista)

Syyskuuhun 2025 mennessä GitHub Copilot Coding Agent tuki tiedostomuotoa (muutosloki, 28.08.2025). Joulukuuhun mennessä Cursor, Junie, Gemini CLI, Aider ja tusina muuta työkalua olivat liittyneet mukaan. Joulukuun 9. päivänä 2025 Linux Foundation perusti Agentic AI Foundationin (AAIF): sen kolme perustajaprojektia olivat OpenAI:n AGENTS.md, Anthropicin MCP ja Blockin goose. Perustajajäseniä olivat AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft ja OpenAI. Helmikuun 24. päivään 2026 mennessä säätiöön kuului jo 146 organisaatiota, muun muassa Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath ja Hitachi.

Sen jälkeen AGENTS.md lakkasi olemasta ”taas yksi OpenAI:n juttu” ja siitä tuli de facto -standardi.

Mitkä AI-agentit lukevat AGENTS.md-tiedoston ja mitkä eivät?#

Tukitaulukko 30. toukokuuta 2026 tilanteen mukaan; Claude Codea koskeva rivi päivitettiin 24. syyskuuta 2026:

Anthropic liittyi mukaan suurista toimijoista viimeisenä. Elokuussa 2025 virallisessa anthropics/claude-code-repositoriossa avattiin issue #6235, jossa pyydettiin AGENTS.md-tukea.

Issue pysyi avoinna lähes vuoden ja suljettiin 17. elokuuta 2026; AGENTS.md-tukea sisältävä versio 2.1.277 julkaistiin 18. syyskuuta. Anthropicin toimintaperiaate on seuraava: CLAUDE.md on etusijalla, ja AGENTS.md luetaan, kun työkansiossa tai missään sen yläpuolisessa kansiossa ei ole CLAUDE.md-tiedostoa. Dokumentaation mukaan se toimii näin:

Tässä on yksi koukku: myös henkilökohtainen CLAUDE.local.md lasketaan mukaan, ja silloin Claude Code lakkaa lukemasta AGENTS.md-tiedostoa. Voit muuttaa tätä toimintaa kohdassa /config, Project instructions -asetuksissa – esimerkiksi niin, että Claude Code lukee molemmat tiedostot samalla kertaa. Versioissa, jotka ovat vanhempia kuin 2.1.277, AGENTS.md-tiedostoa ei löydetä automaattisesti; @AGENTS.md-rivi CLAUDE.md-tiedostossa toimii edelleen kiertotapana.

Miten AGENTS.md eroaa CLAUDE.md-tiedostosta ja .cursorrules-tiedostosta?#

Neljän tiedostomuodon vertailu 30. toukokuuta 2026 tilanteen mukaan:

Keskeinen ajatus: AGENTS.md voi sisältää yhteiset projektiohjeet, mutta kunkin ohjelman lataustapa ja henkilökohtaiset asetukset tarvitsevat silti erillisen määrityksen. Claude Codessa sitä varten on CLAUDE.local.md, ja Cursorissa on paikallisia .mdc-tiedostoja käyttäjän alla. Pelkkä AGENTS.md ei tarjoa tätä – sinun on joko yhdistettävä se muihin tiedostoihin tai sovittava tiiminä, että henkilökohtaiset säännöt kirjoitetaan gitin ohittamiin osioihin.

Toinen tärkeä yksityiskohta liittyy monorepoihin. Codex ja Cursor noudattavat sääntöä ”lähin AGENTS.md voittaa”:

”Monorepossa sijoita jokaiseen pakettiin oma AGENTS.md-tiedosto. Agentit lukevat automaattisesti lähimmän tiedoston hakemistopuusta, ja lähin voittaa.”

(agents.md, käännetty englannista)

agents.md mainitsee, että OpenAI:n päämonorepossa on 88 AGENTS.md-tiedostoa eri alipaketteja varten. Jos työskentelet monorepossa, jaa säännöt eri tasoille: yleiset säännöt juureen ja erityiset alikansioihin.

Mitä hyvän AGENTS.md-tiedoston pitäisi sisältää?#

agents.md-sivusto tarjoaa joustavan muodon – ”mitä tahansa Markdownia”. Silti 80% käytännössä hyvistä tiedostoista sisältää samat kahdeksan osiota. Pääsääntö: jokaisen kohdan pitäisi olla tarkka komento tai konkreettinen esimerkki. Agentti sivuuttaa abstraktin ajatuksen, kuten ”kirjoita siistiä koodia”.

1. Projektin yleiskuvaus – 2–3 riviä. Mikä projekti on, kenelle se on tarkoitettu ja mikä on sen päätavoite. Ei markkinointia. Esimerkki: ”Telegram-botti maksulliseen työpajaan perehdyttämiseen. Stack: Next.js 14, Prisma, PostgreSQL. Käynnistyy, kun purchases-tauluun tulee uusi tietue.”
2. Asennuskomennot – tarkat komentotulkin komennot paikallista käyttöä varten. npm install, npm run dev, npm run build. Ei ”näin meillä yleensä tehdään”.
3. Koodaustyyli / käytännöt – täsmällisiä sääntöjä esimerkin kanssa, ei ”kirjoita siististi”. Esimerkiksi: ”TypeScript strict, yksinkertaiset lainausmerkit, ei default exporteja, komponenttien nimet PascalCasella, hookien nimet alkavat use-sanalla.”
4. Kehitysympäristön vinkit – missä tärkeät asiat sijaitsevat. Mitä muuttujia .env tarvitsee, missä salaisuuksia säilytetään, mitkä portit ovat käytössä ja miten paikallisen DB:n kanssa työskennellään.
5. Testausohjeet – miten tietty testi ajetaan ja mikä lasketaan ”vihreäksi”. Esimerkiksi: npm test -- --testPathPattern=user-auth; odotuksena on 100% läpäisy.
6. PR- / commit-ohjeet – commit-viestien muoto, PR:ää edeltävä tarkistuslista (testit, linter, dokumentaatio) ja hyväksyjä.
7. Tietoturvaan liittyvät näkökohdat – mitä ei saa koskaan tapahtua. ”Älä koskaan commitoi .env-tiedostoa. Salaisuudet kuuluvat vain Vaultiin. Älä näytä käyttäjien henkilötietoja lokeissa.”
8. Rajat / Älä tee näin koskaan – kiellot ja niiden vaihtoehdot. ”Älä käytä git push --force -komentoa main-haarassa. Jos sinun täytyy perua muutoksia, käytä git revert- tai git reset-komentoa feature-haarassa.”

Käytä jokaisessa osiossa periaatetta ”komento ajatuksen sijaan”. Agentti sivuuttaa ohjeen ”ole varovainen migraatioiden kanssa”. Se noudattaa ohjetta ”Aja alembic check ennen alembic upgrade head -komentoa. Jos se ilmoittaa virheestä, älä suorita migraatiota vaan kysy minulta.”

Valmis AGENTS.md-mallipohja (kopioi ja mukauta)#

# AGENTS.md

## Projektin yleiskuvaus

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Asennuskomennot

```bash
# ensimmäinen asennus
npm install
cp .env.example .env  # täytä sitten käsin; katso alla oleva luettelo

# käynnistys
npm run dev           # kehityspalvelin portissa :3000
npm run build         # tuotantorakennus
npm run start         # suorita tuotantorakennus
```

## Kehitysympäristö

- Node 20+ (nvm:n kautta: `nvm use 20`)
- PostgreSQL 16 paikallisesti portissa :5432 (`docker-compose up postgres`)
- Redis on valinnainen, ja sitä tarvitaan vain jonoihin (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Älä koskaan lue koko `.env`-tiedostoa. Jos tarvitset yhden muuttujan: `grep "^VAR=" .env`

## Koodaustyyli

- TypeScript strict mode
- Yksinkertaiset lainausmerkit, ei puolipisteitä (ellei ESLint niitä vaadi)
- Importit: ensin ulkoiset, sitten sisäiset `@/`-polun kautta ja lopuksi suhteelliset
- Komponenttien nimet PascalCasella; hookien nimet alkavat `use`-sanalla
- Ei `any`-tyyppiä ilman nimenomaista kommenttia, jossa selitetään ”miksi sitä ei voi tyypittää”

Esimerkki hyvästä moduulista:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testaus

```bash
npm test                                # kaikki testit
npm test -- --testPathPattern=auth      # vain auth-testit
npm test -- --watch                     # watch-tila
```

Kaikkien testien on läpäistävä (oltava vihreitä) ennen committia. Jos testi on punainen, älä commitoi; kysy minulta, mitä tehdä.

## Pull request -ohjeet

- Commit-muoto: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Ennen PR:ää: `npm run build && npm test && npm run lint`
- PR-kuvaus = mitä muuttuu, miksi ja miten se testataan
- Älä hyväksy omaa PR:ääsi – odota aina ihmisen tekemää tarkistusta

## Tietoturva

- Salaisuudet vain `.env`-tiedostossa ja Vaultissa, ei koskaan koodissa
- Älä lokita henkilötietoja (sähköposti, puhelin, nimi)
- Käytä tuotantotietokannan kanssa työskennellessäsi vain lukukyselyitä, ellet ole saanut nimenomaista lupaa
- Älä kovakoodaa ulkoisten palveluiden API-avaimia (Stripe, OpenAI) testeihin

## Älä tee näin koskaan

- Älä käytä `git push --force` -komentoa main-haaraan. Jos sinun täytyy perua muutoksia, käytä `git revert` -komentoa tai avaa uusi PR
- Älä suorita tietokantamigraatioita ilman `alembic check` -komentoa (tai ORM:n vastaavaa komentoa)
- Älä käytä `npm install -g`- tai `sudo`-komentoa projektin riippuvuuksiin
- Älä lisää riippuvuuksia ilman hyväksyntää (etenkään raskaita, kuten webpack-pluginien tai ORM:n kaltaisia)

Mallipohjassa on keskimäärin 80–120 riviä. Jos tiedosto ylittää 150 riviä, se on merkki siitä, että rakenne kannattaa tarkistaa: siirrä jotain docs/-kansioon, linkitä sisältöön tai tiivistä se yhdeksi riviksi. Käytännössä 100–150-riviset tiedostot toimivat parhaiten; tämän jälkeen laatuhyödyt alkavat kääntyä laskuun.

Mitkä 5 sääntöä tekevät AGENTS.md-tiedostosta todella hyödyllisen?#

1. Komentoja ideoiden sijaan. Agentti ei ymmärrä ohjetta ”ole varovainen migraatioiden kanssa”. Se noudattaa komentoa alembic check ennen komentoa alembic upgrade head. Agentit toimivat komentojen ja ehtojen, eivät tunnelmien, mukaan. Muotoile kaikki keskeiset säännöt näin: ”tee X, muuten Y”.

2. Kielto ja vaihtoehto. Pelkkä ”älä tee force pushia” jää agentilta huomaamatta kahden tai kolmen promptin jälkeen. Ohje ”älä tee X:ää, vaan tee Y” toimii. Esimerkki: ”älä käytä git push --force -komentoa main-haarassa; jos sinun täytyy perua muutoksia, käytä git revert -komentoa tai avaa uusi PR.”

3. Täsmälleen yksi totuuden lähde. Juuren AGENTS.md on koko projektin totuuden lähde. Jos sinulla on monorepo, käytä sisäkkäisiä AGENTS.md-tiedostoja alikansioissa ja noudata sääntöä ”lähin voittaa”. Ei rinnakkaisia tiedostoja, joissa on ristiriitaisia ohjeita.

4. Todennettavat ”valmis”-kriteerit. ”Testien on läpäistävä” on hyödytön ohje. Tarkka kriteeri on: npm test palauttaa poistumiskoodin 0 eikä tulosta FAIL-tekstiä stdout-virtaan. ”Koodin pitää olla siistiä” on niin ikään hyödytöntä. Tarkka kriteeri on: npm run lint menee läpi ilman varoituksia. Agentti ymmärtää ”valmiin” vasta, kun kuvailet ehdon nimenomaisesti.

5. Alle 150-rivinen tiedosto. Yli 150 rivin jälkeen mittarit alkavat heikentyä: agentti käyttää enemmän kontekstia lukemiseen ja ohittaa tärkeitä sääntöjä. Jos sisältö ei mahdu, siirrä tiedot tiedostoon docs/architecture.md ja linkitä siihen AGENTS.md-tiedostosta, jotta jäljelle jäävät vain komennot ja rajat.

Mitkä 10 virhettä tekevät AGENTS.md-tiedostosta roskaa?#

1. Epämääräiset säännöt ilman komentoja. Agentti sivuuttaa ohjeen ”ole varovainen migraatioiden kanssa” – lause on sille tyhjä. Vain täsmällinen komento ja siihen liittyvä ehto toimivat: ”Aja alembic check ennen alembic upgrade head -komentoa. Jos löytyy virhe, älä suorita migraatiota vaan kysy minulta.”

2. ”Siisti koodi.” Hyödytön ilmaus. Korvaa se täsmällisellä mallilla: ”Käytä funktiokomponentteja ja hookeja. Esimerkki: function LoginForm() { const [email, setEmail] = useState(''); ... }”

3. Jäsentymätön proosa. Jos AGENTS.md sisältää 300 riviä proosaa ilman otsikoita, agentti käyttää 80K kontekstitokenia epäolennaisten kohtien lukemiseen ja ohittaa tärkeät asiat. Käytä H2/H3-otsikoita, lyhyitä osioita ja luetteloita.

4. Yli 150-rivinen tiedosto. Laatua kuvaavat mittarit heikkenevät tämän rajan jälkeen. Jaa sisältö päätiedostoon ja linkkeihin docs/-kansion yksityiskohtiin.

5. Yli 30 kieltoa ilman vaihtoehtoja. Jos tiedostossa on pitkä luettelo ”älä tee X:ää, älä tee Y:tä” selittämättä, mitä sen sijaan pitäisi tehdä, agentti hapuilee pimeässä.

6. README.md:n sisällön toistaminen. Jos olet jo kirjoittanut README-tiedostoon ”näin asennat ja käynnistät”, älä kopioi sitä AGENTS.md-tiedostoon. Viittaa sen sijaan README-tiedostoon yhdellä rivillä ja kuvaile AGENTS.md:ssä asiat, joita agentti tarvitsee mutta joita ihmiskäyttäjät eivät tarvitse.

7. Kovakoodatut salaisuudet. AGENTS.md voi olla julkinen (se on gitissä). Älä laita siihen oikeita API-avaimia, tokeneita tai salasanoja. Lisää vain viittauksia salaisuuksien säilytyspaikkoihin: ”Katso Vault: secret/staging/db.”

8. Ristiriitaiset prioriteetit ilman järjestystä. ”Etene nopeasti” + ”pidä testikattavuus 90%:ssa” jättää agentin epävarmaksi siitä, mitä sen pitäisi valita. Aseta prioriteetit selvästi: ”Testikattavuus ≥80% ensin, sitten nopeus. Jos ne ovat ristiriidassa, testit menevät nopeuden edelle.”

9. Vanhentunut dokumentaatio. Arkkitehtuurikuvaus kertoo REST+pollingista, vaikka todellisuudessa käytössä ovat jo WebSocketsit. Agentti seuraa vanhentunutta kuvausta ja rikkoo arkkitehtuurin. Sääntö: päivitä AGENTS.md samaan PR:ään koodimuutoksen kanssa aina, kun arkkitehtuuri muuttuu.

10. Liiallinen arkkitehtuuri yksinkertaiseen tehtävään. Jos joku pyysi muuttamaan kahta riviä konfiguraatiossa, agentin ei pitäisi joutua lukemaan 14 mikropalvelun koko topologiaa. Siirrä ”syvällinen” arkkitehtuurikuvaus tiedostoon docs/architecture.md; jätä AGENTS.md-tiedostoon vain ohje ”jos tehtävä koskee arkkitehtuuria, lue docs/architecture.md”.

Yli 2 500 AGENTS.md-repositoriota kattavan GitHub Blogin tutkimuksen pääjohtopäätös on:

”Useimmat agenttitiedostot epäonnistuvat, koska ne ovat liian yleisluontoisia. ’You are a helpful coding assistant’ ei toimi.”

(GitHub Blog, käännetty englannista)

Miten pidät AGENTS.md- ja CLAUDE.md-tiedostot samassa repositoriossa?#

Käytännössä tärkein kysymys on, miten molempia tiedostoja voi käyttää sisältöä kopioimatta. Kolme tilannetta:

Tilanne 1: Vain Claude Code. Säilytä CLAUDE.md ja hyödynnä kaikkia Claude Coden ominaisuuksia: ~/.claude/CLAUDE.md käyttäjätason ohjeille, CLAUDE.md projektille, CLAUDE.local.md henkilökohtaisille yliajoille, @import muiden tiedostojen sisällyttämiseen ja .claude/skills/ erikoistuneille taidoille. AGENTS.md:tä ei tarvita.

Tilanne 2: Useita koodausohjelmia. Säilytä yhteiset säännöt AGENTS.md:ssä ja kytke sekä tarkista jokainen ohjelma erikseen. Gemini CLI tukee määritettävää kontekstitiedoston nimeä; Aider voi ladata tiedoston lukuasetuksensa kautta. Nämä ovat erikseen määritettyjä lataustapoja, eivät yhtenäistä automaattista löytämistä.

Aloita uusi istunto vaarattomassa testirepositoriossa. Lisää yksilöllinen vaaraton ohje, esimerkiksi ”sisällytä testivastaukseen merkki instructions-loaded”, ja tarkista vastauksen lisäksi ohjelman dokumentoitu ladattujen tiedostojen näkymä tai lokit. Toista jokaiselle käyttämällesi ohjelmalle ja versiolle. Mallin oma väite tiedoston lukemisesta ei ole riippumaton todiste lataamisesta; yhden onnistuneen tarkistuksen perusteella ei voi päätellä muiden työkalujen tukea.

Tilanne 3: Sekatiimi (Claude Code + muut). Tämä on yleisin kokoonpano vuonna 2026. Ratkaisu on tehdä AGENTS.md:stä ensisijainen. Jos sinulla ei ole vain Claude Codea koskevia sääntöjä, älä luo CLAUDE.md-tiedostoa lainkaan: versiosta 2.1.277 alkaen Claude Code lukee AGENTS.md-tiedoston, jos projektissa ei ole CLAUDE.md:tä. Jos tällaisia sääntöjä on, tee CLAUDE.md-tiedostosta joko symbolinen linkki tai lyhyt kääretiedosto, joka sisältää @AGENTS.md-tuonnin.

Tarkista ja varmuuskopioi molemmat tiedostot ennen muutoksia. Jos molemmat ovat olemassa, yhdistä ristiriidattomat yhteiset ohjeet AGENTS.md:hen ja säilytä Claude-kohtaiset ohjeet CLAUDE.md:ssä @AGENTS.md-tuonnilla. Säilytä olemassa olevat symboliset linkit korvaamatta niitä.

Tavalliselle CLAUDE.md-tiedostolle vain AGENTS.md:n puuttuessa tämä macOS/Linux-komentotulkin tarkistus kieltäytyy ylikirjoittamasta kohdetta tai sen olemassa olevaa symbolista linkkiä:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Onnistuneen uudelleennimeämisen jälkeen CLAUDE.md on symbolinen linkki AGENTS.md:hen. Kaikki AGENTS.md:tä lukevat agentit näkevät saman sisällön. Claude Code, joka lukee CLAUDE.md-tiedostoa, näkee saman sisällön symbolisen linkin kautta.

Windowsissa symbolisen linkin luominen edellyttää Developer Modea (tai järjestelmänvalvojan oikeuksia), mikä ei ehkä ole kätevää koko tiimille. Vaihtoehtona on lyhyt CLAUDE.md, joka tuo AGENTS.md-tiedoston sisällön mukaan:

# CLAUDE.md

@AGENTS.md

## Claude Code -kohtaiset ohjeet

- Käytä erikoistuneisiin prompteihin .claude/skills/-kansiota
- Kun työskentelet Skills-toimintojen kanssa, tutustu tiedostoon .claude/skills/INDEX.md
- Käytä Plan Modea ennen suuria muutoksia (Shift+Tab)

Claude Code tuo tällä syntaksilla AGENTS.md-tiedoston mukaan yhdellä rivillä ja lisää sen alle Claude Code -kohtaiset lisäohjeet. Jos haluat myöhemmin poistaa AGENTS.md:n, poista vain tuontirivi. Tämä rivi ei aiheuta sisällön lukemista kahteen kertaan: Claude Coden dokumentaation mukaan se ei lataa samaa AGENTS.md-tiedostoa kahdesti, vaikka se pystyisi lukemaan sen myös itsenäisesti.

Useita työkaluja käyttävän tiimin kanoninen hakemistorakenne vuonna 2026:

repo-root/
├── AGENTS.md                              # totuuden lähde, ≤150 riviä
├── CLAUDE.md                              # vain jos on Claude-kohtaisia sääntöjä: symbolinen linkki → AGENTS.md TAI @AGENTS.md + lisäohjeet
├── .cursor/rules/                         # kohdennetut yliajot vain Cursorille
├── .github/copilot-instructions.md        # ”Katso AGENTS.md”, jos käytössä
└── docs/architecture.md                   # AGENTS.md-tiedostossa viitattu laaja arkkitehtuurikuvaus

Lisää tietoa CLAUDE.md-tiedostosta on oppaassa ”Näin määrität CLAUDE.md:n oikein”. Lue ”Mitä kontekstisuunnittelu tarkoittaa”, jos haluat lisätietoa siitä, miksi agentti tarvitsee laajan ohjetiedoston.

Mikä muuttui vuonna 2026: miksi AAIF toi AGENTS.md:n Linux Foundationin alaisuuteen?#

Toukokuun 2026 merkittävin AI-koodauksen poliittinen kehitys ei ollut uusi mallijulkaisu vaan tiedostomuotojen yhdistyminen. Aiemmin jokaisella toimittajalla oli oma sääntötiedostonsa. Se oli toimittajille kätevää mutta hankalaa tiimeille, jotka käyttivät useita työkaluja.

Joulukuun 9. päivänä 2025 päivätyssä lehdistötiedotteessa Linux Foundation ilmoitti Agentic AI Foundationista kolmen tiedostomuodon sateenvarjona:

• AGENTS.md OpenAI:lta – agenttien ohjetiedoston tiedostomuoto
• Model Context Protocol (MCP) Anthropicilta – protokolla ulkoisten työkalujen yhdistämiseen agentteihin
• goose Blockilta – avoimen lähdekoodin agenttikehys

Linux Foundationin lehdistötiedotteesta:

”Näiden projektien kokoaminen AAIF:n sateenvarjon alle varmistaa, että ne voivat kehittyä läpinäkyvästi ja vakaasti, minkä avoin hallintomalli yksin mahdollistaa.”

(Linux Foundationin lehdistötiedote, 9. joulukuuta 2025, käännetty englannista)

Helmikuun 24. päivänä 2026 AAIF:ään kuului 146 organisaatiota (97 uutta jäsentä kahdessa kuukaudessa). Uusia Gold-jäseniä olivat muun muassa Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express ja Autodesk. Anthropic on Platinum-tasolla ja edistää MCP:tä. OpenAI on Platinum-tasolla ja edistää AGENTS.md:tä. Block on Platinum-tasolla goosen kanssa.

Tämä muuttaa AGENTS.md:n asemaa: se ei ole enää ”OpenAI:n tiedostomuoto” vaan alan standardi. Keväällä 2026 Claude Code oli yhä sivussa, mutta syyskuussa se oppi version 2.1.277 myötä lukemaan AGENTS.md:n itse. CLAUDE.md ei ole kadonnut, ja jos se on projektissa, sillä on edelleen oletusarvoisesti etusija.

Käytännöllinen lähtökohta on yhteiset projektiohjeet AGENTS.md:ssä sekä kunkin ohjelman tarvitsema tuonti, käärintätiedosto tai erillinen lukumääritys. Tarkista Claude Coden asennettu versio ja ohjetiedostojen etusijajärjestys ennen CLAUDE.md-tuonnin tai symbolisen linkin valintaa. Varmista lataaminen jokaisessa ohjelmassa; tässä ei ole osoitettu kattavuusprosenttia.

Mitä seuraavaksi?#

AGENTS.md on ensimmäinen rakennuspalikka siinä, ”miten agentin kanssa sovitaan asioista niin, että se toimii ennustettavasti”. Seuraava on projektin tietokansio, joka sisältää liiketoimintakontekstin, kohderyhmän, tuotteet ja hinnat. Kolmas rakennuspalikka on kontekstisuunnittelu, joka tuo kaiken yhteen: mitä tiedostoja agentti näkee kussakin vaiheessa, miten tila säilytetään istuntojen välillä ja miten eri mallien välillä vaihdetaan.

Käytännön materiaalia: Ailoot-dokumentaatio.

Lisää materiaalia ja työkaluja: Ailoot.