Przejdź do głównej zawartości

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

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 miejsceUzasadnienie
Układ katalogów, dokładne komendy weryfikacji, granice, definicja „gotowe”Główny AGENTS.mdPotrzebne 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ć zawszeHooki, uprawnienia i sandboksy, CIProza podpowiada; kod i sandboksy egzekwują
Stan bieżącego zadania i ustalenia projektoweintent.md, spec.md, plan.md (łańcuch artefaktów)Wygasa po wdrożeniu zadania
Osobiste preferencje pracyKonfiguracja użytkownika lub lokalny plik w .gitignoreDotyczy jednej osoby, nigdy całego zespołu

Zwarty kontrakt główny mieści się na jednym ekranie:

AGENTS.md
# 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:

CLAUDE.md
@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.

Zbuduj i podepnij kontekst repozytorium w pięciu krokach

Dział zatytułowany „Zbuduj i podepnij kontekst repozytorium w pięciu krokach”
  1. 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.

  2. Wytnij wszystko, co wynika z kodu. Usuń opisy frameworków, listy katalogów widoczne z ls i zasady formatowania pilnowane przez linter. Zostaw komendy, granice i nieoczywiste niezmienniki.

  3. Wynieś reguły warunkowe poza plik główny. Przenieś konwencje katalogowe do zagnieżdżonych AGENTS.md lub reguł ścieżkowych (.claude/rules/, .cursor/rules/*.mdc), a wieloetapowe procedury do Agent Skills.

  4. Podepnij cienkie adaptery. Dodaj import @AGENTS.md w CLAUDE.md, zatwierdź zaufanie projektu w Codexie i upewnij się, że Cursor czyta AGENTS.md bez dublujących reguł zawsze aktywnych.

  5. Przypisz własność w CODEOWNERS. Obejmij AGENTS.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:

  1. Uruchom @wondelai/harness-audit. Wykonaj npx @wondelai/harness-audit --lang pl lokalnie i w CI. Stanowisko 1 (Intencja) sprawdza istnienie AGENTS.md, delegację CLAUDE.md przez @AGENTS.md zamiast duplikacji, budżet długości (≤ 150 linii) oraz obecność reguł ścieżkowych (referencja kontroli harness-audit).
  2. 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).
  3. 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.

ObjawPrzyczynaNaprawa
Claude Code pomija AGENTS.md po dodaniu lokalnych notatekLokalny CLAUDE.md lub CLAUDE.local.md wyłącza domyślne sięganie po AGENTS.mdUtrzymuj 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 plikiSkróć plik główny, a procedury przenieś do skilli SKILL.md
Codex nie wczytuje żadnych instrukcji projektuPrzestrzeń robocza nie została oznaczona jako zaufanaOznacz projekt jako zaufany w Codexie i powtórz sondę wykrywania
Agenci stosują regułę niespójnie między sesjamiDwa 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 proziePliki kontekstu kierują uwagą modelu, ale nigdy nie stanowią granicy bezpieczeństwaPrzenieś zakaz do uprawnień i sandboksów lub hooka PreToolUse
W zacommitowanym pliku reguł znalazł się sekretOsobista notatka trafiła do współdzielonego plikuNatychmiast zrotuj poświadczenie, usuń je z historii i wymuś skanowanie sekretów

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.

wcale bardzo

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.