AGENTS.md a CLAUDE.md: 9 tipů, jak psát pravidla pro AI

Soubor s pravidly pro AI agenta vypadá jako nejjednodušší část práce: pár vět v Markdownu. Právě na něm se ale nejsnáz ukáže, že se pravidla a skutečnost rozjedou. V repozitáři tohoto webu mám CLAUDE.md i AGENTS.md a 20. října 2026 jsem při přípravě tohoto článku zjistil, že už nejsou stejné. Z toho vychází devět tipů níže, u každého s příkladem z vlastního repa.

Co je harness a proč jsou tyto soubory jeho součástí, vysvětluje článek o harnessu. Tady jde o praxi: co do souborů psát, jak je udržet pohromadě a co nesvěřovat jen větě.

Co je AGENTS.md a co je CLAUDE.md?

AGENTS.md je prostý Markdown v kořeni repozitáře. Web agents.md ho popisuje jako „README pro agenty“: README je pro lidi, AGENTS.md pro programovací agenty. Formát vznikl ve spolupráci OpenAI Codex, Amp, Jules od Googlu, Cursoru a Factory a dnes ho spravuje Agentic AI Foundation pod Linux Foundation. Žádná pole nejsou povinná. Doporučené sekce jsou přehled projektu, příkazy pro build a testy, styl kódu, testování a bezpečnost.

CLAUDE.md je totéž pro Claude Code. Podle dokumentace se CLAUDE.md i auto memory (poznámky, které si Claude píše sám) načtou na začátku každé session a Claude s nimi zachází jako s kontextem, ne jako s vynucenou konfigurací.

AGENTS.md čte přes 20 nástrojů, takže se hodí jako společný základ: například Codex, Cursor, GitHub Copilot coding agent, OpenCode, Aider, Zed nebo Warp. OpenCode ho po příkazu /init vytvoří sám. Programovací agenty s otevřeným zdrojem (OpenCode, Codex CLI, Gemini CLI) shrnuji v přehledu open-source AI projektů.

Jaký je rozdíl mezi AGENTS.md a CLAUDE.md?

Rozdíl není ve formátu, oba jsou Markdown, ale v tom, kdo soubor čte a jak se pravidla skládají.

Claude Code navíc nečte AGENTS.override.md ani AGENTS.local.md. Přepisující soubor je věc Codexu.

Jak Claude Code a Codex pravidla načítají?

Oba nástroje skládají pravidla z několika míst, ale každý jinak.

• Claude Code pravidla spojuje, nepřepisuje: čte od nadřazených složek k pracovní a bližší složka přijde později. Soubory v podsložkách se načtou až ve chvíli, kdy Claude sáhne na soubor v nich. Odporují-li si dvě věty, může Claude jednu z nich zvolit libovolně.
• Codex čte globální ~/.codex a pak od kořene projektu (git) dolů k aktuální složce, v každé nejvýš jeden soubor. Texty se spojí shora dolů a bližší soubor přebíjí dřívější pokyny.

Potřebuji AGENTS.md i CLAUDE.md, nebo stačí jeden?

Záleží na tom, co už v repozitáři máte. Tabulka vychází z dokumentace Claude Code, stav 20. 10. 2026.

Do kontroly „je tu CLAUDE.md?“ se nepočítají váš ~/.claude/CLAUDE.md, organizační CLAUDE.md ani soubory v .claude/rules/. Počítá se ale CLAUDE.local.md: přidáte-li ho do projektu, který stojí na AGENTS.md, Claude Code přestane AGENTS.md číst.

Dokumentace nabízí tři cesty ke sdílení jednoho souboru: import @AGENTS.md z CLAUDE.md, symlink z CLAUDE.md na AGENTS.md, nebo v /config nastavit Project instructions na claude-md-and-agents-md. Na Windows volím import. Dokumentace upozorňuje, že symlink tam vyžaduje práva správce nebo Developer Mode a Git ho bez nastavení core.symlinks vyexportuje jako textový soubor s jedním řádkem.

@AGENTS.md

## Jen pro Claude Code
- Sem patří jen to, co se týká Claude Code, například hooky nebo skills.

Importovaný soubor se čte první, pokyny pod ním až po něm.

Jak psát pravidla pro AI? Devět tipů z praxe

Tipy vycházejí z dokumentace Claude Code, Codexu a agents.md a z mého repa. U každého uvádím, odkud příklad je.

1. Držte jednu pravdu místo dvou kopií

CLAUDE.md a AGENTS.md v repozitáři tohoto webu byly původně kopie téhož textu. K 20. 10. 2026 měl CLAUDE.md 46 řádků a AGENTS.md 56 řádků a při porovnání k tomuto datu se liší ve dvou věcech:

• Verze Reactu. AGENTS.md uvádí React 19, package.json má react 18.3.1. CLAUDE.md má správně 18.3.
• Tři odrážky jen v AGENTS.md: nadpisy s velkým počátečním písmenem, žádné dlouhé pomlčky, vykání a první osoba; nezasahovat do titulků článků v běžícím testu; nespouštět next build a next start, když ve složce běží vývojový server nebo pracuje jiný agent.

Důsledek vychází z dokumentace: Claude Code čte AGENTS.md jen tehdy, když ve složce ani výš není CLAUDE.md. Tady CLAUDE.md je, takže by pravidla o nadpisech, pomlčkách a buildu Claude Code ve výchozím nastavení nedostal. Codex naopak čte AGENTS.md a místo správného Reactu 18.3 dostane chybné 19.

Od té doby se soubory rozešly ještě víc: 21. 10. 2026 jsem do AGENTS.md přidal pravidla o psaní v první osobě jednotného čísla a o zveřejňování jmen týmu, takže má k 22. 10. 2026 67 řádků, zatímco CLAUDE.md má stále 46. Počty řádků proto uvádím vždy s datem.

Řešení je malé: AGENTS.md jako jediný zdroj a CLAUDE.md s řádkem @AGENTS.md a pokyny jen pro Claude. K 22. 10. 2026 jsem to v repu ještě neudělal. Takhle už funguje můj globální ~/.claude/CLAUDE.md: obsahuje import sdíleného AGENTS.md z mé knihovny pravidel a pod ním jen pokyny specifické pro Claude. Úpravu dělám na jednom místě.

2. Pište věty, které jde ověřit

Dokumentace Claude Code uvádí jako vzor věty typu „Odsazuj dvěma mezerami“ (místo „Formátuj kód správně“) a „Před commitem spusť npm test“. Podle toho se pozná dobré pravidlo: dá se zkontrolovat.

V mém AGENTS.md stojí, že titulky, H1 a H2 začínají velkým písmenem (vlastní jména a zkratky jako AI Act, Kč nebo SEO se píšou, jak se píšou) a že dlouhá pomlčka se jako oddělovač nepoužívá, místo ní čárka, dvojtečka nebo svislítko. Po práci stačí projít nadpisy. U věty „piš kvalitně“ by se neshodli ani dva lidé.

3. U zákazu uveďte důvod a datum

V AGENTS.md mého repa je u pravidla o nadpisech poznámka: 3. 10. 2026 skript převedl 91 titulků a 275 nadpisů na malá písmena, opraveno ručně, znovu ho nespouštět. Pravidlo má tím příčinu a stáří. Agent z něj pozná, jak daleko zákaz sahá, a vy za rok vidíte, jestli ještě platí. Podle mé zkušenosti zákaz bez důvodu působí jako libovůle a hůř se udržuje.

4. Držte soubor krátký a zbytek rozdělte

Claude Code doporučuje do 200 řádků na soubor, delší soubory spotřebují víc kontextu a snižují dodržování pravidel. Import přes @cesta pomáhá s přehledností, ale kontext nešetří, protože se importované soubory načtou při startu. Věci pro část projektu patří do .claude/rules/*.md s polem paths:, které se načtou jen při práci s odpovídajícími soubory, a opakované postupy do skills. U monorepa doporučuje agents.md AGENTS.md v každém podprojektu, platí nejbližší. Codex spojený text omezuje na 32 KiB.

Moje dva soubory (CLAUDE.md a AGENTS.md) měly k 20. 10. 2026 46 a 56 řádků, k 22. 10. 2026 mají 46 a 67. Podrobnosti jsou jinde (strategie SEO ve složce docs/seo/, ceny v datových souborech služeb) a soubor jen říká, kde je hledat.

5. Odkazujte na zdroj pravdy, nekopírujte ho

Pravidlo o cenách v mém repu zní, že ceník je kanonický a zdroj je src/data/services/*.ts. Žádná čísla v něm nejsou, jen místo, kde pravda leží. Číslo v souboru pravidel by byla třetí kopie, která zastará. A podle dokumentace může agent při rozporu dvou vět zvolit libovolnou.

6. Co se nikdy nesmí stát, vynuťte nástrojem

Dokumentace Claude Code to říká přímo: CLAUDE.md je kontext, ne vynucená konfigurace, a k zablokování akce slouží hook PreToolUse. Vrstvy ochrany vypadají takto:

Dva příklady z praxe:

• Lint. npm run seo:content:lint vznikl 22. 8. 2026 po dni ručního hledání vymyšlených referencí, agenturního plurálu místo první osoby jednotného čísla, cen mimo ceník a prázdných řádků uvnitř figur. Při nálezu chyby skončí s kódem 1, takže pravidlo nezávisí na tom, jestli si ho agent přečetl.
• Hook. V globálním nastavení Claude Code mám hook PreToolUse pro příkazy v terminálu. Skript při vzorci, který plýtvá kontextem, skončí s kódem 2 a modelu pošle zprávu, jak to udělat levněji. Není to bezpečnostní hranice, ale ukázka mechanismu: pravidlo, které nástroj skutečně vynutí.

7. Napište příkazy pro ověření a kdy je nespouštět

agents.md uvádí, že agenti se uvedené testy pokusí spustit. Příkaz proto patří do souboru a patří k němu i výjimka. V mém repu stojí, že po změnách SEO musí projít npx tsc --noEmit a npm run build, že starší chyby tsc v src/app/api/cv-pdf a src/lib/cv/pdf-cache.ts se ignorují, ale nové ne, a že se next build a next start nespouští, když ve složce pracuje jiný agent, protože se rozbije sdílený výstup buildu. Poslední pravidlo vzniklo z práce více agentů v jedné složce.

Příklad zároveň ukazuje past z prvního tipu: výjimka je jen v AGENTS.md. Claude Code, který čte CLAUDE.md, se dozví, že build musí projít, ale ne kdy ho nespouštět.

8. Veďte deník pro předávku mezi sessions

Pravidla popisují, jak projekt funguje, ne co se právě dělá. Proto mám docs/worklog.md: nejnovější záznam nahoře, ve tvaru Hotovo, Rozhodnuto, Dál, Otevřené, nejvýš osm řádků. Hook na začátku session vloží do kontextu horních zhruba 45 řádků, takže se celý soubor nečte. Při /clear a /compact doplňuje záznam další hook.

Dokumentace k tomu přidává: CLAUDE.md v kořeni projektu přežije /compact, ale pokyn zadaný jen v konverzaci ne. Co má platit dál, patří do souboru.

9. Pravidelně kontrolujte, co agent opravdu načetl

• Claude Code: /memory ukáže načtené soubory (u přímo čteného AGENTS.md i jeho cestu), /context spotřebu kontextu. /doctor prompt-audit (od verze 2.1.283) hledá pokyny psané pro starší modely, odkazy na neexistující soubory a příkazy a soubory, které si odporují. Vrátí zprávu s návrhy úprav a nic nezmění, dokud o to nepožádáte.
• Codex: příkaz codex --ask-for-approval never "Summarize the current instructions." vypíše, jaké pokyny nástroj vidí.

Rozjetí mých dvou souborů jsem našel prostým porovnáním obou textů. Nejde o složitý nástroj, stačí si kontrolu naplánovat.

Jak vypadá vzorový AGENTS.md?

Kostra podle sekcí doporučených na agents.md. Názvy složek a příkazy jsou ilustrační, upravte je podle projektu. Podle mé zkušenosti stojí za to psát hlavně to, co z kódu nepoznáte.

# AGENTS.md

## Přehled projektu
Co projekt dělá, pro koho, jaký má stack a verze (podle package.json).

## Příkazy
- Instalace: `npm install`
- Vývoj: `npm run dev`
- Test: `npm test` (před každým commitem)
- Lint: `npm run lint`
- Nespouštěj `npm run build`, když ve složce běží vývojový server nebo pracuje jiný agent.

## Styl kódu
- TypeScript, odsazení dvěma mezerami.
- Komponenty PascalCase, soubory kebab-case.

## Zdroje pravdy
- Ceny jsou v `src/data/prices.ts`. Nekopíruj je do textů ručně.
- Překlady jsou ve složce `messages/`.

## Co se nesmí
- Nemaž složku `migrations/` (RRRR-MM-DD: důvod, proč pravidlo vzniklo).

## Bezpečnost
- Nikdy nevypisuj ani necommituj hodnoty z `.env`.

## Předávka
- Po práci doplň horní část `docs/worklog.md`: hotovo, rozhodnuto, otevřené (nejvýš 8 řádků).

Většinu tipů z článku v kostře poznáte: ověřitelné věty, zdroj pravdy místo kopie, příkaz s výjimkou, zákaz s důvodem a datem a deník pro předávku.

Co o psaní pravidel říká komunita?

Samotná vlákna jsem neotevíral. Vycházím z náhledů výsledků Googlu u r/ClaudeAI, takže jde o názor komunity, ne o data:

• držet soubor pod 200 řádků,
• skills nechat na „jak psát kód“ a CLAUDE.md na „jak funguje tento projekt“,
• dělit soubory po složkách,
• vést předávací soubor „co jsem zkoušel, co fungovalo“ pro další session.

S dokumentací se shoduje první a třetí bod. Ostatní jsou zkušenosti jednotlivců, ověřte si je na svém projektu.

Kdy se pravidla pro agenty vyplatí zavést ve firmě?

Podle mé zkušenosti ve chvíli, kdy s AI nad jedním projektem pracuje víc lidí nebo víc nástrojů. Pokud s AI ve firmě teprve začínáte, základy psaní zadání, analýzy a rešerše a bezpečného použití (ChatGPT, Claude, automatizace) probírám na školení AI. Napojení AI na vaše procesy a nástroje řeším v rámci AI automatizace. Kurzy, včetně vibe codingu, najdete v nabídce kurzů.

Časté otázky

Co je AGENTS.md?

Otevřený formát, prostý Markdown v kořeni repozitáře, který agentům říká, jak v projektu pracovat: přehled, příkazy pro build a testy, styl kódu, bezpečnost. Web agents.md mu říká „README pro agenty“. Žádná pole nejsou povinná.

Jaký je rozdíl mezi AGENTS.md a CLAUDE.md?

AGENTS.md je společný formát, který čte přes 20 nástrojů včetně Codexu. CLAUDE.md je soubor Claude Code. Claude Code čte AGENTS.md jen tehdy, když ve složce a výš není CLAUDE.md. Jsou-li oba, čte jen CLAUDE.md.

Potřebuji AGENTS.md i CLAUDE.md?

Používáte-li jen Claude Code, stačí CLAUDE.md. Používáte-li víc nástrojů, veďte pravidla v AGENTS.md a do CLAUDE.md dejte import @AGENTS.md plus pokyny jen pro Claude. Samotný AGENTS.md bez CLAUDE.md také funguje, Claude Code ho čte od verze 2.1.277. V některých sezeních, třeba na Amazon Bedrock před verzí 2.1.281, ho číst nemusí. Import z CLAUDE.md funguje i tam.

Jak dlouhý má být AGENTS.md nebo CLAUDE.md?

Claude Code doporučuje do 200 řádků na soubor, delší soubory snižují dodržování pravidel. Codex spojuje pravidla do výchozího limitu 32 KiB (project_doc_max_bytes). Mé dva soubory (CLAUDE.md a AGENTS.md) měly k 20. 10. 2026 46 a 56 řádků, k 22. 10. 2026 mají 46 a 67.

Čte AGENTS.md Cursor, Copilot a Gemini?

Podle agents.md ho čtou Cursor, GitHub Copilot coding agent i Gemini CLI. Gemini CLI používá kontextové soubory GEMINI.md, proto je potřeba v .gemini/settings.json nastavit název kontextového souboru na AGENTS.md. U Aideru se přidává read: AGENTS.md do .aider.conf.yml.

Může agent pravidla porušit?

Ano. CLAUDE.md i AGENTS.md jsou kontext, ne vynucená konfigurace. Dokumentace Claude Code doporučuje k zablokování akce hook PreToolUse. Pravidla oslabuje i délka souboru a rozpor mezi větami. Co se nesmí stát, hlídejte oprávněními, hookem nebo testem.

Zdroje a odkazy

• agents.md, popis formátu, podporované nástroje a migrace, přečteno 20. 10. 2026
• Claude Code: How Claude remembers your project, CLAUDE.md, AGENTS.md, import, /doctor prompt-audit, přečteno 20. 10. 2026
• Codex: AGENTS.md, pořadí načítání a limit 32 KiB, přečteno 20. 10. 2026
• OpenCode: dokumentace, příkaz /init vytvoří AGENTS.md
• Anthropic: dar MCP fondu Agentic AI Foundation, 9. 12. 2025, AGENTS.md mezi zakládajícími projekty fondu
• r/ClaudeAI, názory komunity (jen náhledy výsledků Googlu)