Pravidlá pre AI agentov v tíme: šablóna CLAUDE.md a AGENTS.md

Pre CTO, tech leadov a vývojárov, ktorých tím už používa Claude Code, Codex, Cursor alebo Copilot. Každý po svojom. Táto šablóna z toho spraví jednu spoločnú vrstvu.

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. Toto je rámec, ktorý pri tom používame.

1. Prečo pravidlá v texte nestačia

Zakážete agentovi otvoriť súbor. Neotvorí ho. Napíše si skript, ktorý ho vypíše.

Nie je to zlomyseľnosť. Agent dostal úlohu a hľadá cestu. Veta v prompte je pre neho prekážka, nie múr. Preto má každé pravidlo nižšie stĺpec, ktorý väčšina „AI politík" nemá: čo ho naozaj zastaví.

Pravidlo, ktoré sa porušilo dvakrát, prestáva byť len veta. Posuňte ho o stupeň vyššie.

2. Osem vecí, ktoré agent nesmie

Pri ôsmom bode poctivo píšeme „len veta". Mechanicky ho dnes poriadne nedrží nič. Pravidlo, ktoré priznáva svoju slabinu, je lepšie ako pravidlo, ktoré predstiera silu.

Koľko z vašich pravidiel je len veta? Toľko máte dier.

3. Kam ktoré pravidlo patrí

Agent načíta súbor s pravidlami pri každom spustení. Čím viac textu, tým horšie sa drží toho podstatného. Preto tri úrovne:

1. Koreň repozitára: krátky CLAUDE.md alebo AGENTS.md. Čo je toto repo, ako spustiť testy, čo agent nesmie, ako vyzerá hotová práca.
2. Priečinok: pravidlá jedného modulu v súbore priamo v ňom. Načítajú sa, až keď agent pracuje tam.
3. Lint alebo test: to najdôležitejšie. Nikto to nemusí čítať, zlú zmenu to zastaví samo.

Používate viac nástrojov? Pravidlá majte v AGENTS.md a v CLAUDE.md naň odkážte riadkom @AGENTS.md. Dve kópie sa rozídu skôr, než si to niekto všimne.

Štruktúra súborov

CLAUDE.md  alebo  AGENTS.md   krátky: repo, príkazy, odkazy
.claude/
  settings.json               zákazy v strojovej podobe
  hooks/push-gate.sh          to, čo nastavenie nevie
  rules/
    00-nikdy.md               8 zákazov + stĺpec "čo to drží"
    10-zadanie.md             čo musí mať úloha, kým ju agent začne
    20-brany.md               lint, typecheck, testy: blokuje áno/nie
    30-review.md              kto recenzuje a čo dostane
    90-vlastnictvo.md         kto pravidlá vlastní a ako pribudne nové

4. Vzory do repozitára

Príklady sú pre Claude Code. Princíp (zákaz, hook, CI, lint) platí aj pre iné nástroje, líši sa len zápis.

Zákazy v nastavení (body 1 až 5)

{
  "permissions": {
    "deny": [
      "Bash(psql:*)",
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Read(.env.prod*)",
      "Read(**/*.pem)"
    ],
    "ask": [
      "Read(**/.env*)",
      "Bash(npx prisma migrate deploy:*)"
    ]
  }
}

Pozor: pravidlo kontroluje text príkazu, nie zámer. Ak má agent povolený cat, cat .env zákaz čítania obíde. Preto secrety patria mimo repozitára. Skripty ich načítajú, nikdy nevypisujú.

Hook proti pushu do main (bod 5)

#!/bin/bash
# .claude/hooks/push-gate.sh  (PreToolUse, Bash)
# exit 0 = povoliť, exit 2 = zastaviť
CMD=$(jq -r '.tool_input.command // empty')
[[ "$CMD" != *"git push"* ]] && exit 0
case "$CMD" in
  *" main"*|*" master"*)
    echo "Push do main je zakázaný. Otvorte PR." >&2
    exit 2 ;;
esac
exit 0

Dve chyby, ktoré hook potichu vypnú. || true za hookom prepíše exit 2 na 0. A 2>/dev/null zahodí hlášku, takže agent nevie, prečo neprešiel. Hook overte raz naostro. Na serveri zapnite ochranu vetvy, lebo hook beží len tam, kde je nainštalovaný.

Testy a review (body 6 a 7)

• Test musí najprv zlyhať. Na pôvodnom kóde. Inak dokazuje len, že agent súhlasí sám so sebou.
• Testy zo zadania schvaľuje človek. CI upozorní, keď PR mení testy aj kód naraz. Rozhoduje reviewer.
• Kto písal, nerecenzuje. Review spustite v novom kontexte, ideálne iným modelom. Dostane diff a vaše pravidlá, nie konverzáciu s autorom.
• CI musí blokovať. Pipeline, ktorá len hlási, je dekorácia.

5. Odkiaľ brať nové pravidlá

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

Podmienka: review sa píše do pull requestu, nie len ústne na hovore. Z ústneho review nevznikne nič, z čoho by sa dalo pravidlo vytiahnuť.

6. Vlastníctvo a meranie

Pravidlá bez vlastníka zastarajú za pár mesiacov. Agent ich bude ďalej poslúchať, aj keď už neplatia. Skopírujte si toto do 90-vlastnictvo.md:

Vlastník: [meno]
Nové pravidlo: PR do .claude/rules/, schvaľuje vlastník.
Čistenie: prvý pondelok v mesiaci, 30 minút.
Rebrík: porušené dvakrát -> o stupeň vyššie
  len veta -> nastavenie alebo hook -> CI -> lint
Mesačne zapíšeme: koľko pravidiel je ešte len veta.

Tri čísla, ktoré stojí za to sledovať každý mesiac:

• Komentáre z review na jeden PR. Ak pravidlá fungujú, klesajú.
• Koľkokrát brána zastavila zmenu. A koľkokrát ju agent potom opravil sám.
• Koľko pravidiel je ešte len veta. To je zoznam práce na ďalší mesiac.

Počet commitov ani riadky kódu nemerajte. Tie AI nafúkne za sekundu.

7. Pracovný hárok pre tím (45 minút)

Vytlačte, dajte na stôl a vyplňte spolu.

Hotové, keď pri každom riadku viete povedať, čo ho drží a kto ho vlastní.