AGENTS.md i CLAUDE.md — zwięzły kontekst repozytorium

Kontekst repozytorium dla agentów kodujących to jeden krótki, wersjonowany plik AGENTS.md, który opisuje układ projektu, dokładne polecenia budowania i testów, granice oraz dowód wymagany, zanim praca zostanie uznana za skończoną. Claude Code, Codex i Cursor wyszukują pliki instrukcji na różne sposoby, więc działająca konfiguracja obejmuje też test pokazujący, co naprawdę wczytało każde narzędzie.

W zeszłym sprincie polecenie testów zmieniło się z npm test na pnpm test:unit. CLAUDE.md dostał poprawkę, AGENTS.md już nie, więc dziś sesja Codexa uruchomiła stare polecenie, zobaczyła błąd i „naprawiła” go, przepisując test. Nikt nie wie, który plik czytał który agent, bo nikt tego nigdy nie sprawdził.

Ta strona jest dla dewelopera, który odpowiada za konfigurację agentów w repozytorium, i dla tech leada, który ją ocenia. Odpowiada na pytanie 9 w Developer Scorecard. Zarządzaniem tymi samymi plikami w skali zespołu zajmuje się strona o wspólnych regułach agentów.

Co daje sprawdzony kontekst repozytorium

Główny AGENTS.md liczący około 40 linii, któremu może zaufać każdy agent i każda nowa osoba w zespole.
Jednolinijkowy adapter CLAUDE.md i awaryjną regułę Cursora, bez skopiowanych zasad, które się rozjadą.
Reguły zawężone do ścieżek dla dwóch lub trzech katalogów, które ich potrzebują, i nic więcej wczytywanego zawsze.
20-linijkowy skrypt, który kończy się błędem, gdy Codex przestaje wczytywać twoje reguły, oraz widoki Claude Code, które pokazują to samo dla Claude’a.
Cztery prompty do skopiowania: szkic rdzenia na podstawie dowodów, sonda wykrywania, sonda reguły zawężonej i audyt rozjazdów.

Co należy do głównego AGENTS.md, a co nie?

Linia trafia do zawsze wczytywanego rdzenia tylko wtedy, gdy jest prawdziwa dla każdego zadania w repozytorium, a agent nie odkryje jej, czytając kod. Wszystko inne idzie do warstwy, która wczytuje się tylko wtedy, gdy jest potrzebna.

Treść	Gdzie trafia	Dlaczego
Układ, dokładne polecenia, granice, dowód ukończenia	Główny `AGENTS.md`	Potrzebuje tego każda sesja
Konwencje jednego katalogu (`src/billing/`, `infra/`)	Reguła zawężona do ścieżki albo zagnieżdżony `AGENTS.md`	Wczytuje się tylko przy tym kodzie
Procedury wieloetapowe (wydanie, migracja, incydent)	Skill	Wczytuje się na żądanie
Zakazy, które muszą obowiązywać	Hooki, uprawnienia i sandboxing, CI, ochrona gałęzi	Instrukcje sterują, ale niczego nie wymuszają
Stan bieżącego zadania	`intent.md`, `spec.md`, `plan.md` w łańcuchu artefaktów	Traci ważność, gdy zadanie się kończy
Preferencje osobiste	`~/.claude/CLAUDE.md`, `CLAUDE.local.md` albo twój plik użytkownika w Codexie	Dotyczy tylko ciebie, nie całego zespołu

Rdzeń zgodny z tą tabelą wygląda tak, dla monorepo TypeScript na pnpm:

# Repository contract
<!-- Owner: @platform-team · reviewed monthly · last review 2026-09-26 -->

## Layout
- Web app: `apps/web/` (Next.js). API: `apps/api/` (Fastify). Shared code: `packages/`.
- Database migrations: `apps/api/migrations/`, one file per change, never edited after merge.

## Commands (run from the repository root)
- Install: `pnpm install --frozen-lockfile`
- Unit tests: `pnpm test:unit` · one package: `pnpm --filter @acme/api test:unit`
- Types: `pnpm typecheck` · Lint: `pnpm lint` · E2E: `pnpm test:e2e` (needs `pnpm dev` running)

## Boundaries
- Do not run commands that reach production, and do not read `.env.production`.
- Ask before adding a dependency or changing an exported API in `packages/`.

## Done means
- `pnpm typecheck`, `pnpm lint` and `pnpm test:unit` pass; report the commands and their results.
- List changed files and anything you could not verify.

Każda linia wskazuje ścieżkę, polecenie albo warunek, który da się sprawdzić. „Pisz czysty kod” i „testuj dokładnie” nie przechodzą tego testu: ani recenzent, ani agent nie ustali, czy zostały spełnione. Dokumentacja pamięci Anthropic radzi to samo („Run npm test before committing” zamiast „Test your changes”) i podaje cel poniżej 200 linii na plik CLAUDE.md (dokumentacja pamięci Claude Code, sprawdzone 2026-09-26).

Jak Claude Code, Codex i Cursor znajdują rdzeń?

Te trzy narzędzia wyszukują pliki instrukcji inaczej, więc adapter zależy od narzędzia. Trzymaj zasady w AGENTS.md i daj każdemu narzędziu najcieńszy adapter, dzięki któremu wczyta ten plik.

Claude Code przy starcie czyta CLAUDE.md albo .claude/CLAUDE.md z katalogu roboczego i każdego katalogu nad nim, a zagnieżdżone pliki CLAUDE.md wtedy, gdy czyta pliki w ich katalogu. Od v2.1.277 czyta też AGENTS.md bezpośrednio, ale tylko wtedy, gdy w katalogu roboczym ani wyżej nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Kanał stable w npm doszedł do v2.1.280 dopiero 30 września 2026, więc kolega na starszej wersji ze stable jeszcze tego bezpośredniego odczytu nie ma.

Użyj importu, który działa w obu kanałach i nigdy nie wczytuje pliku dwa razy:

@AGENTS.md

## Claude Code only
- Use plan mode before changing anything under `apps/api/migrations/`.

Szczegóły zawężone idą do .claude/rules/*.md. Reguła z frontmatterem paths wczytuje się tylko wtedy, gdy Claude czyta pasujący plik; paths to jedyny klucz frontmattera, który Claude Code tam odczytuje (sprawdzone w Claude Code v2.1.285, 30.09.2026).

---
paths:
  - "apps/api/src/billing/**"
---
- Money is integer cents (`number`), never floats. Use `formatCents()` for display.
- Every billing change needs a test in `apps/api/test/billing/`.

.claude/rules/ działa tylko w Claude Code: Codex nigdy go nie czyta. A przy imporcie @AGENTS.md Claude Code nie wczytuje też zagnieżdżonego AGENTS.md, bo jego domyślny tryb „Project instructions” (claude-md-or-agents-md) sięga po AGENTS.md tylko w projekcie bez własnego CLAUDE.md. Dlatego regułę zawężoną, której mają przestrzegać oba narzędzia, zapisz w zagnieżdżonym AGENTS.md, a obok daj Claude’owi zagnieżdżony CLAUDE.md zawierający wyłącznie @AGENTS.md. Claude wczyta go, gdy przeczyta plik w tym katalogu:

@AGENTS.md

Alternatywa to ustawienie „Project instructions” w /config na claude-md-and-agents-md: pliki AGENTS.md wczytują się wtedy obok CLAUDE.md, a plik, który CLAUDE.md już importuje, nie wczytuje się drugi raz (sprawdzone w Claude Code v2.1.285, 30.09.2026). .claude/rules/*.md zostaw na szczegóły zawężone potrzebne tylko Claude’owi.

Dwa szczegóły z dokumentacji pamięci mają tu znaczenie. Importy porządkują długi plik, ale nie zmniejszają jego kosztu w kontekście, bo importowane pliki wczytują się przy starcie. Blokowe komentarze HTML są usuwane, zanim treść trafi do modelu, więc linia z właścicielem w szablonie powyżej nie kosztuje tokenów.

Codex nie potrzebuje adaptera, bo czyta AGENTS.md natywnie. Sprawdzone na codex-cli 0.157.1 (kod codex-rs/core/src/agents_md.rs i lokalne uruchomienia 2026-09-26):

znajduje katalog główny projektu, idąc w górę do najbliższego .git (konfigurowalne przez project_root_markers),
wczytuje po jednym pliku na katalog, od katalogu głównego w dół do katalogu, w którym uruchomiłeś sesję, zaczynając od głównego,
w tym samym katalogu wybiera AGENTS.override.md zamiast AGENTS.md i przyjmuje dodatkowe nazwy z project_doc_fallback_filenames,
zatrzymuje się na łącznym limicie project_doc_max_bytes, domyślnie 32 KiB, a resztę obcina bez ostrzeżenia,
w niezaufanym projekcie całkowicie pomija projektowe pliki AGENTS.md (od 0.150.0).

Szczegóły zawężone idą do zagnieżdżonego AGENTS.md, na przykład apps/api/src/billing/AGENTS.md. Codex wczytuje go z góry tylko wtedy, gdy uruchomisz sesję w tym katalogu lub niżej; po starcie z katalogu głównego agent zobaczy go tylko wtedy, gdy sam otworzy plik. Pliki .rules w Codexie to coś innego: decydują, które polecenia mogą działać poza sandboxem, i nie niosą instrukcji.

Cursor stosuje instrukcje przez Rules (cursor.com/docs/rules, sprawdzone 2026-08-28). Reguły projektu leżą w .cursor/rules/, czyli w katalogu, który czyta też /init w Claude Code, gdy szkicuje CLAUDE.md. Według stanu na 26 września 2026 cursor.com był nieosiągalny z naszego środowiska weryfikacji, więc aktualny format pliku reguły i to, czy twoja wersja Cursora sama wczytuje główny plik instrukcji, nie są tu zweryfikowane.

Adapter: uruchom sondę wykrywania z następnej sekcji w nowym czacie Agent. Jeśli odpowiedź cytuje twój rdzeń, nic nie dodawaj. Jeśli nie, dodaj jedną zawsze stosowaną regułę projektu, która każe agentowi przeczytać rdzeń przed jakąkolwiek pracą, w formacie opisanym dziś na stronie Rules, i trzymaj w niej tylko linie specyficzne dla Cursora.
Szczegóły zawężone: reguła projektu ograniczona do wzorca plików, również w udokumentowanym formacie.
Wariant generowany: jeśli utrzymujesz wiele reguł dla wielu narzędzi, generuj .cursor/rules/ z jednego źródła przez rulesync, jak na stronie jedno źródło reguł dla każdego agenta.

Powtarzaj sondę po każdej aktualizacji Cursora, bo reguła-wskaźnik zależy od tego, czy model zdecyduje się otworzyć plik.

Zbuduj kontekst w sześciu krokach

Szkicuj z dowodów, nie z pamięci. Uruchom /init w Claude Code albo w Codexie, żeby dostać pierwszy szkic, albo wklej prompt szkicujący poniżej. W Claude Code /init czyta też istniejące .cursor/rules/, .cursorrules i .github/copilot-instructions.md i przenosi do szkicu najważniejsze fragmenty, a gdy CLAUDE.md już istnieje, proponuje poprawki zamiast go nadpisywać.
Wytnij każdą linię, która nie przechodzi tabeli powyżej. Usuń wszystko, co agent odczyta z package.json, drzewa katalogów albo konfiguracji lintera. Usuń przymiotniki. Zostaw polecenia, ścieżki i granice.
Uruchom każde polecenie z pliku w czystym checkoucie. Polecenie, które nie przeszło, nie trafia do rdzenia. To także moment, w którym wychodzi na jaw, że pnpm test:e2e po cichu wymaga działającego serwera deweloperskiego.
Wynieś szczegóły zawężone. Dla każdego katalogu, który ma realne lokalne konwencje, napisz jeden zagnieżdżony AGENTS.md i obok jednolinijkowy CLAUDE.md, który go importuje, jak w zakładce Claude Code. .claude/rules/<temat>.md z paths stosuj tylko do szczegółów potrzebnych wyłącznie Claude’owi. Typowo są to dwa lub trzy zawężone pliki; dwadzieścia oznacza, że rdzeń jest dzielony zamiast przycinany.
Podepnij adaptery z zakładek powyżej: CLAUDE.md z @AGENTS.md, nic dla Codexa, sonda i ewentualnie reguła-wskaźnik dla Cursora.
Wyznacz właściciela i bramkę. Dodaj AGENTS.md, CLAUDE.md, .claude/rules/ i .cursor/rules/ do CODEOWNERS i uruchamiaj w CI test wczytywania z następnej sekcji (przypięte CLI, patrz zakładka Codex). Właściciel zatwierdza każdą zmianę rdzenia tak samo jak zmianę konfiguracji CI.

Draft a root AGENTS.md for this repository. Use only facts you can verify here:
1. Read package.json (or the build manifest), the CI workflow files, the README and the top two directory levels.
2. For every build, test, lint and typecheck command you propose, run it once and record the exit code. Leave out any command that failed and tell me why.
3. Sections: Layout, Commands, Boundaries, Done means. Maximum 50 lines.
4. Do not include anything a reader can infer from the code (framework names in package.json, file naming the linter already enforces).
5. Do not write the file. Show the draft, then list each command with its exit code.

Jak udowodnić, że każdy agent wczytał reguły?

Dwa rodzaje dowodu działają bez czytania plików linia po linii: test wczytywania, który pokazuje, jakie pliki dotarły do modelu, oraz sonda zachowania, która pokazuje, że agent potrafi te reguły podać i zastosować.

Test wczytywania w każdym narzędziu.

Uruchom /context w nowej sesji i sprawdź listę pod Memory files; /memory pokazuje te same pliki i je otwiera. Jeśli chcesz mieć zapis do późniejszego sprawdzenia, loguj każde wczytanie hookiem InstructionsLoaded w swoim osobistym .claude/settings.local.json (polecenie wymaga jq):

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{file_path, load_reason}' >> \"$CLAUDE_PROJECT_DIR/.claude/instructions-loaded.log\""
          }
        ]
      }
    ]
  }
}

Otwórz plik w apps/api/src/billing/, a w logu pojawi się linia path_glob_match dla billing.md. Hook działa dla CLAUDE.md, reguł i importów (load_reason: "include"). Log może nie pokazać AGENTS.md, który Claude czyta bezpośrednio bez CLAUDE.md, bo ta ścieżka przechodzi przez wbudowany plugin agents-md; import sprawia, że wczytanie jest widoczne. Hook służy tylko do obserwacji i nie może zablokować wczytania. Dodaj plik logu do .gitignore.

/doctor prompt-audit (sprawdzone w Claude Code v2.1.285, 30.09.2026) audytuje pliki instrukcji wczytywane w tym projekcie. Działa przez wbudowany skill claude-api, więc jest niedostępne, gdy wbudowane skille są wyłączone w ustawieniach. Przejrzyj jego ustalenia, zanim zaakceptujesz jakąkolwiek poprawkę.

codex debug prompt-input wypisuje jako JSON prompt widoczny dla modelu, bez wywoływania modelu (bez logowania, sprawdzone na codex-cli 0.157.1). Dzięki temu test wczytywania da się zautomatyzować:

#!/usr/bin/env bash
# Fails when Codex stops loading a rule you depend on. Run from the repository root.
set -euo pipefail

expect() {  # expect <directory> <string that must reach the model>
  if ! (cd "$1" && codex debug prompt-input) | grep -F -- "$2" >/dev/null; then
    echo "FAIL: '$2' not loaded when Codex starts in $1" >&2
    exit 1
  fi
}

expect .                     'pnpm test:unit'
expect apps/api/src/billing  'integer cents'
echo "Codex loads the expected instructions."

Linia dla billingu zakłada, że reguła leży w apps/api/src/billing/AGENTS.md, jak zaleca krok 4; Codex nigdy nie czyta .claude/rules/.

Skrypt łapie naraz trzy ciche awarie Codexa: obcięcie na 32 KiB, AGENTS.override.md, który zasłania właściwy plik, i zagnieżdżony plik, który przestał się wczytywać. Uruchamiaj go w jobie pull_request bez sekretów w środowisku: czyta pliki kontrybutora i żadnych sekretów nie potrzebuje. W jobie instaluj przypiętą wersję CLI: npm install -g @openai/codex@0.157.1, a przypięcie podbijaj świadomie, bo nowszy Codex może zmienić wynik testu.

Sonda zachowania w każdym narzędziu. Wklej te prompty do świeżej sesji po każdej zmianie plików instrukcji. Oczekiwane odpowiedzi trafiają do opisu pull requesta; błędna odpowiedź blokuje merge.

Before editing anything, answer from your loaded instructions only, not by searching the repository:
1. Which instruction files did you load at session start? Give their paths.
2. What are the exact commands to run unit tests, typecheck and lint?
3. Which actions are you told not to take?
4. What must you report before you call a task done?
If you have no instruction for one of these, say "none loaded" instead of guessing.

Open apps/api/src/billing/invoice.ts and read it without editing. Then tell me:
1. Which repository-wide instructions and which billing-specific instructions apply to this file, with the path of each source file.
2. How you would represent 19.99 EUR in this code, and why.
If no billing-specific instruction loaded, say so explicitly.

Najwięcej mówi drugie pytanie: agent, który odpowiada „integer cents, 1999”, zastosował regułę, a nie tylko ją wymienił.

Kiedy dodać regułę, a kiedy ją usunąć?

Dodawaj linię dopiero wtedy, gdy ten sam błąd zdarzy się dwa razy w osobnych sesjach, i tylko jeśli poprawkę da się zapisać jako coś sprawdzalnego. To właśnie zasada „błąd powtórzony dwa razy trafia do reguł” z najlepszej odpowiedzi w Scorecardzie. Druga połowa to usuwanie: reguła, której od miesięcy nie potrzebowała żadna sonda ani żaden błąd, to kontekst opłacany w każdej sesji. Protokół ablacji do przycinania plików kontekstu usuwa linie pojedynczo i przywraca tylko to, co się psuje.

Audit every instruction file that applies in this repository: AGENTS.md at any depth, AGENTS.override.md, CLAUDE.md, CLAUDE.local.md, .claude/rules/, .cursor/rules/.
For each rule, report one of: DUPLICATE (same rule in two files), CONFLICT (two files disagree), STALE (names a path, script or command that does not exist; check each one), VAGUE (cannot be verified), or OK.
Then propose the smallest patch that leaves the policy in AGENTS.md only and the tool files as adapters. Do not edit runtime code, and do not apply the patch.

Co psuje się w AGENTS.md i CLAUDE.md i jak to naprawić?

Objaw	Przyczyna	Naprawa
Claude Code ignoruje `AGENTS.md` po dodaniu osobistego `CLAUDE.local.md`	Każdy `CLAUDE.md`, `.claude/CLAUDE.md` lub `CLAUDE.local.md` wyłącza bezpośrednie czytanie `AGENTS.md`	Dodaj `@AGENTS.md` do `CLAUDE.md` albo ustaw Project instructions w `/config` na `claude-md-and-agents-md`
Claude Code u kolegi nigdy nie widzi `AGENTS.md`	Kolega ma wersję sprzed v2.1.277 (kanał `stable` doszedł do v2.1.280 30.09.2026), jest w sesji Bedrock, Google Cloud, Microsoft Foundry, przez bramkę LLM lub z wyłączoną telemetrią sprzed v2.1.281 albo ma wyłączony wbudowany plugin `agents-md`	Import `@AGENTS.md` działa w każdej wersji
Codex stosuje reguły z katalogu głównego, ale nie te z końca zagnieżdżonego pliku	Pliki łącznie przekraczają `project_doc_max_bytes` (32 KiB); późniejsze pliki są obcinane jako pierwsze	Skróć rdzeń albo przenieś procedury do skilli; podniesienie limitu to tylko doraźne obejście
Codex ignoruje twoje zmiany w `AGENTS.md` w jednym katalogu	`AGENTS.override.md` w tym samym katalogu go zastępuje	Usuń override albo scal go; skrypt testu wczytywania pokazuje, który plik dotarł do modelu
Codex nie wczytuje żadnych instrukcji projektu	Projekt jest niezaufany	Oznacz projekt jako zaufany, gdy Codex o to zapyta; potwierdź przez `codex debug prompt-input`
W klonie na Windowsie `CLAUDE.md` zawiera tylko tekst `AGENTS.md`	Zacommitowany symlink jest wypakowywany jako plik tekstowy, jeśli `core.symlinks` jest wyłączone	Zastąp symlink importem `@AGENTS.md`
Agent stosuje regułę niekonsekwentnie	Dwa pliki sobie przeczą, a model może wybrać dowolny	Uruchom prompt audytu rozjazdów albo `/doctor prompt-audit` w Claude Code i zostaw jedno źródło
Agent uruchomił polecenie, którego plik zabrania	Pliki instrukcji sterują modelem; nie są granicą bezpieczeństwa	Przenieś granicę do reguły deny, hooka albo CI, a zdanie w pliku zostaw tylko jako wyjaśnienie
W pliku reguł pojawił się token dostępu	Ktoś zacommitował osobistą notatkę	Najpierw unieważnij token, potem usuń go z historii; sekrety trzymaj w zmiennych środowiskowych

Dokąd dalej z kontekstem repozytorium

Przycinanie CLAUDE.md i AGENTS.md Przycinaj pliki kontekstu metodą ablacji i zostaw tylko linie, które zmieniają zachowanie.

Pamięć Claude Code w szczegółach Importy, reguły zawężone do ścieżek, auto memory i sposób wczytywania każdego z nich.

AGENTS.md w Codexie Pliki globalne i projektowe oraz sprawdzanie, co się wczytało, przez codex debug prompt-input.

Reguły projektu w Cursorze Typy reguł w Cursorze i sposób ich zawężania.

Jedno źródło reguł dla każdego agenta Generuj pliki każdego narzędzia z jednego źródła przez rulesync lub Ruler i blokuj rozjazdy w CI.

Wspólne reguły agentów w zespole Własność, przegląd i wdrożenie jednego rdzenia w wielu repozytoriach.

Q6 · Skille agentów Wynieś procedury wieloetapowe z zawsze wczytywanego kontekstu.

Q12 · Hooki agentów Wymuszaj niezmienniki, które pliki instrukcji mogą tylko opisać.