AGENTS.md i CLAUDE.md: wspólne instrukcje dla agentów AI

Informacje o usłudze znajdziesz w dokumentacji Ailoot.

AGENTS.md i CLAUDE.md: wspólne instrukcje dla Claude Code, Codex i Cursor#

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.

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?#

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:

To, co odczyta Claude Code, zależy od plików w projekcie:

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:

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?#

Minimalny działający przykład z oficjalnej dokumentacji:

@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:

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?#

Dokumentacja przedstawia opcję dowiązania symbolicznego tak:

ln -s AGENTS.md CLAUDE.md

Zaraz potem zawiera bezpośrednie ostrzeżenie dotyczące Windows:

Tabela porównawcza:

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.

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?#

Zestawienie siedmiu głównych narzędzi (na podstawie oficjalnej dokumentacji każdego z nich):

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?#

Anthropic opisuje /init w dokumentacji tak:

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:

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.

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?#

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.
• 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?#

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:

---
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:

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?#

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?#

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

Kompletny zestaw vibe coding na jeden wieczór: klon AI + Drugi Mózg + inżynieria kontekstu.

Poznaj Ailoot.