Co je AGENTS.md a jak si vytvořit vlastní za 30 minut

Praktické materiály o vibe codingu a práci s agenty: dokumentace Ailoot.

AGENTS.md v jednom odstavci#

Níže je formát popsán s využitím webu agents.md, dokumentace OpenAI Codex, JetBrains Junie, Cursor Rules Docs, changelogu GitHub Copilot Coding Agent a tiskové zprávy Linux Foundation o Agentic AI Foundation. Všechny údaje a funkce odpovídají stavu k 30. květnu 2026 a podpora AGENTS.md v Claude Code je popsána podle dokumentace Anthropic, aktualizované 24. září 2026.

Pokud vůbec netušíte, co je tahle zoo nástrojů na trhu nebo proč potřebují společný soubor, přečtěte si nejprve průvodce „S čím programovat v roce 2026: 8 nástrojů AI od Claude Code po Antigravity“. Tento článek se zaměřuje konkrétně na formát AGENTS.md a na to, jak si vlastní soubor napsat za 30 minut.

Co je AGENTS.md a odkud se vzal?#

Dříve měl každý nástroj AI vlastní soubor s pravidly: Anthropic měl CLAUDE.md, Cursor .cursorrules, GitHub .github/copilot-instructions.md, Aider .aider.conf.yml a JetBrains .junie/guidelines.md. Pokud váš tým měl tři různé agenty, znamenalo to tři souběžné soubory se stejným obsahem, které se během týdne začaly rozcházet.

OpenAI to omrzelo jako první. V srpnu 2025 vydala Codex CLI a současně spustila agents.md jako otevřený formát. Na webu se píše:

„Představte si AGENTS.md jako soubor README pro agenty.“

(agents.md, přeloženo z angličtiny)

Hlavní pointa je, že AGENTS.md doplňuje README. README je psaný pro lidi: „co je to za projekt, jak ho spustit lokálně a jak přispívat“. AGENTS.md je psaný pro agenta: přesné příkazy shellu, ověřitelná kritéria pro stav „hotovo“ a hranice typu „na tohle nikdy nesahej“.

Na webu se píše:

„AGENTS.md doplňuje README: obsahuje dodatečný, někdy podrobný kontext, který agent potřebuje — kroky sestavení, testy a konvence, jež by v README překážely nebo které lidští přispěvatelé jednoduše nepotřebují.“

(agents.md, přeloženo z angličtiny)

Do září 2025 formát podporoval GitHub Copilot Coding Agent (changelog, 28.08.2025). V prosinci se přidaly Cursor, Junie, Gemini CLI, Aider a další tucet nástrojů. Dne 9. prosince 2025 Linux Foundation založila Agentic AI Foundation (AAIF): jejími třemi zakládajícími projekty byly AGENTS.md od OpenAI, MCP od Anthropic a goose od Blocku. Zakládajícími členy byly AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft a OpenAI. K 24. únoru 2026 nadace zahrnovala už 146 organizací, včetně Red Hatu, ServiceNow, Akamai, Lenova, JPMorgan Chase, Huawei, UiPath a Hitachi.

Od té chvíle přestal být AGENTS.md „další věcí od OpenAI“ a stal se de facto standardem.

Které AI agenty čtou AGENTS.md a které ne?#

Tabulka podpory k 30. květnu 2026; řádek Claude Code byl aktualizován 24. září 2026:

Anthropic se připojil jako poslední z hlavních hráčů. V srpnu 2025 bylo v oficiálním repozitáři anthropics/claude-code otevřeno issue #6235 s žádostí o podporu AGENTS.md.

Issue zůstala otevřená téměř rok a byla uzavřena 17. srpna 2026; verze 2.1.277 s podporou AGENTS.md vyšla 18. září. Logika Anthropic je následující: CLAUDE.md má přednost a AGENTS.md se čte, pokud v pracovní složce ani v žádné nadřazené složce není CLAUDE.md. Podle dokumentace to funguje takto:

Háček: počítá se i osobní CLAUDE.local.md; v takovém případě Claude Code přestane číst AGENTS.md. Toto chování lze změnit v /config v části Project instructions, například nastavit Claude Code, aby četl oba soubory současně. Ve verzích starších než 2.1.277 se AGENTS.md automaticky nenačte; řešením je stále řádek @AGENTS.md v CLAUDE.md.

V čem se AGENTS.md liší od CLAUDE.md a .cursorrules?#

Srovnání čtyř formátů k 30. květnu 2026:

Klíčová myšlenka: AGENTS.md řeší problém „jeden soubor pro všechny agenty“, ale ne problém „osobní nastavení, která nechci commitovat“. Claude Code má pro tento účel CLAUDE.local.md a Cursor má lokální soubory .mdc pod uživatelem. Samotný AGENTS.md tuto možnost nenabízí — je potřeba kombinovat ho s dalšími soubory nebo se v týmu dohodnout na zapisování osobních pravidel do částí ignorovaných Gitem.

Dalším důležitým detailem jsou monorepozitáře. Codex a Cursor uplatňují pravidlo „platí nejbližší AGENTS.md“:

„V monorepozitáři umístěte samostatný AGENTS.md do každého balíčku. Agenti automaticky čtou nejbližší soubor ve stromu adresářů a platí ten nejbližší.“

(agents.md, přeloženo z angličtiny)

agents.md uvádí, že hlavní monorepozitář OpenAI obsahuje 88 souborů AGENTS.md pro různé dílčí balíčky. Pokud pracujete v monorepozitáři, rozdělte pravidla do jednotlivých úrovní: obecná do kořene a konkrétní do podsložek.

Co by měl dobrý AGENTS.md obsahovat?#

Web agents.md nabízí flexibilní formát — „libovolný Markdown“. Ale 80 % dobrých souborů v praxi obsahuje stejných osm sekcí. Hlavní pravidlo: každá položka by měla být přesný příkaz nebo konkrétní příklad. Abstraktní myšlenku typu „pište čistý kód“ bude agent ignorovat.

1. Přehled projektu — 2–3 řádky. Co je projekt, komu slouží a jaký je jeho hlavní cíl. Bez marketingu. Příklad: „Telegramový bot pro onboarding do placeného workshopu. Stack: Next.js 14, Prisma, PostgreSQL. Spouští se po vytvoření nového záznamu v purchases.“
2. Příkazy pro nastavení — přesné příkazy shellu pro lokální spuštění. npm install, npm run dev, npm run build. Žádné „takhle to obvykle děláme“.
3. Styl kódu / konvence — konkrétní pravidla s příkladem, ne „pište čistě“. Například: „TypeScript strict, jednoduché uvozovky, žádné výchozí exporty, názvy komponent v PascalCase, hooky začínají na use.“
4. Tipy k vývojovému prostředí — kde jsou důležité věci. Jaké proměnné jsou potřeba v .env, kde jsou uložená tajemství, které porty jsou obsazené a jak pracovat s lokální DB.
5. Pokyny k testování — jak spustit konkrétní test a co se považuje za „zelený“ výsledek. Například: npm test -- --testPathPattern=user-auth; očekává se 100% úspěšnost.
6. Pravidla pro PR / commity — formát zprávy o commitu, kontrolní seznam před PR (testy, linter, dokumentace) a kdo schvaluje.
7. Bezpečnostní aspekty — co se nesmí stát. „Nikdy necommitujte .env. Tajemství patří pouze do Vaultu. Osobní údaje uživatelů nevypisujte do logů.“
8. Hranice / Nikdy nedělat — zákazy spolu s alternativou. „Na main nepoužívejte git push --force. Pokud potřebujete vrátit změny, použijte git revert nebo git reset na feature branchi.“

V každé sekci se držte principu „příkaz místo myšlenky“. Agent bude ignorovat „dávejte pozor na migrace“. Poslechne „Před alembic upgrade head spusťte alembic check. Pokud nahlásí chybu, migraci neprovádějte a zeptejte se mě“.

Hotová šablona AGENTS.md k použití (zkopírujte a upravte)#

# AGENTS.md

## Project overview

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

## Setup commands

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

## Dev environment

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

## Code style

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

## Testing

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

## Pull request guidelines

- 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

## Security

- 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

## Never do this

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

V průměru má šablona 80–120 řádků. Pokud soubor přesahuje 150 řádků, je to signál k refaktoringu: přesuňte něco do docs/, odkažte na další informace nebo obsah zkraťte na jeden řádek. V praxi nejlépe fungují soubory o 100–150 řádcích; po překročení této hranice se přínosy pro kvalitu začínají obracet.

Kterých 5 pravidel dělá AGENTS.md opravdu užitečným?#

1. Příkazy místo obecných myšlenek. Agent nerozumí pokynu „dávejte pozor na migrace“. Poslechne alembic check před alembic upgrade head. Agenti pracují s příkazy a podmínkami, ne s náladami. Všechna klíčová pravidla formulujte jako „udělej X, jinak Y“.

2. Zákazy s alternativou. Samotné „nedělej force push“ agent po dvou nebo třech zadáních potichu ignoruje. Funguje spojení „nedělej X; místo toho udělej Y“. Příklad: „Na main nepoužívej git push --force; pokud potřebuješ vrátit změny, použij git revert nebo otevři nové PR.“

3. Právě jeden zdroj pravdy. Kořenový AGENTS.md je zdrojem pravdy pro celý projekt. Pokud máte monorepozitář, používejte v podsložkách vnořené soubory AGENTS.md a řiďte se pravidlem „platí nejbližší“. Žádné souběžné soubory s konfliktními pokyny.

4. Ověřitelná kritéria pro stav „hotovo“. „Testy musí projít“ je k ničemu. Přesné kritérium: npm test vrátí návratový kód 0 a na stdout nevypíše FAIL. „Kód musí být čistý“ je také k ničemu. Přesné kritérium: npm run lint proběhne bez varování. Agent pochopí, co znamená „hotovo“, jen když výslovně popíšete podmínku.

5. Soubor kratší než 150 řádků. Nad 150 řádky se metriky začínají zhoršovat: agent spotřebuje více kontextu čtením a přehlédne důležitá pravidla. Pokud se obsah nevejde, přesuňte podrobnosti do docs/architecture.md a odkažte na něj z AGENTS.md; v souboru ponechte pouze příkazy a hranice.

Jakých 10 chyb promění AGENTS.md v odpad?#

1. Vágní pravidla bez příkazů. Agent bude ignorovat „dávejte pozor na migrace“ — tahle věta pro něj nic neznamená. Funguje pouze konkrétní příkaz s podmínkou: „Před alembic upgrade head spusť alembic check. Pokud se objeví chyba, migraci neprováděj a zeptej se mě.“

2. „Čistý kód.“ Nepoužitelná fráze. Nahraďte ji konkrétním vzorem: „Používejte funkční komponenty s hooky. Příklad: function LoginForm() { const [email, setEmail] = useState(''); ... }“

3. Nečleněný text. Pokud má AGENTS.md 300 řádků prózy bez nadpisů, agent stráví 80K kontextových tokenů nepodstatnými pasážemi a přehlédne to důležité. Používejte nadpisy H2/H3, krátké části a odrážkové seznamy.

4. Soubor delší než 150 řádků. Po překročení tohoto limitu se metriky kvality zhoršují. Rozdělte obsah mezi hlavní soubor a odkazy na podrobnosti v docs/.

5. Více než 30 zákazů bez alternativ. Pokud soubor obsahuje dlouhý seznam „nedělej X, nedělej Y“ bez vysvětlení „místo toho udělej Z“, agent bude tápat.

6. Duplikování README.md. Pokud už jste v README napsali „jak instalovat a spustit“, nekopírujte to do AGENTS.md. Místo toho odkažte na README v jednom řádku a popište v AGENTS.md to, co potřebuje agent, ale ne lidští přispěvatelé.

7. Natvrdo zapsaná tajemství. AGENTS.md může být veřejný (je v Gitu). Žádné skutečné API klíče, tokeny ani hesla. Uvádějte pouze odkazy na úložiště tajemství: „Viz Vault: secret/staging/db.“

8. Konfliktní priority bez pořadí. „Postupujte rychle“ + „udržujte 90% pokrytí testy“ nechává agenta na pochybách, čemu dát přednost. Seřaďte je výslovně: „Nejdřív pokrytí testy ≥80 %, potom rychlost. Pokud jsou v konfliktu, přednost mají testy.“

9. Zastaralá dokumentace. Popis architektury uvádí REST + polling, ačkoli ve skutečnosti už používáte WebSockets. Agent se řídí zastaralým popisem a naruší architekturu. Pravidlo: aktualizujte AGENTS.md ve stejném PR jako kód vždy, když se změní architektura.

10. Zbytečně složitá architektura pro jednoduchý úkol. Pokud někdo požádal o změnu dvou řádků v konfiguraci, agent by neměl číst celou topologii 14 mikroslužeb. Přesuňte „hlubokou“ architekturu do docs/architecture.md; v AGENTS.md ponechte jen „pokud je úkol architektonický, přečti si docs/architecture.md“.

Studie blogu GitHubu o více než 2 500 repozitářích AGENTS.md uvádí hlavní závěr:

„Většina souborů pro agenty selhává, protože jsou příliš obecné. ‚Jsi užitečný programovací asistent‘ nefunguje.“

(GitHub Blog, přeloženo z angličtiny)

Jak mít AGENTS.md a CLAUDE.md v jednom repozitáři?#

Hlavní praktickou otázkou je, jak používat oba soubory bez duplikování obsahu. Jsou tři scénáře:

Scénář 1: pouze Claude Code. Ponechte CLAUDE.md a využijte všechny funkce Claude Code: ~/.claude/CLAUDE.md pro pokyny na úrovni uživatele, CLAUDE.md pro projekt, CLAUDE.local.md pro osobní přepsání, @import pro zahrnutí dalších souborů a .claude/skills/ pro specializované dovednosti. AGENTS.md není potřeba.

Scénář 2: více programátorských klientů. Společná pravidla ponechte v AGENTS.md a každého klienta připojte a ověřte zvlášť. Gemini CLI podporuje nastavitelný název kontextového souboru; Aider může soubor načíst přes konfiguraci čtení. Jde o výslovné způsoby načítání, nikoli stejné automatické hledání.

Založte novou relaci v neškodném testovacím repozitáři, přidejte jedinečný neškodný pokyn, například „do testovací odpovědi vlož značku instructions-loaded“, a vedle odpovědi zkontrolujte také zdokumentovaný přehled načtených souborů či logy klienta. Opakujte pro každého skutečně používaného klienta a verzi. Vygenerované tvrzení, že soubor přečetl, není nezávislým důkazem načtení; z jednoho úspěšného testu nevyvozujte podporu ve všech ostatních nástrojích.

Scénář 3: smíšený tým (Claude Code + další nástroje). V roce 2026 jde o nejběžnější nastavení. Řešením je udělat z AGENTS.md hlavní soubor. Pokud nemáte pravidla určená pouze pro Claude Code, CLAUDE.md vůbec nevytvářejte: od verze 2.1.277 čte Claude Code AGENTS.md, pokud v projektu není CLAUDE.md. Pokud taková pravidla máte, vytvořte z CLAUDE.md symbolický odkaz nebo krátký soubor, který načítá AGENTS.md pomocí @AGENTS.md.

Před změnou soubory prohlédněte a oba zálohujte. Existují-li oba, slučte nekonfliktní společné instrukce do AGENTS.md a specifické instrukce Claude ponechte v CLAUDE.md s importem @AGENTS.md. Existující symbolické odkazy zachovejte, nenahrazujte je.

Pro běžný soubor CLAUDE.md pouze při nepřítomnosti AGENTS.md tato ochrana v shellu macOS/Linux odmítne přepsat existující cíl i symbolický odkaz:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md existuje; nejprve soubory slučte.' >&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: nejprve prohlédněte existující cestu CLAUDE.md.' >&2
fi

Po úspěšném přejmenování je CLAUDE.md symbolickým odkazem na AGENTS.md. Všichni agenti, kteří čtou AGENTS.md, uvidí stejný obsah. Claude Code, které čte CLAUDE.md, uvidí tentýž obsah přes symbolický odkaz.

Ve Windows vyžaduje vytvoření symbolického odkazu Developer Mode (nebo oprávnění správce), což nemusí být pro celý tým praktické. Alternativou je krátký CLAUDE.md, který importuje AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

V Claude Code tato syntaxe načte AGENTS.md jedním řádkem a doplní pod něj specifické pokyny pro Claude Code. Pokud později budete chtít AGENTS.md odstranit, stačí smazat import. Tento řádek nezpůsobí dvojí načtení: podle dokumentace Claude Code nenačte stejný AGENTS.md dvakrát, ani když ho dokáže přečíst samo.

Kanoniální uspořádání pro tým s více nástroji v roce 2026:

repo-root/
├── AGENTS.md                              # zdroj pravdy, ≤150 řádků
├── CLAUDE.md                              # jen pokud existují pravidla pro Claude: symbolický odkaz → AGENTS.md NEBO @AGENTS.md + doplňky
├── .cursor/rules/                         # cílená přepsání pouze pro Cursor
├── .github/copilot-instructions.md        # „Viz AGENTS.md“, pokud se používá
└── docs/architecture.md                   # podrobná architektura, na kterou odkazuje AGENTS.md

Více o CLAUDE.md najdete v průvodci „Jak správně nastavit CLAUDE.md“. Další souvislosti o tom, proč agent potřebuje rozsáhlý soubor s pokyny, najdete v článku „Co je context engineering“.

Co se změnilo v roce 2026: proč AAIF přivedla AGENTS.md pod Linux Foundation?#

Hlavním politickým příběhem května 2026 v oblasti programování s AI nebylo vydání dalšího modelu, ale sjednocování formátů. Dříve měl každý dodavatel vlastní soubor s pravidly, což bylo pohodlné pro dodavatele, ale bolestivé pro týmy pracující s několika nástroji.

V tiskové zprávě z 9. prosince 2025 Linux Foundation oznámila Agentic AI Foundation jako zastřešení tří formátů:

• AGENTS.md od OpenAI — formát souboru s pokyny pro agenty
• Model Context Protocol (MCP) od Anthropic — protokol pro připojení externích nástrojů k agentům
• goose od Blocku — open source framework pro agenty

Z tiskové zprávy Linux Foundation:

„Spojení těchto projektů pod záštitou AAIF zajišťuje, že se mohou rozvíjet s transparentností a stabilitou, které může poskytnout pouze otevřená správa.“

(tisková zpráva Linux Foundation, 9. prosince 2025, přeloženo z angličtiny)

K 24. únoru 2026 patřilo do AAIF 146 organizací (97 nových členů za dva měsíce). Novými zlatými členy se staly Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express a Autodesk. Anthropic je na platinové úrovni a prosazuje MCP. OpenAI je na platinové úrovni a prosazuje AGENTS.md. Block je na platinové úrovni s goose.

Tím se mění pozice AGENTS.md: z „formátu OpenAI“ na oborový standard. Na jaře 2026 byl Claude Code stále stranou, ale v září se ve verzi 2.1.277 naučil číst AGENTS.md samostatně. CLAUDE.md nezmizel a ve výchozím nastavení má stále přednost, pokud se v projektu nachází.

Praktickým výchozím bodem jsou společná pravidla projektu v AGENTS.md a import, obalový soubor nebo výslovná konfigurace čtení, které vyžaduje každý používaný klient. U Claude Code ověřte nainstalovanou verzi a přednost souborů s pokyny, než zvolíte import v CLAUDE.md nebo symbolický odkaz. Načtení ověřte v každém klientovi; tento návod nestanovuje procento pokrytých scénářů.

Co dál#

AGENTS.md je první stavební kámen „jak se s agentem domluvit, aby pracoval předvídatelně“. Následuje druhý stavební kámen — složka se znalostmi o projektu, která obsahuje obchodní kontext, publikum, produkty a ceny. Třetím stavebním kamenem je context engineering, který vše propojuje: které soubory agent vidí v každém kroku, jak se zachovává stav mezi relacemi a jak přecházet mezi různými modely.

Praktické materiály: dokumentace Ailoot.

Další materiály a nástroje: Ailoot.