CLAUDE.md a AGENTS.md: pravidla pro AI kód v týmu

CLAUDE.md a AGENTS.md jsou soubory v repozitáři, ze kterých si AI agent při každém úkolu načte pravidla týmu. Pravidla pro AI kód v týmu patří právě tam, ne do hlavy seniora. Krátký soubor pro agenta, CLAUDE.md nebo AGENTS.md, řekne, jak se ověřuje práce a co agent nesmí. To nejdůležitější ale nemá být text. Má to být lint, test nebo CI, které špatnou změnu zastaví samy.

AI dnes píše všechen náš kód a za výsledek ručí senior. Od roku 2023 jsme dodali 15+ produkčních projektů. Předtím byl Filip 7 let v produktovém týmu SaaS, který denně používalo přes 60 000 lidí. Níže uvedená pravidla jsme se naučili na těchto projektech, většinou na vlastních chybách.

Co patří do CLAUDE.md nebo AGENTS.md?

To, co agent nezjistí z kódu, a to, co děláte jinak než ostatní. Konkrétně:

• Jak spustit projekt a testy. Ideálně jedním příkazem, který agent zkopíruje.
• Co agent nesmí. Produkční databáze, tajné klíče, migrace bez schválení, přímý push do hlavní větve.
• Kde co je. Kde je byznys logika, kde testy, co je generované a nemá se ručně měnit.
• Konvence, které nejsou běžné. Jak pojmenováváte věci, jak zpracováváte chyby, kde jsou překlady.
• Jak vypadá hotová práce. Co musí projít, než agent otevře pull request.

Co tam nepatří: styl, který hlídá formátovač. Dlouhé eseje o architektuře. Pravidla, která platí jen v jedné složce.

CLAUDE.md, nebo AGENTS.md?

Claude Code čte CLAUDE.md. Řada dalších nástrojů, třeba Codex, čte AGENTS.md. Pokud tým používá víc nástrojů, nepište pravidla dvakrát.

Mějte je v AGENTS.md a z CLAUDE.md na něj odkažte řádkem @AGENTS.md. Claude Code si ho pak načte sám. Dvě samostatné kopie se rozejdou dřív, než si toho někdo všimne.

Kolik pravidel je moc?

Hranice přijde dřív, než byste čekali. Agent pravidla načítá při každém spuštění. Čím víc textu má v kontextu, tím hůř se drží toho podstatného.

Osvědčilo se nám rozdělení do tří úrovní. V kořeni repozitáře je minimum, které platí všude. Pravidla jednoho modulu jsou v souboru přímo v jeho složce a agent je načte, až když v ní pracuje. To nejdůležitější je lint nebo test: nikdo ho nemusí číst, špatnou změnu zastaví sám.

Upřímně: dokonalou odpověď nemáme. Pravidel přibývá s každou chybou. Proto je pravidelně pročišťujeme a do lintu přesouváme všechno, co jde.

Kde vzít pravidla, když je ještě nemáte?

V review. Komentář, který v review zazní podruhé, není chyba vývojáře. Je to díra v pravidlech. Postup je jednoduchý:

Často doporučujeme nechat agenta projít staré komentáře z review a vytáhnout z nich pravidla. Funguje to jen tehdy, když komentáře existují. Pokud review probíhá jen ústně, během hovoru, do pull requestů se nedostane nic. Agent pak nemá z čeho čerpat.

Proto nejdřív návyk, potom nástroj. Zpětnou vazbu pište do pull requestu, ne jen ústně.

Kam které pravidlo patří?

Zákaz napsaný jako větu agent umí obejít. Soubor neotevře, ale napíše skript, který ho vypíše. Proto u každého pravidla píšeme, čím je vynucené.

Agent, který u nás pracuje samostatně, běží v odděleném virtuálním stroji. K ostrému provozu ani k tajným klíčům se odtud nedostane. Hook, který odmítne nebezpečný příkaz, je dobrý první krok. Je to ale zpomalovač, ne zeď: šikovný agent si najde jinou cestu. Žádná věta „buď opatrný“ nenahradí ani jedno.

Tabulku i zákazy s tím, co je hlídá, najdete v šabloně. Stáhněte si šablonu Pravidla pro AI v týmu (PDF).

Jak sdílet pravidla mezi více repozitáři?

Distribucí, ne disciplínou. My jsme pravidla měli v hlavním repozitáři a ostatní je neviděly. Některé si je zkopírovaly. Za pár měsíců existovalo víc verzí a žádné dvě nebyly stejné.

Dnes máme jeden balík pravidel, který se načítá v každém repozitáři. Má verze a mění se jen přes pull request se schválením. Kopie neexistují, takže se nemají jak rozejít. Osobní pravidla jsou styl práce každého vývojáře. Sdílená patří firmě, a ta musí žít na jednom místě. Stejný balík pravidel nastavujeme týmům, ke kterým se připojujeme v rámci služby AI-native SDLC pro vývojové týmy. Chybí vašemu týmu spíš ruce než pravidla? Podívejte se na seniorního vývojáře do týmu.

Review a testy: pravidla, která nejsou v souboru

Některá pravidla nepatří agentovi, ale procesu kolem něj. Co z toho už váš tým má?

Test, který nikdy neselhal, dokazuje jen to, že agent souhlasí sám se sebou. A pipeline, která jen hlásí, je dekorace.

Jak tato pravidla zavést v celém týmu krok za krokem, popisujeme v článku Jak zavést AI do vývoje softwaru v týmu. Proč je rámec důležitější než model, vysvětluje Agent = model + rámec. Pokud tým ještě vybírá nástroj, podívejte se na Cursor vs Claude Code.

Kdy to nedoporučujeme

• Jste jeden nebo dva vývojáři v jednom repozitáři. Stačí krátký CLAUDE.md nebo AGENTS.md. Sepište si ho sami podle seznamu výše.
• Nemáte testy ani CI, které blokuje. Pravidla pro agenta pak moc nezmění. Nejdřív testy a CI, potom pravidla.

• Čekáte, že šablona nahradí vaše review. Nenahradí. Pravidla vznikají z vašeho review, začněte zpětnou vazbou v pull requestech.

Chcete pravidla nastavit s někým, kdo s nimi pracuje denně?

Podíváme se na vaše repozitáře a navrhneme první verzi pravidel i bran v CI. Senior se zapojí do vašeho repozitáře a pull requestů od prvního dne.

Ozveme se do dvou pracovních dnů a společně vybereme, co vyřešíme jako první.

Pokud si chcete nejdřív promluvit, domluvte si meeting na 15 minut s Filipem.

Kde dnes žijí pravidla vašeho týmu?

Časté otázky

Co je CLAUDE.md?

Soubor v repozitáři, který Claude Code načte při každém spuštění. Píšou se do něj pravidla pro agenta: jak spustit testy, co nesmí a jak vypadá hotová práce. Jiné nástroje čtou podobný soubor AGENTS.md.

CLAUDE.md, nebo AGENTS.md?

Pokud tým používá jen Claude Code, stačí CLAUDE.md. Pokud používáte víc nástrojů, mějte pravidla v AGENTS.md a z CLAUDE.md na něj odkažte řádkem @AGENTS.md. Dvě samostatné kopie se časem rozejdou.

Kolik pravidel má mít CLAUDE.md?

Co nejméně. Agent je načítá při každém spuštění a příliš mnoho textu mu zhorší výsledek. V kořeni nechte jen to, co platí všude. Zbytek dejte do složek a to nejdůležitější do lintu nebo testu.

Kdo má v týmu vlastnit pravidla pro AI?

Jeden určený člověk, který změny schvaluje. Psát je může kdokoli přes pull request. Bez vlastníka si je každý upraví po svém a sdílená vrstva se rozpadne.

Stačí agentovi napsat, co nesmí?

Ne. Textový zákaz umí agent obejít. Co je opravdu důležité, vynuťte přístupovými právy, hookem, lintem nebo CI. U každého pravidla si napište, čím je vynucené.