SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor · Zaktualizowano 2026-10-30

Zagnieżdżone pliki AGENTS.md w monorepo - jak wdrożyć

Pojedynczy plik AGENTS.md w monorepo szybko staje się nieaktualny i marnuje tokeny kontekstu. Sprawdź, jak wdrożyć strukturę zagnieżdżoną, aby ograniczyć instrukcje do katalogów.

Co oznacza zagnieżdżony AGENTS.md w monorepo

Zagnieżdżony plik AGENTS.md w monorepo oznacza jeden mały plik w katalogu głównym repozytorium oraz po jednym dodatkowym pliku wewnątrz każdego katalogu usługi. Plik główny zawiera kilka reguł obowiązujących wszędzie oraz mapę lokalizacji pozostałych plików. Każdy plik wewnątrz usługi zawiera polecenia i konwencje dotyczące wyłącznie tego katalogu. Agent edytujący services/worker/queue.py odczytuje plik główny oraz plik roboczy, nie zużywając przy tym kontekstu na interfejs użytkownika, którego nigdy nie będzie modyfikował.

Nie ma nic do zainstalowania. AGENTS.md to konwencja, co projekt nadrzędny określa wprost:

AGENTS.md to zwykły plik Markdown. Można używać dowolnych nagłówków; agent po prostu analizuje dostarczony tekst.

Dlatego warto dobrze opanować tę technikę. Format nie ulegnie zmianie. Problemem może być jedynie rozmieszczenie i utrzymanie plików, a za oba te aspekty odpowiada użytkownik.

Dlaczego jeden duży plik AGENTS.md w katalogu głównym przestaje działać?

Pojedynczy plik AGENTS.md o długości 600 linii, umieszczony w katalogu głównym repozytorium zawierającego aplikację webową, proces tła oraz katalog Terraform, zawodzi z czterech powodów.

Plik staje się nieaktualny, ponieważ nikt za niego nie odpowiada. Inżynier zmieniający nazwę skryptu testowego w apps/web edytuje pliki w apps/web. Plik AGENTS.md w katalogu głównym nie znajduje się w tym diffie, więc żaden recenzent nie zauważy rozbieżności. Sześć tygodni później plik opisuje krok budowania, który już nie istnieje, a osoba, która wprowadziła zmianę, już o niej zapomniała.

Każde zadanie kosztuje dodatkowy kontekst. Pliki te są ładowane na początku sesji, zanim agent dowie się, o co zostanie zapytany. Dokumentacja Claude Code określa to jasno: „celuj w poniżej 200 linii na plik CLAUDE.md. Dłuższe pliki zużywają więcej kontekstu i obniżają skuteczność”. Codex przestaje łączyć pliki instrukcji, gdy ich łączny rozmiar osiągnie 32 KiB, czyli domyślny limit project_doc_max_bytes. Plik w katalogu głównym dokumentujący cztery usługi zużywa ten budżet na trzy z nich przy każdym zadaniu.

Instrukcje zaczynają być ze sobą sprzeczne. Katalog webowy wymaga pnpm test. Proces tła wymaga pytest -q. Zapisane w jednym pliku, każda z reguł jest poprawna tylko w określonych sytuacjach, więc agent musi zgadywać, która z nich ma zastosowanie. Dokumentacja Claude Code opisuje wynik: „jeśli dwie instrukcje są sprzeczne, Claude może wybrać jedną z nich arbitralnie”. Podział pliku nie eliminuje drugiej reguły z kontekstu. Claude Code łączy wszystkie załadowane pliki instrukcji, zamiast pozwalać, by jeden zastępował drugi. Plik z katalogu głównego jest więc zawsze obecny, a gdy agent otworzy pliki zarówno w apps/web, jak i services/worker, oba pliki z katalogów znajdą się w kontekście jednocześnie. Plik per-katalog przypisuje każdą regułę do katalogu, którego dotyczy. Należy nazwać katalog na początku pliku, tak jak zrobiono to w poniższych przykładach z # apps/web, dzięki czemu każda komenda wskazuje swoje miejsce, nawet gdy załadowanych jest kilka plików jednocześnie. Gdy reguła, co do której jasności zapisu jesteś pewien, jest mimo to pomijana, analiza przyczyn, dla których instrukcja nie jest uwzględniana jest skuteczniejsza niż czwarta próba przeredagowania tekstu.

Plik wypełnia się faktami, które agent może odczytać z kodu. Drzewo katalogów, lista zależności, podsumowanie działania każdego pakietu. Mechanizm /doctor w Claude Code istnieje właśnie po to, aby usuwać takie informacje. „Usuwa treści, które Claude może wywnioskować z bazy kodu, takie jak struktura katalogów, listy zależności i przeglądy architektury”, zachowując jedynie „pułapki, uzasadnienia i konwencje odbiegające od domyślnych ustawień narzędzi”. To zdanie jest najlepszym znanym mi testem sprawdzającym, czy dana linia w ogóle powinna znaleźć się w pliku.

Czy agent odczytuje plik główny (root), czy tylko najbliższy?

W tym miejscu większość osób błędnie interpretuje model działania, dlatego warto przytoczyć konwencję nadrzędną zamiast ją parafrazować:

Umieść kolejny plik AGENTS.md wewnątrz każdego pakietu. Agenci automatycznie odczytują najbliższy plik w drzewie katalogów, więc to ten najbliższy ma pierwszeństwo, a każdy podprojekt może dostarczać własne, dostosowane instrukcje.

W kwestii konfliktów:

Plik AGENTS.md znajdujący się najbliżej edytowanego pliku ma pierwszeństwo; jawne polecenia użytkownika na czacie nadpisują wszystko.

Dla wielu osób „ma pierwszeństwo” oznacza „plik główny jest ignorowany”. Tak nie jest. W narzędziach implementujących tę konwencję każdy plik na ścieżce od katalogu głównego repozytorium aż do katalogu roboczego jest odczytywany i łączony w całość. Najbliższy plik wygrywa tylko wtedy, gdy dwa pliki zawierają sprzeczne informacje na ten sam temat.

Codex jasno określa ten mechanizm: „Codex łączy pliki od katalogu głównego w dół, rozdzielając je pustymi liniami. Pliki znajdujące się bliżej bieżącego katalogu nadpisują wcześniejsze wytyczne”. Claude Code postępuje w ten sam sposób. Przy rozpoczęciu sesji odczytuje „każdy AGENTS.md oraz .claude/AGENTS.md w katalogu roboczym i katalogach nadrzędnych”, a dokumentacja jasno opisuje model ładowania: „Wszystkie wykryte pliki są łączone w kontekst, zamiast wzajemnie się nadpisywać”. Katalogi poniżej katalogu roboczego zachowują się inaczej: Claude Code ładuje plik AGENTS.md z podkatalogu na żądanie, „gdy Claude otwiera tam plik za pomocą narzędzia Read”.

Wynikają z tego dwie praktyczne konsekwencje. Plik główny stanowi prefiks każdej sesji w repozytorium, więc każdą linię w nim zawartą należy traktować jako kosztowną, ponieważ jest przetwarzana sto razy w tygodniu. Plik przypisany do katalogu nie generuje kosztów, dopóki agent nie otworzy pliku w tym katalogu, co oznacza, że szczegółowe instrukcje są tam tanie i właśnie tam powinny się znajdować.

To zachowanie zostało zweryfikowane z dokumentacją Codex oraz Claude Code w dniu 27 października 2026. Narzędzia implementują tę konwencję w nieco odmienny sposób i podlegają zmianom, dlatego należy potwierdzić zasady ładowania dla agenta używanego w danym zespole.

Gotowy układ repozytorium dla trzech usług

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

Plik główny (root) jest celowo krótki. Wskazuje on lokalizacje plików i zawiera wyłącznie reguły obowiązujące w każdym katalogu.

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

Plik wewnątrz każdego katalogu zawiera szczegółowe informacje i może być tak długi, jak wymaga tego dany katalog.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

Plik roboczy (worker) ma taką samą strukturę, ale inną zawartość: polecenie instalacji, pytest -q, powód, dla którego konsument musi zachowywać idempotentność, oraz migrację, która musi zostać wykonana, zanim testy zakończą się powodzeniem. Plik infrastruktury (infra) zawiera reguły zapobiegające wyrządzeniu szkód przez agenta. Nigdy nie należy uruchamiać terraform apply. Należy wykonać terraform plan i na tym poprzestać, wskazując backend stanu, który jest już skonfigurowany, aby agent nie próbował inicjować nowego.

Warto zwrócić uwagę na to, czego nie ma w żadnym z tych plików: opisu przeznaczenia poszczególnych usług. To należy do domeny ludzi. Upstream wyznacza tę samą granicę, stwierdzając, że "pliki README.md są przeznaczone dla ludzi: zawierają szybki start, opisy projektów i wytyczne dotyczące współtworzenia", podczas gdy AGENTS.md zawiera "dodatkowy, czasem szczegółowy kontekst potrzebny agentom programistycznym: kroki budowania, testy i konwencje". Artykuł podział między AGENTS.md a README dla ludzi szczegółowo omawia tę granicę zdanie po zdaniu, a plik DESIGN.md, który dokumentuje powody przyjętej architektury kodu opisuje trzeci rodzaj pliku, wyjaśniający podjęte decyzje, a nie wydawane polecenia.

Kto aktualizuje plik, gdy zmienia się kod?

Obowiązuje jedna zasada, której miejsce jest w pliku głównym: każdy, kto zmienia kod w danym katalogu, aktualizuje plik AGENTS.md tego katalogu w tym samym commicie.

Działa to z powodów technicznych, a nie kulturowych. Plik znajdujący się w danym katalogu jest częścią tego samego diffa co kod, więc osoba sprawdzająca pull request widzi obie zmiany jednocześnie. Plik główny należy do wszystkich, co oznacza, że nie należy do nikogo i nigdy nie pojawia się w diffie, który ktoś aktualnie przegląda.

Zasadę tę należy poprzeć weryfikacją w ramach pull requesta. Mechanizm ten znajduje najbliższy plik AGENTS.md powyżej każdego zmienionego pliku, a następnie zgłasza, jeśli plik ten nie został zmodyfikowany.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

W gałęzi, w której przebudowano API client bez aktualizacji dokumentacji, wynik wygląda następująco:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

Należy zachować to jako ostrzeżenie, a nie jako błąd blokujący. Sztywna blokada uczy ludzi dodawania pustej linii do pliku tylko po to, aby CI przeszło pomyślnie, a plik edytowany w celu zadowolenia robota jest mniej wart niż brak pliku. Ostrzeżenie daje recenzentowi powód do zadania pytania, co jest elementem, który faktycznie przynosi efekty.

Jak rozpoznać nieaktualny plik AGENTS.md?

Dostępne są dwie metody weryfikacji oraz jeden objaw, który występuje w trakcie sesji.

Porównaj wiek każdego pliku z wiekiem kodu, który opisuje. %cs wyświetla datę commitu jako YYYY-MM-DD.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done
apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

Data w dokumentacji starsza o sześć miesięcy od daty kodu nie dowodzi, że plik jest błędny. Wskazuje jedynie, który plik należy przeczytać w pierwszej kolejności, co jest wystarczającą informacją w przypadku testu trwającego sekundę.

Wyszukaj ścieżki, które już nie istnieją. Dokumentacja ulega dezaktualizacji w jeden konkretny sposób: nadal opisuje kod, który został usunięty. Każda ścieżka w tych plikach jest zapisana w backtickach, więc łatwo je wyodrębnić i przetestować.

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

Należy analizować wyniki ręcznie, zamiast integrować to z CI. Metoda ta oznacza również wzorce typu glob, takie jak src/**/*.ts, oraz każdy zacytowany adres URL, ponieważ oba zawierają ukośnik i żaden z nich nie jest plikiem na dysku. W wersji Claude Code v2.1.283 lub nowszej /doctor prompt-audit wykonuje podobną weryfikację: wyszukuje „odwołania do plików lub poleceń, które nie istnieją” oraz pliki, które są ze sobą sprzeczne, domyślnie uwzględnia pliki AGENTS.md i nie wprowadza żadnych zmian, dopóki użytkownik nie zleci zastosowania zaproponowanych edycji.

Objaw w trakcie sesji. Agent odczytuje plik, próbuje otworzyć src/api/client.ts, ponieważ tak wynika z instrukcji, a narzędzie zwraca błąd:

No such file or directory

W rezultacie agent podejmuje logiczne działanie i tworzy własny wrapper fetch. To jest rzeczywisty koszt nieaktualnego pliku. Agent nie ignoruje dokumentacji. Postępuje zgodnie z nią, trafia na ścieżkę usuniętą trzy miesiące temu i ponownie tworzy kod, który już istnieje. Umiejętność taka jak Ponytail, która ogranicza agenta do najmniejszej działającej zmiany, sprawia, że ten instynkt ponownego tworzenia kodu występuje rzadziej, ale nie jest w stanie odnaleźć pomocnika, na którego plik wskazuje błędnie.

Czy Claude Code odczytuje pliki AGENTS.md?

Tak, od wersji Claude Code v2.1.277. Dokładna reguła ma znaczenie, ponieważ zależy od niej zagnieżdżony układ. Zgodnie z dokumentacją z dnia 27 października 2026 r.: „Claude Code może odczytywać AGENTS.md jako instrukcje projektu, więc repozytorium już skonfigurowane dla innych agentów programistycznych działa bez dodawania CLAUDE.md, importu czy ustawienia”. Domyślna wartość Project instructions, claude-md-or-agents-md, odczytuje „pliki AGENTS.md, gdy w katalogu roboczym lub powyżej niego nie ma CLAUDE.md ani CLAUDE.local.md”. Zagnieżdżone pliki również są uwzględniane: Claude odczytuje AGENTS.md z podkatalogu „gdy Claude otwiera tam plik za pomocą narzędzia Read”, pod warunkiem że „ten podkatalog nie posiada własnych trzech plików CLAUDE.md”. Tymi trzema plikami są CLAUDE.md, .claude/CLAUDE.md oraz CLAUDE.local.md, więc osobisty CLAUDE.local.md w apps/web wystarczy, aby zatrzymać ładowanie apps/web/AGENTS.md.

To sprawia, że stara porada umieszczania CLAUDE.md obok każdego AGENTS.md staje się pułapką. Przy obecności AGENTS.md oraz CLAUDE.md lub CLAUDE.local.md w katalogu roboczym lub powyżej, dokumentacja podaje, że Claude odczytuje „tylko pliki CLAUDE.md”. .claude/CLAUDE.md liczy się w ten sam sposób. Jeden plik towarzyszący w katalogu głównym, zawierający pojedynczą linię specyficzną dla Claude, ukrywa każdy AGENTS.md na ścieżce, a osobisty CLAUDE.local.md robi to samo. Jeśli chcesz zachować oba, wpisz /config i ustaw Project instructions na claude-md-and-agents-md, co odczyta oba pliki, najpierw CLAUDE.md z każdego katalogu, a następnie jego AGENTS.md.

Sam numer wersji nie potwierdza poprawności działania. Wymagana jest wersja v2.1.277 lub nowsza, jednak przed wersją v2.1.281 niektóre sesje, takie jak te na Amazon Bedrock lub z wyłączoną telemetrią, odczytują tylko pliki CLAUDE.md. W niektórych przypadkach pierwsza sesja po aktualizacji z wersji v2.1.276 lub starszej również pomija AGENTS.md: dokumentacja stwierdza, że „Claude odczytuje AGENTS.md od następnej sesji”. Należy więc sprawdzić samą sesję. W sesji interaktywnej Claude Code wyświetla linię taką jak no CLAUDE.md found; AGENTS.md loaded:, po której następuje ścieżka, a w bieżących wersjach /memory wymienia plik. Przed wersją v2.1.280 /memory i /context nie wymieniały AGENTS.md, który Claude odczytywał bezpośrednio, więc w tych wersjach należy zapytać Claude, jakie są jego instrukcje projektowe.

Forma importu jest nadal właściwa tam, gdzie Claude nie może odczytać AGENTS.md bezpośrednio: w starszej wersji, w sesji przed v2.1.281 na Amazon Bedrock lub z wyłączoną telemetrią, w sesji, w której wbudowana wtyczka odczytująca ten plik jest wyłączona, lub w projekcie, który przechowuje CLAUDE.md z ustawieniem Project instructions na claude-md. Umieść to w services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

Forma dowiązania symbolicznego (symlink) jest właściwa, gdy nie ma nic specyficznego dla narzędzia do dodania.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln nie wyświetla niczego po pomyślnym wykonaniu, więc sprawdź listę: apps/web/CLAUDE.md -> AGENTS.md. Następnie rozpocznij sesję i uruchom /context, gdzie załadowane pliki pojawią się w sekcji Memory files. W systemie Windows dowiązanie symboliczne wymaga uprawnień administratora lub trybu programisty, a Git sprawdza zatwierdzone dowiązanie symboliczne jako zwykły plik tekstowy, chyba że włączono core.symlinks, co pozostawia ten klon z jednowierszowym CLAUDE.md zamiast instrukcji. Jeśli ktokolwiek, kto klonuje repozytorium, pracuje w systemie Windows, użyj importu @AGENTS.md. Jeśli skonfigurowałeś którekolwiek z obejść, zanim Claude Code zaczął samodzielnie odczytywać AGENTS.md, możesz je pozostawić: dokumentacja podaje, że zachowanie importu „nigdy nie powoduje dwukrotnego odczytania AGENTS.md przez Claude”, a dowiązany symbolicznie CLAUDE.md jest odczytywany raz.

Z tym wiąże się jedna pułapka. Po /compact plik CLAUDE.md z katalogu głównego projektu jest ponownie odczytywany z dysku, ale zagnieżdżone pliki w podkatalogach nie są ponownie wstrzykiwane. Claude Code ładuje je ponownie na żądanie, gdy agent następnym razem pracuje z plikiem w tym katalogu. Dokumentacja wyjaśnia to dla plików CLAUDE.md i nie opisuje oddzielnie kompaktowania dla AGENTS.md odczytywanego bezpośrednio, więc należy oczekiwać, że zagnieżdżone pliki o obu nazwach będą zachowywać się w ten sposób. Jeśli reguła dla danego katalogu przestaje obowiązywać w połowie długiej sesji, zazwyczaj jest to powód, a odczytanie dowolnego pliku w tym katalogu przywraca jej działanie.

Ustawienia wskazujące innym agentom plik AGENTS.md

Codex odczytuje AGENTS.md natywnie. Na każdym poziomie sprawdza najpierw AGENTS.override.md, co pozwala na lokalne nadpisanie w jednym katalogu bez edycji pliku współdzielonego. Przestaje łączyć pliki, gdy łączny rozmiar osiągnie 32 KiB, czyli domyślny project_doc_max_bytes, co jest kolejnym powodem, by utrzymywać mały rozmiar pliku głównego.

Aider przyjmuje go przez .aider.conf.yml z linią read: AGENTS.md.

Gemini CLI przyjmuje go przez .gemini/settings.json z { "context": { "fileName": "AGENTS.md" } }.

Dokumentacja nadrzędna opisuje wstecznie kompatybilną zmianę nazwy dla repozytoriów wciąż używających starszej nazwy w liczbie pojedynczej: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

W bardzo dużym monorepo ustawienie claudeMdExcludes w Claude Code pomija pliki nadrzędne według ścieżki lub wzorca glob, co jest przydatne, gdy katalog innego zespołu znajduje się powyżej Twojego. Jego wzorce mają zastosowanie również do plików AGENTS.md odczytywanych przez Claude Code.

Czym różni się to od pamięci agenta lub umiejętności?

Mechanizmy te wydają się podobne, lecz zawodzą w zupełnie inny sposób, dlatego warto precyzyjnie określić, z którego z nich należy skorzystać.

Plik AGENTS.md jest tworzony przez użytkownika, zatwierdzany w git, sprawdzany w pull request i identyczny dla każdego, kto sklonuje repozytorium. Pamięć agenta jest zapisywana przez agenta, przechowywana poza repozytorium i lokalna dla jednej maszyny. Dokumentacja Claude Code wyznacza tę samą granicę: CLAUDE.md zawiera „Instrukcje i zasady”, które tworzy użytkownik, pamięć automatyczna zawiera „Wnioski i wzorce”, które tworzy Claude, a katalog pamięci nie jest współdzielony między maszynami. Test jest prosty. Jeśli dany fakt musi być prawdziwy dla współpracownika korzystającego ze świeżego klona, nie może on znajdować się w pamięci. Jak pamięć agenta jest utrwalana między sesjami omawia tę część zagadnienia.

Umiejętność (skill) to trzeci element. AGENTS.md to kontekst ładowany podczas każdej sesji; umiejętność to procedura ładowana wtedy, gdy jest potrzebna. Dokumentacja Claude Code podaje użyteczną zasadę: „Jeśli wpis jest wieloetapową procedurą lub dotyczy tylko jednej części bazy kodu, przenieś go do umiejętności lub zasady o zasięgu ścieżki”. Druga połowa tego zdania precyzyjnie określa problem, który rozwiązuje zagnieżdżony plik AGENTS.md. Pierwsza połowa dotyczy tego, do czego służą umiejętności agenta, a gdy ta sama procedura jest potrzebna w więcej niż jednym repozytorium, należy udostępnić umiejętność między repozytoriami, zamiast wklejać te same akapity do dziesięciu różnych plików AGENTS.md.

Upstream zauważa, że „w momencie pisania tego tekstu główne repozytorium OpenAI zawiera 88 plików AGENTS.md”. Ta liczba stanowi cały argument. Duże repozytorium nie potrzebuje większego pliku. Potrzebuje więcej małych plików, z których każdy znajduje się obok opisywanego kodu i jest zarządzany przez osobę, która ostatnio ten kod modyfikowała.

FAQ

Czy zagnieżdżony plik AGENTS.md zastępuje plik główny, czy go uzupełnia?

Uzupełnia go. Dokumentacja upstream podaje, że „najbliższy plik ma pierwszeństwo”, co opisuje zachowanie w przypadku konfliktu, a nie proces ładowania. Codex „łączy pliki od katalogu głównego w dół, rozdzielając je pustymi liniami”, natomiast Claude Code łączy wszystkie pliki znalezione podczas przechodzenia w górę od katalogu roboczego, zamiast je nadpisywać. Najbliższy plik wygrywa tylko wtedy, gdy dwa pliki zawierają sprzeczne instrukcje dotyczące tego samego zagadnienia. Wspólne reguły należy zapisać raz w katalogu głównym i nie powtarzać ich w każdym podkatalogu.

Jak duży powinien być główny plik AGENTS.md?

Na tyle mały, aby jego dołączenie do każdego zapytania w tym repozytorium było akceptowalne, ponieważ dokładnie tak to działa. Dokumentacja Claude Code sugeruje limit poniżej 200 linii na plik i ostrzega, że dłuższe pliki „obniżają skuteczność przestrzegania instrukcji”. Codex domyślnie przestaje łączyć pliki instrukcji po osiągnięciu 32 KiB łącznej wielkości. Jeśli plik główny dokumentuje cztery usługi, większość jego treści jest zbędna dla pojedynczego zadania. Szczegóły należy przenieść do plików w poszczególnych katalogach, pozostawiając w głównym jedynie mapę.

Jak zapobiec dezaktualizacji tych plików?

Należy wprowadzić jedną regułę w pliku głównym: osoba zmieniająca kod w danym katalogu aktualizuje plik AGENTS.md w tym samym commicie. Umieszczenie pliku obok kodu zwiększa szansę na przestrzeganie reguły, ponieważ zmiana trafia do tego samego pull requesta, który jest przeglądany przez człowieka. Warto dodać ostrzeżenie CI, które mapuje każdą zmienioną ścieżkę do najbliższego pliku AGENTS.md powyżej niej, oraz okresowo porównywać git log -1 --format=%cs dla każdego pliku z tym samym poleceniem uruchomionym dla dokumentowanego katalogu.

Czy Claude Code odczytuje pliki AGENTS.md?

Tak, od wersji v2.1.277. Zgodnie z dokumentacją z dnia 27 października 2026 r., Claude Code domyślnie odczytuje AGENTS.md, jeśli w katalogu roboczym lub powyżej nie znajdują się CLAUDE.md ani CLAUDE.local.md. Odczytuje również AGENTS.md z podkatalogu, gdy otwiera tam plik za pomocą narzędzia Read, a dany podkatalog nie posiada własnego CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Nie należy dodawać CLAUDE.md obok każdego AGENTS.md: jeśli plik znajduje się w katalogu roboczym lub powyżej, Claude odczytuje tylko „Twoje pliki CLAUDE.md”. Jeśli wymagany jest również CLAUDE.md, należy ustawić Project instructions na claude-md-and-agents-md w /config lub umieścić @AGENTS.md w pierwszej linii pliku. Należy uruchomić /memory w sesji i potwierdzić, że ścieżka AGENTS.md pojawia się na liście.

Gdzie umieścić regułę, która ma znaczenie tylko czasami?

Nie w pliku AGENTS.md. Ten plik jest ładowany w każdej sesji, więc każda linia w nim zawarta konkuruje o uwagę z treścią zapytania. Procedura składająca się z kilku kroków, potrzebna tylko okazjonalnie, powinna znaleźć się w umiejętności (skill), która jest ładowana na żądanie. Reguła dotycząca jednego katalogu powinna znaleźć się w pliku AGENTS.md tego katalogu. Fakt, który agent może odczytać bezpośrednio z kodu, taki jak drzewo katalogów czy lista zależności, nie powinien znajdować się w żadnym z tych plików.

Czy ten artykuł był przydatny?