# AGENTS.md i CLAUDE.md: wspólne instrukcje dla agentów AI
> Jedno źródło prawdy dla Claude Code, Codex i Cursor w 2026 roku: kiedy Claude Code sam odczytuje AGENTS.md, import @AGENTS.md w CLAUDE.md, dowiązanie symboliczne i /init.
Source: https://ailoot.ai/blog/pl/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/pl/agents-md-claude-md-one-instruction-file/
Language: pl
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-6ef38b93bf17e3b565c04a0b0a85b0c794788126884e95c9f18c8bad035d1b7c
Informacje o usłudze znajdziesz w [dokumentacji Ailoot](https://ailoot.ai/docs/).
## AGENTS.md i CLAUDE.md: wspólne instrukcje dla Claude Code, Codex i Cursor
Najważniejsze informacje
W 2026 roku typowe środowisko vibe codera obejmuje nie jedno narzędzie, lecz 3–5. Claude Code jako główne narzędzie, Codex do długich zadań autonomicznych, Cursor do szybkich edycji w IDE. Każde ma własny plik instrukcji: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Jeśli synchronizujesz je ręcznie, edytujesz tę samą linię w pięciu miejscach, zapominasz zaktualizować Cursor, a tydzień później Claude i Codex dają różne wyniki dla tego samego promptu.
W opisanym przykładzie Claude Code jest głównym narzędziem, a Codex i Cursor służą do konkretnych zadań. Mój `CLAUDE.md` zawiera około 250 wierszy instrukcji: co czytać i w jakiej kolejności, czego nie wolno ruszać, jakich poleceń używać do wdrażania oraz jakie są zasady formatowania commitów. Kiedy po raz pierwszy wypróbowałem Codex CLI w projekcie, nie znał żadnej z tych zasad: wykonał `git push --force`, zaglądał do `.env` i beztrosko zmieniał nazwy plików.
Najpierw ręcznie skopiowałem `CLAUDE.md` do `AGENTS.md`. Dwa tygodnie później odkryłem, że projekt ma już cztery wersje tych samych instrukcji: w `CLAUDE.md`, `AGENTS.md`, `.cursorrules` i `.windsurf/rules/`. Każda nieco się różniła. To nie problem Claude’a ani Cursora, lecz podstawowa pułapka każdego systemu z wieloma źródłami prawdy. Omawiam ją szerzej w [przewodniku po pracy z wieloma agentami](https://ailoot.ai/blog/pl/claude-code-codex-together/).
W czerwcu 2026 roku dokumentacja pamięci Claude Code od Anthropic przedstawiała jedno rozwiązanie: wspólny plik i import. Od września 2026 roku Claude Code sam odczytuje `AGENTS.md`, jeśli projekt nie zawiera `CLAUDE.md`; import jest potrzebny, gdy masz reguły przeznaczone wyłącznie dla Claude’a. Poniżej wyjaśniam, kiedy wystarczy jeden plik `AGENTS.md`, jak skonfigurować import i jak oddzielić wspólne reguły od tych specyficznych dla Claude’a.
## Czy Claude Code sam odczytuje AGENTS.md?
Najważniejsze informacje
Tak, począwszy od wersji 2.1.277, wydanej 18 września 2026 roku, ale tylko wtedy, gdy w katalogu roboczym ani żadnym jego katalogu nadrzędnym nie ma `CLAUDE.md`, `.claude/CLAUDE.md` ani `CLAUDE.local.md`. Jeśli istnieje `CLAUDE.md`, Claude Code domyślnie odczytuje tylko ten plik, a `AGENTS.md` dołącza się za pomocą wiersza `@AGENTS.md` w `CLAUDE.md` albo dowiązania symbolicznego. Zachowanie można zmienić w `/config`, w sekcji Project instructions. Przed wrześniem Claude Code w ogóle nie odczytywał `AGENTS.md`, więc jedynym sposobem był import.
Przed wrześniem 2026 roku odpowiedź brzmiała „nie”. Issue #6235, w którym zgłoszono prośbę o obsługę AGENTS.md, pozostawało otwarte od sierpnia 2025 roku i zamknięto je 17 sierpnia 2026 roku. Przez cały ten czas dokumentacja pamięci wskazywała jedno rozwiązanie: utwórz plik CLAUDE.md i zaimportuj do niego `AGENTS.md`. Od wersji 2.1.277 dokumentacja mówi już co innego:
Claude Code może odczytywać AGENTS.md jako instrukcje projektu, dzięki czemu repozytorium skonfigurowane już dla innych agentów działa bez CLAUDE.md, importu ani konfiguracji.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
To, co odczyta Claude Code, zależy od plików w projekcie:
| Pliki w projekcie | Co odczytuje Claude Code |
|----|----|
| `AGENTS.md`, bez `CLAUDE.md` ani `CLAUDE.local.md` w katalogu roboczym lub wyżej | `AGENTS.md` |
| `AGENTS.md` oraz `CLAUDE.md` (lub `CLAUDE.local.md`) w katalogu roboczym lub wyżej | Tylko `CLAUDE.md` |
| `CLAUDE.md` z wierszem `@AGENTS.md` | `CLAUDE.md` oraz zawarty w nim przez import plik `AGENTS.md` |
W tej kontroli uwzględnia się pliki `CLAUDE.md`, `.claude/CLAUDE.md` i `CLAUDE.local.md` znajdujące się w katalogu roboczym i dowolnym katalogu nadrzędnym. Osobisty `~/.claude/CLAUDE.md`, zarządzany plik firmowy oraz reguły z `.claude/rules/` nie są uwzględniane: są ładowane razem z `AGENTS.md`.
Jeśli nie ma `CLAUDE.md`, Claude Code podczas uruchamiania odczytuje wszystkie pliki `AGENTS.md` i `.claude/AGENTS.md` z katalogu roboczego i jego katalogów nadrzędnych, a plik `AGENTS.md` w podkatalogu wczytuje po otwarciu pliku w tym podkatalogu. Działają też importy `@path` wewnątrz `AGENTS.md`. Claude Code nie odczytuje `AGENTS.local.md`, `AGENTS.override.md` ani zawartości katalogu `.agents/`.
Pułapka polega na tym, że liczy się także osobisty plik `CLAUDE.local.md`. Utwórz go, aby przechowywać niezatwierdzone reguły, a Claude Code po cichu przestanie odczytywać `AGENTS.md`. Rozwiązaniem jest poniższe ustawienie.
Zachowanie zmienia się w `/config`, w sekcji Project instructions:
| Ustawienie | Co odczytuje Claude Code |
|----|----|
| `claude-md-or-agents-md` (domyślne) | `CLAUDE.md` albo, jeśli nie istnieje ani on, ani `CLAUDE.local.md`, `AGENTS.md` |
| `claude-md-and-agents-md` | Oba pliki: w każdym katalogu najpierw `CLAUDE.md`, potem `AGENTS.md` |
| `claude-md` | Tylko `CLAUDE.md` |
| `managed-only` | Tylko zarządzany firmowy `CLAUDE.md` i pamięć automatyczna |
Jeśli chcesz zachować `CLAUDE.local.md` bez utraty `AGENTS.md`, ustaw `claude-md-and-agents-md`. Nie dojdzie do podwójnego odczytu: jeśli `AGENTS.md` jest już dołączony przez wiersz `@AGENTS.md` albo dowiązanie symboliczne, Claude Code nie wczyta go drugi raz, niezależnie od ustawienia.
Za pomocą polecenia `/memory` możesz sprawdzić, czy plik został wczytany: od wersji 2.1.280 na liście pojawia się ścieżka do `AGENTS.md`. W wersjach starszych niż 2.1.277 oraz w sesjach, w których wyłączono wbudowaną wtyczkę `agents-md`, Claude Code odczytuje tylko `CLAUDE.md`, a w `/config` nie ma pozycji Project instructions. Przed wersją 2.1.281 tak samo zachowywały się sesje przez Amazon Bedrock i sesje z wyłączoną telemetrią. W pierwszej sesji po aktualizacji ze starszej wersji `AGENTS.md` może też nie zostać wczytany; zacznie działać od następnej sesji.
Co to oznacza, jeśli chcesz mieć jeden plik? Jeśli nie masz reguł przeznaczonych wyłącznie dla Claude’a, możesz pominąć `CLAUDE.md`: wystarczy `AGENTS.md`, który odczytają Claude Code, Codex i Cursor. Jeśli masz takie reguły (tryb planowania dla ryzykownych katalogów, umiejętności, hooks), potrzebujesz `CLAUDE.md`, a Claude Code przestanie samodzielnie czytać `AGENTS.md`. W takim przypadku umieść w `CLAUDE.md` wiersz `@AGENTS.md`, aby go zaimportować. Ta konfiguracja działa tak samo jak przed wrześniem i obsługuje starsze wersje Claude Code. Wyjaśniam ją szczegółowo poniżej.
## Jak zaimportować @AGENTS.md w CLAUDE.md?
Najważniejsze informacje
Import jest potrzebny, gdy projekt ma plik `CLAUDE.md`: jeśli on istnieje, Claude Code domyślnie nie odczytuje samodzielnie `AGENTS.md`. Aby to skonfigurować, wpisz `@AGENTS.md` na początku pliku `CLAUDE.md`. Gdy Claude Code rozpoczyna sesję, wstawia w miejsce tego wiersza zawartość `AGENTS.md` i odczytuje całość jako jeden tekst. Pod importem możesz dodać sekcję „Claude Code” z regułami obowiązującymi tylko Claude’a. Importy obsługują ścieżki względne i bezwzględne oraz mogą być zagnieżdżone na maksymalnie czterech poziomach.
Minimalny działający przykład z oficjalnej dokumentacji:
```markdown
@AGENTS.md
## Claude Code
Używaj trybu planowania przy zmianach w `src/billing/`.
```
Oto, co się dzieje. Pierwszy wiersz, `@AGENTS.md`, jest dyrektywą importu. Gdy Claude Code analizuje `CLAUDE.md` na początku sesji, znajduje ten import i wstawia w jego miejsce całą zawartość `AGENTS.md`. Następnie pojawia się nagłówek `## Claude Code`: to zwykły Markdown, ale pełni funkcję sekcji „dodatkowe reguły specyficzne dla Claude’a”. Pod nim znajduje się reguła obowiązująca tylko Claude Code: używaj trybu planowania przy zmianach w katalogu billing. Codex CLI ani Cursor nie otwierają tego pliku; korzystają ze zwykłego `AGENTS.md`.
Cytat z dokumentacji o działaniu importów:
Pliki CLAUDE.md mogą importować dodatkowe pliki za pomocą składni @path/to/import. Importowane pliki są rozwijane i ładowane do kontekstu podczas uruchamiania sesji razem z plikiem CLAUDE.md, który się do nich odwołuje.
— Anthropic, https://code.claude.com/docs/en/memory
Kilka praktycznych szczegółów:
- **Ścieżki względne i bezwzględne.** `@AGENTS.md` jest ścieżką względną względem pliku zawierającego import. `@/Users/me/shared/rules.md` lub `@~/.claude/personal.md` to ścieżki bezwzględne. Używam `@~/.claude/personal.md` do przechowywania osobistych preferencji, których nie chcę umieszczać w repozytorium.
- **Maksymalnie cztery poziomy.** `AGENTS.md` może importować `@docs/coding-style.md`, a `coding-style.md` może importować kolejny plik, do czterech poziomów. To wystarczy do każdej praktycznej struktury.
- **Backticki blokują import.** Jeśli tekst zawiera `` `@README` ``, jest to tylko wzmianka o nazwie, a nie import. Przydaje się to, gdy wyjaśniasz czytelnikom działanie importów, nie uruchamiając go.
- **Pliki spoza projektu wymagają zatwierdzenia.** Jeśli import wskazuje lokalizację poza katalogiem roboczym, na przykład `@~/.claude/personal.md`, Claude Code przy pierwszej próbie wyświetli okno z listą takich plików. Jeśli odmówisz, importy zewnętrzne pozostaną wyłączone, a okno nie pojawi się ponownie. `@AGENTS.md` w katalogu głównym projektu nie wywołuje okna. Chroni to przed przypadkowym wczytaniem do kontekstu niepowiązanego pliku.
Po przejściu na tę konfigurację w opisanym projekcie mój `CLAUDE.md` skurczył się z 250 do 60 wierszy: `@AGENTS.md` oraz pięć do siedmiu reguł obowiązujących tylko Claude Code (tryb planowania dla ryzykownych katalogów, czego nie ruszać w obszarze administracyjnym i jak formułować commity). Wszystkie wspólne zasady znajdują się w `AGENTS.md`, który odczytują Codex i Cursor.
## Kiedy wybrać dowiązanie symboliczne, a kiedy import?
Najważniejsze informacje
Anthropic oferuje dwa mechanizmy: import przez `@AGENTS.md` albo dowiązanie symboliczne `ln -s AGENTS.md CLAUDE.md`. Dowiązanie jest prostsze — to tylko alias i nie wymaga zmian w plikach. Ma jednak trzy wady: w Windows wymaga uprawnień administratora, nie pozwala dodawać reguł specyficznych dla Claude’a do `CLAUDE.md`, a Git czasem pokazuje dowiązanie w diffie w nieczytelny sposób. Import to rozwiązanie uniwersalne. Jeśli nie masz reguł tylko dla Claude’a, od wersji 2.1.277 nie potrzebujesz żadnego z tych rozwiązań: Claude Code sam odczyta `AGENTS.md`.
Dokumentacja przedstawia opcję dowiązania symbolicznego tak:
```bash
ln -s AGENTS.md CLAUDE.md
```
Zaraz potem zawiera bezpośrednie ostrzeżenie dotyczące Windows:
Jeśli Ty lub ktokolwiek klonujący repozytorium pracuje w Windows, użyj importu @AGENTS.md. Utworzenie dowiązania symbolicznego wymaga tam uprawnień administratora lub trybu deweloperskiego, a Git z wyłączonym core.symlinks sprawdza zatwierdzone dowiązanie jako zwykły plik tekstowy. W efekcie powstaje jednoliniowy plik CLAUDE.md zamiast instrukcji w tej kopii.
— Anthropic, https://code.claude.com/docs/en/memory
Tabela porównawcza:
| Kryterium | Import `@AGENTS.md` | Dowiązanie symboliczne `ln -s` |
|----|----|----|
| **Działa w Windows bez uprawnień administratora** | tak | nie (wymagany tryb deweloperski) |
| **Można dodać reguły tylko dla Claude’a** | tak, pod importem | nie, plik jest identyczny |
| **W Git jest widoczny jako zwykły Markdown** | tak | jako dowiązanie (zależy od `core.symlinks`) |
| **Można importować wiele plików** | tak, do czterech poziomów | nie, relacja jeden do jednego |
| **Buforowanie/unieważnianie w Claude Code** | standardowe dla CLAUDE.md | działa, ale dowiązania symboliczne mają ukryte pułapki |
| **Domyślny wybór** | odpowiedni dla każdego | tylko jeśli praca na różnych platformach nie ma znaczenia |
W opisanym projekcie używam importów. Oto powody:
1. **Zespół korzysta z różnych systemów.** Używam Maca; w opisanym przykładzie zespół jest mniej więcej równo podzielony między użytkowników Windows i Maca. Jeśli w repozytorium pojawi się dowiązanie symboliczne, użytkownikom Windows bez trybu deweloperskiego zostanie ono pobrane jako zwykły plik tekstowy zawierający jeden wiersz: `AGENTS.md`. Powoduje to dziwne błędy: czasem reguły działają, czasem nie, a przyczyna jest niejasna.
2. **Chcę mieć reguły tylko dla Claude’a.** Pod `@AGENTS.md` mój `CLAUDE.md` zawiera sekcję „Claude Code” z regułami: używaj `--effort high` przy zadaniach architektonicznych, uruchom `npm run build` przed `git push` i nie wywołuj ręcznie `/api/v1/deploy`. Codex nie rozumie tych poleceń.
3. **Łatwiej diagnozować problemy.** Gdy coś pójdzie nie tak, otwieram `CLAUDE.md` i widzę import oraz własne nadpisania. Dowiązanie symboliczne nie wskazuje, że „to zostało dodane tutaj”. Więcej informacji o diagnozowaniu ustawień Claude Code znajdziesz w [przewodniku po trybie bezpiecznym](https://ailoot.ai/blog/pl/claude-code-safe-mode-recovery/).
Jeśli nie masz reguł specyficznych dla Claude’a, od wersji 2.1.277 dowiązanie nie jest już potrzebne: usuń `CLAUDE.md`, a Claude Code sam odczyta `AGENTS.md`. Zachowaj dowiązanie tylko wtedy, gdy ktoś w zespole używa wersji starszej niż 2.1.277 i nie może jej zaktualizować. Jeśli masz reguły dla Claude’a, import jest wygodniejszy w dziewięciu przypadkach na dziesięć.
## Co odczytują Codex, Cursor, Copilot, Windsurf i Gemini CLI?
Najważniejsze informacje
Każde narzędzie odczytuje własny plik, czasem więcej niż jeden. Claude Code odczytuje `CLAUDE.md`, a od września 2026 roku odczytuje też `AGENTS.md`, jeśli projekt nie zawiera `CLAUDE.md`. Codex CLI odczytuje `AGENTS.md` oraz `AGENTS.override.md`. Cursor odczytuje starszy format `.cursorrules` albo nowszy `.cursor/rules/*.mdc`, a od lata 2026 roku także `AGENTS.md`. Copilot odczytuje `.github/copilot-instructions.md` lub `.github/instructions/*.instructions.md`. Windsurf odczytuje starszy plik `.windsurfrules` albo nowszy katalog `.windsurf/rules/`. Gemini CLI odczytuje `GEMINI.md`. Aider i Cline już obsługują `AGENTS.md`.
Zestawienie siedmiu głównych narzędzi (na podstawie oficjalnej dokumentacji każdego z nich):
| Narzędzie | Główny plik instrukcji | Alternatywy | Czy odczytuje AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, zarządzana polityka | tak, jeśli projekt nie ma `CLAUDE.md` (od 2.1.277), w przeciwnym razie przez import |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | tak (natywnie) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (przestarzały) | tak |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | przez rozszerzenia |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (przestarzały) | tak |
| **Gemini CLI** | `GEMINI.md` | \- | nie |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | tak (natywnie) |
Co z tego wynika? Jeśli repozytorium zawiera `AGENTS.md` (oraz `CLAUDE.md` z importem, gdy potrzebne są reguły specyficzne dla Claude’a), pięć z siedmiu narzędzi automatycznie otrzymuje aktualne instrukcje. Cursor i Windsurf mają własne pliki natywne. Możesz zostawić je bez zmian (`AGENTS.md` również jest przez nie odczytywany) albo dodać import `@AGENTS.md` — ich składnia jest jednak inna i nie zawsze obsługiwana.
Najprostsza strategia dla nowego projektu:
1. **Umieść wszystkie wspólne reguły w `AGENTS.md`** — 95% reguł powinno tam trafić.
2. **Utwórz `CLAUDE.md`, jeśli potrzebujesz zasad tylko dla Claude’a:** w pierwszym wierszu umieść `@AGENTS.md`, a pod nim dodaj sekcję z regułami wyłącznie dla Claude’a. Jeśli takich reguł nie ma, `CLAUDE.md` jest zbędny; od wersji 2.1.277 Claude Code sam odczytuje `AGENTS.md`.
3. **Zachowaj `.cursor/rules/` dla Cursora** na rzadkie przypadki wymagające czegoś specyficznego dla Cursor (np. poleceń `@Codebase` i `@Docs`).
4. **W przypadku Windsurf postępuj podobnie:** zapomnij o starym `.windsurfrules`; używaj nowego `.windsurf/rules/` tylko wtedy, gdy potrzebujesz wzorców w jego składni.
Takie podejście daje 80% korzyści przy 20% nakładu pracy. Z mojego doświadczenia, gdy porządkowałem zespoły korzystające z różnych narzędzi w „Antigravity”, utrzymanie więcej niż dwóch źródeł prawdy (wspólnego i przeznaczonego tylko dla Claude’a) staje się uciążliwe. Jeśli ktoś doda regułę do `.cursorrules` i zapomni o `AGENTS.md`, tydzień później Cursor i Codex będą się ze sobą nie zgadzać.
## Jak /init w Claude Code wykorzystuje istniejący plik AGENTS.md?
Najważniejsze informacje
`/init` tworzy `CLAUDE.md` na podstawie zawartości repozytorium i oszczędza 20–30 minut ręcznej pracy. Domyślnie uwzględnia reguły Cursora (`.cursor/rules/`, `.cursorrules`) i Copilota (`.github/copilot-instructions.md`), a w trybie `CLAUDE_CODE_NEW_INIT=1` także `AGENTS.md`, `.windsurfrules` i `.clinerules`. Ten tryb uruchamia również interaktywny, wieloetapowy proces: zadaje pytania, bada kod za pomocą subagenta i przedstawia plan przed zapisaniem. Od września 2026 roku `/init` ma wadę w projekcie zawierającym `AGENTS.md`: nowy `CLAUDE.md` wyłącza bezpośredni odczyt `AGENTS.md`, a reguły trafiają do dwóch plików.
Anthropic opisuje `/init` w dokumentacji tak:
Uruchomienie /init odczytuje pliki instrukcji innych narzędzi i przenosi odpowiednie fragmenty do wygenerowanego pliku CLAUDE.md: reguły Cursora z .cursor/rules/ lub .cursorrules, reguły Copilota z .github/copilot-instructions.md, a przy CLAUDE_CODE_NEW_INIT=1 również AGENTS.md, .devin/rules/, .windsurf/rules/ lub .windsurfrules, a także .clinerules.
— Anthropic, https://code.claude.com/docs/en/memory
Co to oznacza w praktyce? Opisywane repozytorium zawierało plik `.cursorrules` z czasów, gdy próbowałem Cursora (około 80 wierszy), oraz `AGENTS.md` (120 wierszy), który przygotowałem ręcznie. Po uruchomieniu `claude /init` polecenie uwzględniło oba pliki, usunęło podobne reguły i w ciągu minuty utworzyło przejrzysty `CLAUDE.md`. Potem sprawdziłem wynik i wprowadziłem drobne poprawki — usunąłem nieaktualne elementy i dodałem strukturę z nagłówkami. Było to szybsze niż pisanie od zera.
Tryb interaktywny, w którym `/init` odczytuje również `AGENTS.md`, włącza się za pomocą zmiennej środowiskowej:
```bash
CLAUDE_CODE_NEW_INIT=1 claude
```
Po uruchomieniu `/init` Claude zadaje serię pytań doprecyzowujących: które artefakty skonfigurować (`CLAUDE.md`, skills, hooks), z jakiego stosu korzysta projekt i jakich poleceń używać do testów. Następnie subagent eksploruje bazę kodu — odczytuje `package.json`, `README.md` i pliki konfiguracyjne — oraz uzupełnia brakujące elementy. Na końcu przedstawia propozycję, którą można edytować przed zapisaniem. Więcej informacji o konfigurowaniu Claude Code przy rozpoczynaniu projektu znajdziesz w [osobnym przewodniku](https://ailoot.ai/blog/pl/spec-kit-claude-code-spec-driven-development/).
Teraz o wadzie. Jeśli projekt ma już aktywny plik `AGENTS.md`, `/init` utworzy obok niego `CLAUDE.md` z kopią jego reguł. Od tej chwili Claude Code domyślnie odczytuje tylko `CLAUDE.md`, więc znowu powstają dwa źródła prawdy: aktualizujesz `AGENTS.md`, a Claude nadal korzysta ze starej kopii. Polecenie `/import` działa podobnie: dopisuje jednorazową kopię `AGENTS.md` do `CLAUDE.md`. Aby zachować jedno źródło, po `/init` umieść import `@AGENTS.md` w pierwszym wierszu `CLAUDE.md` i usuń z niego wszystko, co powtarza zawartość `AGENTS.md`.
`/init` to dobry punkt wyjścia dla nowego projektu lub projektu przenoszonego z Cursora albo Copilota. Nie musisz szukać w internecie „najlepszego szablonu CLAUDE.md” — Anthropic już uwzględnia zawartość repozytorium. Jeśli projekt ma już aktywny `AGENTS.md` i nie ma reguł przeznaczonych wyłącznie dla Claude’a, `/init` jest zbędny: Claude Code sam odczyta `AGENTS.md`.
## Jak rozdzielić wspólne instrukcje i instrukcje specyficzne dla Claude’a?
Najważniejsze informacje
Reguły zrozumiałe dla dowolnego agenta AI umieść w `AGENTS.md`: czego nie ruszać, jak nazywać branche, że `.env` zawiera sekret i jakich poleceń używać do testów. Zasady specyficzne dla Claude Code umieść w `CLAUDE.md` (pod importem): tryb planowania, skills, hooks, odwołania do umiejętności i nazwy modeli zależne od wersji. Rozróżnienie jest proste: jeśli reguła zaczyna się od „Claude powinien”, należy do `CLAUDE.md`. Jeśli zaczyna się od „narzędzie powinno”, należy do `AGENTS.md`.
Rozdzielam je według tej zasady. Wspólne reguły, które trafiają do `AGENTS.md`:
- **Czego nie ruszać w kodzie.** Plik `.env`, `node_modules`, katalog `prisma/migrations` (zmiany wyłącznie przez `prisma migrate`), `.next/`, `.git/`.
- **Jak nazywać elementy.** Branche: `feat/`, `fix/`, `chore/`. Commity: prefiksy `feat:`, `fix:`, `docs:` oraz krótki opis. Pliki komponentów w `kebab-case`.
- **Polecenia testów i lintowania.** `npm run build`, `npm run lint`, `npm test`. Wskaż, które polecenie należy uruchomić przed `git push`.
- **Zasady architektoniczne.** Co trafia do `src/lib/`, co do `src/components/`, gdzie znajduje się logika biznesowa i gdzie interfejs użytkownika.
- **Bezpieczeństwo.** Nigdy nie zatwierdzaj sekretów w repozytorium. Dostęp do produkcyjnej bazy danych uzyskuj wyłącznie przez `prod-psql`. Do łączenia się z produkcją przez SSH używaj aliasu `prod`, a nie `root@IP`.
Reguły specyficzne dla Claude’a, które umieszczam w `CLAUDE.md` pod `@AGENTS.md`:
- **Tryb planowania.** Przy zmianach w ryzykownych katalogach (na przykład `src/billing/`) używaj `plan mode`.
- **Poziom wysiłku.** Przy zadaniach architektonicznych używaj `--effort high`, a przy rutynowej pracy `medium`.
- **Skills.** Wskaż, których agentów AI i umiejętności używać w poszczególnych sytuacjach. Na przykład: „Podczas pracy nad przewodnikiem uruchom skill `build-masterskaya-guide`”.
- **Pamięć Claude’a.** Określ, co zapisywać w pamięci automatycznej, a co w `CLAUDE.local.md`. Więcej informacji znajdziesz w [przewodniku po pamięci i CLAUDE.md](https://ailoot.ai/blog/pl/claude-memory-claude-md-auto-memory/).
- **Hooks.** Jeśli w `.claude/settings.json` skonfigurowano hooks, opisz w `CLAUDE.md`, co robią (Codex i Cursor ich nie znają i nie muszą ich znać).
- **Skills i polecenia.** Lista często używanych przeze mnie poleceń slash (`/init`, `/cd`, `/memory`, `/plan`).
Granica nie zawsze jest oczywista. Na przykład „nigdy nie wykonuj `git push --force` do `main`” to wyraźnie wspólna reguła, więc trafia do `AGENTS.md`. Jednak „przed `git push` do aktywnego brancha najpierw użyj trybu planowania” dotyczy wyłącznie Claude Code, więc należy do `CLAUDE.md`. Sprawdź: „Gdybym jutro usunął Claude Code i zostawił tylko Codex, czy ta reguła nadal miałaby zastosowanie?” Jeśli tak, umieść ją w `AGENTS.md`; jeśli nie, w `CLAUDE.md`.
## Co powinno znaleźć się w AGENTS.md, a co w CLAUDE.md lub .claude/rules?
Najważniejsze informacje
W dużym projekcie jeden `AGENTS.md` nie wystarczy — zbytnio się rozrasta, a każdy agent otrzymuje w kontekście niepotrzebne materiały. Rozwiązaniem jest katalog `.claude/rules/` z osobnymi plikami tematycznymi oraz nagłówkiem YAML `paths:` do uruchamiania reguł zależnie od ścieżki. Na przykład reguła API obowiązuje tylko wtedy, gdy Claude pracuje w `src/api/`. Pozwala to znacznie oszczędzić miejsce w oknie kontekstowym. Odpowiednikiem dla Cursora jest `.cursor/rules/`, a dla Windsurf — `.windsurf/rules/`.
Jeśli reguły przekraczają 200 wierszy, czas je podzielić. Dokumentacja Anthropic zaleca celować w 200 wierszy na plik, ponieważ długie pliki `CLAUDE.md` sprawiają, że Claude po cichu coraz rzadziej stosuje się do instrukcji: wygląda, jakby je czytał, ale rzadziej ich przestrzega.
Struktura dużego projektu, która sprawdza się u mnie:
```
my-project/
├── AGENTS.md # 100-150 wierszy, wspólne
├── CLAUDE.md # 30-50 wierszy: @AGENTS.md + reguły Claude’a
└── .claude/
├── CLAUDE.md # alternatywa dla pliku w katalogu głównym, ten sam plik
└── rules/
├── api.md # z paths: ['src/api/**']
├── components.md # z paths: ['src/components/**']
├── testing.md # bez paths, zawsze aktywne
└── security.md # bez paths, zawsze aktywne
```
Każdy plik w `.claude/rules/` może mieć nagłówek:
```markdown
---
paths:
- "src/api/**/*.ts"
---
# Reguły API
- Każdy endpoint waliduje dane wejściowe za pomocą zod
- Błędy używają standardowego formatu `{error, code}`
- Wymagane są komentarze OpenAPI
```
Claude ładuje te reguły tylko podczas pracy z plikami pasującymi do tego wzorca. Jeśli zmieni `src/components/Button.tsx`, reguły API nie zostaną dodane do kontekstu. Dzięki temu okno kontekstowe wykorzystuje się tylko do tego, co istotne. Katalog `.claude/rules/` działa również bez `CLAUDE.md`: jeśli projekt zawiera tylko `AGENTS.md`, jego reguły są ładowane razem z nim i nie wyłączają bezpośredniego odczytu `AGENTS.md`.
Cursor i Windsurf obsługują to samo podejście przez katalogi `.cursor/rules/` i `.windsurf/rules/`. Standard AGENTS.md może odwoływać się do tych katalogów, ale składnia między narzędziami nie jest jeszcze w pełni stabilna. Bezpieczniej jest trzymać wspólne reguły w `AGENTS.md`, a reguły ograniczone do ścieżek powielać w `.claude/rules/` i `.cursor/rules/` — to rzadkie przypadki specyficzne dla narzędzi, a nie większość reguł.
Przydatne lokalizacje pliku CLAUDE.md, od najszerszego do najwęższego zakresu:
| Poziom | Lokalizacja | Przeznaczenie |
|----|----|----|
| **Zarządzana polityka** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Reguły firmowe, IT/DevOps |
| **Użytkownik** | `~/.claude/CLAUDE.md` | Osobiste preferencje we wszystkich projektach |
| **Projekt** | `./CLAUDE.md` lub `./.claude/CLAUDE.md` | Reguły zespołu projektowego |
| **Lokalny** | `./CLAUDE.local.md` (w `.gitignore`) | Osobiste preferencje dla konkretnego projektu |
Przykładowy `~/.claude/CLAUDE.md` może zawierać dwie reguły: „odpowiadaj w preferowanym przez użytkownika języku” oraz „pisz nazwę Ailoot dokładnie w tej formie”. Reguły obowiązują we wszystkich projektach, więc nie trzeba ich powielać w każdym repozytorium.
Spośród tych czterech poziomów bezpośredni odczyt `AGENTS.md` wyłączają tylko projektowy `CLAUDE.md` i `CLAUDE.local.md`. Osobisty `~/.claude/CLAUDE.md` i zarządzana polityka nie przeszkadzają — Claude Code odczytuje je razem z `AGENTS.md`.
## Co zrobić, jeśli AGENTS.md w projekcie jest już nieaktualny?
Najważniejsze informacje
Jeśli `AGENTS.md` został przygotowany w 2025 roku dla Codex lub Aider i od tamtej pory go nie edytowano, otwórz projekt w Claude Code i poproś Claude’a o edycję pliku. AGENTS.md to dokument, który powinien żyć i być aktualizowany; specyfikacja Linux Foundation również ulega zmianom. Główna zasada aktualizacji brzmi: każda reguła musi odpowiadać na pytanie „Co mam dość powtarzać Claude’owi/Codexowi?”. Jeśli nie odpowiada, zarchiwizuj ją.
W opisanym projekcie miałem plik `AGENTS.md` z maja 2025 roku — 180 wierszy, z których wiele było nieaktualnych (wspominał o zmienionych endpointach Anthropic API, przykładach składni `claude --tools`, która już nie istnieje, oraz regułach dotyczących `~/.claude/projects/` opartych na nieaktualnej strukturze).
Oto plan, którego użyłem do jego aktualizacji:
1. **Przejrzyj plik z `claude` w trybie planowania.** Otwieram repozytorium, uruchamiam `claude --safe-mode` i proszę: „Przeczytaj ponownie `AGENTS.md` i zaproponuj listę nieaktualnych lub powtarzających się elementów. Nie edytuj pliku — tylko je wymień”. W dwie minuty otrzymałem listę 23 elementów do sprawdzenia.
2. **Usuń oczywiście nieaktualne elementy.** Spośród 23 pozycji 9 było ewidentnie nieaktualnych — składnia poleceń, endpointy i nazwy flag. Usunąłem te wiersze.
3. **Połącz duplikaty.** Kolejne 6 pozycji powtarzało tę samą treść innymi słowami („nie wymuszaj pushowania”, „nigdy nie używaj `--force`”, „unikaj `git push -f`”). Połączyłem je w jeden wiersz.
4. **Dodaj nowe pozycje.** Dodałem to, co zauważyłem, że Claude/Codex regularnie robiły źle w ciągu ostatniego miesiąca, zgodnie z zasadą „jeden wiersz na wzorzec błędu”. W ten sposób doszło 8 nowych pozycji.
5. **Uruchom subagenta do końcowego przeglądu.** Zleciłem Claude’owi przegląd z instrukcją „znajdź sprzeczności, niejasności i duplikaty”. Znalazł trzy sformułowania, które można było ulepszyć. Poprawiłem je.
Po godzinie `AGENTS.md` miał 110 wierszy, był aktualny, a ja znałem osobiście każdy z nich. Bez trudu przygotowałem na jego podstawie 30-wierszowy `CLAUDE.md`. Codex zaczął też wyraźnie ostrożniej podchodzić do testów — podejrzewam, że niektóre jego „dziwne” decyzje wynikały z tego, że w dobrej wierze stosował się do nieaktualnych instrukcji.
Główne zasady utrzymywania aktualnego `AGENTS.md`:
- **Każda reguła odpowiada na powtarzający się błąd.** Jeśli w ciągu miesiąca ani razu o niej nie pomyślałem, nie warto jej zachowywać.
- **Pisz reguły jako polecenia, nie teorię.** „Używaj dwóch spacji” to reguła. „Styl kodu powinien być schludny” — nie.
- **Konkret jest lepszy od ogólników.** „Uruchom `npm run build` przed `git push`” to reguła. „Przetestuj swoje zmiany” — nie.
## Co zdecydowanie NIE działa w tej konfiguracji?
Najważniejsze informacje
Import `@AGENTS.md` nie sprawi, że różne narzędzia będą zachowywać się tak samo. Każde ma swoje osobliwości: Codex CLI nie zna `.claude/rules/` ani hooks. Cursor ma własny mechanizm autouzupełniania, który nie odczytuje CLAUDE.md podczas podpowiadania tekstu. Copilot stosuje się do `.github/copilot-instructions.md`, a same reguły w AGENTS.md mu nie wystarczą. Nie chodzi o zasadę „jeden plik = jedno zachowanie”, lecz o „jedno źródło reguł podstawowych, a następnie dodatki dla każdego narzędzia”.
Kilka rzeczy, których nauczyłem się przez sześć miesięcy pracy z tą konfiguracją:
**1. Autouzupełnianie Cursor nie korzysta z AGENTS.md.** Gdy Cursor podpowiada dokończenie wiersza w edytorze, nie odczytuje `AGENTS.md` w czasie rzeczywistym — działa wtedy osobny, szybki mechanizm. Reguły z AGENTS.md mają znaczenie tylko wtedy, gdy wysyłasz prośbę w czacie Cursor. Oznacza to, że zapisanie w AGENTS.md „nie używaj `var`, używaj `const`” nie wpłynie na autouzupełnianie; trzeba to skonfigurować w ESLint lub konfiguracji TypeScript.
**2. Hooks Claude Code zapisane w AGENTS.md nie działają w Codex.** Jeśli `.claude/settings.json` zawiera skonfigurowany hook PreToolUse, który blokuje określone działanie, ta informacja jest przydatna tylko Claude’owi. Codex nie zna hooks — dla niego „narzędzie samo decyduje”. Warto więc napisać „nie rób X” w `AGENTS.md`, a „istnieje hook, który fizycznie blokuje X” w `CLAUDE.md`, pod importem.
**3. Copilot i `.github/copilot-instructions.md`.** GitHub Copilot odczytuje własny plik i nadal nie radzi sobie dobrze z odczytem AGENTS.md. Jeśli Twój zespół aktywnie korzysta z Copilota, dodaj osobny `.github/copilot-instructions.md` ze skróconą wersją reguł albo użyj [Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions) obsługujących AGENTS.md. Sytuacja szybko się zmienia, więc za trzy do sześciu miesięcy może wyglądać inaczej.
**4. Git nie śledzi dowiązania symbolicznego jako zmiany w CLAUDE.md.** Jeśli uruchomisz `ln -s AGENTS.md CLAUDE.md`, a tydzień później zaktualizujesz `AGENTS.md`, Git pokaże diff tylko dla `AGENTS.md`. To normalne, ale osoba przeglądająca PR może nie zauważyć, że `CLAUDE.md` też został zaktualizowany przez dowiązanie symboliczne. Rozwiązanie: napisz jawnie w opisie PR: „zaktualizowano `AGENTS.md`; Claude Code widzi ten sam plik przez dowiązanie symboliczne”.
**5. Głębokie importy trudno diagnozować.** Jeśli `AGENTS.md` importuje `@docs/coding-style.md`, a ten importuje `@docs/typescript.md`, rozwiązywanie konfliktów między regułami staje się trudne. Ograniczam importy do jednego poziomu (`CLAUDE.md` → `AGENTS.md`) i nie zagnieżdżam ich dalej. Anthropic udostępnia hook `InstructionsLoaded`, który rejestruje wczytane pliki — przydatne narzędzie do diagnozowania konfiguracji warstwowych. Uwaga: hook uruchamia się dla `AGENTS.md` dołączonego przez import lub dowiązanie symboliczne, ale nie dla `AGENTS.md` odczytanego samodzielnie przez Claude Code.
### Źródła
- [Dokumentacja pamięci Claude Code — sekcja AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) — kiedy Claude Code sam odczytuje AGENTS.md, ustawienia Project instructions, importy, dowiązania symboliczne i działanie `/init`.
- [Dokumentacja pamięci Claude Code — importowanie dodatkowych plików](https://code.claude.com/docs/en/memory#import-additional-files) — składnia `@path/to/file`, maksymalnie cztery poziomy oraz ścieżki względne i bezwzględne.
- [agents.md — standard Linux Foundation](https://agents.md/) — oficjalny standard AGENTS.md i lista obsługujących go narzędzi.
- [Dokumentacja Cursor Rules](https://docs.cursor.com/context/rules-for-ai) — co odczytuje Cursor (`.cursor/rules/*.mdc`, AGENTS.md).
- [Niestandardowe instrukcje GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) — format `.github/copilot-instructions.md`.
- [Specyfikacja AGENTS.md w Linux Foundation](https://aaif.io/projects/agents-md/) — żywa specyfikacja.
Kompletny zestaw vibe coding na jeden wieczór: **klon AI + Drugi Mózg + inżynieria kontekstu**.
Poznaj [Ailoot](https://ailoot.ai/).
## Pytania i odpowiedzi
### Kiedy użyć importu zamiast dowiązania?
Użyj `@AGENTS.md` w `CLAUDE.md` przy dodatkach właściwych Claude lub Windows w zespole. Dowiązanie łączy obie nazwy z tą samą treścią, więc nie przechowa osobnej sekcji tylko Claude.
### Jak sprawdzić wczytanie wspólnych instrukcji?
Uruchom `/memory` i sprawdź listę plików. Jeśli CLAUDE.md lub CLAUDE.local.md blokuje bezpośrednie AGENTS.md w konfiguracji, dodaj import lub ustaw ładowanie obu i zacznij świeżą sesję.
## Ailoot · Firma i jej portfel projektów
Ailoot opiera się na zgromadzonym doświadczeniu operacyjnym, szerokiej bazie klientów, stabilnej usłudze i stałej kontroli KPI.
Firma i jej portfel projektów: miliony klientów; miesięczna sprzedaż liczona w miliardach.
Ailoot wykorzystuje to doświadczenie operacyjne, zapewniając dostęp przez API do funkcji AI w produktach klientów, agentach, aplikacjach i automatyzacjach.