CLAUDE.md a AGENTS.md: pravidlá pre AI kód v tíme

CLAUDE.md a AGENTS.md sú súbory v repozitári, z ktorých si AI agent pri každej úlohe načíta pravidlá tímu. Pravidlá pre AI kód v tíme patria práve tam, nie do hlavy seniora. Krátky súbor pre agenta, CLAUDE.md alebo AGENTS.md, povie, ako sa overuje práca a čo agent nesmie. To najdôležitejšie však nemá byť text. Má to byť lint, test alebo CI, ktoré zlú zmenu zastavia samy.

AI dnes píše všetok náš kód a za výsledok ručí senior. Od roku 2023 sme dodali 15+ produkčných projektov. Predtým bol Filip 7 rokov v produktovom tíme SaaS, ktorý denne používalo 60 000+ ľudí. Pravidlá nižšie sme sa naučili na týchto projektoch, väčšinou na vlastných chybách.

Čo patrí do CLAUDE.md alebo AGENTS.md?

To, čo agent nezistí z kódu, a to, čo robíte inak ako ostatní. Konkrétne:

• Ako spustiť projekt a testy. Ideálne jedným príkazom, ktorý agent skopíruje.
• Čo agent nesmie. Produkčná databáza, tajné kľúče, migrácie bez schválenia, priamy push do hlavnej vetvy.
• Kde čo je. Kde je biznis logika, kde testy, čo je vygenerované a nemá sa ručne meniť.
• Konvencie, ktoré nie sú bežné. Ako pomenúvate veci, ako spracúvate chyby, kde sú preklady.
• Ako vyzerá hotová práca. Čo musí prejsť, kým agent otvorí pull request.

Čo tam nepatrí: štýl, ktorý stráži formátovač. Dlhé eseje o architektúre. Pravidlá, ktoré platia len v jednom priečinku.

CLAUDE.md alebo AGENTS.md?

Claude Code číta CLAUDE.md. Viaceré iné nástroje, napríklad Codex, čítajú AGENTS.md. Ak tím používa viac nástrojov, nepíšte pravidlá dvakrát.

Majte ich v AGENTS.md a v CLAUDE.md naň odkážte riadkom @AGENTS.md. Claude Code si ho potom načíta sám. Dve samostatné kópie sa rozídu skôr, než si to niekto všimne.

Koľko pravidiel je priveľa?

Hranica príde skôr, ako by ste čakali. Agent pravidlá načíta pri každom spustení. Čím viac textu má v kontexte, tým horšie sa drží toho podstatného.

Dobre nám funguje rozdelenie do troch úrovní. V koreni repozitára je minimum, ktoré platí všade. Pravidlá jedného modulu sú v súbore priamo v jeho priečinku a agent ich načíta, až keď v ňom pracuje. To najdôležitejšie je lint alebo test: nikto ho nemusí čítať, zlú zmenu zastaví sám.

Úprimne: dokonalú odpoveď nemáme. Pravidiel pribúda s každou chybou. Preto ich pravidelne čistíme a do lintu presúvame všetko, čo sa dá.

Odkiaľ brať pravidlá, keď ich ešte nemáte?

Z review. Komentár, ktorý v review zaznie druhýkrát, nie je chyba vývojára. Je to diera v pravidlách. Postup je jednoduchý:

Často odporúčame nechať agenta prejsť staré komentáre z review a vytiahnuť z nich pravidlá. Funguje to len vtedy, keď komentáre existujú. Ak review prebieha iba ústne, počas hovoru, do pull requestov sa nedostane nič. Agent potom nemá z čoho čerpať.

Preto najprv návyk, potom nástroj. Spätnú väzbu píšte do pull requestu, nie len ústne.

Kam ktoré pravidlo patrí?

Zákaz napísaný ako veta agent vie obísť. Súbor neotvorí, ale napíše skript, ktorý ho vypíše. Preto pri každom pravidle píšeme, čím je vynútené.

Agent, ktorý u nás pracuje samostatne, beží v oddelenom virtuálnom stroji. K ostrej prevádzke ani k tajným kľúčom sa odtiaľ nedostane. Hook, ktorý odmietne nebezpečný príkaz, je dobrý prvý krok. Je to však spomaľovač, nie stena: šikovný agent si nájde inú cestu. Žiadna veta „buď opatrný“ nenahradí ani jedno.

Tabuľku aj zákazy s tým, čo ich stráži, nájdete v šablóne. Stiahnite si šablónu Pravidlá pre AI v tíme (PDF).

Ako zdieľať pravidlá medzi viacerými repozitármi?

Distribúciou, nie disciplínou. My sme pravidlá mali v hlavnom repozitári a ostatné ich nevideli. Niektoré si ich skopírovali. O pár mesiacov existovalo viac verzií a žiadne dve neboli rovnaké.

Dnes máme jeden balík pravidiel, ktorý sa načíta v každom repozitári. Má verzie a mení sa iba cez pull request so schválením. Kópie neexistujú, takže sa nemajú ako rozísť. Osobné pravidlá sú štýl práce každého vývojára. Zdieľané patria firme a musia žiť na jednom mieste. Rovnaký balík pravidiel nastavujeme tímom, ku ktorým sa pripájame ako súčasť služby AI-native SDLC pre vývojové tímy. Chýbajú vášmu tímu skôr ruky než pravidlá? Pozrite si seniorského vývojára do tímu.

Review a testy: pravidlá, ktoré nie sú v súbore

Niektoré pravidlá nepatria agentovi, ale procesu okolo neho. Čo z toho váš tím už má?

Test, ktorý nikdy nezlyhal, dokazuje len, že agent súhlasí sám so sebou. A pipeline, ktorá len hlási, je dekorácia.

Ako tieto pravidlá zaviesť v celom tíme krok po kroku, opisujeme v článku Ako zaviesť AI do vývojového tímu. Prečo je rámec dôležitejší ako model, vysvetľuje Agent = model + rámec. Ak tím ešte vyberá nástroj, pozrite si Cursor vs Claude Code.

Kedy to neodporúčame

• Ste jeden alebo dvaja vývojári v jednom repozitári. Stačí krátky CLAUDE.md alebo AGENTS.md. Spíšte si ho sami podľa zoznamu vyššie.
• Nemáte testy ani CI, ktoré blokuje. Pravidlá pre agenta vtedy veľa nezmenia. Najprv testy a CI, potom pravidlá.

• Čakáte, že šablóna nahradí vaše review. Nenahradí. Pravidlá vznikajú z vášho review, začnite spätnou väzbou v pull requestoch.

Chcete pravidlá nastaviť s niekým, kto s nimi pracuje denne?

Pozrieme sa na vaše repozitáre a navrhneme prvú verziu pravidiel aj brán v CI. Senior sa zapojí do vášho repozitára a pull requestov od prvého týždňa.

Ozveme sa do dvoch pracovných dní a spolu vyberieme, čo vyriešime ako prvé.

Ak sa chcete najprv porozprávať, dohodnite si meeting na 15 minút s Filipom.

Kde dnes žijú pravidlá vášho tímu?

Časté otázky

Čo je CLAUDE.md?

Súbor v repozitári, ktorý Claude Code načíta pri každom spustení. Píšu sa doň pravidlá pre agenta: ako spustiť testy, čo nesmie a ako vyzerá hotová práca. Iné nástroje čítajú podobný súbor AGENTS.md.

CLAUDE.md alebo AGENTS.md?

Ak tím používa len Claude Code, stačí CLAUDE.md. Ak viac nástrojov, majte pravidlá v AGENTS.md a v CLAUDE.md naň odkážte riadkom @AGENTS.md. Dve samostatné kópie sa časom rozídu.

Koľko pravidiel má mať CLAUDE.md?

Čo najmenej. Agent ich načíta pri každom spustení a priveľa textu mu zhorší výsledok. V koreni nechajte len to, čo platí všade. Zvyšok dajte do priečinkov a to najdôležitejšie do lintu alebo testu.

Kto má vlastniť pravidlá pre AI v tíme?

Jeden určený človek, ktorý zmeny schvaľuje. Písať ich môže ktokoľvek cez pull request. Bez vlastníka si ich každý upraví po svojom a zdieľaná vrstva sa rozpadne.

Stačí agentovi napísať, čo nesmie?

Nie. Agent textový zákaz vie obísť. Čo je naozaj dôležité, vynúťte prístupmi, hookom, lintom alebo CI. Pri každom pravidle si napíšte, čím je vynútené.