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

URL: https://developertoolkit.ai/pl/workflows/context/agents-md-context/
Description: Napisz jeden zwięzły kontrakt AGENTS.md, podepnij Claude Code, Codexa i Cursora bez duplikacji i zweryfikuj, jakie reguły wczytał każdy agent.

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.

## 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`)](/pl/ecosystem/skills/) | Stopniowe ujawnianie: ładuje się na żądanie |
| Twarde zakazy, które muszą obowiązywać zawsze | [Hooki](/pl/workflows/harness/agent-hooks/), [uprawnienia i sandboksy](/pl/workflows/harness/permissions-and-sandboxing/), CI | Proza podpowiada; kod i sandboksy egzekwują |
| Stan bieżącego zadania i ustalenia projektowe | `intent.md`, `spec.md`, `plan.md` ([łańcuch artefaktów](/pl/method/lifecycle/artifact-chain/)) | 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:

```md title="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

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

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:

```md title="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](https://code.claude.com/docs) i przewodniku [system pamięci Claude Code](/pl/claude-code/build/memory-system/).

**Codex**

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.md` dopiero po oznaczeniu przestrzeni roboczej jako zaufanej.
- **Limit bajtów:** zbyt obszerny plik główny po cichu ucina głębsze, najbardziej konkretne pliki `AGENTS.md` w 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](https://developers.openai.com/codex) oraz w [optymalizacji AGENTS.md dla Codexa](/pl/codex/build/agents-md-optimization/).

**Cursor**

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](https://cursor.com/docs) oraz [reguły projektu w Cursorze](/pl/cursor-ide/quick-start/project-rules/).

## 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](https://agentskills.io).

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.

**Prompt do skopiowania: szkic zweryfikowanego AGENTS.md**

```text
Draft a root AGENTS.md for this repository using only verified evidence:
1. Read the build manifest, CI workflows, README, and top two directory levels.
2. Run each proposed build, typecheck, lint, and test command once; drop any
   command that fails and explain why.
3. Structure strictly into: Layout, Commands, Boundaries, Done means. Keep it
   under 60 lines.
4. Omit anything derivable from source files or already enforced by linters.
Show the draft and each command's exit code before writing any file.
```

## 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](/pl/reference/harness-audit-checks/)).
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.

**Prompt do skopiowania: sonda wykrywania i stosowania reguł**

```text
Without searching the repository, answer from your loaded instructions only:
1. List the exact paths of the repository instruction files loaded for this session.
2. Quote the exact commands required for unit tests, typecheck, and lint.
3. List every forbidden action and boundary stated in your instructions.
4. Open one file in `src/billing/` (read-only) and state which scoped conventions
   apply to it and how you would represent 19.99 EUR in code.
If any item is missing from your loaded instructions, state "none loaded".
```

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](/pl/workflows/context/pruning-context-files/).

## 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](/pl/workflows/harness/permissions-and-sandboxing/) lub [hooka `PreToolUse`](/pl/workflows/harness/agent-hooks/) |
| 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

Aktualne reguły wykrywania plików, pola frontmattera i polecenia inspekcji pamięci sprawdzaj w dokumentacji dostawców: [Claude Code](https://code.claude.com/docs), [OpenAI Codex](https://developers.openai.com/codex), [Cursor](https://cursor.com/docs) oraz [Agent Skills](https://agentskills.io).

- [Przycinanie plików kontekstu](/pl/workflows/context/pruning-context-files/) — Skróć przerośnięte instrukcje metodą ablacji i zostaw wyłącznie linie potwierdzone błędami.
- [Okna kontekstu i limity tokenów](/pl/workflows/context/context-windows/) — Utrzymaj kluczowe ograniczenia mimo kompaktowania i wieloetapowych zadań.
- [Współpraca zespołu i wspólne reguły](/pl/teams/adopt/team-collaboration/) — Zorganizuj własność, przegląd i wdrażanie jednego kontraktu w wielu repozytoriach.
- [Hooki agentów](/pl/workflows/harness/agent-hooks/) — Przenieś nienegocjowalne niezmienniki z prozy do deterministycznych skryptów.
