Používáš AI coding agenta — Codex, Copilot, Cursor, Gemini CLI — a přepadá tě pocit, že už tisíckrát vysvětluješ to samé. Jaký je build příkaz. Které soubory si nesahat. Že testy běží přes pnpm test, ne npm test. Žes zakázal jednu knihovnu, a přesto ji agent pátý pokus po sobě zase nainstaluje.
AGENTS.md je soubor, který tento problém řeší. Je to verzovaný markdown v kořeni repa, který říká agentovi, jak tvůj kód opravdu funguje. V srpnu 2026 ho čte 30+ nástrojů a spravuje ho Agentic AI Foundation pod Linux Foundation. Pojďme si ukázat, jak ho napsat tak, aby agent jeho instrukce skutečně respektoval.
Proč AGENTS.md a ne jen README
README je pro lidi. Agent ho sice taky vidí, ale čte ho stejně jako ostatní soubory — musí si z něj odvodit, co je důležité. AGENTS.md je prediktibilní místo, kam si agent instrukce natáhne na začátku každé session, hned pod systémový prompt. Má jasnou prioritu a agent s ním pracuje jako se základním kontextem, ne jako s jedním z mnoha souborů.
Druhý důvod je portabilita. Doteď jsi možná udržoval CLAUDE.md pro Claude Code, .cursorrules pro Cursor a .github/copilot-instructions.md pro Copilot. Tři soubory, které si odporují, jakmile jeden zapomeneš aktualizovat. AGENTS.md je vendor-neutralní: jeden soubor, který funguje napříč. Nástrojům, které ho nečtou nativně (hlavně Claude Code), dáš jednoduchý symlink nebo import.
Co do něj patří — a co ne
Nejčastější chyba je nacpat do AGENTS.md všechno. Výzkum ukazuje, že redundance s informacemi, které agent už má z kódu a dokumentace, zvyšuje náklady na tokenu o zhruba 23 % a zároveň ztěžuje agentovi rozpoznat, co je vlastně důležité. Codex má výchozí limit 32 KiB, ale praktická hranice užitečnosti je mnohem níž — kolem 150–200 řádků.
Do souboru patří pouze to, co agent nemůže získat z kódu, manifestů ani existující dokumentace:
| Patří sem | Nepatří sem | Proč |
|---|---|---|
| Pravidla, která se odchylují od defaultů | Standardní jazykové konvence (PEP 8, Prettier) | Agent je už zná |
| Architektonické omezení ("neměň vrstvu X") | Plná API dokumentace | Odkáži, nezabudovávat |
| Projekt-specific gotchas ("nesahat na legacy/") | Bývalé postupy ("piš čistý kód") | Zbytečné, agent se o to snaží už defaultně |
| Přesné build/test příkazy | To, co je už v README | Duplikace snižuje výkon |
Jak ho napsat: čtyři pravidla, která fungují
1. Používej přesné, kopírovatelné příkazy
Slabé: "spusť testy". Lepší: "spusť pnpm test". Nejlepší: "spusť pnpm test --filter web pro testování jen web appky". Agent pak nepátrá, který test runner používáš — prostě to udělá.
2. Tvrdá omezení buď explicitní
Neřikej "čistý kód" nebo "idiomatický" — to se na chování agenta nepřeloží. Místo toho: "Neimportuj z internal/legacy/. Používej const, nikdy var. Nová funkce maximálně 40 řádků." Agent poslouchá konkrétní zákazy mnohem spolehlivěji než adjektiva.
3. Rozděl na "always / ask first / never"
Tento pattern převzal například Sanity ve svém veřejném AGENTS.md a funguje skvěle:
- Always — věci, které agent dělá automaticky (po změně spusť
pnpm lint) - Ask first — věci, které vyžadují potvrzení (instalace nové závislosti, úprava migrace)
- Never — netlaktné zákazy (nesmaž produkční data, nedělej force-push, neupravuj lock soubor ručně)
Autonomní agent se chová mnohem prediktabilněji, když jsou rizika napsaná jako přímé příkazy, ne jako společenské narážky.
4. Drž to krátké pomocí progresivního odkrytí
Máš jazykově-specific pravidla pro TypeScript, Python i SQL? Nedávej je všechna do kořenového souboru. Místo toho:
Pro TypeScript konvence viz docs/TYPESCRIPT.md
Pro SQL migrace viz docs/MIGRATIONS.md
Agent si tyto soubory načte jen tehdy, když píše TypeScript nebo sahá na migrace. Ostatní úkoly neztrácejí tokeny na kontext, který zrovna nepotřebují.
Jak nástroje soubor načítají
Rozdíly v načítání nejsou detail — ovlivňují, kam soubor umístíš a jak strukturuješ:
- Codex (OpenAI): vrstvení shora dolů — globální
~/.codex/AGENTS.md→ kořen repa → aktuální adresář. SouborAGENTS.override.mdmá přednost. Zastaví se při 32 KiB. - Copilot (GitHub): "nejbližší soubor vyhrává". Můžeš dát
AGENTS.mdkdekoli v repu, ten nejblíž upravovanému souboru má přednost. - Kilo: načítá kořen + podadresáře, podadresář přepisuje kořen. Defaultně je soubor chráněný proti přepsání, aby ho agent sám neupravoval.
- Claude Code:
AGENTS.mdnečte nativně, čteCLAUDE.md. Řešení je jednoduché — symlink nebo import.
Kompatibilita: jeden zdroj pravdy
Praktický pattern, který zavedou dospělé týmy: jeden autoritativní AGENTS.md, ostatní soubory z něj derivuj.
# Claude Code: symlink
ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md
Pro Cursor a Gemini analogicky. Tím máš jeden soubor k údržbě a instrukce se nikdy nerozjedou. Pokud používáš jen jeden nástroj, klidně zůstaň u jeho nativního formátu — AGENTS.md se vyplatí, až když přepínáš mezi agenty nebo máš v týmu lidé s různými preferencemi.
Šablona, kterou můžeš zkopírovat
# AGENTS.md
## Projekt
Krátký popis (2–3 věty). Technologický stack: PHP 8.2, Symfony 7, MySQL 8.
## Build a testy
- Build: `docker compose up -d`
- Testy (jedna třída): `bin/phpunit tests/Entity/UserTest.php`
- Testy (vše): `bin/phpunit`
- Statická analýza: `bin/phpstan analyse src --level=6`
## Architektura
- Tenké controllery, logika do service vrstvy
- Entity používají constructor property promotion
- Příkazy přes Symfony Messenger (async transport)
## Always
- Po změně entity spusť `bin/console doctrine:schema:validate`
- Dodržuj `declare(strict_types=1)` v každém souboru
## Ask first
- Přidání nové závislosti do composer.json
- Úprava databázové migrace, která už je v produkci
## Never
- Nesahat na `config/services_prod.yaml`
- Nedělat `git push --force` na main
- Nevypisovat do kódu API klíče ani hesla
Tato šablona má 25 řádků. Agent ji načte celou, pochopí ji a bude se jí řídit. Kdyby měla 500 řádků, polovinu by ignoroval.
Bezpečnost: co do souboru nikdy nedávat
AGENTS.md je agent-visible kontext. Cokoli do něj napíšeš, může skončit v promptu, který agent pošle modelu. Nikdy tam nedávej:
- API klíče, tokeny, hesla
- Zákaznická data
- Skryté provozní předpoklady, které nechceš vidět v logu
Tajemství patří do .env (který je v .gitignore) nebo do CI/CD secretů. AGENTS.md je verzovaný soubor — představ si, že ho přímo uvidí každý, kdo má přístup k repu.
Kdy stojí za to přidat podadresářový AGENTS.md
Monorepo s několika subprojekty? Codex jich v hlavním repu OpenAI má 88. Pravidlo je jednoduché: kořenový AGENTS.md obsahuje pravidla platná všude, podadresářové soubory přidávají specifika pro daný subtree. Frontend appka pak má vlastní pravidla pro React konvence, backend pro databázové migrace. Agent si načte jen to relevantní.
Shrnutí
AGENTS.md není další soubor k údržbě — je to jedna z nejlevnějších, nejvyšších-leverage investic, které můžeš udělat pro práci s AI agenty. Začni krátkým souborem (50 řádků), sleduj co agent dělá špatně, postupně přidávej konkrétní pravidla. Za měsíc se divíš, že už agenta nemusíš opravovat stokrát denně.
Klíčové principy: přesné příkazy místo adjektiv, explicitní zákazy místo narážek, progresivní odkrytí místo jednoho obřího souboru, a nikdy tajemství. Pokud používáš více nástrojů, drž jeden autoritativní AGENTS.md a ostatní z něj symlinkuj. Tvůj agent (i ty sám) to oceníš.
