Zasady dla agentów AI w zespole: szablon CLAUDE.md i AGENTS.md

Dla CTO, tech leadów i programistów, których zespół już korzysta z Claude Code, Codex, Cursora lub Copilota. Każdy po swojemu. Ten szablon zamienia to we wspólną warstwę.

Dziś AI pisze cały nasz kod, a za wynik odpowiada senior. Od 2023 roku dostarczyliśmy ponad 15 projektów produkcyjnych. To jest ramka, której w nich używamy.

1. Dlaczego spisane zasady nie wystarczą

Zabraniają Państwo agentowi otwierać plik. Nie otwiera go. Pisze skrypt, który go wypisuje.

To nie złośliwość. Agent dostał zadanie i szuka drogi. Zdanie w prompcie jest dla niego przeszkodą, nie murem. Dlatego każda zasada poniżej ma kolumnę, której brakuje w większości „polityk AI”: co ją naprawdę zatrzymuje.

Zasada złamana dwa razy przestaje być tylko zdaniem. Proszę podnieść ją o poziom.

2. Osiem rzeczy, których agent nie może robić

Przy punkcie ósmym uczciwie piszemy „tylko zdanie”. Dziś nic nie wymusza go mechanicznie. Zasada, która przyznaje się do słabości, jest lepsza niż zasada, która udaje silną.

Ile Państwa zasad to tylko zdanie? To są Państwa dziury.

3. Gdzie trafia która zasada

Agent wczytuje plik z zasadami przy każdym uruchomieniu. Im więcej tekstu, tym gorzej trzyma się tego, co ważne. Dlatego trzy poziomy:

1. Katalog główny repozytorium: krótki CLAUDE.md lub AGENTS.md. Czym jest to repozytorium, jak uruchomić testy, czego agent nie może robić, jak wygląda skończona praca.
2. Folder: zasady jednego modułu, w pliku w jego folderze. Wczytują się tylko wtedy, gdy agent tam pracuje.
3. Lint lub test: najważniejsze zasady. Nikt nie musi ich czytać, same zatrzymują złą zmianę.

Używają Państwo kilku narzędzi? Proszę trzymać zasady w AGENTS.md i odwołać się do nich z CLAUDE.md linią @AGENTS.md. Dwie kopie rozjadą się, zanim ktokolwiek to zauważy.

Struktura plików

CLAUDE.md  lub  AGENTS.md     krótko: repo, polecenia, linki
.claude/
  settings.json               zakazy w formacie maszynowym
  hooks/push-gate.sh          to, czego ustawienia nie potrafią wyrazić
  rules/
    00-nigdy.md               8 zakazów + kolumna "co to wymusza"
    10-zadanie.md             czego zadanie potrzebuje, zanim agent zacznie
    20-kontrole.md            lint, typecheck, testy: blokuje tak/nie
    30-review.md              kto recenzuje i co dostaje
    90-wlasciciel.md          kto odpowiada za zasady i jak dodać nową

4. Wzorce do Państwa repozytorium

Przykłady są dla Claude Code. Zasada (deny, hook, CI, lint) działa także w innych narzędziach, zmienia się tylko składnia.

Zakazy w ustawieniach (punkty 1 do 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:*)"
    ]
  }
}

Uwaga: reguła porównuje tekst polecenia, nie intencję. Jeśli agent może uruchomić cat, cat .env obchodzi zakaz odczytu. Dlatego sekrety mieszkają poza repozytorium. Skrypty je wczytują i nigdy ich nie wypisują.

Hook przeciw pushowi do main (punkt 5)

#!/bin/bash
# .claude/hooks/push-gate.sh  (PreToolUse, Bash)
# exit 0 = przepuść, exit 2 = zatrzymaj
CMD=$(jq -r '.tool_input.command // empty')
[[ "$CMD" != *"git push"* ]] && exit 0
case "$CMD" in
  *" main"*|*" master"*)
    echo "Push do main jest zabroniony. Proszę otworzyć PR." >&2
    exit 2 ;;
esac
exit 0

Dwa błędy po cichu wyłączają hook. || true po hooku zamienia exit 2 na 0. A 2>/dev/null wyrzuca komunikat, więc agent nie wie, dlaczego się nie udało. Proszę raz przetestować hook naprawdę. Proszę też włączyć ochronę gałęzi na serwerze, bo hook działa tylko tam, gdzie jest zainstalowany.

Testy i review (punkty 6 i 7)

• Test musi najpierw nie przejść. Na oryginalnym kodzie. Inaczej dowodzi tylko, że agent zgadza się sam ze sobą.
• Testy do zadania zatwierdza człowiek. CI ostrzega, gdy PR zmienia jednocześnie testy i kod. Decyduje recenzent.
• Kto napisał, ten nie recenzuje. Proszę uruchomić review w nowym kontekście, najlepiej innym modelem. Dostaje diff i Państwa zasady, nie rozmowę z autorem.
• CI musi blokować. Pipeline, który tylko informuje, jest dekoracją.

5. Skąd biorą się nowe zasady

Z review. Komentarz, który pojawia się po raz drugi, to nie błąd programisty. To dziura w zasadach.

Jeden warunek: review pisze się w pull requeście, nie tylko ustnie na rozmowie. Review powiedziane na głos nie zostawia niczego, z czego dałoby się wyciągnąć zasadę.

6. Właściciel i pomiar

Zasady bez właściciela w kilka miesięcy się dezaktualizują. Agent nadal ich słucha, nawet gdy już nie obowiązują. Proszę skopiować to do 90-wlasciciel.md:

Właściciel: [imię]
Nowa zasada: PR do .claude/rules/, zatwierdza właściciel.
Porządki: pierwszy poniedziałek miesiąca, 30 minut.
Drabina: złamana dwa razy -> poziom wyżej
  zdanie -> ustawienie lub hook -> CI -> lint
Co miesiąc zapisujemy: ile zasad to wciąż tylko zdanie.

Trzy liczby, które warto śledzić co miesiąc:

• Komentarze z review na jeden PR. Jeśli zasady działają, spadają.
• Ile razy kontrola zatrzymała zmianę. I ile razy agent potem sam to poprawił.
• Ile zasad to wciąż tylko zdanie. To lista zadań na kolejny miesiąc.

Proszę nie mierzyć commitów ani linii kodu. AI napompuje je w sekundę.

7. Arkusz dla zespołu (45 minut)

Proszę go wydrukować, położyć na stole i wypełnić razem.

Jest gotowy, gdy przy każdym wierszu potrafią Państwo powiedzieć, co go wymusza i kto jest właścicielem.