CLAUDE.md – instrukcje dla Claude Code

CLAUDE.md to mechanizm pamięci jawnej (explicit memory) w Claude Code. W odróżnieniu od auto memory, którą Claude zapisuje sam, CLAUDE.md tworzysz Ty – i decydujesz, co ma się znaleźć w stałym kontekście agenta.

Plik działa na zasadzie „przeczytaj przed rozpoczęciem”. Na starcie każdej sesji Claude ładuje treść CLAUDE.md do okna kontekstowego. Dzięki temu agent od razu wie, z jakim projektem pracuje, jakie masz preferencje i czego od niego oczekujesz. Nie musisz tego powtarzać w czacie.

Oficjalna dokumentacja Anthropic wyróżnia trzy poziomy zakresu:

Poziom zarządzany (Managed policy) – plik w /etc/claude-code/CLAUDE.md (Linux) lub /Library/Application Support/ClaudeCode/CLAUDE.md (macOS). Narzucany przez administratora; użytkownik nie może go edytować. Przydatny w firmach, które chcą wymusić bezpieczeństwo lub standardy.

Poziom użytkownika (User-level) – plik ~/.claude/CLAUDE.md. Dotyczy każdej sesji, niezależnie od projektu. Umieszczasz tu swoje osobiste preferencje: domyślny edytor, ulubione narzędzia, ogólne reguły pracy. To Twoja „bazowa instrukcja”.

Poziom projektu (Project-root) – plik CLAUDE.md w katalogu głównym repozytorium. Zazwyczaj wersjonowany w git, współdzielony z zespołem. Zawiera kontekst specyficzny dla danego projektu: stack technologiczny, konwencje nazewnictwa, komendy build/test/deploy, architekturę, znane ograniczenia.

Oprócz tego istnieją reguły ścieżkowe (.claude/rules/), które ładują się tylko przy pracy z określonymi plikami, oraz importy @path umożliwiające dzielenie CLAUDE.md na moduły.

Co umieścić w CLAUDE.md?

Dokumentacja Anthropic radzi, żeby CLAUDE.md traktować jako miejsce na rzeczy, które musiałbyś powtarzać przy każdej sesji. Przykłady:

Stack techniczny: „Next.js 16 + Tailwind 4 + Sanity + Supabase. Routing przez src/proxy.ts.”

Komendy: „npm run dev – dev server, npm run build – pełny build, npm run lint – ESLint.”

Konwencje kodowania: „Komponenty w kebab-case, export default. Testy w __tests__.”

Zasady bezpieczeństwa: „Nigdy nie commit .env. Nie używaj force push. Sprawdzaj, czy nie ma secretsów.”

Kontekst architektoniczny: „Struktura katalogów: src/app na routing, src/components na UI, src/lib na logikę.”

CLAUDE.md w systemie AI soloprzedsiębiorcy

Dla soloprzedsiębiorcy budującego własny system AI, CLAUDE.md to coś więcej niż plik konfiguracyjny – to rdzeń źródła prawdy (source of truth) dla agenta. W praktyce oznacza to:

Mapa Kontekstu: umieszczasz w CLAUDE.md opis swojego biznesu, grupy docelowej, oferty i tonu głosu. Agent używa tego do tworzenia spójnego contentu.

Automatyzacje: definiujesz reguły uruchamiania skryptów, hooków i integracji – agent wie, kiedy i jak ma je wywołać.

Ograniczenia: określasz, czego agent ma nie robić – np. nie kasować plików bez potwierdzenia, nie deployować na produkcję bez zgody.

Spójność między sesjami: każda nowa sesja zaczyna się z tym samym kontekstem – agent nie „zapomina” Twoich ustaleń z poprzedniego dnia.

Ograniczenia i pułapki

CLAUDE.md to instrukcja, nie wymóg. Claude może, ale nie musi, jej przestrzegać – model ocenia kontekst i podejmuje decyzje samodzielnie. Jeśli potrzebujesz absolutnej gwarancji (np. „nigdy nie kasuj bazy danych”), użyj hooka PreToolUse, który działa deterministycznie.

Plik nie może być zbyt długi. Oficjalne zalecenie to maksymalnie 200 linii lub 25 KB. Powyżej tego Claude zaczyna gorzej trzymać się instrukcji. Narzędzie /doctor w Claude Code (od wersji 2.1.206) proponuje przycięcie zawartości, którą model może wywnioskować sam z kodu.

Zagnieżdżone pliki CLAUDE.md w podkatalogach nie są automatycznie przeładowywane po kompakcji (/compact). Ładują się ponownie dopiero, gdy Claude otworzy plik z tego katalogu. Instrukcje, które mają działać zawsze, trzymaj w pliku głównym.

W systemach multi-agoentowych (sub-agent) każdy sub-agent może mieć własny plik CLAUDE.md i własną auto memory. Zarządzanie spójnością między nimi to osobne wyzwanie – warto centralizować wspólne reguły w user-level CLAUDE.md.

CLAUDE.md vs AGENTS.md vs inne formaty

Na rynku pojawiło się kilka konkurencyjnych formatów plików instrukcji. AGENTS.md to standard przyjęty przez Codex (OpenAI), który działa też z Claude Code i Cursor. Różnica: CLAUDE.md jest specyficzny dla Claude i ładuje się zawsze; AGENTS.md jest bardziej uniwersalny. Niektóre zespoły używają obu, inne wybierają jeden. Bartek w swoim systemie używa głównie CLAUDE.md z dodatkowymi regułami w .claude/rules/