Wspólne reguły agentów — jeden rdzeń, przetestowane adaptery

Wspólne reguły agentów to jeden wersjonowany rdzeń instrukcji (główny plik AGENTS.md), najcieńszy adapter dla każdego narzędzia, dzięki któremu Claude Code, Codex i Cursor go wczytują, oraz test dowodzący, że każde narzędzie to zrobiło. Reguły sterują modelem; wszystko, co nie może się zdarzyć, należy do uprawnień, sandboxa, CI i ochrony gałęzi.

Twoje repozytorium ma 400-linijkowy CLAUDE.md napisany w marcu, AGENTS.md dodany w lipcu przez osoby pracujące w Codexie i regułę Cursora, która nadal mówi npm test, choć zespół dawno przeszedł na pnpm. Trzy agenty czytają trzy wersje prawdy i nikt nie potrafi powiedzieć, którą wczytała dana sesja. Ta strona jest dla tech leada, który odpowiada za wspólny harness, i dla CTO odpowiadającego na pytanie 5 w CTO Scorecard.

Co daje przetestowany zestaw wspólnych reguł

Układ plików i szablon rdzenia AGENTS.md, który możesz zacommitować jeszcze dziś.
Adapter, którego potrzebuje każde narzędzie, wynikający z tego, jak wyszukuje pliki instrukcji (sprawdzone 2026-09-26 na Claude Code 2.1.283 i Codex 0.157.1).
Spisaną tabelę pierwszeństwa, która rozstrzyga konflikty regułą, a nie kolejnością wczytywania.
Deterministyczną kontrolę w CI i sondę w świeżej sesji, które dowodzą, że każdy agent wczytał reguły, bez czytania transkryptów.
Tryby awarii, w których agent po cichu ignoruje reguły, i sposób wyjścia z każdego z nich.

Jak CTO Scorecard ocenia wspólne reguły?

Pytanie 5 brzmi: „Czy zespół ma wspólne reguły dla agentów (CLAUDE.md / AGENTS.md / managed policy)?”. Uczciwie umieść zespół w tabeli, a potem domknij lukę do następnego wiersza.

Punkty	Odpowiedź	Dowód, o który pyta recenzent
0	Każdy ma własne, brak współdzielenia	brak
1	„Polecany” `CLAUDE.md` w README	fragment do skopiowania, bez egzekwowania
2	`CLAUDE.md`/`AGENTS.md` w każdym repo, zacommitowany do `main`	plik istnieje; nikt nie wie, czy każde narzędzie go wczytuje
3	Wersjonowany wspólny rdzeń z przetestowanymi adapterami, właścicielami, pierwszeństwem, review zmian i zewnętrznym egzekwowaniem twardych wymagań	wpis w `CODEOWNERS`, kontrola w CI opisana niżej, wyniki sondy dla każdego narzędzia, lista łącząca każdą twardą regułę z jej kontrolą

Przejście z 2 na 3 to niemal wyłącznie weryfikacja. Sam plik jest najłatwiejszą częścią.

Oddziel trwałą prawdę od adapterów narzędzi

Każda warstwa ma jedno zadanie. Jeśli zdanie pasuje do dwóch warstw, należy do niższej.

Warstwa	Zawiera	Gdzie leży
Wspólny rdzeń	mapa repozytorium, komendy, definition of done, chronione ścieżki, bramki ludzkie, właściciele	główny `AGENTS.md`
Zakres katalogu	reguły jednego pakietu, serwisu, języka albo obszaru ryzyka	`services/billing/AGENTS.md` i podobne
Adapter narzędzia	klej do wyszukiwania plików i naprawdę specyficzne zachowania narzędzia, nic więcej	`CLAUDE.md`, reguła projektu w Cursorze
Zewnętrzne egzekwowanie	to, co musi zachodzić nawet wtedy, gdy model zignoruje wszystkie pliki powyżej	sandbox, reguły uprawnień, CI, ochrona gałęzi, zatwierdzanie wdrożeń

Rdzeń trafia do AGENTS.md, bo w tym formacie spotykają się narzędzia: to otwarty format rozwijany przez Agentic AI Foundation w ramach Linux Foundation, który według jego strony jest „używany przez ponad 60 tys. projektów open source” (agents.md, wrzesień 2026). Jak pisać samą treść (co umieścić, a co pominąć), opisuje strona AGENTS.md i CLAUDE.md: zwięzły kontekst repozytorium.

Układ, który sprawdza się w monorepo:

AGENTS.md                    # wspólny rdzeń, cel: poniżej 200 linii
CLAUDE.md                    # adapter: "@AGENTS.md" + linie tylko dla Claude
services/billing/AGENTS.md   # zakres katalogu
services/billing/CLAUDE.md   # adapter: "@AGENTS.md"
.claude/rules/               # opcjonalne reguły Claude z zakresem ścieżek (frontmatter paths:)
.github/CODEOWNERS           # pliki reguł należą do właściciela harnessu
scripts/check-agent-rules.sh # deterministyczna kontrola w CI (niżej)
tests/agent-rules/probe.sh   # sonda w świeżej sesji (niżej)

Szablon wspólnego rdzenia do dostosowania. Treść zostaje po angielsku, bo agenty i sondy porównują ją dosłownie:

Rules version: 2026-09-26.1

## Commands
- Install: `pnpm install --frozen-lockfile`
- Unit tests: `pnpm test`
- Types and lint: `pnpm typecheck && pnpm lint`

## Definition of done
- Tests, types and lint pass locally before you open a pull request.
- New behaviour has a test that fails without the change.

## Protected paths (ask a human first)
- `services/billing/migrations/`
- `infra/` and anything that changes production access

## Human gates
- Merging to `main` and deploying are human decisions. Never push to `main`.

## Precedence
- A directory `AGENTS.md` may add constraints. It may not relax a rule in this file.
- If two rules conflict, stop and ask; do not pick one.

## Owners
- This file: @acme/agent-platform. Change it through a pull request.

Linia Rules version: to kanarek: każdy test na tej stronie sprawdza, czy agent potrafi ją zacytować.

Jak każdy agent wyszukuje pliki instrukcji

To na etapie wyszukiwania wspólne reguły się sypią, a każde narzędzie robi to inaczej, więc i adaptery się różnią.

Sprawdzone 2026-09-26 w dokumentacji pamięci i na Claude Code 2.1.283.

Start: Claude Code wczytuje CLAUDE.md, .claude/CLAUDE.md i CLAUDE.local.md z katalogu roboczego i z każdego katalogu powyżej. Pliki z podkatalogów wczytuje wtedy, gdy czyta tam pliki. Wszystko jest sklejane, od korzenia w dół; nic niczego nie nadpisuje.
AGENTS.md: czytany bezpośrednio od v2.1.277 (v2.1.281 na Bedrock, Google Cloud, Foundry, bramkach LLM i w sesjach z wyłączoną telemetrią), domyślnie tylko wtedy, gdy w katalogu roboczym ani powyżej nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Na dzień 2026-09-26 dotyczy to wyłącznie kanału latest; kanał stable to 2.1.274 i czyta tylko pliki CLAUDE.md.
Czyta też, tylko Claude Code: .claude/AGENTS.md w katalogu roboczym i powyżej. Codex go ignoruje, więc to kolejny sposób, by oba narzędzia się rozjechały; kontrola w CI opisana niżej na nim pada.
Nie czyta: AGENTS.override.md, AGENTS.local.md ani niczego w katalogu .agents/.
Adapter: obok każdego AGENTS.md plik CLAUDE.md, którego pierwsza linia to @AGENTS.md. Import działa w każdej wersji i każdym kanale, a wersja, która czyta AGENTS.md także bezpośrednio, nigdy nie wczyta go dwa razy.
Alternatywa: w /config ustaw Project instructions na claude-md-and-agents-md, a Claude Code wczyta CLAUDE.md i AGENTS.md razem, bez duplikatów. Ustawienie działa tylko w ustawieniach użytkownika albo zarządzanych, nigdy w ustawieniach projektu. Pozwala też połączyć CLAUDE.local.md z AGENTS.md; przy ustawieniu domyślnym CLAUDE.local.md liczy się jak CLAUDE.md i wyłącza AGENTS.md. Adapter z importem zostaw mimo to, bo działa w każdym kanale.

@AGENTS.md

## Claude Code only
- Use plan mode for changes under `services/billing/`.

Sprawdzenie: uruchom /context i potwierdź, że pliki są widoczne w sekcji Memory files; /memory otwiera wczytane pliki CLAUDE.md do edycji.

Sprawdzone 2026-09-26 w źródłach agents_md.rs i config_toml.rs z tagu rust-v0.157.1 oraz na zainstalowanym Codex 0.157.1.

Start: Codex znajduje korzeń projektu (najbliższy katalog z .git, konfigurowalne przez project_root_markers) i zbiera instrukcje od korzenia w dół do katalogu roboczego, zaczynając od korzenia. Nigdy nie wychodzi ponad korzeń.
W każdym katalogu: Codex bierze pierwszy istniejący plik z listy AGENTS.override.md, AGENTS.md, a potem nazwy z project_doc_fallback_filenames. Override zastępuje więc AGENTS.md danego katalogu, ale tylko dla Codexa.
Budżet: project_doc_max_bytes domyślnie ogranicza cały łańcuch do 32 KiB. Powyżej limitu Codex przycina treść, a najgłębsze pliki znikają pierwsze.
Zaufanie: od 0.150.0 projekt oznaczony jako niezaufany nie dostarcza AGENTS.md na poziomie projektu. Projekt, który nie ma jeszcze wpisu o zaufaniu, nadal go wczytuje.
Adapter: żaden. Codex czyta AGENTS.md natywnie.
Sprawdzenie: codex debug prompt-input wypisuje jako JSON wejście widoczne dla modelu, więc możesz wyszukać w nim kanarka bez uruchamiania zadania.

# Terminal, w katalogu, w którym inżynierowie uruchamiają Codexa
codex debug prompt-input "noop" | grep -c "Rules version: 2026-09-26.1"

Cursor stosuje instrukcje przez Rules (cursor.com/docs/rules, zweryfikowane 2026-08-28). W dniu 2026-09-26 serwis cursor.com był niedostępny z naszego środowiska weryfikacji, dlatego aktualny format plików reguł pozostaje tu niezweryfikowany, a to sonda poniżej rozstrzyga, czy Cursor potrzebuje reguły-wskaźnika.

Adapter: jeśli sonda z następnej sekcji pokaże, że twoja wersja wczytuje AGENTS.md, nie dodawaj nic. W przeciwnym razie dodaj jedną zawsze stosowaną regułę projektu, która kieruje agenta do AGENTS.md i zawiera tylko linie specyficzne dla Cursora, w formacie, który dziś podaje strona Rules.
Nie wklejaj rdzenia do reguły. To przez kopię linia npm test z przykładu na początku przetrwała migrację na pnpm.
Sprawdzenie: otwórz nowy czat Agenta i wklej prompt sondy z następnej sekcji. Reguła-wskaźnik zależy od tego, czy model zdecyduje się otworzyć AGENTS.md, więc powtarzaj sondę po każdej aktualizacji Cursora.

Spisz pierwszeństwo reguł

Ani Claude Code, ani Codex nie rozstrzygają konfliktów za ciebie. Oba sklejają pliki, a strona o pamięci Anthropic ostrzega, że przy dwóch sprzecznych regułach Claude może wybrać jedną arbitralnie. Pierwszeństwo jest więc regułą, którą piszesz, recenzujesz i testujesz, a nie kolejnością wczytywania, na którą liczysz.

Sytuacja	Co wygrywa	Jak to jest egzekwowane
Plik katalogu przeczy korzeniowi	reguła surowsza; katalog może dodawać ograniczenia, nigdy ich nie luzuje	zapisane w rdzeniu; audyt konfliktów w review
Istnieje `AGENTS.override.md`	Codex czyta go zamiast `AGENTS.md` z tego katalogu; Claude Code go ignoruje	nigdy nie jest commitowany; kontrola w CI na nim pada
Preferencje osobiste	`CLAUDE.local.md` albo pliki użytkownika, w `.gitignore`	plik osobisty nie osłabi twardej reguły, bo twarde reguły nie żyją w plikach
Reguły dla całej organizacji	instrukcje zarządzane wdrażane przez IT, np. zarządzany `CLAUDE.md` w Claude Code, który wczytuje się przed plikami projektu	polityka zarządzana dla wszystkich agentów
Reguła i kontrola sobie przeczą	kontrola; popraw brzmienie reguły	mapa twardych reguł na kontrole, przeglądana co kwartał

Wdróż wspólne reguły bez przepisywania wszystkiego naraz

Zinwentaryzuj każde źródło. Wypisz każdy AGENTS.md, CLAUDE.md, plik w .claude/rules/, regułę Cursora i osobiste ustawienia domyślne w użyciu, z zakresem i właścicielem. Czytanie zrobi za ciebie pierwszy prompt poniżej; po stronie Claude sprzeczne pliki CLAUDE.md i AGENTS.md wskaże też /doctor prompt-audit (v2.1.283, kanał latest).
Wybierz kanoniczny rdzeń. Przenieś trwałe reguły do głównego AGENTS.md, trzymaj go poniżej 200 linii (tyle na plik zaleca strona o pamięci Anthropic) i linkuj do dokumentacji architektury zamiast jej wklejać. O tym, co zasługuje na linię, zdecyduj protokołem ablacji.
Zastąp kopie adapterami. Każdy CLAUDE.md staje się @AGENTS.md plus linie tylko dla Claude. Usuń zduplikowany tekst w tym samym pull requeście, żeby nigdy nie istniały dwie żywe kopie.
Połącz twarde reguły z kontrolami. Dla każdego „nigdy” w rdzeniu wskaż kontrolę, która go egzekwuje: regułę uprawnień, tryb sandboxa, job w CI, ochronę gałęzi. Reguła bez kontroli jest radą i rdzeń powinien to mówić wprost.
Dodaj kontrolę w CI i sondę. Obie są niżej. Kontrola uruchamia się przy każdym pull requeście; sonda przy zmianie reguł i po aktualizacji narzędzi.
Przypisz własność. Obejmij pliki reguł wpisem w CODEOWNERS i wymagaj, żeby każda zmiana reguły wskazywała swój powód: incydent, komentarz z review, problem przy onboardingu.

List every file in this repository that gives a coding agent instructions:
AGENTS.md, AGENTS.override.md, CLAUDE.md, CLAUDE.local.md, .claude/rules/**,
Cursor project rules, and any SessionStart hook that prints instructions.
For each file give: path, which tools load it (Claude Code, Codex, Cursor),
lines and bytes, owner from CODEOWNERS. Then list every rule that appears in
more than one file, every pair of rules that contradict each other, and every
"never" or "always" rule with no enforcing control (permission rule, sandbox,
CI job, branch protection). Output three tables. Do not edit any file.

Refactor this repository's agent instructions into one shared core:
1. Merge durable rules (commands, definition of done, protected paths, human
   gates, owners) into the root AGENTS.md, under 200 lines. Keep the first
   "Rules version:" line and bump its suffix.
2. Replace each CLAUDE.md with "@AGENTS.md" on line 1, followed only by rules
   that apply to Claude Code alone.
3. Keep directory-specific rules in that directory's AGENTS.md, each with a
   CLAUDE.md adapter next to it.
4. Delete every duplicated sentence; do not leave two copies of any rule.
Show the diff and a table mapping each old rule to its new location or to
"deleted: duplicate of <location>". Do not change any file outside these.

Answer only from the project instructions you were given at session start.
Do not open any file. Reply in exactly four lines:
1. The "Rules version:" line, verbatim.
2. The command that runs the unit tests.
3. May you edit services/billing/migrations/ without asking? Yes or no, and why.
4. Which rule wins if services/billing/AGENTS.md contradicts the root AGENTS.md?

Udowodnij, że każdy agent wczytał reguły, bez czytania transkryptów

Weryfikacja ma dwie warstwy. Warstwa deterministyczna sprawdza pliki i nie potrzebuje modelu. Warstwa sondy pyta każdego agenta, co wczytał, i porównuje odpowiedź z kanarkiem.

Warstwa 1: kontrola w CI przy każdym pull requeście. Pada, gdy brakuje adaptera, gdy ktoś zacommitował override działający tylko w Codexie lub .claude/AGENTS.md czytany tylko przez Claude Code albo gdy łańcuch któregoś katalogu przekracza domyślny budżet Codexa. Przetestowane w bashu 2026-09-26.

#!/usr/bin/env bash
# scripts/check-agent-rules.sh: deterministic, no model calls. Run from the repository root.
set -euo pipefail
fail=0
files=$(find . -name 'AGENTS*.md' -not -path './node_modules/*' -not -path './.git/*')

for f in $files; do
  d=$(dirname "$f")
  case "$f" in
    */AGENTS.override.md) echo "$f: Codex-only override is committed"; fail=1; continue ;;
    */.claude/AGENTS.md) echo "$f: read by Claude Code only; merge it into AGENTS.md"; fail=1; continue ;;
    */AGENTS.md) ;;
    *) continue ;;
  esac
  # Claude Code adapter: a CLAUDE.md next to every AGENTS.md whose first line imports it
  if [ "$(head -n 1 "$d/CLAUDE.md" 2>/dev/null)" != "@AGENTS.md" ]; then
    echo "$d: needs a CLAUDE.md whose first line is @AGENTS.md"; fail=1
  fi
  # Codex budget: every AGENTS.md from the root down to this directory
  total=0; p="$d"
  while :; do
    [ -f "$p/AGENTS.md" ] && total=$(( total + $(wc -c < "$p/AGENTS.md") ))
    [ "$p" = "." ] && break
    p=$(dirname "$p")
  done
  if [ "$total" -gt 32768 ]; then
    echo "$d: AGENTS.md chain is $total bytes, over Codex's 32 KiB default"; fail=1
  fi
done
exit "$fail"

Warstwa 2: sonda w świeżej sesji dla każdego narzędzia. Uruchamiaj ją przy zmianie pliku reguł i po każdej aktualizacji narzędzia. O wyniku decyduje wyszukanie kanarka; pozostałe trzy odpowiedzi właściciel tylko przegląda.

#!/usr/bin/env bash
# tests/agent-rules/probe.sh: run from the repository root on a trusted checkout
set -euo pipefail
CANARY=$(grep -m1 '^Rules version:' AGENTS.md)
PROBE=$(cat tests/agent-rules/probe-prompt.txt)   # the probe prompt above

codex debug prompt-input "noop" | grep -qF "$CANARY" || { echo "Codex: core not in prompt"; exit 1; }
claude -p "$PROBE" --permission-mode plan > claude.out
codex exec --sandbox read-only --ephemeral -o codex.out "$PROBE"
for out in claude.out codex.out; do
  grep -qF "$CANARY" "$out" || { echo "$out: canary missing"; exit 1; }
done

Cursora nie ma w skrypcie, bo na dzień 2026-09-26 nie dało się zweryfikować jego CLI; wklej tę samą sondę do nowego czatu Agenta i zapisz wynik w pull requeście.

Akceptacja. Właściciel harnessu z CODEOWNERS zatwierdza każdą zmianę reguł. Pull request zawiera wynik kontroli w CI, wynik sondy dla każdego narzędzia oraz incydent albo komentarz z review, który wywołał zmianę. Recenzent sprawdza te artefakty, a nie pełne transkrypty. Te same trzy elementy przedstawiasz, odpowiadając na pytanie 5.

Co się psuje, gdy zespół współdzieli reguły agentów?

Claude Code ignoruje AGENTS.md. Objaw: sonda w Claude Code nie zwraca kanarka, a w Codexie przechodzi. Przyczyna: ktoś ma CLAUDE.md albo CLAUDE.local.md w katalogu roboczym lub powyżej, korzysta z kanału stable (2.1.274 na dzień 2026-09-26) albo, w niektórych przypadkach, jest w pierwszej sesji po aktualizacji z 2.1.276 lub starszej. Wyjście: dodaj adapter @AGENTS.md; działa we wszystkich trzech przypadkach.

Codex gubi reguły pakietu. Objaw: reguła z services/billing/AGENTS.md działa, gdy Codex startuje w services/billing/, i jest ignorowana, gdy startuje w korzeniu. Przyczyna: Codex buduje łańcuch startowy tylko od korzenia w dół do katalogu roboczego. Wyjście: przenieś reguły potrzebne w każdej sesji do rdzenia i uruchamiaj Codexa w pakiecie, który zmieniasz.

Codex przycina łańcuch. Objaw: kanarek jest, ale w codex debug prompt-input brakuje reguły katalogu. Przyczyna: łańcuch przekroczył 32 KiB i Codex go przyciął, zapisując jedynie ostrzeżenie w logu. Wyjście: odchudź rdzeń, zaczynając od tego, czego nie broni protokół ablacji. project_doc_max_bytes podnoś dopiero po cięciu i tylko ze spisanym uzasadnieniem.

Codex i Claude Code różnią się w jednym katalogu. Objaw: zachowanie zależy od narzędzia tylko w jednym katalogu. Przyczyna: AGENTS.override.md, który Codex czyta, a Claude Code ignoruje. Wyjście: usuń go, przenieś treść do AGENTS.md i zostaw kontrolę w CI, która na nim pada.

Codex nie wczytuje żadnych reguł projektu. Objaw: pusty blok instrukcji w codex debug prompt-input na jednej maszynie. Przyczyna: projekt jest tam oznaczony jako niezaufany, bo ktoś odrzucił pytanie o zaufanie albo ~/.codex/config.toml ustawia dla niego trust_level = "untrusted"; od 0.150.0 niezaufany projekt nie dostarcza AGENTS.md na poziomie projektu. Wyjście: oznacz projekt jako zaufany na tej maszynie i zostaw sprawdzanie kanarka w teście onboardingowym.

Rdzeń wczytuje się dwa razy. Objaw: kontekst rośnie, a sonda w świeżej sesji (albo prośba, by sesja zacytowała swoje instrukcje) pokazuje rdzeń dwa razy: raz z wyjścia hooka SessionStart i raz z wczytanego pliku. Przyczyna: hook SessionStart, który wypisuje AGENTS.md, działa dalej, choć Claude Code już sam czyta ten plik. Wyjście: usuń hook; import @AGENTS.md nigdy nie dubluje treści.

Reguła traktowana jak zabezpieczenie. Objaw: agent czyta .env, choć rdzeń mówi „never read .env”. Przyczyna: instrukcje sterują modelem, ale go nie wiążą. Wyjście: egzekwuj to regułami uprawnień albo sandboxem, recenzowanymi jak kod zgodnie z zasadami zarządzania wspólnymi hookami, a zdanie w rdzeniu zostaw tylko jako wyjaśnienie kontroli.

Polityka przez duplikację wraca. Objaw: prompt inwentaryzacyjny znajduje tę samą regułę w trzech plikach. Przyczyna: komenda migracji albo życzliwy inżynier skopiował tekst zamiast go zaimportować. Zarówno Claude Code, jak i Codex mają /import do przenoszenia konfiguracji z innego narzędzia; uruchom go raz przy migracji, potem puść prompt inwentaryzacyjny i usuń kopie.

Dokąd dalej po wspólnych regułach agentów

Przed tą stroną: przygotuj kod na pracę z agentami i przeczytaj, jak zespoły współdzielą kontekst i reguły. Po niej spakuj procedury, które nie powinny wczytywać się w każdej sesji, jako skille, a twarde wymagania przenieś do recenzowanych kontroli.

Q6 · Wspólne skille Spakuj przetestowane procedury, które mają się wczytywać na żądanie, a nie w każdej sesji.

Q18 · Zarządzanie wspólnymi hookami Recenzuj i testuj kontrole w runtime, które egzekwują twarde reguły.

Polityka zarządzana dla wszystkich agentów Egzekwuj jedną politykę organizacji, której pliki projektu nie osłabią.

Backlog dla agentów Następny krok ścieżki tech leada: zadania, które agent potrafi skończyć i udowodnić.