Čo je AGENTS.md a ako si vytvoriť vlastný za 30 minút

Praktické materiály o vibe codingu a práci s agentmi: dokumentácia Ailoot.

AGENTS.md v jednom odseku#

Nižšie si formát predstavíme na základe stránky agents.md, dokumentácie OpenAI Codex, JetBrains Junie, Cursor Rules Docs, prehľadu zmien GitHub Copilot Coding Agent a tlačovej správy Linux Foundation o Agentic AI Foundation. Všetky čísla a funkcie sú aktuálne k 30. máju 2026. Podpora AGENTS.md v Claude Code je opísaná podľa dokumentácie Anthropic, aktualizovanej 24. septembra 2026.

Ak vôbec netušíte, čo je táto zoologická záhrada nástrojov na trhu a prečo potrebujú spoločný súbor, najprv si prečítajte príručku „S čím programovať v roku 2026: 8 AI nástrojov od Claude Code po Antigravity“. Tento článok sa zameriava konkrétne na formát AGENTS.md a na to, ako si za 30 minút vytvoriť vlastný súbor.

Čo je AGENTS.md a odkiaľ pochádza?#

Predtým mal každý AI nástroj vlastný súbor pravidiel: Anthropic mal CLAUDE.md, Cursor mal .cursorrules, GitHub mal .github/copilot-instructions.md, Aider mal .aider.conf.yml a JetBrains mal .junie/guidelines.md. Ak váš tím používal troch rôznych agentov, znamenalo to tri paralelné súbory s rovnakým obsahom, ktoré sa do týždňa začali rozchádzať.

OpenAI bola prvá, koho to prestalo baviť. V auguste 2025 vydala Codex CLI a zároveň spustila agents.md ako otvorený formát. Zo stránky:

„Predstavte si AGENTS.md ako README pre agentov.“

(agents.md, preklad z angličtiny)

Hlavnou myšlienkou je, že AGENTS.md dopĺňa README. README sa píše pre ľudí: „čo je projekt, ako ho spustiť lokálne, ako prispieť“. AGENTS.md sa píše pre agenta: presné príkazy shellu, overiteľné kritériá dokončenia a hranice typu „tohto sa nikdy nedotýkaj“.

Zo stránky:

„AGENTS.md dopĺňa README: obsahuje ďalšie, niekedy podrobné informácie, ktoré agent potrebuje—postup zostavenia, testy a konvencie, ktoré by zahltili README alebo ktoré ľudskí prispievatelia jednoducho nepotrebujú.“

(agents.md, preklad z angličtiny)

V septembri 2025 už formát podporoval GitHub Copilot Coding Agent (prehľad zmien, 28.08.2025). Do decembra sa pridali Cursor, Junie, Gemini CLI, Aider a ďalší tucet nástrojov. Dňa 9. decembra 2025 založila Linux Foundation Agentic AI Foundation (AAIF): jej tromi zakladajúcimi projektmi boli AGENTS.md od OpenAI, MCP od Anthropic a goose od Block. Zakladajúcimi členmi boli AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft a OpenAI. Do 24. februára 2026 mala nadácia už 146 organizácií vrátane Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath a Hitachi.

Odvtedy AGENTS.md prestal byť „ďalšou vecou od OpenAI“ a stal sa de facto štandardom.

Ktorí AI agenti čítajú AGENTS.md a ktorí nie?#

Tabuľka podpory k 30. máju 2026; riadok Claude Code bol aktualizovaný 24. septembra 2026:

Anthropic sa k formátu pridala ako posledná z veľkých spoločností. V auguste 2025 bolo v oficiálnom repozitári anthropics/claude-code otvorené issue #6235 so žiadosťou o podporu AGENTS.md.

Issue zostal otvorený takmer rok a zatvorili ho 17. augusta 2026; verzia 2.1.277 s podporou AGENTS.md vyšla 18. septembra. Logika Anthropic je takáto: CLAUDE.md má prednosť a AGENTS.md sa číta, ak sa CLAUDE.md nenachádza v pracovnom adresári ani v žiadnom nadradenom adresári. Podľa dokumentácie to funguje takto:

Háčik je v tom, že počíta sa aj osobný súbor CLAUDE.local.md a v takom prípade Claude Code prestane čítať AGENTS.md. Toto správanie môžete zmeniť v /config v časti Project instructions—napríklad nastaviť Claude Code tak, aby čítal oba súbory naraz. Vo verziách starších než 2.1.277 sa AGENTS.md nenačíta automaticky; riešením je stále riadok @AGENTS.md v súbore CLAUDE.md.

Ako sa AGENTS.md líši od CLAUDE.md a .cursorrules?#

Porovnanie štyroch formátov k 30. máju 2026:

Hlavná myšlienka je, že AGENTS.md rieši problém „jeden súbor pre všetkých agentov“, ale nie problém „osobné nastavenia, ktoré nezahrniem do commitu“. Claude Code na to má CLAUDE.local.md a Cursor má lokálne súbory .mdc v používateľskom adresári. Samotný AGENTS.md túto možnosť neposkytuje—musíte ho buď skombinovať s ďalšími súbormi, alebo sa v tíme dohodnúť, že osobné pravidlá budete písať do častí ignorovaných systémom git.

Ďalším dôležitým detailom sú monorepozitáre. Codex a Cursor uplatňujú pravidlo „vyhráva najbližší AGENTS.md“:

„V monorepozitári umiestnite samostatný AGENTS.md do každého balíka. Agenti automaticky čítajú najbližší súbor v adresárovom strome a najbližší má prednosť.“

(agents.md, preklad z angličtiny)

Stránka agents.md uvádza, že hlavný monorepozitár OpenAI obsahuje 88 súborov AGENTS.md pre rôzne podbalíky. Ak pracujete v monorepozitári, rozdeľte pravidlá do viacerých úrovní: všeobecné pravidlá do koreňového adresára a špecifické pravidlá do podpriečinkov.

Čo má obsahovať dobrý AGENTS.md?#

Stránka agents.md ponúka flexibilný formát—„ľubovoľný Markdown“. No 80 % dobrých súborov, ktoré nájdete v praxi, obsahuje rovnakých osem sekcií. Hlavné pravidlo: každá položka má byť presný príkaz alebo konkrétny príklad. Agent ignoruje abstraktnú myšlienku, ako je „píš čistý kód“.

1. Prehľad projektu — 2–3 riadky. Čo je projekt, komu slúži a aký je jeho hlavný cieľ. Bez marketingu. Príklad: „Telegram bot na zapojenie účastníkov do plateného workshopu. Stack: Next.js 14, Prisma, PostgreSQL. Spúšťa sa pri novom zázname v purchases.“
2. Príkazy na nastavenie — presné príkazy shellu na lokálne spustenie. npm install, npm run dev, npm run build. Žiadne „takto to zvyčajne robíme“.
3. Štýl kódu / konvencie — konkrétne pravidlá s príkladom, nie „píš čisto“. Napríklad: „TypeScript strict, jednoduché úvodzovky, bez default exports, názvy komponentov v PascalCase, názvy hooks sa začínajú na use.“
4. Tipy k vývojovému prostrediu — kde sa nachádzajú dôležité veci. Ktoré premenné treba v .env, kde sú uložené tajomstvá, ktoré porty sa používajú a ako pracovať s lokálnou DB.
5. Pokyny na testovanie — ako spustiť konkrétny test a čo sa považuje za úspech. Napríklad: npm test -- --testPathPattern=user-auth; očakáva sa 100 % úspešnosť.
6. Pokyny k PR / commitom — formát správy commitu, kontrolný zoznam pred PR (testy, linter, dokumentácia) a kto schvaľuje.
7. Bezpečnostné hľadiská — čo sa nesmie nikdy stať. „Nikdy nezahrňte .env do commitu. Tajomstvá patria iba do Vaultu. Osobné údaje používateľov nezobrazujte v logoch.“
8. Hranice / Toto nikdy nerobte — zákazy spolu s alternatívou. „Nepoužívajte git push --force na main. Ak potrebujete zmeny vrátiť, použite git revert alebo git reset vo feature branche.“

Pri každej sekcii sa riaďte zásadou „príkaz namiesto myšlienky“. Agent bude ignorovať „dávaj pozor pri migráciách“. Bude sa riadiť pokynom „Pred alembic upgrade head spusti alembic check. Ak oznámi chybu, migráciu nevykonávaj a opýtaj sa ma“.

Šablóna AGENTS.md pripravená na použitie (skopírujte a upravte)#

# AGENTS.md

## Prehľad projektu

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

## Príkazy na nastavenie

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

## Vývojové prostredie

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Štýl kódu

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

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

## Testovanie

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pokyny k pull requestom

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Bezpečnosť

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Toto nikdy nerobte

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

Šablóna má v priemere 80–120 riadkov. Ak súbor presiahne 150 riadkov, je to signál na reorganizáciu: presuňte niečo do docs/, na niečo odkážte alebo skráťte text na jeden riadok. V praxi najlepšie fungujú súbory so 100–150 riadkami; po prekročení tejto hranice sa prínos pre kvalitu začína obracať.

Ktorých 5 pravidiel robí AGENTS.md skutočne užitočným?#

1. Príkazy namiesto myšlienok. Agent nerozumie pokynu „dávaj pozor pri migráciách“. Bude sa riadiť príkazom alembic check pred alembic upgrade head. Agenti pracujú s príkazmi a podmienkami, nie s náladami. Všetky kľúčové pravidlá formulujte ako „urob X, inak Y“.

2. Zákazy s alternatívou. Samotné „nerob force push“ agent po dvoch či troch zadaniach potichu ignoruje. Funguje dvojica „nerob X; namiesto toho urob Y“. Príklad: „Nepoužívaj git push --force na main; ak potrebuješ vrátiť zmeny, použi git revert alebo otvor nový PR.“

3. Presne jeden zdroj pravdy. Koreňový AGENTS.md je zdrojom pravdy pre celý projekt. Ak máte monorepozitár, použite vnorené súbory AGENTS.md v podpriečinkoch a riaďte sa pravidlom „vyhráva najbližší“. Žiadne paralelné súbory s protichodnými pokynmi.

4. Overiteľné kritériá dokončenia. „Testy musia prejsť“ je zbytočné. Presné kritérium je: npm test vráti návratový kód 0 a na stdout nevypíše FAIL. Rovnako zbytočné je „kód má byť čistý“. Presné kritérium je: npm run lint prejde bez upozornení. Agent pochopí, čo znamená „hotovo“, len ak výslovne opíšete podmienku.

5. Súbor kratší ako 150 riadkov. Nad hranicou 150 riadkov sa ukazovatele začínajú zhoršovať: agent venuje viac kontextu čítaniu a prehliadne dôležité pravidlá. Ak sa všetko nezmestí, podrobnosti presuňte do docs/architecture.md a odkážte naň v AGENTS.md; v súbore ponechajte len príkazy a hranice.

Akých 10 chýb zmení AGENTS.md na odpad?#

1. Nejasné pravidlá bez príkazov. Agent bude ignorovať vetu „dávaj pozor pri migráciách“—nič konkrétne mu nehovorí. Funguje len konkrétny príkaz s podmienkou: „Pred alembic upgrade head spusti alembic check. Ak sa objaví chyba, migráciu nevykonávaj a opýtaj sa ma.“

2. „Čistý kód.“ Zbytočná fráza. Nahraďte ju konkrétnym vzorom: „Používaj funkčné komponenty s hooks. Príklad: function LoginForm() { const [email, setEmail] = useState(''); ... }“

3. Neštruktúrovaný text. Ak má AGENTS.md 300 riadkov textu bez nadpisov, agent strávi 80K kontextových tokenov nepodstatnými pasážami a prehliadne dôležité informácie. Používajte nadpisy H2/H3, krátke sekcie a zoznamy s odrážkami.

4. Súbor dlhší ako 150 riadkov. Po prekročení tejto hranice sa ukazovatele kvality zhoršujú. Rozdeľte obsah na hlavný súbor a odkazy na podrobnosti v docs/.

5. 30+ zákazov bez alternatív. Ak súbor obsahuje dlhý zoznam typu „nerob X, nerob Y“ bez vysvetlenia „namiesto toho urob Z“, agent bude bezradne tápať.

6. Duplikovanie README.md. Ak ste už do README napísali, ako projekt nainštalovať a spustiť, nekopírujte to do AGENTS.md. Namiesto toho odkážte na README jedným riadkom a opíšte v AGENTS.md to, čo agent potrebuje, no ľudskí prispievatelia nie.

7. Napevno zapísané tajomstvá. AGENTS.md môže byť verejný (je v gite). Nevkladajte doň skutočné kľúče API, tokeny ani heslá. Uvádzajte len odkazy na úložiská tajomstiev: „Pozri Vault: secret/staging/db.“

8. Protichodné priority bez poradia. Pokyny „pracuj rýchlo“ + „udržuj 90% pokrytie testami“ nechávajú agenta na pochybách, čo si má vybrať. Výslovne ich zoraďte: „Najprv pokrytie testami ≥80%, potom rýchlosť. Ak sú v konflikte, prednosť majú testy.“

9. Zastaraná dokumentácia. Opis architektúry tvrdí, že sa používa REST+polling, hoci systém už používa WebSockets. Agent sa riadi zastaraným opisom a naruší architektúru. Pravidlo: vždy aktualizujte AGENTS.md v tom istom PR ako kód, keď sa zmení architektúra.

10. Zbytočne zložitá architektúra pri jednoduchej úlohe. Ak niekto požiadal o zmenu dvoch riadkov v konfiguračnom súbore, agent by nemal musieť čítať kompletnú topológiu 14 microservices. Podrobnú architektúru presuňte do docs/architecture.md; v AGENTS.md nechajte iba pokyn „ak je úloha architektonická, prečítaj si docs/architecture.md“.

Štúdia GitHub Blogu o viac ako 2 500 repozitároch AGENTS.md uvádza hlavný záver:

„Väčšina súborov s pokynmi pre agentov zlyháva, pretože sú príliš všeobecné. Veta ‚Si užitočný asistent na programovanie‘ nefunguje.“

(GitHub Blog, preklad z angličtiny)

Ako uchovávať AGENTS.md a CLAUDE.md v jednom repozitári?#

Hlavnou praktickou otázkou je, ako používať oba súbory bez duplikovania obsahu. Existujú tri scenáre:

Scenár 1: Iba Claude Code. Ponechajte CLAUDE.md a využívajte všetky funkcie Claude Code: ~/.claude/CLAUDE.md na pokyny na úrovni používateľa, CLAUDE.md pre projekt, CLAUDE.local.md na osobné úpravy, @import na zahrnutie ďalších súborov a .claude/skills/ na špecializované skills. AGENTS.md netreba.

Scenár 2: viacerí programátorskí klienti. Spoločné pravidlá ponechajte v AGENTS.md, potom každého klienta pripojte a overte samostatne. Gemini CLI podporuje nastavený názov kontextového súboru; Aider môže načítať súbor cez konfiguráciu čítania. Ide o výslovné spôsoby načítania, nie rovnaké automatické vyhľadávanie.

Začnite novú reláciu v neškodnom testovacom repozitári, pridajte jedinečný neškodný pokyn, napríklad „do testovacej odpovede vlož značku instructions-loaded“, a okrem odpovede skontrolujte aj zdokumentovaný prehľad načítaných súborov či logy klienta. Opakujte pre každého skutočne používaného klienta a verziu. Vygenerované tvrdenie, že súbor prečítal, nie je nezávislým dôkazom načítania; z jedného úspešného testu nevyvodzujte podporu vo všetkých ostatných nástrojoch.

Scenár 3: Zmiešaný tím (Claude Code + ďalšie nástroje). V roku 2026 ide o najbežnejšie nastavenie. Riešením je určiť AGENTS.md ako hlavný súbor. Ak nemáte pravidlá určené výhradne pre Claude Code, CLAUDE.md vôbec nevytvárajte: od verzie 2.1.277 číta Claude Code AGENTS.md, ak projekt nemá CLAUDE.md. Ak také pravidlá máte, vytvorte z CLAUDE.md buď symbolický odkaz, alebo krátky obalový súbor s importom @AGENTS.md.

Pred zmenou prezrite a zálohujte oba súbory. Ak existujú oba, spoločné nekonfliktné pokyny zlúčte do AGENTS.md a špecifické pre Claude ponechajte v CLAUDE.md s importom @AGENTS.md. Existujúce symbolické odkazy zachovajte.

Pre bežný CLAUDE.md iba pri neprítomnom AGENTS.md táto ochrana shellu macOS/Linux odmieta prepísať cieľ aj existujúci symbolický odkaz:

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 úspešnom premenovaní je CLAUDE.md symbolickým odkazom na AGENTS.md. Agenti čítajúci AGENTS.md aj Claude Code čítajúce odkaz uvidia rovnaký obsah.

V systéme Windows si vytvorenie symbolického odkazu vyžaduje Developer Mode (alebo Admin), čo nemusí byť pre celý tím praktické. Alternatívou je krátky súbor CLAUDE.md, ktorý importuje AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Špecifické pre Claude Code

- Na špecializované prompty používaj .claude/skills/
- Pri práci so Skills si pozri .claude/skills/INDEX.md
- Pred veľkými zmenami používaj Plan Mode (Shift+Tab)

V Claude Code táto syntax jedným riadkom načíta AGENTS.md a nižšie pridá špecifické pokyny pre Claude Code. Ak budete chcieť AGENTS.md neskôr odstrániť, stačí vymazať import. Tento riadok nespôsobuje dvojité načítanie: podľa dokumentácie Claude Code nenačíta ten istý AGENTS.md dvakrát, aj keď ho dokáže načítať samostatne.

Odporúčaná štruktúra pre tím používajúci viacero nástrojov v roku 2026:

repo-root/
├── AGENTS.md                              # zdroj pravdy, ≤150 riadkov
├── CLAUDE.md                              # iba ak existujú pravidlá pre Claude Code: symbolický odkaz → AGENTS.md ALEBO @AGENTS.md + dodatky
├── .cursor/rules/                         # cielené úpravy iba pre Cursor
├── .github/copilot-instructions.md        # „Pozri AGENTS.md“, ak sa používa
└── docs/architecture.md                   # podrobná architektúra, na ktorú odkazuje AGENTS.md

Viac o CLAUDE.md sa dozviete v príručke „Ako správne nakonfigurovať CLAUDE.md“. Ďalší kontext o tom, prečo agent potrebuje rozsiahly súbor pokynov, nájdete v článku „Čo je Context Engineering“.

Čo sa zmenilo v roku 2026: prečo AAIF zastrešila AGENTS.md pod Linux Foundation?#

Hlavnou politickou udalosťou mája 2026 v oblasti AI programovania nebolo vydanie ďalšieho modelu, ale zjednocovanie formátov. Predtým mal každý dodávateľ vlastný súbor pravidiel. Dodávateľom to vyhovovalo, no tímom pracujúcim s viacerými nástrojmi to komplikovalo život.

V tlačovej správe z 9. decembra 2025 oznámila Linux Foundation vznik Agentic AI Foundation ako zastrešujúcej organizácie pre tri formáty:

• AGENTS.md od OpenAI — formát súboru s pokynmi pre agentov
• Model Context Protocol (MCP) od Anthropic — protokol na pripájanie externých nástrojov k agentom
• goose od Block — open-source framework agentov

Z tlačovej správy Linux Foundation:

„Zastrešenie týchto projektov pod AAIF im umožní rozvíjať sa transparentne a stabilne, čo dokáže zabezpečiť iba otvorená správa.“

(tlačová správa Linux Foundation, 9. decembra 2025, preklad z angličtiny)

Do 24. februára 2026 patrilo do AAIF 146 organizácií (97 nových členov za dva mesiace). Medzi novými členmi na úrovni Gold boli Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express a Autodesk. Anthropic je na úrovni Platinum a presadzuje MCP. OpenAI je na úrovni Platinum a presadzuje AGENTS.md. Block je na úrovni Platinum s goose.

Mení sa tým postavenie AGENTS.md: z „formátu OpenAI“ sa stal priemyselným štandardom. Na jar 2026 Claude Code ešte stálo bokom, no v septembri sa vo verzii 2.1.277 naučilo čítať AGENTS.md samostatne. CLAUDE.md nezaniklo a predvolene má stále prednosť, ak sa v projekte nachádza.

Praktickým východiskom sú spoločné pravidlá projektu v AGENTS.md a import, sprostredkujúci súbor alebo výslovná konfigurácia čítania, ktoré vyžaduje každý používaný klient. Pri Claude Code overte nainštalovanú verziu a prednosť súborov s pokynmi, skôr než zvolíte import v CLAUDE.md alebo symbolický odkaz. Načítanie overte v každom klientovi; tento návod neurčuje percento pokrytých prípadov.

Čo ďalej#

AGENTS.md je prvým stavebným prvkom v téme „ako sa dohodnúť s agentom, aby pracoval predvídateľne“. Ďalším je priečinok so znalosťami o projekte, ktorý obsahuje obchodný kontext, publikum, produkty a ceny. Tretím stavebným prvkom je context engineering, ktorý všetko prepája: ktoré súbory agent vidí v každom kroku, ako sa zachováva stav medzi reláciami a ako prepínať medzi rôznymi modelmi.

Praktické materiály: dokumentácia Ailoot.

Ďalšie materiály a nástroje: Ailoot.