Inicjalizacja projektu dla Claude Code: CLAUDE.md, reguły i pamięć

Inicjalizacja projektu dla Claude Code polega na zacommitowaniu krótkiego pliku CLAUDE.md z poleceniami, konwencjami i pułapkami, których Claude nie wywnioskuje z kodu, oraz na przeniesieniu węższych instrukcji do reguł w .claude/rules/ zawężonych do ścieżek. Polecenie /init tworzy szkic pliku. Konfiguracja jest gotowa dopiero wtedy, gdy /context pokazuje plik, a pytanie kontrolne zwraca dokładne polecenia.

Otwierasz Claude Code w serwisie TypeScript i prosisz o nowy endpoint. Claude instaluje pakiet przez npm, choć repozytorium używa pnpm, pisze testy w Jest do zestawu opartego na Vitest i pomija migrację, której wymaga każda zmiana schematu. To nie jest problem modelu: sesja wystartowała bez kontekstu twojego projektu. Ta strona jest dla developera, który konfiguruje Claude Code w istniejącym repozytorium, i dla tech leada, który potem odpowiada za zacommitowane pliki instrukcji.

Co zyskasz, inicjalizując projekt dla Claude Code

• Zacommitowany CLAUDE.md poniżej 200 linii, ze sprawdzonymi poleceniami i konwencjami, które odbiegają od domyślnych ustawień narzędzi.
• Jedną regułę w .claude/rules/ zawężoną do ścieżek i wygenerowaną z kodu, który już jest w repozytorium.
• Jasny podział na to, co piszesz ty (CLAUDE.md, reguły), co zostaje prywatne (CLAUDE.local.md, ~/.claude/CLAUDE.md) i co Claude zapisuje sam (pamięć automatyczna).
• Weryfikację w trzech krokach, którą powtarzasz po każdej zmianie: /context, pytanie kontrolne w nowej sesji i bramkę przeglądu samych plików.

Jeśli zaczynasz repozytorium od zera, a nie dodajesz Claude Code do istniejącego, najpierw rozpocznij nowy projekt z terminala, a potem wróć tutaj.

Skąd Claude Code czyta instrukcje projektu?

Claude Code czyta pliki instrukcji z kilku zakresów. Pierwsze wiersze odpowiadają kolejności ładowania z oficjalnej dokumentacji pamięci, od najszerszego; reguły, pliki podkatalogów i pamięć automatyczna ładują się tak, jak pokazuje ostatnia kolumna:

Zakres	Lokalizacja	Kto go widzi	Kiedy się ładuje
Polityka zarządzana	macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux i WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md	Wszyscy na danej maszynie; użytkownik nie może go wykluczyć	Przy starcie
Użytkownik	~/.claude/CLAUDE.md i ~/.claude/rules/	Tylko ty, każdy projekt	Przy starcie
Projekt	./CLAUDE.md lub ./.claude/CLAUDE.md	Zespół, przez git	Przy starcie
Reguły projektu	./.claude/rules/**/*.md	Zespół, przez git	Przy starcie albo, gdy reguła ma paths, kiedy Claude czyta pasujący plik
Lokalny	./CLAUDE.local.md	Tylko ty, ten projekt	Przy starcie
Podkatalog	./packages/api/CLAUDE.md i podobne	Zespół	Kiedy Claude czyta pliki w tym katalogu
Pamięć automatyczna	~/.claude/projects/<project>/memory/MEMORY.md	Tylko ty, ta maszyna	Przy starcie: pierwsze 200 linii lub 25KB

Dwa szczegóły z tej tabeli zmieniają sposób pisania plików:

• Pliki są sklejane, a nie nadpisywane. Każdy plik, który Claude Code znajdzie, trafia do kontekstu. Reguła projektu nie zastępuje reguły użytkownika; po prostu jest czytana później. Gdy dwa pliki sobie przeczą, Claude może pójść za którymkolwiek z nich, więc konflikt naprawiasz, usuwając jedną ze stron.
• Instrukcje to kontekst, a nie egzekwowanie. Claude czyta CLAUDE.md i stara się go przestrzegać. Wszystko, co ma się dziać za każdym razem, na przykład uruchomienie lintera po edycji albo zakaz dotykania migrations/, należy do hooka lub reguły uprawnień, które klient egzekwuje niezależnie od decyzji modelu.

Repozytoria, które mają już AGENTS.md

Od wersji v2.1.277 (v2.1.281 w Amazon Bedrock, Google Cloud, Microsoft Foundry, bramkach LLM i sesjach z wyłączoną telemetrią; oba na kanałach wydań latest i stable na dzień 2026-10-12) Claude Code czyta AGENTS.md, gdy w katalogu roboczym ani powyżej nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Żeby mieć jeden plik dla Claude Code i Codeksa, który czyta AGENTS.md, wpisz @AGENTS.md w pierwszej linii CLAUDE.md, a instrukcje specyficzne dla Claude dodaj poniżej. Ten import działa w każdej wersji i każdym kanale.

Zainicjuj projekt w pięciu krokach

1. Uruchom sesję w katalogu głównym repozytorium. W terminalu otwórz repozytorium i uruchom tam Claude Code, bo Claude Code ładuje pliki CLAUDE.md z katalogu roboczego i wszystkich katalogów powyżej:

   cd ~/code/orders-api
   claude

2. Uruchom /init. W prompcie Claude Code wpisz:

   /init

   Claude czyta kod i zapisuje startowy CLAUDE.md z poleceniami budowania i testów oraz konwencjami, które wykrył. Jeśli CLAUDE.md już istnieje, /init proponuje poprawki zamiast go nadpisywać. Uwzględnia też .cursor/rules/, .cursorrules i .github/copilot-instructions.md, jeśli repozytorium je ma. Jeśli chcesz tryb prowadzony, który proponuje też skille i hooki i przed zapisem pokazuje propozycję do przejrzenia, ustaw CLAUDE_CODE_NEW_INIT=1 w powłoce przed uruchomieniem claude; ten tryb czyta też AGENTS.md, .devin/rules/, .windsurf/rules/ lub .windsurfrules oraz .clinerules. Jeśli przechodzisz z innego agenta, /import codex, /import cursor lub /import gemini (v2.1.213 lub nowszy; dla Cursora v2.1.265; niedostępne w Amazon Bedrock, Google Cloud, Microsoft Foundry, Claude Platform on AWS ani przez bramkę Claude apps) dopisuje jednorazową kopię plików instrukcji tego narzędzia i przenosi jego serwery MCP, polecenia, subagentów i skille.

3. Zetnij szkic do tego, czego Claude nie wywnioskuje. Szkic z /init zwykle opisuje drzewo katalogów i listę zależności, a to Claude odczyta z kodu w każdej sesji. Zostaw polecenia, nieoczywiste konwencje i pułapki. Pierwszy prompt poniżej robi to cięcie w oparciu o dowody.

4. Przenieś wąskie instrukcje do reguły zawężonej do ścieżek. Konwencja, która dotyczy tylko src/routes/ albo tylko migracji, trafia do .claude/rules/ z polem paths, więc ładuje się tylko wtedy, gdy Claude pracuje na tych plikach. Drugi prompt poniżej pisze taką regułę na podstawie istniejącego kodu.

5. Zweryfikuj, potem zacommituj. Wykonaj trzy sprawdzenia, które udowadniają, że konfiguracja działa, a następnie zacommituj CLAUDE.md i .claude/rules/ w osobnym pull requeście, żeby zespół przejrzał je jak kod.

Prompt do skopiowania: zetnij szkic z /init w oparciu o dowody

Rewrite CLAUDE.md for this repository. Work from evidence only:

1. Read package.json (or pyproject.toml / Makefile), the CI workflow files,
   and the test, lint, and type-check configs.
2. Commands: list the exact build, test, single-test, lint, type-check, and
   migration commands, copied verbatim from the scripts or CI. Do not invent
   a command you cannot point to.
3. Conventions: list only the 3-7 conventions that differ from the defaults
   of this stack, each with the file that demonstrates it.
4. Traps: list generated files, required env vars, services that must be
   running, and anything CI checks that a local run does not.
5. Delete directory tours, dependency lists, and architecture prose that
   Claude can derive by reading the code.

Keep it under 120 lines. Mark anything you are unsure about with
"UNVERIFIED:" instead of guessing. Show me a diff before writing.

Co należy do CLAUDE.md, a co trafia gdzie indziej?

Większość plików instrukcji zawodzi dlatego, że zawiera za dużo, a nie za mało. Oficjalne zalecenie to mniej niż 200 linii na jeden CLAUDE.md, bo każda linia kosztuje kontekst w każdej sesji, a dłuższe pliki są gorzej przestrzegane. Ta tabela pomaga zdecydować, gdzie umieścić daną instrukcję:

Instrukcja jest…	Umieść ją w	Dlaczego
Poleceniem, konwencją całego projektu, pułapką	CLAUDE.md	Potrzebna w każdej sesji
Prawdziwa tylko dla jednego katalogu lub typu pliku	.claude/rules/<topic>.md z paths	Ładuje się tylko, gdy Claude czyta pasujące pliki
Procedurą wieloetapową (wydanie, migracja)	Skillu lub własnym poleceniu	Ładuje się tylko po wywołaniu albo gdy jest istotna
Czymś, co musi się dziać za każdym razem	Hooku lub regule uprawnień	Egzekwuje ją klient, a nie model
Twoim adresem sandboksa, twoimi danymi testowymi	CLAUDE.local.md	Prywatne dla tego projektu
Twoimi preferencjami we wszystkich repozytoriach	~/.claude/CLAUDE.md	Prywatne, każdy projekt
Poprawką, którą raz dałeś Claude	Pamięci automatycznej (Claude ją zapisze)	Claude decyduje, co warto zachować

CLAUDE.md zgodny z tym podziałem jest krótki. Ten przykład dotyczy API w TypeScripcie na pnpm i Vitest, a każda linia to coś, co Claude inaczej zrobiłby źle:

CLAUDE.md

# orders-api

## Commands
- Install: `pnpm install` (never npm or yarn; the lockfile is pnpm-lock.yaml)
- Dev server: `pnpm dev` (port 8080)
- All tests: `pnpm test` · one file: `pnpm vitest run src/orders/orders.test.ts`
- Type check: `pnpm typecheck` · lint: `pnpm lint`
- New migration: `pnpm db:generate`, then `pnpm db:migrate` against the local database

## Conventions that differ from the defaults
- Routes use Hono, not Express. Follow src/routes/orders.ts.
- Validate every request body with the Zod schema in src/schemas/, never inline.
- Money is an integer number of cents. Never use floats for amounts.
- Tests use Vitest with the fake clock in tests/setup.ts; do not add Jest.

## Traps
- src/db/generated/ is generated by `pnpm db:generate`. Never edit it by hand.
- Integration tests need Postgres from `docker compose up db`.
- CI runs `pnpm typecheck`; a green `pnpm test` alone does not mean CI passes.

<!-- Owner: platform team. Review changes in PRs like code. -->

Blokowe komentarze HTML, takie jak ostatnia linia, są usuwane, zanim treść trafi do Claude, więc możesz zostawiać w nich notatki dla opiekunów pliku bez kosztu kontekstu.

Jak wygląda dobry CLAUDE.md w innych stosach?

Kształt jest taki sam w każdym stosie: polecenia, konwencje łamiące domyślne ustawienia stosu i pułapki. Zmienia się tylko treść. Te dwa przykłady powstały przez przycięcie typowych długich szablonów do linii, które zmieniają zachowanie Claude:

Python i Django

CLAUDE.md

# billing-api (Django REST Framework)

## Commands
- Env: `uv sync` · tests: `uv run pytest -x` · one test: `uv run pytest billing/tests/test_invoices.py::test_void`
- Lint and format: `uv run ruff check --fix . && uv run ruff format .`
- Migrations: `uv run python manage.py makemigrations billing`, then `migrate`

## Conventions that differ from the defaults
- JSON is camelCase through djangorestframework-camel-case; models stay snake_case.
- Serializers own all validation. Views never validate by hand.
- Test data comes from factory_boy factories in billing/tests/factories.py.

## Traps
- Never edit a migration that has shipped. Add a new one.
- Stripe calls are mocked in tests via conftest.py; a real key in .env breaks CI.

Terraform

CLAUDE.md

# platform-infra (Terraform)

## Commands
- Format and validate: `terraform fmt -check -recursive && terraform validate`
- Security scan: `trivy config .` (CI fails on HIGH)
- Plan one environment: `cd environments/staging && terraform plan -out=plan.tfplan`

## Conventions that differ from the defaults
- Reusable code lives in modules/; environments/ only wires modules together.
- State is in S3 with a DynamoDB lock. Never use local state.

## Traps
- Never run `terraform apply`. Production applies go through the CI pipeline
  after manual approval; you produce a plan and stop.

Oba pliki pomijają to, co zwykle trafia do długich szablonów: opis drzewa katalogów, pełną listę technologii, ogólne rady („używaj opisowych nazw”, „pisz testy”) oraz cele sprintu i listy znanych błędów. Pierwsze trzy Claude wywnioskuje sam albo już je stosuje; dwa ostatnie dezaktualizują się w ciągu kilku tygodni i należą do systemu zgłoszeń. Linia Terraform „never apply” to też kandydat na regułę uprawnień, która blokuje to polecenie, bo sama instrukcja go nie zatrzyma.

Zawęź instrukcje do ścieżek w .claude/rules/

Reguła to plik Markdown w .claude/rules/. Podkatalogi są wykrywane rekurencyjnie, więc foldery frontend/ i backend/ działają. Bez frontmattera reguła ładuje się przy starcie, tak jak CLAUDE.md. Z polem paths ładuje się tylko wtedy, gdy Claude czyta plik pasujący do któregoś z wzorców glob:

.claude/rules/api-routes.md

---
paths:
  - "src/routes/**/*.ts"
  - "src/schemas/**/*.ts"
---

# API route rules

- Parse the body with the matching schema from src/schemas/ before any logic.
- Return errors as { error: string, code: string } with an explicit status.
- Every new route gets a test in the same folder that covers a 400 response.

paths to jedyne pole frontmattera, które Claude Code czyta z reguły. Jeśli YAML się nie parsuje, Claude Code ignoruje frontmatter i ładuje regułę wszędzie, więc literówka po cichu zamienia regułę zawężoną w globalną. Uruchom claude --debug, żeby zobaczyć błąd parsowania.

Prompt do skopiowania: reguła zawężona do ścieżek na podstawie kodu

Create .claude/rules/api-routes.md scoped to src/routes/**/*.ts.

First read three existing route files and their tests. Then write:
- YAML frontmatter with a `paths` list of glob patterns.
- Only the conventions that all three files follow (validation library,
  error shape, status codes, auth handling), each one line.
- No rule you cannot point to in at least two of the files.

After writing it, list which rules you left out because the files disagree.

Podziel długi CLAUDE.md importami @path

CLAUDE.md może dołączać inne pliki przez @path/to/file. Ścieżki względne są rozwiązywane względem pliku, który zawiera import, importy można zagnieżdżać maksymalnie na cztery poziomy, a @ w backtickach lub w bloku kodu pozostaje zwykłym tekstem:

CLAUDE.md

See @README.md for the product overview and @package.json for scripts.

## Area guides
- Payments: @docs/agents/payments.md
- Git workflow: @docs/agents/git.md

Importy porządkują plik, ale nie zmniejszają kontekstu. Importowane pliki ładują się przy starcie razem z plikiem, który je importuje. Jeśli celem jest ograniczenie tego, za co płaci każda sesja, użyj reguł zawężonych do ścieżek albo plików CLAUDE.md w podkatalogach, które ładują się dopiero wtedy, gdy Claude czyta pasujące pliki.

Gdy projekt po raz pierwszy importuje plik spoza katalogu roboczego, na przykład @~/.claude/my-orders-notes.md, Claude Code prosi o zatwierdzenie importów zewnętrznych. Jeśli odmówisz, te importy pozostaną wyłączone, a okno dialogowe już nie wróci. Import z katalogu domowego to też sposób na współdzielenie prywatnych notatek między worktree gita, bo ignorowany przez gita CLAUDE.local.md istnieje tylko w tym worktree, w którym go utworzyłeś.

Prompt do skopiowania: odchudź za duży CLAUDE.md bez utraty reguł

Our CLAUDE.md is over 200 lines. Restructure it without dropping any rule:

1. Group every instruction by where it applies: whole repo, one directory,
   one file type, or one multi-step procedure.
2. Keep whole-repo commands, conventions, and traps in CLAUDE.md.
3. Move directory- or file-type-specific rules to .claude/rules/<topic>.md
   with a `paths` field.
4. List multi-step procedures separately as candidates for skills; do not
   move them yet.
5. Delete anything Claude can derive by reading the code, and list what you
   deleted with a one-line reason each.

Show the proposed file tree and the new CLAUDE.md before writing anything.

Trzymaj prywatne instrukcje poza wspólnym plikiem

Dwa pliki przechowują to, co jest prawdziwe dla ciebie, a nie dla zespołu:

• CLAUDE.local.md w katalogu głównym projektu: twój lokalny port, twoje dane startowe, flaga, którą przekazujesz do testów end-to-end. Ładuje się po CLAUDE.md na tym samym poziomie. Dokumentacja pamięci (sprawdzona 2026-09-26, v2.1.283) każe samodzielnie dodać go do .gitignore; robi to za ciebie tylko opcja prywatna w trybie CLAUDE_CODE_NEW_INIT=1.
• ~/.claude/CLAUDE.md i ~/.claude/rules/: preferencje dla wszystkich repozytoriów, na przykład „przed edycją więcej niż trzech plików najpierw przedstaw plan”.

CLAUDE.local.md ukrywa AGENTS.md

CLAUDE.local.md liczy się jako CLAUDE.md, gdy Claude Code decyduje, czy czytać AGENTS.md. W repozytorium opartym na AGENTS.md dodanie własnego CLAUDE.local.md sprawia, że w twoich sesjach Claude przestaje czytać AGENTS.md. Ustaw Project instructions w /config na claude-md-and-agents-md, żeby ładować oba.

Poprawki zostaw pamięci automatycznej

Pamięć automatyczna jest domyślnie włączona. W trakcie pracy Claude zapisuje dla siebie notatki o twoich preferencjach, poprawkach, które mu dajesz, i kontekście projektu, którego nie wywnioskuje z kodu, w ~/.claude/projects/<project>/memory/. Wszystkie worktree jednego repozytorium gita dzielą ten katalog, a on sam zostaje na twojej maszynie. MEMORY.md to indeks; Claude Code ładuje jego pierwsze 200 linii lub 25KB na początku każdej sesji, a pliki tematyczne czyta na żądanie.

To, gdzie trafi informacja, zależy od sformułowania prośby:

• „Remember that the API tests need Redis on port 6379” trafia do pamięci automatycznej, którą widzisz tylko ty.
• „Add to CLAUDE.md that the API tests need Redis on port 6379” edytuje wspólny plik, który przegląda zespół.

Wszystko, czego potrzebuje też ktoś z zespołu, wpisz do CLAUDE.md. Polecenie /memory otwiera dowolny plik pamięci, pozwala przejrzeć folder pamięci automatycznej i ją przełączyć. Żeby wyłączyć ją w jednym projekcie, ustaw "autoMemoryEnabled": false w ustawieniach tego projektu; dla całej maszyny lub zadania CI ustaw CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Skrót # do pamięci już nie istnieje

Starsze poradniki każą zacząć wiadomość od #, żeby zapisać wspomnienie. Claude Code usunął ten skrót w v2.0.70 (2025-12-15). Poproś Claude o edycję CLAUDE.md albo otwórz plik przez /memory.

Jak udowodnić, że CLAUDE.md działa, bez czytania każdej linii?

Nikt nie powinien czytać od nowa 150-liniowego pliku instrukcji po każdej zmianie. Zamiast tego wystarczą trzy sprawdzenia, a dwa pierwsze zajmują mniej niż minutę.

1. Sprawdź, co się załadowało. Uruchom nową sesję i wpisz /context. Twój CLAUDE.md, CLAUDE.local.md i reguły bez paths pojawiają się w sekcji Memory files. Plik, którego nie ma na tej liście, dla Claude nie istnieje, cokolwiek w nim napisano. Jeśli plik przekracza zalecaną długość albo kilka plików razem przekracza łączny limit, Claude Code ostrzega też przy starcie i w /status.

2. Zadaj pytanie kontrolne w nowej sesji. Pytanie kontrolne to takie, na które poprawna odpowiedź istnieje tylko w twoich plikach instrukcji. Jeśli Claude odpowiada z pliku, instrukcje działają; jeśli zgaduje, nie działają. Użyj promptu poniżej i trzymaj go w repozytorium, żeby każdy mógł go powtórzyć po edycji plików.

3. Postaw bramkę na zmiany w plikach. Traktuj CLAUDE.md i .claude/rules/ jak kod: zmiany wchodzą przez pull request, a nazwany właściciel, zwykle tech lead, zatwierdza je przez CODEOWNERS. Te pliki sterują agentem, który uruchamia polecenia powłoki, a przegląd ataków na łańcuch dostaw Phoenix Security z 2026 roku (blog jednego dostawcy, źródło wtórne; odczyt 2026-09-26) wskazał narzędzia agentów (wstrzykiwanie przez MCP, .cursorrules, CLAUDE.md i hooki SessionStart) jako kanał dostarczenia w co najmniej 14 z 59 śledzonych kampanii.

Prompt do skopiowania: sprawdź, czy instrukcje się załadowały

Answer from your loaded project instructions only, without reading any file
or running any command. For each answer, name the instruction file it came
from, or say "not in my instructions".

1. Which package manager does this repo use, and what must I never use?
2. What is the exact command to run a single test file?
3. Which directory must never be edited by hand, and why?
4. What must happen after a schema change?
5. Which command does CI run that a local test run does not?

Uruchamiaj pytanie kontrolne w nowej sesji albo po /clear, nigdy w rozmowie, w której właśnie edytowałeś plik: ta rozmowa zawiera już odpowiedzi. Każda odpowiedź „not in my instructions” to luka w pliku. Pewna siebie, błędna odpowiedź zwykle oznacza konflikt między dwoma plikami albo instrukcję, która istnieje tylko w historii rozmowy.

Do głębszego śledzenia służy hook podpięty pod zdarzenie InstructionsLoaded, które odpala się przy każdym załadowaniu pliku CLAUDE.md lub reguły; taki hook może logować, które pliki się załadowały, kiedy i dlaczego. Pomaga, gdy reguła zawężona do ścieżek nigdy nie działa. Przewodnik po hookach pokazuje, jak go dodać.

Utrzymanie to część weryfikacji. /doctor (v2.1.206 lub nowszy) proponuje przycięcie zacommitowanego CLAUDE.md: wycina treści, które Claude wywnioskuje z kodu, a zostawia pułapki i konwencje. Od v2.1.283 /doctor prompt-audit sprawdza pliki CLAUDE.md, skille, agentów i polecenia pod kątem nieaktualnych ścieżek i poleceń, sprzecznych plików instrukcji oraz wzorców promptów pisanych pod starsze modele. Uruchamiaj jedno z nich przed kwartalnym przeglądem plików i zanim dodasz regułę na każdy błąd, przeczytaj protokół ablacji dla plików kontekstu.

Wdróż CLAUDE.md w zespole

Plik, który jeden developer napisał w piątkowe popołudnie, utrwala nawyki jednej osoby. Dla zespołu tech lead robi z niego wspólny artefakt:

• Napiszcie pierwszą wersję razem. Uruchom /init i prompt ścinający szkic, a potem przejrzyj wynik w jednym pull requeście z dwiema lub trzema osobami, które znają repozytorium. Każdą sporną konwencję rozstrzygacie tam, a nie w kolejnych sesjach.
• Wyznacz właściciela. Dodaj CLAUDE.md i .claude/rules/ do CODEOWNERS, żeby zmiana tego, co słyszy agent, wymagała takiej samej zgody jak zmiana CI.
• Wykorzystaj go w onboardingu. Krótki CLAUDE.md z prawdziwymi poleceniami i pułapkami to też najszybsza lektura dla nowego inżyniera. Jeśli nowa osoba znajdzie w nim błąd, agent też się myli.
• Przeglądaj go co kwartał. Uruchom /doctor, powtórz pytanie kontrolne i usuń linie, których nikt nie potrafi powiązać z prawdziwym błędem.

Rozmieść instrukcje w monorepo

W monorepo umieść krótki CLAUDE.md w katalogu głównym, z poleceniami działającymi wszędzie, i po jednym w każdym pakiecie na to, co się różni:

repo/
├── CLAUDE.md                 # install, workspace commands, repo-wide traps
├── .claude/rules/
│   └── migrations.md         # paths: ["packages/*/migrations/**"]
├── packages/api/CLAUDE.md    # loads when Claude reads files in packages/api/
└── packages/web/CLAUDE.md    # loads when Claude reads files in packages/web/

Uruchomienie Claude Code w packages/api/ ładuje CLAUDE.md tego pakietu i główny plik powyżej. Uruchomienie w katalogu głównym ładuje pliki pakietów dopiero na żądanie. Jeśli CLAUDE.md innego zespołu ciągle się ładuje i nie dotyczy twojej pracy, dodaj jego ścieżkę do claudeMdExcludes w .claude/settings.local.json. Zarządzanego CLAUDE.md z polityki nie da się wykluczyć. Przewodnik po dużych bazach kodu opisuje nawigację w tej skali.

Kiedy instrukcje projektu przestają działać

Claude ignoruje CLAUDE.md. Uruchom /context i zajrzyj do Memory files. Jeśli pliku brakuje, sprawdź, czy uruchomiłeś claude w repozytorium lub poniżej i czy nazwa to dokładnie CLAUDE.md. Jeśli plik jest na liście, ale Claude go ignoruje, instrukcja jest pewnie niejasna („formatuj ładnie”) albo gdzieś indziej jej zaprzeczono. Przepisz ją na coś sprawdzalnego („Use 2-space indentation”). Jeśli nie wolno jej pominąć, przenieś ją do hooka.

Claude wybiera złą z dwóch instrukcji. Pliki są sklejane, więc obie trafiają do modelu. Przeszukaj ~/.claude/CLAUDE.md, plik projektu, CLAUDE.local.md, pliki w podkatalogach i .claude/rules/ pod kątem tematu, a potem usuń przegraną instrukcję, zamiast dopisywać „ALWAYS” do zwycięskiej.

Reguła zawężona do ścieżek nigdy nie działa. Takie reguły uruchamiają się, gdy Claude czyta pasujący plik, a nie przy każdym użyciu narzędzia. Sprawdź wzorzec glob na prawdziwej ścieżce, sprawdź, czy YAML się parsuje (claude --debug), i potwierdź to hookiem InstructionsLoaded.

Instrukcja znika po /compact. Główny CLAUDE.md projektu jest po kompakcji czytany ponownie z dysku. Pliki z podkatalogów i reguły zawężone do ścieżek wracają dopiero, gdy Claude znów przeczyta pasujący plik. Instrukcja, która istniała tylko w rozmowie, przepadła; wpisz ją do CLAUDE.md.

AGENTS.md nie jest czytany. Przed v2.1.280 /context i /memory nie pokazywały AGENTS.md, który Claude czytał bezpośrednio, więc zanim uznasz, że go brakuje, zapytaj Claude, co mówią jego instrukcje projektu. W pozostałych przypadkach poszukaj CLAUDE.md, .claude/CLAUDE.md lub CLAUDE.local.md w katalogu roboczym i powyżej, uruchom claude --version, żeby potwierdzić v2.1.277 lub nowszą (v2.1.281 lub nowszą w Bedrock, Google Cloud, Foundry, bramkach LLM albo z wyłączoną telemetrią), i sprawdź Project instructions w /config. W każdej wersji działa @AGENTS.md w pliku CLAUDE.md.

Import niczego nie ładuje. Być może odrzuciłeś okno importów zewnętrznych, a wtedy pozostają one wyłączone dla tego projektu. Sprawdź też, czy ścieżka rozwiązuje się względem pliku importującego, a nie katalogu roboczego, i czy @ nie stoi w backtickach.

Plik powoli wypełnia się ogólnikami. Linie w rodzaju „pisz czysty kod” albo „stosuj dobre praktyki” kosztują kontekst i niczego nie zmieniają. Uruchom /doctor albo prompt odchudzający powyżej i usuń każdą linię, która byłaby prawdziwa w dowolnym repozytorium.

Polecenia w pliku się starzeją. Po zmianie nazwy skryptu Claude z pełnym przekonaniem uruchamia polecenie, które już nie istnieje. Dodaj do szablonu pull requesta punkt „zaktualizuj CLAUDE.md, jeśli zmieniasz skrypty w package.json lub CI” i powtarzaj pytanie kontrolne po każdej zmianie skryptów.

Co dalej po inicjalizacji projektu

Zbuduj pierwszą funkcję Przeprowadź jedną funkcję od zgłoszenia do commita: tryb planowania, najpierw testy, małe kroki z bramkami.

System pamięci w szczegółach Wszystkie zakresy, zasady ładowania i ustawienia CLAUDE.md oraz pamięci automatycznej.

Hooki dla instrukcji, które muszą działać Zamień „zawsze uruchamiaj linter” z prośby w bramkę.

Konfiguracja Claude Code Pliki ustawień, uprawnienia oraz domyślny model i poziom wysiłku.

Poprzedni krok tego szybkiego startu to integracja z IDE. Użytkownicy Codeksa przygotowują odpowiednik tego pliku w przewodniku konfiguracja AGENTS.md.