CLAUDE.md i AGENTS.md: zasady dla kodu AI w zespole

CLAUDE.md i AGENTS.md to pliki w repozytorium, które agent AI wczytuje przy każdym zadaniu, aby poznać zasady zespołu. Zasady dla kodu AI w zespole należą właśnie tam, a nie do głowy seniora. Krótki plik dla agenta, CLAUDE.md lub AGENTS.md, mówi, jak weryfikuje się pracę i czego agentowi nie wolno. Ale najważniejsze zasady nie powinny być tekstem. Powinny być lintem, testami lub CI, które same zatrzymują złą zmianę.

U nas większość kodu pisze AI. Każdą zmianę sprawdza senior i odpowiada za produkcję. Od 2023 roku dostarczyliśmy ponad 15 projektów produkcyjnych, a do kwietnia 2026 pracowaliśmy w zespole produktowym SaaS-a, z którego codziennie korzystało ponad 60 000 osób. Poniższych zasad nauczyliśmy się na tych projektach, głównie na własnych błędach.

Co należy do CLAUDE.md lub AGENTS.md?

To, czego agent nie wyczyta z kodu, i to, co robią Państwo inaczej niż wszyscy. Konkretnie:

• Jak uruchomić projekt i testy. Najlepiej jedno polecenie, które agent może skopiować.
• Czego agentowi nie wolno. Produkcyjnej bazy danych, tajnych kluczy, migracji bez zgody, pushowania prosto do głównej gałęzi.
• Gdzie co jest. Gdzie jest logika biznesowa, gdzie testy, co jest generowane i nie wolno tego edytować ręcznie.
• Niestandardowe konwencje. Jak nazywają Państwo rzeczy, jak obsługują błędy, gdzie są tłumaczenia.
• Jak wygląda skończona praca. Co musi przejść, zanim agent otworzy pull request.

Czego tam nie ma: stylu, który już wymusza formater. Długich esejów o architekturze. Zasad, które obowiązują tylko w jednym folderze.

CLAUDE.md czy AGENTS.md?

Claude Code czyta CLAUDE.md, a gdy repozytorium go nie ma, aktualne wersje czytają bezpośrednio AGENTS.md. Wiele innych narzędzi, na przykład Codex, też czyta AGENTS.md. Jeśli zespół używa kilku narzędzi, proszę nie pisać zasad dwa razy.

Proszę trzymać je w AGENTS.md i wskazać go z CLAUDE.md linią @AGENTS.md. Claude Code wczyta go wtedy sam. Dwie osobne kopie rozjadą się, zanim ktokolwiek to zauważy.

Ile zasad to za dużo?

Granica przychodzi szybciej, niż się wydaje. Agent wczytuje zasady przy każdym uruchomieniu. Im więcej tekstu ma w kontekście, tym gorzej trzyma się tego, co ważne.

U nas sprawdza się podział na trzy poziomy. Katalog główny repozytorium zawiera minimum, które obowiązuje wszędzie. Zasady jednego modułu są w pliku w jego folderze i agent wczytuje je tylko wtedy, gdy tam pracuje. Najważniejsze zasady to lint lub testy: nikt nie musi ich czytać, same zatrzymują złą zmianę.

Szczerze: nie mamy idealnej odpowiedzi. Zasady przybywają z każdym błędem. Dlatego regularnie je porządkujemy i przenosimy do lintu wszystko, co się da.

Skąd wziąć zasady, gdy jeszcze ich nie ma?

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

Często polecamy, żeby agent przejrzał stare komentarze z review i wyciągnął z nich zasady. Działa to tylko wtedy, gdy komentarze istnieją. Jeśli review odbywa się tylko ustnie, na callu, nic nie trafia do pull requestów. Agent nie ma wtedy z czego pracować.

Najpierw więc nawyk, potem narzędzie. Proszę zapisywać uwagi w pull requeście, a nie tylko mówić je na głos.

Gdzie należy każda zasada?

Agent potrafi obejść zakaz zapisany jako zdanie. Nie otworzy pliku, ale napisze skrypt, który go wypisze. Dlatego przy każdej zasadzie zapisujemy, co ją wymusza.

Agenta, który pracuje samodzielnie, proszę uruchamiać tylko w osobnym środowisku, bez dostępu do produkcji i tajnych kluczy. Hook, który odrzuca niebezpieczne polecenie, to dobry pierwszy krok. Ale to próg zwalniający, nie mur: sprytny agent znajdzie inną drogę. Żadne zdanie w stylu „uważaj” nie zastąpi ani jednego, ani drugiego.

Szablon zawiera tabelę i zakazy wraz z tym, co każdy z nich wymusza. Otwórz szablon: Zasady dla agentów AI w Państwa zespole (online lub PDF).

Jak dzielić zasady między kilka repozytoriów?

Przez dystrybucję, nie dyscyplinę. Trzymaliśmy zasady w głównym repozytorium, a pozostałe ich nie widziały. Część je skopiowała. Po kilku miesiącach było kilka wersji i żadne dwie nie były takie same.

Dziś mamy jeden pakiet zasad, który wczytuje się w każdym repozytorium. Jest wersjonowany i zmienia się tylko przez zatwierdzony pull request. Nie ma kopii, więc nic nie może się rozjechać. Zasady osobiste to styl pracy każdego programisty. Wspólne zasady należą do firmy i muszą żyć w jednym miejscu. Ten sam pakiet zasad konfigurujemy w zespołach, do których dołączamy w ramach AI-native SDLC dla zespołów deweloperskich. Zespołowi brakuje raczej rąk niż zasad? Proszę zobaczyć senior developera dla Państwa zespołu.

Review i testy: zasady, których nie ma w pliku

Niektóre zasady nie dotyczą agenta, tylko procesu wokół niego. Które z nich Państwa zespół już ma?

Test, który nigdy nie zawiódł, dowodzi tylko, że agent zgadza się sam ze sobą. A pipeline, który tylko raportuje, to dekoracja.

Jak krok po kroku wprowadzić te zasady w całym zespole, opisujemy w Claude Code best practices dla zespołu: 7 zasad, które się trzymają. Dlaczego środowisko pracy agenta jest ważniejsze niż model, wyjaśnia Agent = model + środowisko. Jeśli zespół wciąż wybiera narzędzie, proszę przeczytać Cursor vs Claude Code.

Kiedy tego nie polecamy

• Jest Państwa jeden lub dwóch programistów w jednym repozytorium. Wystarczy krótki CLAUDE.md lub AGENTS.md. Proszę napisać go samodzielnie na podstawie listy powyżej.
• Nie mają Państwo testów ani CI, które blokuje. Wtedy zasady dla agenta niewiele zmienią. Najpierw testy i CI, potem zasady.

• Oczekują Państwo, że szablon zastąpi review. Nie zastąpi. Zasady wynikają z Państwa review, więc proszę zacząć od uwag w pull requestach.

Chcą Państwo ustawić zasady z kimś, kto pracuje z nimi codziennie?

Przyglądamy się Państwa repozytoriom i proponujemy pierwszą wersję zasad oraz bramek w CI. Senior dołącza do Państwa repozytorium i pull requestów pierwszego dnia.

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ą.

Gdzie dziś żyją zasady Państwa zespołu?

Najczęstsze pytania

Czym jest CLAUDE.md?

Plikiem w repozytorium, który Claude Code wczytuje przy każdym uruchomieniu. Zawiera zasady dla agenta: jak uruchomić testy, czego nie wolno mu robić i jak wygląda skończona praca. Inne narzędzia czytają podobny plik o nazwie AGENTS.md.

CLAUDE.md czy AGENTS.md?

Jeśli zespół używa tylko Claude Code, wystarczy CLAUDE.md. Jeśli kilku narzędzi, proszę trzymać zasady w AGENTS.md. Bez CLAUDE.md Claude Code czyta go bezpośrednio; z nim proszę wskazać AGENTS.md linią @AGENTS.md. Dwie osobne kopie z czasem się rozjeżdżają.

Ile zasad powinien mieć CLAUDE.md?

Jak najmniej. Agent wczytuje je przy każdym uruchomieniu, a za dużo tekstu pogarsza jego wyniki. W katalogu głównym tylko to, co obowiązuje wszędzie. Resztę do folderów, a najważniejsze zasady do lintu lub testów.

Kto powinien odpowiadać za zasady dla AI w zespole?

Jedna wskazana osoba, która zatwierdza zmiany. Pisać je może każdy, przez pull request. Bez właściciela każdy dopasowuje je po swojemu i wspólna warstwa się rozpada.

Czy wystarczy powiedzieć agentowi, czego mu nie wolno?

Nie. Agent potrafi obejść zakaz zapisany słowami. To, co naprawdę ważne, proszę wymusić uprawnieniami, hookiem, lintem lub CI. Przy każdej zasadzie proszę zapisać, co ją wymusza.