O autorze

Jakub Stankowski – programista .NET i Angular od 2018 roku. Pracował nad projektami frontendowymi, backendowymi i fullstackowymi, przestrzegając zasad czystego kodu, DRY i stosując CQRS. Ma również doświadczenie jako trener programowania.

Od 2023 roku intensywnie pracuje z Claude AI oraz metodą Spec-Driven Development (SDD) – produkcyjnym workflow do pracy z AI opartym na zasadzie: najpierw specyfikacja, potem implementacja. Na ProgramujZAI.pl dzieli się praktyczną wiedzą o tym, jak programować z AI bez chaosu w kodzie.

Poznaj Jakuba →

Dobry CLAUDE.md jest krótki, konkretny i sprawdzalny. Wpisz do niego komendy, konwencje, granice i definicję ukończenia, czyli to, co inaczej tłumaczyłbyś agentowi w każdej sesji. Trzymaj go poniżej 200 linii. Procedury przenieś do skilli, a twarde zakazy do hooków, bo CLAUDE.md to kontekst, a nie egzekwowana reguła. Jeśli pracujesz też z innymi agentami, trzymaj treść w AGENTS.md i zaimportuj ją jedną linijką.

CLAUDE.md to stała część specyfikacji projektu

Każda sesja Claude Code startuje z pustym kontekstem. CLAUDE.md jest plikiem, który agent czyta na początku każdej z nich. W podejściu Spec Driven Development to kontrakt obowiązujący przy każdym zadaniu, a specyfikacja funkcji opisuje tylko bieżącą zmianę.

Dokumentacja Claude Code podaje prostą regułę. Dopisz coś do pliku, gdy agent drugi raz popełnia ten sam błąd albo gdy kolejny raz wpisujesz tę samą poprawkę w czacie. Plik projektu trzymasz w ./CLAUDE.md i commitujesz do repozytorium. Swoje prywatne ustawienia zapisujesz w ~/.claude/CLAUDE.md.

Wpisz komendy, konwencje, granice i definicję ukończenia

Skuteczny plik odpowiada na cztery pytania:

• Komendy: jak zbudować projekt, uruchomić testy i linter.
• Konwencje: nazewnictwo, struktura katalogów, styl, który odbiega od domyślnego.
• Granice: czego agentowi nie wolno, np. edytować migracji albo zmieniać publicznego API.
• Definicja ukończenia: kiedy zadanie jest skończone, np. testy i linter przechodzą bez błędów.

Każda instrukcja musi dać się sprawdzić. „Pisz czysty kod” niczego nie zmienia. „Handlery API trzymaj w src/api/handlers/” agent zastosuje od razu. Unikaj też sprzeczności, bo przy dwóch różnych regułach agent wybierze jedną przypadkowo.

Nie wpisuj tego, co agent wyczyta z kodu

Najczęstszy błąd to plik na 600 linii z opisem architektury i listą zależności. Agent sam to odczyta z repozytorium, a Ty płacisz tokenami w każdej sesji.

Do CLAUDE.md nie wpisuj:

• drzewa katalogów i listy bibliotek,
• ogólników typu „dbaj o jakość”,
• wieloetapowych procedur, np. wdrożenia,
• reguł dotyczących jednego modułu,
• sekretów i adresów środowisk.

Notatki dla ludzi wpisuj jako komentarze HTML. Claude Code usuwa je przed załadowaniem pliku, więc nie zużywają kontekstu.

Zakazy przenieś do hooków, procedury do skilli

Agent traktuje CLAUDE.md jak kontekst, a nie jak twardą konfigurację. Zwykle się go trzyma, ale nie ma gwarancji. Zasada, której złamanie kosztuje, musi być egzekwowana w kodzie.

Przykład z refaktoryzacji kodu z AI: „agent nie edytuje testów” zapisz w CLAUDE.md jako regułę, a zablokuj hookiem. Skille ładują się dopiero wtedy, gdy są potrzebne, więc nie zajmują kontekstu. Przykłady znajdziesz w zestawieniu najlepszych skilli Claude Code.

Jeden plik działa też jako AGENTS.md

AGENTS.md to otwarty standard, który czyta m.in. Codex. Claude Code od wersji 2.1.277 czyta go samodzielnie, ale tylko wtedy, gdy w projekcie nie ma CLAUDE.md.

Najpewniejszy układ dla obu narzędzi:

• wspólne zasady trzymasz w AGENTS.md,
• w CLAUDE.md wpisujesz pierwszą linię @AGENTS.md,
• pod nią dopisujesz tylko rzeczy specyficzne dla Claude.

Dowiązanie symboliczne też działa, ale nie polecam go zespołom z Windowsem. Różnice między narzędziami opisuję w porównaniu Codex vs Claude Code.

Szablon CLAUDE.md do skopiowania

# Projekt: [nazwa]
[Jedno zdanie: co robi system i dla kogo.]

## Komendy
- Build: `[komenda]`
- Testy: `[komenda]`
- Lint: `[komenda]`

## Konwencje
- [Konwencja odbiegająca od domyślnej]
- [Gdzie trzymać nowe pliki danego typu]

## Granice
- Nie edytuj testów bez wyraźnej prośby.
- Nie zmieniaj publicznego API ani migracji.
- Nie dodawaj zależności bez pytania.

## Sposób pracy
- Przed większą zmianą pokaż plan i poczekaj na akceptację.
- Jedna zmiana = jeden mały diff.
- Specyfikacje zadań są w `docs/specs/`.

## Definicja ukończenia
- Testy i lint przechodzą.
- Zmiana jest zgodna ze specyfikacją zadania.
- Podsumuj, co zmieniłeś i czego nie sprawdziłeś.

Szablon ma ok. 25 linii, więc zostaje dużo miejsca na Twoje reguły. Specyfikację zadań przygotujesz według poradnika jak napisać dobrą specyfikację dla AI.

Jak wdrożyć to w praktyce

1. Uruchom /init. Claude przeanalizuje repozytorium i wygeneruje szkic.
2. Wytnij ze szkicu wszystko, co agent i tak wyczyta z kodu.
3. Uzupełnij szablon o granice i definicję ukończenia.
4. Sprawdź /context, czy plik się załadował.
5. Dopisuj regułę po każdym powtórzonym błędzie agenta.
6. Raz w miesiącu uruchom audyt /doctor prompt-audit i usuń przestarzałe zapisy.

Pełną konfigurację środowiska opisuję w tutorialu konfiguracji Claude Code.

FAQ

Gdzie umieścić plik CLAUDE.md?

W katalogu głównym projektu, jako ./CLAUDE.md lub ./.claude/CLAUDE.md. Osobiste preferencje dla wszystkich projektów zapisz w ~/.claude/CLAUDE.md.

Jak długi powinien być CLAUDE.md?

Dokumentacja zaleca mniej niż 200 linii na plik. Dłuższy plik zużywa więcej kontekstu i obniża skuteczność instrukcji.

Dlaczego Claude ignoruje CLAUDE.md?

Najczęściej przez ogólnikowe lub sprzeczne instrukcje albo plik, który się nie załadował. Sprawdź /context, doprecyzuj reguły, a zakazy przenieś do hooków.

Czym różni się CLAUDE.md od AGENTS.md?

Oba opisują projekt dla agenta. AGENTS.md to otwarty standard wielu narzędzi, a CLAUDE.md jest plikiem Claude Code. Najprościej trzymać treść w AGENTS.md i zaimportować ją w CLAUDE.md.

Chcesz zobaczyć mój CLAUDE.md w akcji? Subskrybuj kanał na YouTube i pobierz darmowy workflow ze strony standev.it/ai-workflow-bonus.