Kaj je AGENTS.md in kako v 30 minutah napisati svojega

Praktična gradiva o vibe codingu in delu z agenti: dokumentacija Ailoot.

AGENTS.md v enem odstavku#

V nadaljevanju je oblika predstavljena na podlagi spletnega mesta agents.md, dokumentacije za OpenAI Codex, JetBrains Junie, Cursor Rules Docs, dnevnika sprememb GitHub Copilot Coding Agent in sporočila za javnost fundacije Linux Foundation o Agentic AI Foundation. Vsi podatki in funkcije so aktualni na dan 30. maja 2026, podpora za AGENTS.md v Claude Code pa je opisana na podlagi dokumentacije Anthropica, posodobljene 24. septembra 2026.

Če ne veš, kaj je ta živalski vrt orodij na trgu ali zakaj potrebuje skupno datoteko, najprej preberi vodnik »S čim kodirati v letu 2026: 8 orodij AI od Claude Code do Antigravity«. Ta članek se osredotoča posebej na obliko AGENTS.md in na to, kako v 30 minutah napišeš svojo datoteko.

Kaj je AGENTS.md in od kod izvira?#

Prej je imelo vsako orodje AI svojo datoteko s pravili: Anthropic je imel CLAUDE.md, Cursor .cursorrules, GitHub .github/copilot-instructions.md, Aider .aider.conf.yml, JetBrains pa .junie/guidelines.md. Če je tvoja ekipa uporabljala tri različne agente, so to pomenile tri vzporedne datoteke z enako vsebino, ki so se v enem tednu začele razlikovati.

OpenAI se je tega prvi naveličal. Avgusta 2025 je izdal Codex CLI in hkrati uvedel agents.md kot odprto obliko. Na spletnem mestu piše:

»Na AGENTS.md glej kot na datoteko README za agente.«

(agents.md, prevedeno iz angleščine)

Bistvo je, da AGENTS.md dopolnjuje README. README je napisan za ljudi: »kaj je projekt, kako ga zagnati lokalno in kako prispevati.« AGENTS.md je napisan za agenta: natančni ukazi lupine, preverljiva merila za »končano« in omejitve, kot je »tega se nikoli ne dotikaj«.

S spletnega mesta:

»AGENTS.md dopolnjuje README: vsebuje dodatne, včasih podrobne informacije, ki jih agent potrebuje — korake gradnje, teste in konvencije, ki bi po nepotrebnem obremenili README ali jih človeški sodelavci preprosto ne potrebujejo.«

(agents.md, prevedeno iz angleščine)

Do septembra 2025 je obliko podpiral GitHub Copilot Coding Agent (dnevnik sprememb, 28.08.2025). Do decembra so se pridružili Cursor, Junie, Gemini CLI, Aider in še ducat orodij. 9. decembra 2025 je Linux Foundation ustanovil Agentic AI Foundation (AAIF): njeni trije ustanovni projekti so bili AGENTS.md podjetja OpenAI, MCP podjetja Anthropic in goose podjetja Block. Ustanovni člani so bili AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft in OpenAI. Do 24. februarja 2026 je fundacija vključevala že 146 organizacij, med njimi Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath in Hitachi.

Od takrat AGENTS.md ni bil več »še ena stvar podjetja OpenAI«, temveč de facto standard.

Kateri agenti AI berejo AGENTS.md in kateri ne?#

Tabela podpore na dan 30. maja 2026; vrstica za Claude Code je bila posodobljena 24. septembra 2026:

Anthropic se je pridružil zadnji med večjimi ponudniki. Avgusta 2025 je bil v uradnem repozitoriju anthropics/claude-code odprt issue #6235 z zahtevo po podpori za AGENTS.md.

Issue je ostal odprt skoraj leto dni in bil zaprt 17. avgusta 2026; različica 2.1.277 s podporo za AGENTS.md je izšla 18. septembra. Anthropicova logika je naslednja: CLAUDE.md ima prednost, AGENTS.md pa se bere, kadar CLAUDE.md ni v delovni mapi ali kateri koli nadrejeni mapi. Po dokumentaciji deluje tako:

Zanka: tudi osebna datoteka CLAUDE.local.md šteje, zato Claude Code preneha brati AGENTS.md. To vedenje lahko spremeniš v /config v razdelku Project instructions — na primer tako, da Claude Code hkrati bere obe datoteki. Različice, starejše od 2.1.277, AGENTS.md ne zaznajo samodejno; vrstica @AGENTS.md v CLAUDE.md je še vedno rešitev.

V čem se AGENTS.md razlikuje od CLAUDE.md in .cursorrules?#

Primerjava štirih formatov na dan 30. maja 2026:

Ključna zamisel: AGENTS.md rešuje težavo »ena datoteka za vse agente«, ne pa težave »osebne nastavitve, ki jih ne oddam v commit«. Claude Code ima za to CLAUDE.local.md, Cursor pa lokalne datoteke .mdc v uporabniški mapi. AGENTS.md tega sam ne omogoča — kombinirati ga moraš z drugimi datotekami ali pa se v ekipi dogovoriti, da osebna pravila zapišete v razdelke, ki jih Git ne sledi.

Druga pomembna podrobnost so monorepozitoriji. Codex in Cursor uporabljata pravilo »velja najbližji AGENTS.md«:

»V monorepozitoriju dodaj ločeno datoteko AGENTS.md v vsak paket. Agenti samodejno preberejo najbližjo datoteko v drevesu map; velja najbližja.«

(agents.md, prevedeno iz angleščine)

Na spletnem mestu agents.md piše, da glavni monorepozitorij podjetja OpenAI vsebuje 88 datotek AGENTS.md za različne podpakete. Če delaš v monorepozitoriju, razporedi pravila po ravneh: splošna pravila v korenski mapi, posebna v podmapah.

Kaj mora vsebovati dober AGENTS.md?#

Spletno mesto agents.md ponuja prilagodljivo obliko — »poljuben Markdown«. Toda 80 % dobrih datotek v praksi vsebuje istih osem razdelkov. Glavno pravilo: vsaka točka mora biti natančen ukaz ali konkreten primer. Abstraktno zamisel, kot je »piši čisto kodo«, bo agent prezrl.

1. Pregled projekta — 2–3 vrstice. Kaj je projekt, komu je namenjen in kaj je njegov glavni cilj. Brez trženjskih besedil. Primer: »Telegramov bot za uvajanje v plačljivo delavnico. Stack: Next.js 14, Prisma, PostgreSQL. Sproži ga nov zapis v purchases.«
2. Ukazi za nastavitev — natančni ukazi lupine za lokalni zagon. npm install, npm run dev, npm run build. Brez »tako to običajno počnemo«.
3. Slog kode / konvencije — konkretna pravila s primerom, ne »piši čisto«. Na primer: »strogi TypeScript, enojni narekovaji, brez privzetih izvozov, imena komponent v PascalCase, imena hookov se začnejo z use.«
4. Nasveti za razvojno okolje — kje so pomembne stvari. Katere spremenljivke so potrebne v .env, kje so shranjene skrivnosti, kateri porti se uporabljajo in kako delati z lokalno DB.
5. Navodila za testiranje — kako zagnati določen test in kaj šteje kot »uspešno«. Na primer: npm test -- --testPathPattern=user-auth; pričakuje se 100-odstotna uspešnost.
6. Smernice za PR-je / commite — oblika sporočil commitov, kontrolni seznam pred PR-jem (testi, linter, dokumentacija) in kdo odobri.
7. Varnostni vidiki — kaj se nikoli ne sme zgoditi. »Nikoli ne oddaj .env v commit. Skrivnosti spadajo samo v Vault. Osebnih podatkov uporabnikov ne zapisuj v dnevnike.«
8. Omejitve / Tega nikoli ne počni — prepovedi z nadomestno možnostjo. »Na glavni veji ne uporabljaj git push --force. Če moraš razveljaviti spremembe, uporabi git revert ali git reset na veji funkcije.«

V vsakem razdelku uporabi načelo »ukaz namesto zamisli«. Agent bo prezrl »bodi previden pri migracijah«. Upošteval pa bo: »Pred alembic upgrade head zaženi alembic check. Če javi napako, migracije ne uporabi; vprašaj me.«

Predloga AGENTS.md za takojšnjo uporabo (kopiraj in prilagodi)#

# AGENTS.md

## Pregled projekta

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

## Ukazi za nastavitev

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Razvojno okolje

- Node 20+ (prek nvm: `nvm use 20`)
- PostgreSQL 16 lokalno na :5432 (`docker-compose up postgres`)
- Redis je neobvezen, potreben samo za vrste opravil (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Nikoli ne beri celotne datoteke `.env`. Če potrebuješ eno spremenljivko: `grep "^VAR=" .env`

## Slog kode

- TypeScript strict mode
- Enojni narekovaji, brez podpičij (razen če jih zahteva ESLint)
- Uvozi: najprej zunanji, nato notranji prek `@/`, nato relativni
- Komponente v PascalCase; imena hookov se začnejo z `use`
- Ne uporabljaj `any` brez izrecnega komentarja, ki pojasni, »zakaj tipa ni mogoče določiti«

Primer dobrega modula:

```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)
}
```

## Testiranje

```bash
npm test                                # vsi testi
npm test -- --testPathPattern=auth      # samo auth
npm test -- --watch                     # način watch
```

Pred oddajo commita morajo vsi testi uspeti (biti zeleni). Če je test neuspešen, ne oddaj commita; vprašaj me, kaj storiti.

## Smernice za pull requeste

- Oblika commita: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Pred PR-jem: `npm run build && npm test && npm run lint`
- Opis PR-ja = kaj se spremeni, zakaj in kako to preizkusiti
- Ne odobri svojega PR-ja — vedno počakaj na človeški pregled

## Varnost

- Skrivnosti so samo v `.env` in Vaultu, nikoli v kodi
- Ne zapisuj osebnih podatkov (e-pošte, telefonske številke, imena)
- Pri delu s produkcijsko DB uporabljaj samo poizvedbe za branje, razen če si za kaj drugega izrecno pooblaščen
- V testih ne vgrajuj ključev API zunanjih storitev (Stripe, OpenAI) neposredno v kodo

## Tega nikoli ne počni

- Na glavno vejo ne izvajaj `git push --force`. Če moraš razveljaviti spremembe, uporabi `git revert` ali odpri nov PR
- Ne izvajaj migracij DB brez `alembic check` (ali enakovrednega ukaza v svojem ORM-ju)
- Za projektne odvisnosti ne uporabljaj `npm install -g` ali `sudo`
- Ne dodajaj odvisnosti brez odobritve (zlasti velikih: vtičnikov webpack, ORM)

Predloga ima povprečno 80–120 vrstic. Če datoteka presega 150 vrstic, je to znak, da jo je treba preurediti: nekaj premakni v docs/, dodaj povezavo ali vsebino stisni v eno vrstico. V praksi datoteke s 100–150 vrsticami delujejo najbolje; po tej točki se izboljšanje kakovosti začne obračati.

Katerih 5 pravil naredi AGENTS.md res uporabnega?#

1. Ukazi namesto zamisli. Agent ne razume »bodi previden pri migracijah«. Upošteval bo alembic check pred alembic upgrade head. Agenti delajo z ukazi in pogoji, ne z razpoloženji. Vsa ključna pravila oblikuj kot »naredi X, sicer Y«.

2. Prepovedi z nadomestno možnostjo. Agent čisto potiho prezre golo »ne izvajaj force push«, če mu to ponoviš dva- ali trikrat. Deluje par »ne naredi X; namesto tega naredi Y«. Primer: »na glavni veji ne uporabljaj git push --force; če moraš razveljaviti spremembe, uporabi git revert ali odpri nov PR.«

3. Natanko en vir resnice. Korenski AGENTS.md je vir resnice za celoten projekt. Če imaš monorepozitorij, v podmapah uporabi ugnezdene datoteke AGENTS.md in sledi pravilu »velja najbližji«. Brez vzporednih datotek z nasprotujočimi si navodili.

4. Preverljiva merila za »končano«. »Testi morajo uspeti« je neuporabno. Natančno merilo je: npm test vrne izhodno kodo 0 in v stdout ne izpiše FAIL. Tudi »koda mora biti čista« je neuporabno. Natančno merilo je: npm run lint uspe brez opozoril. Agent razume, kaj pomeni »končano«, samo če pogoj izrecno opišeš.

5. Datoteka, krajša od 150 vrstic. Nad 150 vrsticami začnejo meritve upadati: agent porabi več konteksta za branje in spregleda pomembna pravila. Če vsebine ne moreš spraviti v datoteko, podrobnosti premakni v docs/architecture.md in dodaj povezavo nanjo iz AGENTS.md; v datoteki pusti samo ukaze in omejitve.

Katerih 10 napak spremeni AGENTS.md v navlako?#

1. Nejasna pravila brez ukazov. Agent bo prezrl »bodi previden pri migracijah« — ta stavek zanj ne pomeni nič. Deluje samo konkreten ukaz s pogojem: »Pred alembic upgrade head zaženi alembic check. Če pride do napake, ne uporabi migracije; vprašaj me.«

2. »Čista koda.« Neuporabna fraza. Zamenjaj jo s konkretnim vzorcem: »Uporabi funkcijske komponente s hooki. Primer: function LoginForm() { const [email, setEmail] = useState(''); ... }«

3. Nestrukturirana proza. Če ima AGENTS.md 300 vrstic proze brez naslovov, bo agent porabil 80K kontekstnih tokenov za nepomembne odlomke in spregledal bistveno. Uporabljaj naslove H2/H3, kratke razdelke in sezname z alinejami.

4. Datoteka, daljša od 150 vrstic. Po tem pragu se kazalniki kakovosti poslabšajo. Razdeli vsebino na glavno datoteko in povezave do podrobnosti v docs/.

5. Več kot 30 prepovedi brez nadomestnih možnosti. Če je v datoteki dolg seznam »ne delaj X, ne delaj Y«, ne da bi pojasnila »kaj naredi namesto tega«, se bo agent brezciljno opotekal.

6. Podvajanje README.md. Če si v README že napisal »kako namestiti in zagnati«, tega ne kopiraj v AGENTS.md. Namesto tega se v eni vrstici sklicuj na README in v AGENTS.md opiši, kaj potrebuje agent, česar človeški sodelavci ne.

7. Trdo kodiranje skrivnosti. AGENTS.md je lahko javna datoteka (je v Gitu). Ne vpisuj pravih ključev API, žetonov ali gesel. Dodaj samo sklic na mesto shranjevanja skrivnosti: »Glej Vault: secret/staging/db.«

8. Nasprotujoče si prednostne naloge brez vrstnega reda. »Delaj hitro« + »vzdržuj 90-odstotno pokritost testov« agenta pusti v dvomih, kaj naj izbere. Prednostni vrstni red določi izrecno: »Najprej pokritost testov ≥80 %, nato hitrost. Če sta v nasprotju, imajo prednost testi.«

9. Zastarela dokumentacija. Opis arhitekture pravi REST+polling, v resnici pa se že uporabljajo WebSockets. Agent sledi zastarelemu opisu in pokvari arhitekturo. Pravilo: kadar se spremeni arhitektura, v istem PR-ju kot kodo posodobi tudi AGENTS.md.

10. Pretirana arhitekturna zapletenost za preprosto opravilo. Če nekdo zahteva spremembo dveh vrstic v konfiguraciji, agentu ni treba prebrati celotne topologije 14 mikrostoritev. »Poglobljeno« arhitekturo premakni v docs/architecture.md; v AGENTS.md pusti le »če je opravilo arhitekturno, preberi docs/architecture.md.«

Študija GitHub Bloga o več kot 2.500 repozitorijih AGENTS.md navaja glavni sklep:

»Večina datotek z navodili za agente ne deluje, ker so preveč splošne. »Si koristen pomočnik za kodiranje« ne deluje.«

(GitHub Blog, prevedeno iz angleščine)

Kako imeti AGENTS.md in CLAUDE.md v istem repozitoriju?#

Glavno praktično vprašanje je, kako uporabljati obe datoteki, ne da bi podvajal vsebino. Obstajajo trije scenariji:

Scenarij 1: Samo Claude Code. Obdrži CLAUDE.md in uporabljaj vse funkcije Claude Code: ~/.claude/CLAUDE.md za navodila na ravni uporabnika, CLAUDE.md za projekt, CLAUDE.local.md za osebne prilagoditve, @import za vključevanje drugih datotek in .claude/skills/ za posebne veščine. AGENTS.md ni potreben.

Scenarij 2: Več programskih odjemalcev. Skupna pravila hrani v AGENTS.md, nato pa vsakega odjemalca poveži in preveri posebej. Gemini CLI podpira nastavljivo ime kontekstne datoteke; Aider lahko datoteko naloži prek konfiguracije za branje. To so izrecne poti nalaganja, ne enako samodejno odkrivanje.

V neškodljivem preizkusnem repozitoriju začni novo sejo z enoličnim, neškodljivim navodilom, na primer »v preizkusni odgovor vključi oznako instructions-loaded«. Preglej dokumentirani prikaz naloženih datotek ali dnevnike odjemalca ter njegov odgovor. Ponovi za vsakega odjemalca in različico, ki ju dejansko uporabljaš. Ustvarjena trditev, da je bila datoteka prebrana, ni neodvisen dokaz; uspeh enega preverjanja ne dokazuje podpore v vseh drugih orodjih.

Scenarij 3: Mešana ekipa (Claude Code + drugi). To je najpogostejša postavitev v letu 2026. Rešitev je, da AGENTS.md postane primarna datoteka. Če nimaš pravil, namenjenih samo Claude Code, sploh ne ustvari CLAUDE.md: od različice 2.1.277 Claude Code bere AGENTS.md, kadar projekt nima CLAUDE.md. Če takšna pravila imaš, naj bo CLAUDE.md simbolna povezava ali kratka ovojnica z uvozom @AGENTS.md.

Pred spreminjanjem preglejte in varnostno kopirajte obe datoteki. Če obstajata obe, skupna nekonfliktna navodila združite v AGENTS.md, posebna navodila Claude pa ohranite v CLAUDE.md z uvozom @AGENTS.md. Obstoječe simbolne povezave ohranite, ne zamenjujte jih.

Za običajno datoteko CLAUDE.md samo ob odsotnem AGENTS.md to varovalo lupine macOS/Linux zavrne prepis obstoječega cilja ali simbolne povezave:

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

Po uspešnem preimenovanju je CLAUDE.md simbolna povezava do AGENTS.md. Vsi agenti, ki berejo AGENTS.md, vidijo isto vsebino. Claude Code, ki bere CLAUDE.md, jo prek simbolne povezave vidi enako.

V sistemu Windows je za ustvarjanje simbolne povezave potreben Developer Mode (ali Admin), kar za celotno ekipo morda ne bo praktično. Druga možnost je kratek CLAUDE.md, ki uvozi AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Posebno za Claude Code

- Za specializirane pozive uporabi .claude/skills/
- Pri delu s Skills preveri .claude/skills/INDEX.md
- Pred večjimi spremembami uporabi Plan Mode (Shift+Tab)

V Claude Code ta sintaksa z eno vrstico vključi AGENTS.md in spodaj doda posebne nastavitve za Claude Code. Če želiš pozneje odstraniti AGENTS.md, preprosto izbriši uvoz. Ta vrstica ne povzroči dvojnega branja: dokumentacija Claude Code pravi, da iste datoteke AGENTS.md ne naloži dvakrat, četudi jo lahko prebere samodejno.

Kanonična postavitev za ekipo z več orodji v letu 2026:

repo-root/
├── AGENTS.md                              # vir resnice, ≤150 vrstic
├── CLAUDE.md                              # samo za pravila, specifična za Claude: simbolna povezava → AGENTS.md ALI @AGENTS.md + dodatna pravila
├── .cursor/rules/                         # ciljno določene prilagoditve samo za Cursor
├── .github/copilot-instructions.md        # »Glej AGENTS.md«, če se uporablja
└── docs/architecture.md                   # podrobna arhitektura, na katero se sklicuje AGENTS.md

Več o datoteki CLAUDE.md najdeš v vodniku »Kako pravilno nastaviti CLAUDE.md«. Več konteksta o razlogih, zakaj agent potrebuje veliko datoteko z navodili, ponuja »Kaj je Context Engineering«.

Kaj se je spremenilo v letu 2026: zakaj je AAIF pripeljal AGENTS.md pod Linux Foundation?#

Glavna politična zgodba maja 2026 pri kodiranju z AI ni bila izdaja novega modela, temveč poenotenje formatov. Prej je imel vsak ponudnik svojo datoteko s pravili, kar je bilo priročno za ponudnike, a naporno za ekipe, ki so delale z več orodji.

Linux Foundation je v sporočilu za javnost z dne 9. decembra 2025 predstavil Agentic AI Foundation kot krovno organizacijo za tri formate:

• AGENTS.md podjetja OpenAI — oblika datoteke z navodili za agente
• Model Context Protocol (MCP) podjetja Anthropic — protokol za povezovanje zunanjih orodij z agenti
• goose podjetja Block — odprtokodni ogrodni sistem za agente

Iz sporočila za javnost fundacije Linux Foundation:

»Združitev teh projektov pod okriljem AAIF zagotavlja, da se lahko razvijajo s preglednostjo in stabilnostjo, ki ju lahko zagotovi samo odprto upravljanje.«

(sporočilo za javnost fundacije Linux Foundation, 9. december 2025, prevedeno iz angleščine)

Do 24. februarja 2026 je AAIF pripadalo 146 organizacij (97 novih članic v dveh mesecih). Med novimi članicami na ravni Gold so bile Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express in Autodesk. Anthropic je na ravni Platinum in podpira MCP. OpenAI je na ravni Platinum in podpira AGENTS.md. Block je na ravni Platinum z goose-om.

To spreminja položaj AGENTS.md: iz »formata OpenAI« se je razvil v industrijski standard. Spomladi 2026 je bil Claude Code še ob strani, septembra pa se je z različico 2.1.277 naučil samostojno brati AGENTS.md. CLAUDE.md ni izginil in ima privzeto še vedno prednost, če je v projektu.

Praktično izhodišče so skupna projektna pravila v AGENTS.md, dopolnjena z uvozom, ovojno datoteko ali izrecno nastavitvijo branja, ki jo zahteva posamezni odjemalec. Pri Claude Code preveri nameščeno različico in prednost datotek z navodili, preden se odločiš, ali potrebuješ uvoz iz CLAUDE.md ali simbolno povezavo. Nalaganje preveri pri vsakem odjemalcu; delež pokritih primerov tukaj ni izmerjen.

Kaj sledi?#

AGENTS.md je prvi gradnik pri vprašanju »kako se dogovoriti z agentom, da bo deloval predvidljivo«. Sledi drugi gradnik — mapa z znanjem o projektu, ki vsebuje poslovni kontekst, občinstvo, izdelke in cene. Tretji gradnik je context engineering, ki vse poveže: katere datoteke agent vidi v posameznem koraku, kako se ohranja stanje med sejami in kako preklapljati med različnimi modeli.

Praktična gradiva: dokumentacija Ailoot.

Več gradiv in orodij: Ailoot.