Claude Code: dobre praktyki dla zespołu. 7 zasad, które działają

Dobre praktyki Claude Code, które mają znaczenie w zespole, to nie triki promptowania. To siedem zasad, które działają nawet wtedy, gdy nikt nie patrzy: krótki CLAUDE.md, którego długości pilnuje CI, jeden wspólny plugin, uprawnienia i hooki w repozytorium, jedno issue to jeden PR, test, który najpierw nie przechodzi, i recenzent, który nie pisał kodu. Każdej pilnuje plik albo kontrola, a nie pamięć.

Tak pracujemy w każdym repozytorium, a większość naszego kodu pisze AI. Dalej pokazujemy, jak egzekwujemy każdą praktykę, na prawdziwych plikach.

Które praktyki Claude Code działają w zespole?

Porady dla jednej osoby żyją w jej głowie. Praktyka zespołowa potrzebuje miejsca, w którym jest zapisana, i kontroli, która zauważy, kiedy przestaje działać:

Proszę czytać tabelę także jako kolejność. Pierwsze cztery kosztują jedno popołudnie. Ostatnie trzy zmieniają przepływ pracy.

1. Dlaczego CLAUDE.md ma być krótki i jak to egzekwować?

CLAUDE.md i każdy zawsze ładowany plik zasad trafiają do kontekstu przy każdym zapytaniu. Przewodnik po kosztach Anthropic zaleca trzymać go poniżej 200 linii, a instrukcje dotyczące przepływu pracy przenieść do skilli, które ładują się tylko wtedy, gdy są używane.

"Proszę pisać krótko" wytrzymuje mniej więcej dwa tygodnie. Dlatego nasz walidator liczy linie. Sumuje CLAUDE.md i wszystkie zawsze ładowane zasady, i dlatego jego limit to 300 linii, a nie 200:

# CLAUDE.md + every .claude/rules/*.md that loads on every session
# (rules scoped with `paths:` load only under matching paths and are skipped)
if [ "$total_lines" -gt 300 ]; then
  log_critical "Context budget exceeded: $total_lines lines (max 300)."
fi

Działa w CI w każdym repozytorium. W repozytoriach firmowych i klientów zatrzymuje build, w repozytoriach z kodem ostrzega.

Druga połowa to miejsce, w którym zasada ląduje. Osobisty styl pracy należy do ~/.claude. Wszystko, czego musi przestrzegać cały zespół, należy do repozytorium.

Jak podzielić zasady między CLAUDE.md, AGENTS.md i pliki osobiste, opisujemy szczegółowo w artykule Zasady dla kodu AI w zespole.

2. Dlaczego jeden wspólny plugin zamiast kopii?

Kiedyś kopiowaliśmy nasze skille do planowania, budowania i przeglądu do każdego repozytorium. W ciągu kilku tygodni kopie się rozjechały, a niektóre były pustymi zaślepkami. Dyscyplina tego nie naprawiła. Naprawił to jeden plugin: wizrd, nasz wewnętrzny plugin i CLI do Claude Code (niepubliczny). Skille, agenci i hooki żyją w jednym repozytorium, a każde inne repozytorium włącza go dwiema linijkami ustawień:

{
  "enabledPlugins": { "wizrd@digitaliko": true },
  "extraKnownMarketplaces": {
    "digitaliko": { "source": { "source": "directory", "path": "services/wizrd" } }
  }
}

Poprawka w skillu do przeglądu trafia teraz do każdej sesji przy jej następnym starcie. Jak zbudowaliśmy sam plugin, opisujemy w artykule Skille i pluginy Claude Code dla zespołu.

3. Dlaczego uprawnienia mają być w repozytorium?

Bo deny w repozytorium wygrywa z allow w każdym innym miejscu. Claude Code najpierw sprawdza reguły deny, potem ask, a potem allow, we wszystkich plikach ustawień. Zespół decyduje więc raz, w .claude/settings.json: deny dla plików .env i kluczy, ask przed pushem, merge'em lub deployem, allow dla skryptów, których agent potrzebuje, żeby sprawdzić własną pracę.

Wszystko, co osobiste, zostaje w ~/.claude/settings.json. Strukturę i nasze dokładne wpisy pokazujemy w artykule Claude Code dangerously-skip-permissions: kiedy jest bezpieczne?.

4. Dlaczego blokować hookami, zamiast prosić w CLAUDE.md?

Zdanie w CLAUDE.md to prośba. Pewnego październikowego dnia agent wpisał stopkę z atrybucją AI do opisów kilku pull requestów w naszych własnych repozytoriach, w sesji, której CLAUDE.md zabraniał dokładnie tego wprost.

Rozwiązaniem był hook PreToolUse, który sprawdza każde polecenie git commit, gh pr i gh issue, łącznie z plikami przekazanymi przez --body-file, i kończy się kodem exit 2. Komentarz na początku skryptu mówi to najlepiej: "A rule is a request. This is the lock." (Zasada to prośba. To jest zamek.)

Hooki mają własny sposób awarii: mogą zamilknąć i dalej przechodzić. Cztery kontrole, które to wyłapują, opisujemy w artykule Hooki Claude Code, które po cichu nic nie robią.

5. Dlaczego jedno issue to jeden PR?

Sesja agenta zapomina. Issue na GitHubie nie. Każde zadanie zaczyna się jako issue z opisem, co znaczy "gotowe", napisanym tak, żeby recenzent mógł odpowiedzieć tak lub nie, i kończy się jednym pull requestem z Closes #N.

To daje trzy rzeczy, których sesja czatu dać nie może. Plan jest widoczny, zanim zacznie się praca. Dwóch agentów może pracować równolegle, każdy we własnym git worktree na własnej gałęzi, bez wchodzenia sobie w drogę. A scalone pull requesty są changelogiem, więc nikt nie pisze dziennika pracy.

Plan mode pomaga wewnątrz sesji. Gdzie przestaje wystarczać zespołowi, opisujemy w artykule Claude Code plan mode: kiedy wystarczy?.

6. Dlaczego test musi najpierw nie przechodzić?

Agent potrafi napisać testy, które przechodzą bez względu na to, czy kod działa. Dlatego nasz gate uruchamia nowe lub zmienione testy na gałęzi bazowej, przed poprawką. Jeśli tam też przechodzą, niczego nie dowodzą i pull request wraca. Liczy się tylko test, który bez zmiany jest czerwony, a ze zmianą zielony. Cały mechanizm opisujemy w artykule Red-green TDD z agentami AI.

7. Dlaczego kod powinien przejrzeć inny agent?

Agent autor zdążył już przekonać sam siebie. Nowa sesja, która czyta tylko diff, znajduje to, co autor pominął. Nasz recenzent w CI dostaje listę narzędzi tylko do odczytu (git diff, git log, gh pr diff, Read, Grep) i checklistę przeglądu z repozytorium. Komentuje. Nigdy nie zatwierdza. Ochrona gałęzi wymaga człowieka, więc merge jest zawsze ludzką decyzją. Konfigurację i prompt pokazujemy w artykule Code review z Claude Code w CI.

Od czego zespół powinien zacząć?

Nie od wszystkich siedmiu naraz. Kolejność, która sprawdziła się u nas:

Pierwsze trzy zajmują dzień w istniejącym repozytorium. Czwarty to nawyk i potrzeba kilku tygodni komentarzy w przeglądach, zanim zespół zacznie pisać issues, które agent zamknie bez dopytywania.

Gdzie jest dziś Państwa zespół?

Proszę policzyć, co już jest w Państwa repozytoriach, a nie to, co ludzie mówią, że robią:

Ustawienia, hooki, gate i workflow przeglądu mogą Państwo skopiować z naszego Claude Code production starter na licencji MIT.

Chcą Państwo, żeby te praktyki działały w Państwa repozytoriach?

Wdrażamy je bezpośrednio w repozytoriach zespołu, razem z programistami, w ramach AI-native SDLC dla zespołów deweloperskich. Większość naszego kodu pisze AI. Każdą zmianę sprawdza senior i to on odpowiada za produkcję. Od 2023 roku dostarczyliśmy ponad 15 projektów produkcyjnych.

Odezwiemy się w ciągu dwóch dni roboczych z kilkoma pytaniami o Państwa pracę. Potem ustalimy, co zrobimy najpierw.

Jeśli wolą Państwo najpierw porozmawiać, proszę zarezerwować 15-minutową rozmowę wstępną.

Która z tych siedmiu zasad rozpadłaby się w Państwa zespole jako pierwsza, gdyby nikt jej nie sprawdzał?

Najczęstsze pytania

Jakie są najważniejsze dobre praktyki Claude Code?

Dla zespołu: trzymać CLAUDE.md krótko i egzekwować limit, udostępniać skille i hooki jako jeden plugin, umieścić uprawnienia w repozytorium, blokować hookami zamiast prosić prozą, prowadzić jedno issue do jednego PR, udowadniać każdą zmianę testem, który najpierw nie przechodzi, i dać ją do przeglądu innemu agentowi, zanim człowiek zrobi merge.

Jak długi powinien być CLAUDE.md?

Na tyle krótki, żeby opłacał się przy każdym zapytaniu. Anthropic zaleca poniżej 200 linii. My liczymy CLAUDE.md razem z każdym zawsze ładowanym plikiem zasad i w repozytoriach firmowych i klientów CI nie przechodzi powyżej 300 linii.

Czy ustawienia Claude Code powinny trafić do gita?

Część zespołowa tak: .claude/settings.json z uprawnieniami i hookami należy do repozytorium. Osobiste preferencje trafiają do ~/.claude/settings.json, a lokalne nadpisania do .claude/settings.local.json, który zostaje poza gitem.

Jak udostępniać skille Claude Code w zespole?

Jako plugin, który każde repozytorium włącza w swoich ustawieniach. Kopie skilli w poszczególnych repozytoriach rozjeżdżają się w ciągu kilku tygodni; jeden plugin daje każdej sesji te same skille, agentów i hooki.

Czy plan mode to dobra praktyka przy każdym zadaniu?

Do rozeznania przed większą zmianą tak. W zespole plan musi też być tam, gdzie inni mogą go przeczytać, na przykład w issue z kryteriami akceptacji, a nie tylko w sesji jednego programisty.