# Jeden soubor s pokyny pro Claude Code, Codex a Cursor v roce 2026
> Jeden zdroj pravdy pro Claude Code, Codex a Cursor v roce 2026: kdy Claude Code čte samotný AGENTS.md, import @AGENTS.md do CLAUDE.md, symbolický odkaz a /init.
Source: https://ailoot.ai/blog/cs/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/cs/agents-md-claude-md-one-instruction-file/
Language: cs
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-10d9e9da16b4ec62c27cf037d13715f06323915c95066be5ce456afac649c7ca
Informace o službě najdete v [dokumentaci Ailoot](https://ailoot.ai/docs/).
## Co se změní, když používáte Claude Code, Codex a Cursor společně?
Hlavní poznatek
V roce 2026 typická sestava vibe codera neobsahuje jeden nástroj, ale 3–5. Claude Code jako hlavní nástroj, Codex pro dlouhé autonomní úkoly, Cursor pro rychlé úpravy v IDE. Každý má vlastní soubor s pokyny: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Pokud je synchronizujete ručně, upravíte jeden řádek na pěti místech, zapomenete aktualizovat Cursor a o týden později budou Claude a Codex dávat na stejné zadání různé výsledky.
V popsaném příkladu je hlavním nástrojem Claude Code, zatímco Codex a Cursor se používají pro konkrétní úkoly. Moje `CLAUDE.md` obsahuje asi 250 řádků pokynů: co číst a v jakém pořadí, na co se nesmí sahat, jaké příkazy používat při nasazení a jak formátovat commity. Když jsem na projektu poprvé zkusil Codex CLI, neznal žádná pravidla: spustil `git push --force`, prohrabával se v `.env` a bez rozmyslu přejmenovával soubory.
Nejprve jsem ručně zkopíroval `CLAUDE.md` do `AGENTS.md`. O dva týdny později jsem zjistil, že projekt už má čtyři verze stejných pokynů: v `CLAUDE.md`, `AGENTS.md`, `.cursorrules` a `.windsurf/rules/`. Všechny se trochu lišily. To není problém Claude nebo Cursoru; je to základní past každého systému s více zdroji pravdy. Podrobněji se tomuto problému věnuji v [návodu k práci s více agenty](https://ailoot.ai/blog/cs/claude-code-codex-together/).
V červnu 2026 nabídla dokumentace paměti Claude Code od Anthropic jedno řešení: sdílený soubor a import. Od září 2026 Claude Code čte samotný `AGENTS.md`, pokud projekt nemá `CLAUDE.md`; import je potřeba, když máte pravidla specifická pro Claude. Níže vysvětluji, kdy stačí jediný `AGENTS.md`, jak nastavit import a jak oddělit sdílená pravidla od pravidel specifických pro Claude.
## Čte Claude Code samotný AGENTS.md?
Hlavní poznatek
Ano, počínaje verzí 2.1.277, vydanou 18. září 2026, ale jen pokud v pracovním adresáři ani nadřazených adresářích není `CLAUDE.md`, `.claude/CLAUDE.md` ani `CLAUDE.local.md`. Pokud `CLAUDE.md` existuje, Claude Code ve výchozím nastavení čte pouze tento soubor a `AGENTS.md` se zahrne řádkem `@AGENTS.md` uvnitř `CLAUDE.md` nebo pomocí symbolického odkazu. Chování se mění v `/config` v části Project instructions. Před zářím Claude Code `AGENTS.md` vůbec nečetl a import byl jedinou možností.
Před zářím 2026 zněla odpověď „ne“. Issue \#6235, které požadovalo podporu AGENTS.md, zůstalo otevřené od srpna 2025 a bylo uzavřeno 17. srpna 2026. Dokumentace paměti po celou tu dobu uváděla jedno řešení: vytvořit CLAUDE.md a vložit do něj AGENTS.md jako import. Počínaje verzí 2.1.277 dokumentace říká něco jiného:
Claude Code může číst AGENTS.md jako projektové pokyny, takže repozitář již nastavený pro jiné agenty funguje bez CLAUDE.md, importu nebo konfigurace.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
To, co Claude Code čte, přesně závisí na souborech v projektu:
| Soubory v projektu | Co Claude Code čte |
|----|----|
| `AGENTS.md`, bez `CLAUDE.md` nebo `CLAUDE.local.md` v pracovním adresáři či nad ním | `AGENTS.md` |
| `AGENTS.md` a `CLAUDE.md` (nebo `CLAUDE.local.md`) v pracovním adresáři či nad ním | Pouze `CLAUDE.md` |
| `CLAUDE.md` s řádkem `@AGENTS.md` | `CLAUDE.md` a `AGENTS.md` v něm prostřednictvím importu |
Do této kontroly se počítá `CLAUDE.md`, `.claude/CLAUDE.md` a `CLAUDE.local.md` v pracovním adresáři i ve všech nadřazených adresářích. Osobní `~/.claude/CLAUDE.md`, firemní spravovaný soubor a pravidla z `.claude/rules/` se nepočítají: načítají se společně s `AGENTS.md`.
Pokud žádný `CLAUDE.md` neexistuje, Claude Code při spuštění čte všechny soubory `AGENTS.md` a `.claude/AGENTS.md` v pracovním adresáři i nadřazených adresářích a při otevření souboru v podadresáři načte také `AGENTS.md` z tohoto podadresáře. Importy `@path` uvnitř `AGENTS.md` také fungují. Claude Code nečte `AGENTS.local.md`, `AGENTS.override.md` ani obsah adresáře `.agents/`.
Háček: počítá se také osobní `CLAUDE.local.md`. Pokud ho vytvoříte kvůli necommitovaným pravidlům, Claude Code přestane `AGENTS.md` tiše číst. Řešením je níže uvedené nastavení.
Chování se mění v `/config` v části Project instructions:
| Nastavení | Co Claude Code čte |
|----|----|
| `claude-md-or-agents-md` (výchozí) | `CLAUDE.md`, nebo pokud neexistuje ani ten, ani `CLAUDE.local.md`, pak `AGENTS.md` |
| `claude-md-and-agents-md` | Oba soubory: v každém adresáři nejprve `CLAUDE.md` a pak `AGENTS.md` |
| `claude-md` | Pouze `CLAUDE.md` |
| `managed-only` | Pouze firemní spravovaný `CLAUDE.md` a automatická paměť |
Pokud chcete zachovat `CLAUDE.local.md` a zároveň nepřijít o `AGENTS.md`, nastavte `claude-md-and-agents-md`. K duplicitnímu čtení nedojde: pokud je `AGENTS.md` již zahrnut řádkem `@AGENTS.md` nebo symbolickým odkazem, Claude Code ho nenačte podruhé bez ohledu na nastavení.
Pomocí příkazu `/memory` můžete ověřit, zda byl soubor načten: počínaje verzí 2.1.280 se v seznamu objeví cesta k `AGENTS.md`. Ve verzích starších než 2.1.277 a v relacích, kde je vypnutý vestavěný plugin `agents-md`, Claude Code čte pouze `CLAUDE.md` a v `/config` není položka Project instructions. Před verzí 2.1.281 se stejně chovaly relace přes Amazon Bedrock a relace s vypnutou telemetrií. Ani v první relaci po aktualizaci ze starší verze se `AGENTS.md` nemusí načíst; začne fungovat od následující relace.
Co to znamená pro sestavu s jedním souborem? Pokud nemáte pravidla určená pouze pro Claude, můžete `CLAUDE.md` vynechat: stačí `AGENTS.md` a přečtou ho Claude Code, Codex i Cursor. Pokud taková pravidla máte (plan mode pro rizikové adresáře, skills, hooks), potřebujete `CLAUDE.md` a Claude Code přestane `AGENTS.md` číst samostatně. Pak vložte `AGENTS.md` do `CLAUDE.md` řádkem `@AGENTS.md`; tato sestava funguje stejně jako před zářím. Pomáhá také se staršími verzemi Claude Code. Podrobně to vysvětlím níže.
## Jak importovat @AGENTS.md uvnitř CLAUDE.md?
Hlavní poznatek
Import je potřeba, když projekt obsahuje `CLAUDE.md`: pokud existuje, Claude Code ve výchozím nastavení nečte `AGENTS.md` samostatně. Nastavíte ho tak, že na začátek souboru `CLAUDE.md` napíšete řádek `@AGENTS.md`. Při spuštění relace Claude Code vloží obsah `AGENTS.md` na místo tohoto řádku a výsledek načte jako jeden text. Pod import můžete přidat sekci „Claude Code“ s pravidly platnými jen pro Claude. Importy fungují s relativními i absolutními cestami a lze je vnořit až do čtyř úrovní.
Minimální funkční příklad z oficiální dokumentace:
```markdown
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
```
Takto to funguje. První řádek, `@AGENTS.md`, je direktiva importu. Když Claude Code na začátku relace zpracovává `CLAUDE.md`, najde tento import a vloží na jeho místo celý obsah `AGENTS.md`. Následující nadpis `## Claude Code` je jen markdown, ale tvoří sekci „doplňky specifické pro Claude“. Pod ním je pravidlo platné jen pro Claude Code: při změnách v adresáři billing použijte plan mode. Codex CLI ani Cursor tento soubor vůbec neotevírají; používají prostý `AGENTS.md`.
Citace z dokumentace o fungování importů:
Soubory CLAUDE.md mohou importovat další soubory pomocí syntaxe @path/to/import. Importované soubory se rozbalí a načtou do kontextu při spuštění relace spolu se souborem CLAUDE.md, který na ně odkazuje.
— Anthropic, https://code.claude.com/docs/en/memory
Několik praktických podrobností:
- **Relativní a absolutní cesty.** `@AGENTS.md` je relativní k souboru, který import obsahuje. `@/Users/me/shared/rules.md` nebo `@~/.claude/personal.md` jsou absolutní. Pro osobní preference, které nechci ukládat do repozitáře, používám `@~/.claude/personal.md`.
- **Hloubka čtyř úrovní.** `AGENTS.md` může importovat `@docs/coding-style.md` a `coding-style.md` může importovat další soubor, a to až do čtyř úrovní. To stačí pro každou reálnou strukturu.
- **Zpětné apostrofy blokují importy.** Pokud text obsahuje `` `@README` ``, jde jen o zmínku názvu, ne o import. To se hodí, když chcete čtenářům vysvětlit fungování importů, aniž byste nějaký spustili.
- **Schválení pro soubory mimo projekt.** Pokud import odkazuje mimo pracovní adresář, například `@~/.claude/personal.md`, Claude Code při prvním použití zobrazí dialog se seznamem těchto souborů. Pokud ho odmítnete, externí importy zůstanou vypnuté a dialog se už znovu nezobrazí. `@AGENTS.md` v kořenu projektu dialog nevyvolá. Chrání vás to před nechtěným načtením nesouvisejícího souboru do kontextu.
Po přechodu na tuto sestavu se moje `CLAUDE.md` v popsaném projektu zkrátila z 250 řádků na 60: `@AGENTS.md` plus pět až sedm pravidel platných pouze pro Claude Code (plan mode pro rizikové adresáře, co nedělat v administraci a jak formulovat commity). Všechno sdílené je v `AGENTS.md`, který čtou Codex a Cursor.
## Kdy zvolit symbolický odkaz a kdy import?
Hlavní poznatek
Anthropic nabízí dva způsoby: import přes `@AGENTS.md` nebo symbolický odkaz `ln -s AGENTS.md CLAUDE.md`. Symbolický odkaz je jednodušší — jde jen o alias a není potřeba upravovat žádný soubor. Má ale tři nevýhody: Windows vyžaduje oprávnění správce, do `CLAUDE.md` nemůžete přidat pravidla specifická pro Claude a Git někdy zobrazuje symbolický odkaz jako nesmyslnou změnu v diffu. Import je univerzální přístup. Pokud nemáte pravidla určená pouze pro Claude, pak od verze 2.1.277 nepotřebujete ani jedno: Claude Code bude číst samotný `AGENTS.md`.
Dokumentace ukazuje možnost se symbolickým odkazem takto:
```bash
ln -s AGENTS.md CLAUDE.md
```
A hned nato otevřeně varuje před Windows:
Pokud vy nebo kdokoli, kdo klonuje repozitář, pracujete ve Windows, použijte import @AGENTS.md. Vytvoření symbolického odkazu tam vyžaduje oprávnění správce nebo režim pro vývojáře a Git bez zapnutého core.symlinks při checkoutu uložený odkaz převede na běžný textový soubor. V této kopii pak místo pokynů zůstane jednořádkový soubor CLAUDE.md.
— Anthropic, https://code.claude.com/docs/en/memory
Srovnávací tabulka:
| Kritérium | Import `@AGENTS.md` | Symbolický odkaz `ln -s` |
|----|----|----|
| **Funguje ve Windows bez oprávnění správce** | ano | ne (vyžaduje režim pro vývojáře) |
| **Lze přidat pravidla pouze pro Claude** | ano, pod import | ne, soubor je totožný |
| **V Gitu se zobrazuje jako běžný markdown** | ano | jako odkaz (závisí na `core.symlinks`) |
| **Lze importovat více souborů** | ano, až do čtyř úrovní | ne, jeden k jednomu |
| **Ukládání do mezipaměti/neplatnost v Claude Code** | standardní pro CLAUDE.md | funguje, ale symbolické odkazy mají záludnosti s metadaty |
| **Výchozí volba** | vhodná pro všechny | pouze pokud nezáleží na multiplatformním použití |
V popsaném projektu používám importy. Důvody:
1. **Tým používá různé systémy.** Pracuji na Macu; v příkladu je tým zhruba rovnoměrně rozdělený mezi Windows a Mac. Pokud je v repozitáři symbolický odkaz, uživatelům Windows bez režimu pro vývojáře se při checkoutu zobrazí běžný textový soubor s jediným řádkem `AGENTS.md`. To způsobuje podivné chyby: pravidla někdy fungují, někdy ne, a není jasné proč.
2. **Chci pravidla pouze pro Claude.** Pod `@AGENTS.md` má moje `CLAUDE.md` sekci „Claude Code“ s pravidly: pro architektonické úkoly použít `--effort high`, před `git push` spustit `npm run build` a ručně nevolat `/api/v1/deploy`. Codex těmto příkazům nerozumí.
3. **Snáze se hledají chyby.** Když se něco pokazí, otevřu `CLAUDE.md` a vidím import i svá přepsaná pravidla. Symbolický odkaz neukazuje, „že to bylo přidáno sem“. Další informace o ladění nastavení Claude Code najdete v [návodu k bezpečnému režimu](https://ailoot.ai/blog/cs/claude-code-safe-mode-recovery/).
Pokud nemáte pravidla specifická pro Claude, symbolický odkaz už od verze 2.1.277 není potřeba: smažte `CLAUDE.md` a Claude Code bude číst samotný `AGENTS.md`. Symbolický odkaz si ponechte jen tehdy, pokud někdo v týmu používá verzi starší než 2.1.277 a nemůže ji aktualizovat. Pokud pravidla specifická pro Claude máte, import je pohodlnější v devíti případech z deseti.
## Co čtou Codex, Cursor, Copilot, Windsurf a Gemini CLI?
Hlavní poznatek
Každý nástroj čte vlastní soubor, někdy i více souborů. Claude Code čte `CLAUDE.md` a od září 2026 také `AGENTS.md`, pokud projekt nemá `CLAUDE.md`. Codex CLI čte `AGENTS.md` a `AGENTS.override.md`. Cursor čte starší formát `.cursorrules` nebo novější `.cursor/rules/*.mdc` a od léta 2026 také `AGENTS.md`. Copilot čte `.github/copilot-instructions.md` nebo `.github/instructions/*.instructions.md`. Windsurf čte starší `.windsurfrules` nebo novější `.windsurf/rules/`. Gemini CLI čte `GEMINI.md`. Aider a Cline už podporují `AGENTS.md`.
Přehled sedmi hlavních nástrojů (vychází z oficiální dokumentace jednotlivých nástrojů):
| Nástroj | Hlavní soubor s pokyny | Alternativy | Čte AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, spravovaná politika | ano, pokud projekt nemá `CLAUDE.md` (od 2.1.277), jinak přes import |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | ano (nativně) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (zastaralé) | ano |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | přes rozšíření |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (zastaralé) | ano |
| **Gemini CLI** | `GEMINI.md` | \- | ne |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | ano (nativně) |
Co z toho plyne? Pokud repozitář obsahuje `AGENTS.md` (a v případě potřeby pravidel specifických pro Claude také `CLAUDE.md` s importem), pět ze sedmi nástrojů automaticky získá aktuální pokyny. Cursor a Windsurf, které mají vlastní nativní soubory, je mohou používat beze změny (`AGENTS.md` čtou také) nebo do nich lze přidat import `@AGENTS.md` — jejich syntaxe se však liší a není vždy podporovaná.
Nejjednodušší strategie pro nový projekt:
1. **Všechna sdílená pravidla dejte do `AGENTS.md`** — 95 % pravidel patří tam.
2. **Vytvořte `CLAUDE.md`, pokud potřebujete pravidla pouze pro Claude:** na první řádek dejte `@AGENTS.md` a pod něj přidejte sekci s pravidly jen pro Claude. Pokud žádná taková pravidla nemáte, `CLAUDE.md` není potřeba; Claude Code čte samotný `AGENTS.md` od verze 2.1.277.
3. **Adresář `.cursor/rules/` si nechte pro Cursor** pro vzácné případy, kdy potřebujete něco specifického pro Cursor (jeho příkazy `@Codebase` a `@Docs`).
4. **U Windsurfu postupujte stejně:** zapomeňte na starý `.windsurfrules`; nový `.windsurf/rules/` používejte jen tehdy, když potřebujete vzory pro jeho syntaxi.
Tento přístup přináší 80 % přínosu za 20 % práce. Z vlastní zkušenosti vím, že při sjednocování různorodých týmů v „Antigravity“ je údržba více než dvou zdrojů pravdy (sdíleného a pouze pro Claude) náročná. Pokud někdo v týmu přidá pravidlo do `.cursorrules` a zapomene na `AGENTS.md`, za týden si Cursor a Codex budou protiřečit.
## Jak /init v Claude Code načte existující AGENTS.md?
Hlavní poznatek
`/init` vytvoří `CLAUDE.md` z toho, co už je v repozitáři, a ušetří 20–30 minut ruční práce. Ve výchozím nastavení načte pravidla Cursoru (`.cursor/rules/`, `.cursorrules`) a Copilotu (`.github/copilot-instructions.md`), zatímco `AGENTS.md`, `.windsurfrules` a `.clinerules` čte v režimu `CLAUDE_CODE_NEW_INIT=1`. Tento režim spouští interaktivní vícefázový postup: klade otázky, prozkoumá kód pomocí subagenta a před zápisem navrhne plán. Od září 2026 má `/init` v projektu s `AGENTS.md` nevýhodu: nový `CLAUDE.md` vypne přímé čtení `AGENTS.md` a pravidla skončí ve dvou souborech.
Anthropic popisuje `/init` ve své dokumentaci takto:
Spuštění /init přečte soubory s pokyny ostatních nástrojů a přesune příslušné části do vytvořeného CLAUDE.md: pravidla Cursoru z `.cursor/rules/` nebo `.cursorrules`, pravidla Copilotu z `.github/copilot-instructions.md` a při nastavení CLAUDE_CODE_NEW_INIT=1 také AGENTS.md, `.devin/rules/`, `.windsurf/rules/` nebo `.windsurfrules` a `.clinerules`.
— Anthropic, https://code.claude.com/docs/en/memory
Co to znamená v praxi? Popsaný repozitář obsahoval `.cursorrules` z doby, kdy jsem zkoušel Cursor (asi 80 řádků), a `AGENTS.md` (120 řádků sestavených ručně). Když jsem spustil `claude /init`, příkaz vzal oba soubory, sloučil podobná pravidla a za minutu sestavil čistý `CLAUDE.md`. Potom jsem ho zkontroloval a provedl drobné úpravy — odstranil zastaralé položky a doplnil strukturu s nadpisy. Bylo to rychlejší než přepisovat vše od začátku.
Interaktivní režim, ve kterém `/init` čte také `AGENTS.md`, se zapíná pomocí proměnné prostředí:
```bash
CLAUDE_CODE_NEW_INIT=1 claude
```
Po spuštění `/init` Claude položí řadu upřesňujících otázek: které prvky nastavit (`CLAUDE.md`, skills, hooks), jaký stack projekt používá a jaké příkazy se používají pro testy. Potom subagent prozkoumá kódovou základnu — přečte `package.json`, `README.md` a konfigurační soubory — a doplní chybějící části. Nakonec zobrazí návrh, který můžete před uložením upravit. Další informace o nastavení Claude Code při zahájení projektu najdete v [samostatném návodu](https://ailoot.ai/blog/cs/spec-kit-claude-code-spec-driven-development/).
A teď nevýhoda. Pokud projekt už obsahuje aktivní `AGENTS.md`, `/init` vedle něj vytvoří `CLAUDE.md` s kopií jeho pravidel. Od té chvíle Claude Code ve výchozím nastavení čte pouze `CLAUDE.md`, takže znovu vzniknou dva zdroje pravdy: vy aktualizujete `AGENTS.md`, zatímco Claude dál pracuje se starou kopií. Příkaz `/import` dělá něco podobného: připojí k `CLAUDE.md` jednorázovou kopii `AGENTS.md`. Chcete-li zachovat jediný zdroj, vložte po `/init` na první řádek `CLAUDE.md` import `@AGENTS.md` a odstraňte z `CLAUDE.md` vše, co opakuje `AGENTS.md`.
`/init` je vhodný začátek pro nový projekt nebo projekt, který převádíte z Cursoru či Copilotu. Není třeba hledat na internetu „nejlepší šablonu CLAUDE.md“ — Anthropic už při tom zohlední obsah repozitáře. Pokud projekt už má aktivní `AGENTS.md` a žádná pravidla pouze pro Claude, `/init` není potřeba: Claude Code přečte samotný `AGENTS.md`.
## Jak oddělit sdílené pokyny od pokynů specifických pro Claude?
Hlavní poznatek
Pravidla srozumitelná každému AI agentovi dejte do `AGENTS.md`: na co nesahat, jak pojmenovávat větve, že `.env` obsahuje tajný údaj a jaké příkazy používat pro testy. Pravidla specifická pro Claude Code dejte do `CLAUDE.md` (pod import): plan mode, skills, hooks, odkazy na skills a názvy modelů podle verze. Rozlišení je jednoduché: pokud pravidlo začíná „Claude by měl“, patří do `CLAUDE.md`. Pokud začíná „nástroj by měl“, patří do `AGENTS.md`.
Odděluji je podle tohoto principu. Sdílená pravidla, která patří do `AGENTS.md`:
- **Na co v kódu nesahat.** Složky `.env`, `node_modules`, `prisma/migrations` (pouze přes `prisma migrate`), `.next/`, `.git/`.
- **Jak pojmenovávat věci.** Větve: `feat/`, `fix/`, `chore/`. Commity: prefixy `feat:`, `fix:`, `docs:` a krátký popis. Soubory komponent v `kebab-case`.
- **Příkazy pro testy a lint.** `npm run build`, `npm run lint`, `npm test`. Který příkaz spustit před `git push`.
- **Architektonické zásady.** Co patří do `src/lib/`, co do `src/components/`, kde je obchodní logika a kde uživatelské rozhraní.
- **Zabezpečení.** Nikdy necommitujte tajné údaje. K produkční databázi přistupujte pouze přes `prod-psql`. K produkci se přes SSH připojujte pouze přes alias `prod`, ne jako `root@IP`.
Pravidla specifická pro Claude, která patří do `CLAUDE.md` (pod `@AGENTS.md`):
- **Plan mode.** Pro změny v rizikových adresářích (například `src/billing/`) používejte `plan mode`.
- **Úroveň úsilí.** Pro architektonické úkoly používejte `--effort high`, pro běžnou práci `medium`.
- **Skills.** Které AI agenty a skills spouštět v různých situacích. Například: „při práci na návodu spusťte skill `build-masterskaya-guide`.“
- **Paměť Claude.** Co ukládat do automatické paměti a co do `CLAUDE.local.md`. Více informací o paměti Claude najdete v [návodu k Memory a CLAUDE.md](https://ailoot.ai/blog/cs/claude-memory-claude-md-auto-memory/).
- **Hooks.** Pokud jsou v `.claude/settings.json` nastavené hooks, popište v `CLAUDE.md`, co dělají (Codex a Cursor o nich nevědí a nepotřebují to).
- **Skills a příkazy.** Seznam příkazů se lomítkem, které často používám (`/init`, `/cd`, `/memory`, `/plan`).
Hranice není vždy jasná. Například „nikdy nespouštěj `git push --force` do `main`“ je zjevně sdílené pravidlo, a proto patří do `AGENTS.md`. Ale „při `git push` do větve hot nejdřív použij plan mode“ je specifické pro Claude Code, a proto patří do `CLAUDE.md`. Zkuste si položit otázku: „Kdybych zítra odstranil Claude Code a nechal jen Codex, platilo by toto pravidlo dál?“ Pokud ano, dejte ho do `AGENTS.md`. Pokud ne, dejte ho do `CLAUDE.md`.
## Co patří do AGENTS.md a co do CLAUDE.md nebo .claude/rules?
Hlavní poznatek
U velkého projektu jeden `AGENTS.md` nestačí — příliš naroste a každý agent do kontextu načítá zbytečný obsah. Řešením je adresář `.claude/rules/` se samostatnými soubory podle tématu a YAML frontmatterem `paths:` pro spouštění podle cesty. Například pravidlo pro API se uplatní pouze tehdy, když Claude pracuje v `src/api/`. Tím se ušetří spousta místa v kontextovém okně. Obdobou pro Cursor je `.cursor/rules/` a pro Windsurf `.windsurf/rules/`.
Pokud pravidla přesahují 200 řádků, je čas je rozdělit. Dokumentace Anthropic doporučuje mířit na 200 řádků na soubor, protože Claude u dlouhých souborů `CLAUDE.md` začne pokyny potichu méně dodržovat: vypadá to, že je čte, ale řídí se jimi méně často.
Struktura velkého projektu, která se mi osvědčila:
```
my-project/
├── AGENTS.md # 100-150 lines, shared
├── CLAUDE.md # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
├── CLAUDE.md # alternative to root file, same file
└── rules/
├── api.md # with paths: ['src/api/**']
├── components.md # with paths: ['src/components/**']
├── testing.md # without paths, always active
└── security.md # without paths, always active
```
Každý soubor v `.claude/rules/` může obsahovat frontmatter:
```markdown
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required
```
Claude tato pravidla načítá pouze při práci se soubory odpovídajícími tomuto vzoru. Pokud upraví `src/components/Button.tsx`, pravidla pro API se do kontextu nepřidají. Kontextové okno tak zabírá jen relevantní obsah. Adresář `.claude/rules/` funguje i bez `CLAUDE.md`: pokud projekt obsahuje pouze `AGENTS.md`, jeho pravidla se načtou spolu s ním a nevypnou přímé čtení `AGENTS.md`.
Cursor a Windsurf podporují stejný přístup přes adresáře `.cursor/rules/` a `.windsurf/rules/`. Standard AGENTS.md může na tyto adresáře odkazovat, ale syntaxe napříč nástroji zatím není zcela stabilní. Bezpečnější je ponechat sdílená pravidla v `AGENTS.md` a pravidla omezená na konkrétní cesty duplikovat v `.claude/rules/` a `.cursor/rules/` — jde o vzácné specifické případy, ne o většinu pravidel.
Užitečná umístění pro CLAUDE.md (od nejširšího po nejužší):
| Úroveň | Umístění | Účel |
|----|----|----|
| **Spravovaná politika** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Firemní pravidla, IT/DevOps |
| **Uživatel** | `~/.claude/CLAUDE.md` | Osobní preference napříč všemi projekty |
| **Projekt** | `./CLAUDE.md` nebo `./.claude/CLAUDE.md` | Pravidla projektového týmu |
| **Místní** | `./CLAUDE.local.md` (v `.gitignore`) | Osobní preference pro konkrétní projekt |
Příklad `~/.claude/CLAUDE.md` může obsahovat dvě pravidla: „odpovídej v jazyce preferovaném uživatelem“ a „piš Ailoot přesně tímto způsobem“. Tato pravidla platí pro každý projekt, není tedy třeba je duplikovat v jednotlivých repozitářích.
Ze čtyř úrovní pouze projektové `CLAUDE.md` a `CLAUDE.local.md` vypínají přímé čtení `AGENTS.md`. Osobní `~/.claude/CLAUDE.md` a spravovaná politika nepřekážejí; Claude Code je čte společně s `AGENTS.md`.
## Co dělat, pokud je AGENTS.md ve vašem projektu už zastaralý?
Hlavní poznatek
Pokud byl `AGENTS.md` sestaven v roce 2025 pro Codex nebo Aider a od té doby se neupravoval, otevřete projekt v Claude Code a požádejte Claude, aby soubor upravil. AGENTS.md je živý dokument; specifikace Linux Foundation se aktualizuje. Hlavní pravidlo pro udržování aktuálnosti: každé pravidlo musí odpovídat na otázku „Co už mě nebaví opakovat Claude/Codex?“ Pokud ne, archivujte ho.
V popisovaném projektu jsem měl `AGENTS.md` z května 2025 — 180 řádků, z nichž mnohé už byly zastaralé (zmiňoval koncové body Anthropic API, které se mezitím změnily; příklady se syntaxí `claude --tools`, která už neexistuje; a pravidla o `~/.claude/projects/` se zastaralou strukturou).
Postup, kterým jsem ho aktualizoval:
1. **Zkontrolujte ho s `claude` v režimu plan mode.** Otevřu repozitář, spustím `claude --safe-mode` a požádám: „Znovu si přečti `AGENTS.md` a navrhni seznam zastaralých nebo opakujících se položek. Neupravuj ho; pouze je vypiš.“ Za dvě minuty jsem dostal seznam 23 položek ke kontrole.
2. **Odstraňte zjevně zastaralé položky.** Z 23 položek jich bylo 9 očividně zastaralých — syntaxe příkazů, koncové body a názvy přepínačů. Tyto řádky jsem smazal.
3. **Sloučte duplicity.** Dalších 6 položek opakovalo totéž jinými slovy („neprováděj force-push“, „nikdy nepoužívej `--force`“, „vyhni se `git push -f`“). Sloučil jsem je do jednoho řádku.
4. **Přidejte nové položky.** Doplnil jsem to, v čem Claude/Codex v posledním měsíci opakovaně chybovali, podle pravidla „jeden řádek na vzorec chyby“. Přibylo tak 8 nových položek.
5. **Nechte subagenta provést závěrečnou kontrolu.** Požádal jsem Claude o kontrolu s pokynem „najdi rozpory, nejasnosti a duplicity“. Našel tři formulace, které šlo zpřesnit. Upravil jsem je.
Po hodině měl `AGENTS.md` 110 řádků, byl aktuální a znal jsem osobně každý řádek. Bylo snadné z něj vytvořit třicetiřádkový `CLAUDE.md`. Codex byl potom při práci s testy znatelně opatrnější — domnívám se, že některá jeho „podivná“ rozhodnutí vycházela ze zastaralých pokynů, kterými se poctivě řídil.
Hlavní zásady pro živý `AGENTS.md`:
- **Každé pravidlo odpovídá na opakující se chybu.** Pokud mě během měsíce žádné pravidlo ani jednou nenapadlo, nemá smysl ho tam nechávat.
- **Pište pravidla jako příkazy, ne jako teorii.** „Používej dvě mezery“ je pravidlo. „Styl kódu má být úhledný“ není.
- **Konkrétnost je lepší než obecnost.** „Před `git push` spusť `npm run build`“ je pravidlo. „Testuj změny“ není.
## Co s touto sestavou rozhodně NEFUNGUJE?
Hlavní poznatek
Import `@AGENTS.md` nesjednotí chování různých nástrojů. Každý má své zvláštnosti: Codex CLI nezná `.claude/rules/` ani hooks. Cursor má vlastní engine automatického doplňování, který při doplňování textu nečte CLAUDE.md. Copilot se řídí `.github/copilot-instructions.md` a samotná pravidla v AGENTS.md mu nestačí. Nejde o „jeden soubor = jedno chování“, ale o „jeden zdroj základních pravidel a potom vlastní doplňky pro každý nástroj“.
Během šesti měsíců práce s touto sestavou jsem se několika věcem naučil tvrdou cestou:
**1. Automatické doplňování Cursoru nepoužívá AGENTS.md.** Když Cursor navrhuje doplnění řádku v editoru, nečte `AGENTS.md` v reálném čase — pracuje samostatný rychlý engine. Pravidla v AGENTS.md mají význam, jen když zadáte požadavek v chatu Cursoru. To znamená, že zápis „nepoužívej `var`, používej `const`“ do AGENTS.md neovlivní automatické doplňování; musíte to nastavit přes ESLint nebo konfiguraci TypeScriptu.
**2. Hooks Claude Code v AGENTS.md pro Codex nefungují.** Pokud je v `.claude/settings.json` nastaven hook PreToolUse, který blokuje určitou akci, tato informace je užitečná jen pro Claude. Codex o hooks neví; z jeho pohledu „nástroj rozhoduje sám“. Do `AGENTS.md` má smysl napsat „nedělej X“ a do `CLAUDE.md` pod import „existuje hook, který X fyzicky blokuje“.
**3. Copilot a `.github/copilot-instructions.md`.** GitHub Copilot čte vlastní soubor a stále AGENTS.md nečte příliš dobře. Pokud váš tým Copilot aktivně používá, přidejte buď samostatný `.github/copilot-instructions.md` se zkrácenou verzí pravidel, nebo použijte [rozšíření Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions), která AGENTS.md znají. To se rychle mění, takže za tři až šest měsíců může situace vypadat jinak.
**4. Git nesleduje symbolický odkaz jako změnu CLAUDE.md.** Pokud spustíte `ln -s AGENTS.md CLAUDE.md` a o týden později aktualizujete `AGENTS.md`, Git zobrazí diff pouze pro `AGENTS.md`. To je normální, ale kolega kontrolující PR si nemusí uvědomit, že se aktualizoval i `CLAUDE.md` (přes symbolický odkaz). Řešení: do popisu PR výslovně napište „aktualizoval jsem `AGENTS.md`; Claude Code vidí tentýž soubor přes symbolický odkaz“.
**5. Hluboko vnořené importy se obtížně ladí.** Pokud `AGENTS.md` importuje `@docs/coding-style.md`, který importuje `@docs/typescript.md`, a některá pravidla si odporují, chyby se hledají obtížně. Importy omezuji na jednu úroveň (`CLAUDE.md` → `AGENTS.md`) a dál je nevnořuji. Anthropic poskytuje hook `InstructionsLoaded`, který zaznamenává načtené soubory — hodí se při ladění vrstvených sestav. Poznámka: hook se spustí u `AGENTS.md` zahrnutého importem nebo symbolickým odkazem, ale ne u `AGENTS.md`, který Claude Code načetl samostatně.
### Zdroje
- [Dokumentace Claude Code Memory – část AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) – kdy Claude Code čte samotný AGENTS.md, nastavení Project instructions, importy a symbolické odkazy a chování `/init`.
- [Dokumentace Claude Code Memory – importování dalších souborů](https://code.claude.com/docs/en/memory#import-additional-files) – syntaxe `@path/to/file`, hloubka čtyř úrovní, relativní a absolutní cesty.
- [agents.md – standard Linux Foundation](https://agents.md/) – oficiální standard AGENTS.md a seznam podporovaných nástrojů.
- [Dokumentace pravidel Cursoru](https://docs.cursor.com/context/rules-for-ai) – co Cursor čte (`.cursor/rules/*.mdc`, AGENTS.md).
- [Vlastní pokyny GitHub Copilotu](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) – formát `.github/copilot-instructions.md`.
- [Specifikace AGENTS.md v Linux Foundation](https://aaif.io/projects/agents-md/) – živá specifikace.
Kompletní sestava pro vibe coding na celý večer: **klon AI + Second Brain + kontextové inženýrství**.
Poznejte [Ailoot](https://ailoot.ai/).
## Časté otázky
### Kdy místo symbolického odkazu použít import?
Použijte `@AGENTS.md` v `CLAUDE.md`, potřebujete-li doplňky pouze pro Claude nebo kolegové používají Windows. Symbolický odkaz připojí obě jména ke stejnému obsahu, takže neumožní samostatnou sekci jen pro Claude.
### Jak ověřit načtení sdílených instrukcí?
Spusťte `/memory` a zkontrolujte uvedené instrukční soubory. Pokud `CLAUDE.md` nebo `CLAUDE.local.md` v dané konfiguraci potlačuje přímé načtení AGENTS.md, přidejte import nebo zvolte nastavení načítající oba a začněte novou relaci.
## Ailoot · Společnost a její portfolio projektů
Ailoot staví na dlouhodobých provozních zkušenostech, široké klientské základně, stabilních službách a průběžném sledování KPI.
Společnost a její portfolio projektů: miliony zákazníků; měsíční tržby v miliardách.
Ailoot využívá tyto provozní zkušenosti k poskytování přístupu přes API k funkcím AI v produktech zákazníků, agentech, aplikacích a automatizacích.