Co je AGENTS.md?
AGENTS.md je otevřený formát, kterým dáte AI coding agentům kontext potřebný k práci v kódu. Je to obyčejný soubor v Markdownu, obvykle uložený v rootu repozitáře. Jsou v něm provozní znalosti, které agent z kódu sám nevyčte: příkazy pro build a testy, pravidla stylu kódu, konvence code review a omezení, která si nikdo nedal práci sepsat.
Formát vznikl z problému, který měli všichni stejný. Každý coding agent si zavedl vlastní soubor s instrukcemi, takže tým s víc než jedním nástrojem udržoval stejná pravidla třikrát. AGENTS.md je slučuje do jediného souboru, který čte celá řada nástrojů. Vzešel z práce na OpenAI Codexu, Ampu, Julesovi, Cursoru a Factory. Dnes ho zastřešuje Agentic AI Foundation pod Linux Foundation. Web formátu uvádí 23 nástrojů, které ho čtou, a přes 60 000 open-source repozitářů, kde ho najdete.
Žádné schéma ani povinný seznam sekcí neexistuje. Agent soubor čte jako běžný text, takže obyčejné nadpisy a krátké věty v rozkazovacím způsobu fungují lépe než vymyšlená struktura.
Lidsky řečeno
V pondělí vám nastupuje externista. Nedáte mu do ruky firemní brožuru. Řeknete mu, jak se spouští aplikace, do kterého adresáře nemá sahat a jak tým formuluje commit message. AGENTS.md je přesně takový vzkaz. Napíšete ho jednou, necháte ho v repozitáři a on pak zaučuje kolegu, který si nepamatuje včerejšek a každou relaci začíná od nuly.
Jak to funguje
Celý mechanismus je záměrně nudný. Přesně o to jde.
- Jeden soubor, obyčejný Markdown. Žádné schéma, žádný frontmatter, žádný krok navíc při buildu. Nadpisy si zvolíte podle projektu.
- Platí nejbližší soubor. Když agent upravuje soubor, hledá nejbližší AGENTS.md nad ním ve stromu adresářů. Pravidla balíčku tedy přebijí pravidla celého repozitáře.
- V monorepu soubory zanořujte. Místo jednoho rozbujelého souboru v rootu dejte jeden do každého balíčku. Repozitář OpenAI jich obsahuje 88.
- Váš prompt má pořád přednost. Soubor nastavuje výchozí chování. Výslovný pokyn v chatu přebije cokoli, co v něm stojí.
- Migrace je přejmenování. Kdo přechází ze souboru vázaného na jeden nástroj, přejmenuje ho na AGENTS.md a nechá po něm symlink kvůli zpětné kompatibilitě.
AGENTS.md vs CLAUDE.md
Oba soubory odpovídají na stejnou otázku a liší se v tom, komu patří, ne v tom, co umí. CLAUDE.md je vlastní konvence Claude Code. AGENTS.md je společná konvence pro víc nástrojů. Proto v repozitářích, kde běží několik agentů vedle sebe, najdete tentýž obsah dvakrát.
Vyberte jeden soubor jako zdroj pravdy a druhý na něj nasměrujte. Buď symlinkem, nebo jednořádkovým CLAUDE.md, který ten druhý naimportuje — dokumentace Claude Code doporučuje přesně to. Dva soubory se stejnými pravidly se dřív nebo později rozejdou a instrukce, které si odporují, škodí víc než žádné instrukce.
Proč na tom záleží
Agent si na začátku každé relace nepamatuje o vašem projektu nic. Bez psaného zadání bude hádat, a hádat bude věrohodně, ne správně.
- Přestanete opakovat stejnou opravu. „Používej pnpm, ne npm“ patří do souboru, ne do každé druhé zprávy v chatu.
- Přežije výměnu nástroje. Jeden soubor obslouží Codex, Cursor, Copilot i zbytek, takže přechod na jiného agenta není migrační projekt.
- Podléhá review jako kód. Pravidla žijí v gitu a chodí přes pull requesty jako každý jiný soubor.
- Funguje ve velkém i v malém. Díky zanořenému souboru si jeden balíček vynutí pravidlo, které by v rootu nedávalo smysl.
Na co si dát pozor
Většina toho, co vám šablony radí do souboru napsat, se nezaplatí.
Vyplývá to ze studie, která si otázku položila přímo: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? Gloaguen, Mündler, Müller, Raychev a Vechev (arXiv, únor 2026) pustili coding agenty na úlohy ze SWE-bench. Vybrali repozitáře, do kterých už vývojáři vlastní soubor s kontextem dřív přidali. Závěr zněl nesmlouvavě: kontextové soubory „obecně nezlepšují úspěšnost řešení úloh, zatímco cenu inference zvyšují v průměru o víc než 20 %“. Platilo to u všech modelů i agentů, které vyzkoušeli. Výslovné pokyny agenti spolehlivě dodržovali. Co se nevyplatilo, byl přehled repozitáře, tedy sekce, kterou každá šablona staví na první místo.
Pište ho tedy méně. Ne vůbec.
- Vynechte přehled, nechte příkazy. Kód si agent přečte sám. Neuhádne ale, že integrační testy potřebují běžící kontejner nebo že jeden adresář je generovaný a nikdo do něj nesmí sahat ručně.
- Každý řádek stojí tokeny při každém běhu. Soubor o 400 řádcích platíte znovu v každé relaci. Sepište deset věcí, které se rozbíjejí, ne prohlídku projektu.
- Zastaralá pravidla matou. Příkaz, který přestal fungovat v březnu, bude agent v srpnu poslušně volat. Berte soubor jako kód a upravujte ho ve stejném pull requestu, který mění chování.
- Nikdy do něj nedávejte citlivé údaje. Soubor jde do gitu, indexuje se a čtou ho nástroje třetích stran. Přihlašovací údaje patří do secret manageru.
- Raději zanořujte, než abyste přidávali. Jakmile se v root souboru začnou množit věty typu „v API balíčku ale…“, říká si to pravidlo o vlastní soubor v balíčku API.
Související články
- Context engineering: dovednost, která rozhoduje o kvalitě vývoje s AI – Proč na tom, co dáte do kontextového okna, záleží víc než na samotném promptu.
- Co to je Agent? – Krátká verze: AI, která zvládne úkol sama, jakmile jí zadáte cíl.
- Co je spec-driven development? – Druhá půlka zadání: říct agentovi, co má postavit, ne jen jak má pracovat.
- Claude Code vs Cursor vs Copilot – Jak se nástroje, které tento soubor čtou, liší v praxi.
Chcete být o krok napřed?
Nenechte si utéct naše nejlepší postřehy. Žádný spam, jen praktické analýzy, pozvánky na exkluzivní eventy a shrnutí podcastů přímo do vaší schránky.