AGENTS.md i CLAUDE.md — zwięzły kontekst repozytorium
ENKontekst repozytorium dla agentów kodujących to jeden zwięzły, wersjonowany kontrakt AGENTS.md, który opisuje układ projektu, dokładne komendy budowania i weryfikacji, jawne granice oraz dowód wymagany przed uznaniem zadania za gotowe. Programiści i tech leadzi stosują tę architekturę, aby podpiąć Claude Code, Codexa i Cursora do jednego źródła prawdy i wyeliminować rozjazdy między narzędziami.
W poprzednim sprincie zespół zmienił komendę testów jednostkowych z npm test na pnpm test:unit. Ktoś poprawił CLAUDE.md, ale zapomniał o AGENTS.md. Dziś sesja Codexa uruchomiła starą komendę, trafiła na błąd i „naprawiła” go, przerabiając skrypt testowy. Zduplikowane pliki instrukcji gwarantują ciche rozjazdy.
Co trafia do głównego AGENTS.md, a co poza niego
Dział zatytułowany „Co trafia do głównego AGENTS.md, a co poza niego”Wpisuj linię do zawsze ładowanego pliku głównego wyłącznie wtedy, gdy dotyczy każdego zadania w repozytorium i agent nie wywnioskuje jej z kodu ani manifestów. Trzymaj plik poniżej 150 linii — najlepiej w przedziale 40–80 linii — aby każda reguła zachowała siłę uwagi w długich sesjach. Resztę kieruj do warstw ładowanych na żądanie lub egzekwowanych deterministycznie.
| Treść | Właściwe miejsce | Uzasadnienie |
|---|---|---|
| Układ katalogów, dokładne komendy weryfikacji, granice, definicja „gotowe” | Główny AGENTS.md | Potrzebne w każdej sesji, niezależnie od narzędzia |
Konwencje jednego katalogu (src/billing/, infra/) | Zagnieżdżony AGENTS.md, .claude/rules/*.md lub .cursor/rules/*.mdc | Ładuje się tylko przy pracy na pasujących plikach |
| Procedury wieloetapowe (wydanie, migracja, incydent) | Agent Skill (SKILL.md) | Stopniowe ujawnianie: ładuje się na żądanie |
| Twarde zakazy, które muszą obowiązywać zawsze | Hooki, uprawnienia i sandboksy, CI | Proza podpowiada; kod i sandboksy egzekwują |
| Stan bieżącego zadania i ustalenia projektowe | intent.md, spec.md, plan.md (łańcuch artefaktów) | Wygasa po wdrożeniu zadania |
| Osobiste preferencje pracy | Konfiguracja użytkownika lub lokalny plik w .gitignore | Dotyczy jednej osoby, nigdy całego zespołu |
Zwarty kontrakt główny mieści się na jednym ekranie:
# Repository contract<!-- Owner: @platform-team · review on toolchain or model changes -->
## Layout- Web app: `apps/web/` · API: `apps/api/` · Shared packages: `packages/`.- Database migrations live in `apps/api/migrations/`; never edit merged migrations.
## Commands (run from repository root)- Install: `pnpm install --frozen-lockfile`- Fast check: `pnpm check:changed`- Full check: `pnpm typecheck && pnpm lint && pnpm test:unit`
## Boundaries- Never run commands targeting production or read `.env.production`.- Stop and propose an ADR before adding a runtime dependency or changing exported APIs.
## Done means- Full check exits 0; paste exact commands and exit codes in the PR summary.- List every changed file and flag anything you could not verify locally.Każda linia wskazuje konkretną ścieżkę, komendę albo warunek możliwy do sprawdzenia. Ogólniki typu „pisz czysty kod” lub „testuj dokładnie” marnują tokeny, bo ani agent, ani recenzent nie potrafią rozstrzygnąć, czy zostały spełnione.
Jak Claude Code, Codex i Cursor czytają jedno źródło prawdy
Dział zatytułowany „Jak Claude Code, Codex i Cursor czytają jedno źródło prawdy”Trzymaj całą politykę niezależną od narzędzia w AGENTS.md, a każdemu narzędziu daj możliwie najcieńszy adapter. Unikaj zacommitowanych symlinków w zespołach z Windows; importy tekstowe i natywne wczytywanie działają przenośnie.
Claude Code czyta CLAUDE.md hierarchicznie przy starcie i ładuje pliki .claude/rules/*.md ograniczone polem paths we frontmatterze, gdy dotyka pasujących ścieżek. Aby zapewnić przewidywalne ładowanie w każdym środowisku bez duplikowania treści, wskaż AGENTS.md importem @ w CLAUDE.md, a w samym CLAUDE.md zostaw wyłącznie dyrektywy swoiste dla Claude’a:
@AGENTS.md
## Claude Code notes- Enter plan mode before modifying `apps/api/migrations/`.Wspólne zasady katalogowe trzymaj w zagnieżdżonym AGENTS.md (z jednolinijkowym CLAUDE.md zawierającym @AGENTS.md obok, jeśli potrzebujesz pewnego załadowania), a .claude/rules/<temat>.md z globami paths rezerwuj na konwencje specyficzne dla Claude Code. Pamiętaj, że importy @ porządkują strukturę, ale rozwijają się przy starcie sesji, więc trzymaj importowane pliki krótkie. Szczegóły mechaniki sprawdzaj w dokumentacji Claude Code i przewodniku system pamięci Claude Code.
Codex czyta AGENTS.md natywnie bez żadnego adaptera. Przechodzi od katalogu głównego projektu (zwykle najbliższego .git) w dół do bieżącego katalogu roboczego, wybierając AGENTS.override.md, jeśli istnieje, albo AGENTS.md, aż do skonfigurowanego limitu bajtów.
Dwie zasady architektoniczne mają tu kluczowe znaczenie:
- Zaufanie do projektu: Codex wczytuje projektowe pliki
AGENTS.mddopiero po oznaczeniu przestrzeni roboczej jako zaufanej. - Limit bajtów: zbyt obszerny plik główny po cichu ucina głębsze, najbardziej konkretne pliki
AGENTS.mdw podkatalogach.
Lokalne reguły zapisuj w zagnieżdżonych plikach AGENTS.md, a bieżące reguły wyszukiwania i konfiguracji sprawdzaj w dokumentacji OpenAI Codex oraz w optymalizacji AGENTS.md dla Codexa.
Cursor obsługuje AGENTS.md w katalogu głównym i podkatalogach równolegle z regułami projektu w .cursor/rules/*.mdc. Używaj plików .mdc z polami frontmattera description, globs i alwaysApply do reguł uruchamianych automatycznie dla konkretnych wzorców plików i nie kopiuj treści AGENTS.md do reguł stosowanych zawsze.
Aktualną składnię i kolejność reguł opisują dokumentacja Cursora oraz reguły projektu w Cursorze.
Zbuduj i podepnij kontekst repozytorium w pięciu krokach
Dział zatytułowany „Zbuduj i podepnij kontekst repozytorium w pięciu krokach”-
Szkicuj z dowodów w repozytorium. Niech agent przeczyta manifesty budowania, workflowy CI i dwa górne poziomy katalogów, a następnie uruchomi każdą proponowaną komendę i zostawi tylko te, które zwracają kod 0.
-
Wytnij wszystko, co wynika z kodu. Usuń opisy frameworków, listy katalogów widoczne z
lsi zasady formatowania pilnowane przez linter. Zostaw komendy, granice i nieoczywiste niezmienniki. -
Wynieś reguły warunkowe poza plik główny. Przenieś konwencje katalogowe do zagnieżdżonych
AGENTS.mdlub reguł ścieżkowych (.claude/rules/,.cursor/rules/*.mdc), a wieloetapowe procedury do Agent Skills. -
Podepnij cienkie adaptery. Dodaj import
@AGENTS.mdwCLAUDE.md, zatwierdź zaufanie projektu w Codexie i upewnij się, że Cursor czytaAGENTS.mdbez dublujących reguł zawsze aktywnych. -
Przypisz własność w
CODEOWNERS. ObejmijAGENTS.md,CLAUDE.md,.claude/rules/i.cursor/rules/wymaganym przeglądem właścicieli kodu. Traktuj zmiany instrukcji jak zmiany konfiguracji CI.
Zweryfikuj, czy każdy agent wczytał i stosuje reguły
Dział zatytułowany „Zweryfikuj, czy każdy agent wczytał i stosuje reguły”Nigdy nie zakładaj, że zacommitowany plik dotarł do modelu. Połącz automatyczny audyt ze sprawdzeniem w świeżej sesji:
- Uruchom
@wondelai/harness-audit. Wykonajnpx @wondelai/harness-audit --lang pllokalnie i w CI. Stanowisko 1 (Intencja) sprawdza istnienieAGENTS.md, delegacjęCLAUDE.mdprzez@AGENTS.mdzamiast duplikacji, budżet długości (≤ 150 linii) oraz obecność reguł ścieżkowych (referencja kontroli harness-audit). - Sprawdź załadowany kontekst w narzędziu. Potwierdź listę załadowanych plików pamięci w inspektorze kontekstu Claude Code oraz zweryfikuj zmontowany prompt diagnostyką Codexa (bieżące polecenia podaje dokumentacja dostawców).
- Uruchom sondę zachowania po każdej zmianie. Wklej poniższy prompt w świeżej sesji po edycji instrukcji i dołącz wynik do opisu pull requesta.
W utrzymaniu stosuj zasadę dwóch powtórzeń: dopisuj nową linię dopiero wtedy, gdy ten sam błąd wystąpi w dwóch osobnych sesjach i da się go zapisać jako sprawdzalny warunek. Gdy plik zacznie puchnąć, przeprowadź protokół ablacji.
Kiedy AGENTS.md i CLAUDE.md zawodzą po cichu
Dział zatytułowany „Kiedy AGENTS.md i CLAUDE.md zawodzą po cichu”| Objaw | Przyczyna | Naprawa |
|---|---|---|
Claude Code pomija AGENTS.md po dodaniu lokalnych notatek | Lokalny CLAUDE.md lub CLAUDE.local.md wyłącza domyślne sięganie po AGENTS.md | Utrzymuj w repozytorium jawny import @AGENTS.md w CLAUDE.md |
| Codex przestrzega reguł głównych, ale ignoruje lokalne | Łączny rozmiar plików AGENTS.md przekroczył budżet bajtów i uciął głębsze pliki | Skróć plik główny, a procedury przenieś do skilli SKILL.md |
| Codex nie wczytuje żadnych instrukcji projektu | Przestrzeń robocza nie została oznaczona jako zaufana | Oznacz projekt jako zaufany w Codexie i powtórz sondę wykrywania |
| Agenci stosują regułę niespójnie między sesjami | Dwa pliki instrukcji przeczą sobie (AGENTS.md kontra .cursor/rules/ lub CLAUDE.md) | Audytuj wszystkie pliki instrukcji pod kątem duplikatów i trzymaj zasady wyłącznie w AGENTS.md |
| Agent wykonał polecenie zakazane w prozie | Pliki kontekstu kierują uwagą modelu, ale nigdy nie stanowią granicy bezpieczeństwa | Przenieś zakaz do uprawnień i sandboksów lub hooka PreToolUse |
| W zacommitowanym pliku reguł znalazł się sekret | Osobista notatka trafiła do współdzielonego pliku | Natychmiast zrotuj poświadczenie, usuń je z historii i wymuś skanowanie sekretów |
Oficjalna dokumentacja i kolejne kroki
Dział zatytułowany „Oficjalna dokumentacja i kolejne kroki”Aktualne reguły wykrywania plików, pola frontmattera i polecenia inspekcji pamięci sprawdzaj w dokumentacji dostawców: Claude Code, OpenAI Codex, Cursor oraz Agent Skills.
Czy ten artykuł Ci pomógł?
Jedno kliknięcie, bez logowania.
Co z tym zrobisz?
Jak się czytało?
Co przeszkadzało? Możesz zaznaczyć kilka
Twoja rola?
Dzięki. Czytam każdą odpowiedź. Michał Jaskólski
Pomógł Ci ten artykuł?
Każde to jedno kliknięcie. Zamknij, kiedy chcesz.
bez logowania
Najczęstsze pytania
Co powinno znaleźć się w pliku `AGENTS.md` lub `CLAUDE.md` w repozytorium?
Zwięzły plik kontekstu repozytorium określa układ projektu, dokładne komendy budowania i testów, jawne granice działania oraz dowód wymagany przed uznaniem pracy za skończoną.
Jak zweryfikować, które pliki instrukcji faktycznie wczytały Claude Code, Codex i Cursor?
Uruchom deterministyczny skan @wondelai/harness-audit, sprawdź załadowane pliki w inspektorze kontekstu każdego narzędzia i wykonaj sondę zachowania w świeżej sesji.