Współpraca zespołowa: wspólny kontekst i reguły

Współpraca zespołowa z agentami AI oznacza, że kontekstem, z którego pracuje każdy agent, zarządza zespół, a nie pojedynczy inżynier: jeden zatwierdzony rdzeń AGENTS.md z cienkimi adapterami, decyzje z code review zamienione w reguły i plany zapisane obok kodu. Wspólna reguła liczy się dopiero wtedy, gdy kontrola w CI albo sonda w świeżej sesji dowodzi, że każdy agent ją wczytał.

Dwóch inżynierów z twojego zespołu prosi tego samego ranka swoich agentów o nowy endpoint API. Jeden dostaje handler owinięty w wasz asyncHandler(), który rzuca AppError; drugi — gołą funkcję asynchroniczną rzucającą surowe błędy, w innym katalogu. Pull request kończy się 30 komentarzami o konwencjach i żaden nie dotyczy tego, czy endpoint działa. Ta strona jest dla tech leada, który chce, żeby konwencje żyły w repozytorium, gdzie czyta je każdy agent, a nie w komentarzach z review, których nikt nie czyta drugi raz.

Co zespół zyskuje na wspólnym kontekście agentów

Mapę tego, co należy do wspólnego kontekstu, co zostaje prywatne i gdzie każda z tych rzeczy mieszka w Claude Code, Codeksie i Cursorze.
Prompt, który szkicuje wspólny rdzeń na podstawie istniejącego kodu, więc nikt nie zaczyna od pustego pliku.
Pętlę z review do reguł, która każdą rozstrzygniętą dyskusję z review zamienia w regułę w tym samym pull requeście.
Konwencję zapisywania planów i notatek przekazania, dzięki której agent kolegi może podjąć rozpoczętą pracę.
Kontrolę zgodności, która pokazuje, czy diff trzyma się reguł, bez czytania każdej linii przez człowieka.
Sposoby, w jakie wspólny kontekst po cichu przestaje działać, i wyjście z każdego z nich.

Mechanika plików (kolejność wykrywania, adaptery, kontrola w CI, pierwszeństwo) jest opisana na stronie kanonicznej: wspólne reguły agentów — jeden rdzeń, przetestowane adaptery. Ta strona dotyczy codziennej pracy zespołu z tym kontekstem.

Co należy do wspólnego kontekstu, a co zostaje prywatne?

Wspólny kontekst to wszystko, czego agent kolegi potrzebuje, żeby napisać kod akceptowany przez waszych recenzentów. Prywatny kontekst to wszystko, co przyspiesza tylko jednego inżyniera. Mieszanie tych dwóch rzeczy to najczęstszy powód, dla którego wspólne reguły się psują: prywatny nawyk zatwierdzony w rdzeniu staje się regułą, na którą nikt się nie umawiał.

Kontekst	Wspólny czy prywatny	Gdzie mieszka	Kto go zmienia
Komendy, definicja ukończenia, chronione ścieżki, bramki ludzkie	Wspólny	główny `AGENTS.md`	właściciel harnessu, przez pull request
Konwencje jednego pakietu lub obszaru ryzyka	Wspólny	`AGENTS.md` w tym katalogu	właściciel pakietu
Plany, specyfikacje i notatki przekazania dla trwającej pracy	Wspólny	`docs/plans/` w repozytorium	właściciel zgłoszenia
Powtarzalne procedury (release, migracja, triage)	Wspólny, ładowany na żądanie	skill, zobacz wspólne skille	właściciel skilla
Nawyki edytorowe, rozwlekłość odpowiedzi, prywatne skróty	Prywatny	ustawienia na poziomie użytkownika, nigdy w repozytorium	każdy inżynier
To, czego agent nauczył się w sesjach jednego inżyniera	Prywatny, dopóki go nie awansujesz	pamięć narzędzia	awans do reguły przez pull request

Jak to przekłada się na pliki, zależy od narzędzia:

Wspólne: zatwierdzony CLAUDE.md, którego pierwsza linia to @AGENTS.md, a dalej tylko linie specyficzne dla Claude. Import działa w każdej wersji i każdym kanale wydań.
Bezpośrednie czytanie AGENTS.md: Claude Code sam czyta AGENTS.md, ale tylko wtedy, gdy projekt nie ma CLAUDE.md: od v2.1.277 w sesjach first-party i od v2.1.281 na Bedrock, Google Cloud, Foundry, w bramkach LLM i w sesjach z wyłączoną telemetrią (26.09.2026 obie wersje są dostępne tylko w kanale latest). Kanał stable (2.1.274) czyta tylko pliki CLAUDE.md, a przełącznik „Project instructions” w /config może wyłączyć bezpośrednie czytanie. Adapter obsługuje każdy z tych przypadków.
Prywatne: CLAUDE.local.md (trzymaj go w .gitignore) i auto memory, którą Claude gromadzi z twoich własnych sesji. Gdy auto memory nauczy się czegoś, czego potrzebuje cały zespół, wpisz to do AGENTS.md przez pull request, zamiast liczyć na to, że sesja każdego kolegi też się tego nauczy.
Sprawdzenie, co się wczytało: /context pokazuje pliki pamięci w sesji.

Wspólne: główny AGENTS.md oraz pliki AGENTS.md w katalogach. Codex zbiera je od korzenia projektu w dół do katalogu roboczego, zaczynając od korzenia, do limitu project_doc_max_bytes (domyślnie 32 KiB). /init szkicuje pierwszy AGENTS.md.
Nie zatwierdzaj AGENTS.override.md: Codex czyta go zamiast AGENTS.md z tego katalogu, a Claude Code go ignoruje, więc narzędzia zaczynają się rozjeżdżać.
Prywatne: pamięć Codeksa (memories) jest stabilna, ale domyślnie wyłączona (sprawdzone w Codex 0.157.1, 26.09.2026). Jeśli ją włączysz, przenieś do AGENTS.md wszystko, czego potrzebuje zespół.
Zaufanie: od 0.150.0 projekt oznaczony na danej maszynie jako niezaufany nie dostarcza tam projektowego AGENTS.md.
Sprawdzenie, co się wczytało: codex debug prompt-input "noop" wypisuje wejście widoczne dla modelu.

Wspólne: Cursor stosuje instrukcje projektu przez Rules (cursor.com/docs/rules, zweryfikowane 28.08.2026). Aktualnego formatu pliku reguły nie dało się ponownie sprawdzić 26.09.2026, więc składnię bierz ze strony Rules, a regułę trzymaj jako wskaźnik do AGENTS.md plus linie tylko dla Cursora.
Nie wklejaj rdzenia do reguły Cursora. Kopia rozjedzie się przy pierwszej edycji AGENTS.md.
Prywatne: prywatne preferencje trzymaj poza zatwierdzonymi regułami.
Sprawdzenie, co się wczytało: po każdej aktualizacji Cursora wklej sondę świeżej sesji z wspólnych reguł agentów do nowego czatu Agent.

Naszkicuj wspólny rdzeń z kodu, który już masz

Pisz rdzeń na podstawie konwencji, których kod faktycznie przestrzega, a nie na podstawie wiki. Czytanie wykonuje agent; decyzje podejmuje zespół.

Niech agent naszkicuje rdzeń. Uruchom poniższy prompt w Claude Code, Codeksie albo Cursorze z katalogu głównego repozytorium. W Codeksie pierwszy AGENTS.md utworzy też /init; prompt dokłada listę niespójności, a to ona jest najcenniejsza.
Rozstrzygnij wszystkie niespójności na jednym spotkaniu. Szkic wyciąga konflikty w rodzaju „dwa style obsługi błędów w src/api/”. Dla każdego wybierzcie wzorzec kanoniczny, a przegrany zapiszcie w sekcji „Do not”. Wystarczy 30 minut z osobami, które robią najwięcej review.
Zatwierdź rdzeń i adaptery w jednym pull requeście. Główny AGENTS.md, adapter CLAUDE.md, regułę-wskaźnik dla Cursora i wpis w CODEOWNERS dla wszystkich trzech. W tym samym pull requeście dodaj kontrolę CI ze wspólnych reguł agentów.
Powiedz zespołowi, co się zmieniło. Jedna wiadomość: gdzie jest rdzeń, jak zaproponować regułę i że komentarze z review o konwencjach od teraz linkują do reguły albo się nią stają.

Draft a root AGENTS.md that captures this repository's real, current
conventions. Read enough to be accurate, not everything:
- 3-4 route handlers under src/api/ for endpoint and error-handling patterns
- 2-3 UI components for naming, file structure and state handling
- the test files next to those modules for test naming and structure
- package.json, tsconfig.json and the CI workflow for the real commands

Write these sections: Rules version (today's date + ".1"), Commands,
Project structure, Naming, Error handling, Testing, Definition of done,
Protected paths, Do not. Quote real file paths and helper names. Give each
rule a one-line "why". Stay under 150 lines.

Then, separately, list every place where the code follows two patterns
for the same thing, with two file paths per pattern, so the team can pick
the canonical one. Do not write any file; print the draft and the list.

Zamieniaj komentarze z review w reguły w tym samym pull requeście

Rdzeń pozostaje aktualny tylko wtedy, gdy zasila go review. Kiedy wątek w review rozstrzyga konwencję, to rozstrzygnięcie trafia do AGENTS.md w pull requeście, w którym zapadło. Reguła zostawiona w komentarzu przepada przy merge’u; reguła w rdzeniu trafia do każdego agenta przy najbliższym git pull.

Trzy konwencje pilnują, żeby ta pętla działała naprawdę:

Każda zmiana reguły podaje swój powód: wątek z review, incydent albo problem przy onboardingu, który ją wywołał. Reguła, której nikt nie umie uzasadnić, idzie pierwsza do usunięcia, gdy plik rośnie.
Każdą zmianę reguły zatwierdza właściciel harnessu przez CODEOWNERS. Proponować może każdy; spójność rdzenia utrzymuje jedna osoba.
Powtarzający się komentarz o konwencji to zgłoszenie błędu w rdzeniu. Gdy recenzent pisze ten sam komentarz drugi raz w miesiącu, drugi komentarz linkuje do nowej reguły, zamiast znów ją tłumaczyć.

Reguły sterują też botami do review, więc jedna edycja zmienia zarówno generowanie, jak i przegląd. Codex, robiąc code review w GitHubie, bierze własne reguły przeglądu z AGENTS.md (zweryfikowane 28.08.2026). Zarządzany Code Review w Claude Code (research preview, plany Team i Enterprise) konfiguruje się przez CLAUDE.md i plik REVIEW.md w katalogu głównym repozytorium, zawierający instrukcje wyłącznie dla przeglądu. Konfigurację opisuje przegląd PR przez agentów.

In code review on this branch we settled a convention: every repository
function that can return zero rows returns a typed Result from
src/lib/result.ts and handles the empty case explicitly. It never returns
null.

1. Add this to AGENTS.md under "Error handling" as one imperative bullet
   with a one-line "why" and a two-line before/after example.
2. If an existing rule contradicts it, show that rule and propose the
   edit; do not keep both.
3. List every current function under src/repositories/ that breaks the
   new rule, with file:line, so we can decide whether to fix them now.
Show the AGENTS.md diff and the list. Do not change any other file.

Zapisuj plany i przekazania, żeby agent kolegi mógł kontynuować

Reguły opisują, jak zespół pisze kod. Plany opisują, w środku czego zespół właśnie jest. Gdy plan istnieje tylko w sesji jednego inżyniera, agent żadnej innej osoby nie może przejąć pracy, porównać jej z zamierzeniem ani zauważyć, że dwie osoby rozwiązują ten sam problem.

Trzymaj kontekst trwającej pracy w repozytorium:

Jeden plik planu na zgłoszenie w docs/plans/<ticket-id>.md, zatwierdzony na gałęzi funkcji: cel, kryteria akceptacji, podjęte decyzje, otwarte pytania i komenda weryfikacji. Co zawiera dobry plan i dobra specyfikacja, opisują łańcuch artefaktów i spec-driven development.
Notatka przekazania, zanim skończysz — dopisana do planu zawsze, gdy gałąź podejmie ktoś inny (albo ty za tydzień). Pisze ją agent; ty sprawdzasz ją względem diffu.
Usuń albo zarchiwizuj plan przy merge’u. Nieaktualny plan w docs/plans/ to kontekst, który wprowadzi w błąd następnego agenta.

I am handing this branch to a teammate. Append a "Handoff" section to
docs/plans/PAY-412.md with:
1. What is done, citing the commits on this branch (git log main..HEAD).
2. What is not done, as a checklist in the order it should happen.
3. Decisions made in this session and the reason for each, including
   options we rejected.
4. The exact command that proves the work so far passes, and its current
   result (run it).
5. Anything surprising about the code that the next agent will trip on.
Only state what you can point to in the diff, the plan or the command
output. Mark anything you are unsure of as "unverified".

PAY-412 to identyfikator zgłoszenia; podmień go na swój. Kolega zaczyna sesję od „Read docs/plans/PAY-412.md and continue from the Handoff checklist” w dowolnym z trzech narzędzi.

Wdrażaj nowego inżyniera przez kontekst zespołu

Pierwsze pytanie nowej osoby w zespole zwykle ma już odpowiedź we wspólnym kontekście. Agent czyta zatwierdzony rdzeń, więc jego odpowiedzi odzwierciedlają wasze konwencje, a nie ogólne porady — a każda błędna odpowiedź pokazuje lukę w rdzeniu.

I am new to this codebase. Using AGENTS.md and the code itself, give me an
orientation, not a lecture:
1. The request lifecycle for an authenticated API call, from entry point
   to response, with the file for each step.
2. Our error-handling and validation conventions, with the helper names
   I should reuse.
3. The naming and folder pattern for a new feature module.
4. Which directories are generated, protected or off-limits.
Cite a file for every claim. End with a "first pull request checklist" of
the conventions reviewers will check. If AGENTS.md and the code disagree,
say so explicitly instead of choosing.

Najważniejsza jest ostatnia linia: każda rozbieżność, którą zgłosi orientacja, to reguła do poprawienia. Onboarding developera: udowodnij jeden bezpieczny przepływ zamienia to w mierzalny test onboardingu.

Wprowadź agenta do kanałów, których zespół już używa

Gdy agent odpowiada na wspólnym kanale, a nie w terminalu jednego inżyniera, odpowiedź staje się wiedzą zespołu. Product manager pyta na Slacku, jak działa funkcja, agent odpowiada w wątku na podstawie kodu i wszyscy widzą tę samą odpowiedź. Te integracje czytają ten sam zatwierdzony kontekst, więc trzymają się tych samych reguł.

GitHub: anthropics/claude-code-action@v1 odpowiada na @claude w issue i pull requestach i potrafi zamienić issue w pull request.
Slack: Claude Tag uruchamia @Claude jako wspólną tożsamość organizacji z dostępem konfigurowanym przez administratora (Team i Enterprise). Wcześniejsza aplikacja Claude Code dla Slacka pozostaje ścieżką w planach Pro i Max. Zobacz Claude Tag.
Review: zarządzany Code Review publikuje komentarze inline w pull requestach (research preview, Team i Enterprise, niedostępny przy Zero Data Retention).

Zweryfikowane 28.08.2026; 26.09.2026 host z dokumentacją OpenAI był nieosiągalny.

GitHub: poproś o review przez @codex review albo @codex security review lub włącz automatyczne review; własne reguły przeglądu pochodzą z AGENTS.md.
Slack: oznacz @Codex z promptem; Codex tworzy czat w chmurze i odpowiada wynikami.
Linear: przypisz issue do Codeksa albo oznacz @Codex w komentarzu.

Skąd wiesz, że każdy agent trzyma się wspólnych reguł?

Nikt w zespole nie powinien sprawdzać konwencji, czytając każdą wygenerowaną linię. Użyj trzech warstw, od najtańszej do najdroższej:

Najpierw deterministyczne bramki. Wszystko, co może egzekwować linter, formatter, type checker albo test architektury, należy tam, a nie do AGENTS.md. Reguły, którą sprawdza narzędzie, model nie musi pamiętać.
Kontrola wczytania przy zmianie reguł. Kontrola CI i sonda świeżej sesji ze wspólnych reguł agentów dowodzą, że każde narzędzie wczytało aktualny rdzeń. Uruchamiaj je przy każdej zmianie reguł i po każdej aktualizacji narzędzia.
Przegląd zgodności przy każdym pull requeście. Zanim poprosisz człowieka o review, niech agent sprawdzi diff względem rdzenia i niczego więcej. Zwraca naruszenia z zacytowaną regułą, więc recenzent sprawdza krótką listę zamiast całego diffu.

Review only the changes on this branch against main: use the diff piped
to you, or run git diff main...HEAD if none was piped.
Check them against the rules in AGENTS.md and any AGENTS.md in the
directories the diff touches. Ignore style a formatter would fix.
For each violation output one line:
file:line | the rule, quoted verbatim | the smallest fix
If a change is not covered by any rule but looks like a new convention,
list it under "Candidate rules". If there are no violations, print
NO VIOLATIONS and nothing else. Do not edit any file.

Uruchom go nieinteraktywnie z zaufanej lokalnej kopii repozytorium (plik z promptem to powyższy Aside zapisany jako tests/agent-rules/conformance.txt):

# Terminal, katalog główny repozytorium, na własnej gałęzi (nie na kodzie z forka).
# Claude Code: diff przez potok; tryb plan nie pozwala edytować plików.
git diff main...HEAD | claude -p "$(cat tests/agent-rules/conformance.txt)" \
  --permission-mode plan --output-format text

# Codex: sandbox tylko do odczytu pozwala uruchomić git diff, ale nie zapisywać.
codex exec --sandbox read-only --ephemeral "$(cat tests/agent-rules/conformance.txt)"

codex review --base main uruchamia zamiast tego wbudowany preset przeglądu Codeksa; w Codex 0.157.1 nie przyjmuje on własnych instrukcji razem z --base, więc do kontroli samych reguł użyj codex exec. W trybie print tryb planu może zakończyć się przedstawieniem planu zamiast raportu; jeśli wynik przyjdzie opakowany jako plan, uruchom Claude Code w trybie domyślnym z --disallowedTools Edit Write (sprawdzone w claude --help, v2.1.283). W Cursorze wklej prompt do nowego czatu Agent na tej gałęzi.

Kto zatwierdza. Autor pull requesta dołącza wynik kontroli zgodności. Recenzent sprawdza listę naruszeń, kandydatów na reguły i testy, a nie każdą linię. Właściciel harnessu zatwierdza każdego kandydata, który staje się prawdziwą regułą. Żeby sprawdzić, czy pętla działa, licz co miesiąc komentarze z review oznaczone jako dotyczące konwencji na każdy zmergowany pull request: liczba powinna spadać, w miarę jak rdzeń je wchłania. Szerszą zmianę opisuje jak pomóc zespołowi przestać czytać każdy diff.

Co się psuje, gdy zespół dzieli kontekst agentów?

Rdzeń rozjeżdża się z kodem. Objaw: agenci trzymają się wzorca, który zespół porzucił miesiące temu. Przyczyna: reguły napisano raz i nigdy nie aktualizowano. Wyjście: co kwartał uruchom ponownie prompt szkicujący, porównaj wynik z zatwierdzonym rdzeniem i rozstrzygnij każdą różnicę w pull requeście.

Agent jednego inżyniera ignoruje reguły. Objaw: ten sam prompt daje zgodny kod u wszystkich poza jedną osobą. Przyczyna w Claude Code: CLAUDE.md w dowolnym miejscu, z którego Claude Code wczytuje pliki, kanał stable albo przełącznik „Project instructions” wyłączony w /config blokują bezpośrednie wczytanie AGENTS.md. W Codeksie: projekt jest na tej maszynie oznaczony jako niezaufany. Wyjście: adapter @AGENTS.md naprawia przypadki w Claude Code; w Codeksie oznacz projekt jako zaufany; potwierdź przez /context albo codex debug prompt-input.

Codex i Claude Code nie zgadzają się w jednym katalogu. Objaw: zachowanie różni się między narzędziami tylko w jednym pakiecie. Przyczyna: zatwierdzony AGENTS.override.md, który Codex czyta zamiast AGENTS.md z tego katalogu, a Claude Code ignoruje. Wyjście: przenieś jego treść do AGENTS.md, usuń go i zostaw kontrolę CI, która zgłasza błąd, gdy ten plik się pojawi.

Rdzeń rośnie, aż reguły giną. Objaw: reguły z katalogu brakuje w codex debug prompt-input albo agenci trzymają się reguł z początku pliku i zapominają te z końca. Przyczyna: łańcuch przekroczył domyślne 32 KiB Codeksa i został obcięty albo plik jest za długi, żeby dobrze sterować jakimkolwiek narzędziem. Wyjście: procedury przenieś do skilli, sprawdzalne reguły do linterów, a protokołem przycinania usuń to, co nie zmienia zachowania.

Reguły bez uzasadnienia są stosowane niekonsekwentnie. Objaw: agent stosuje „używaj AppError” w handlerach, ale nie w zadaniach w tle. Przyczyna: reguła mówi „co”, a nie „dlaczego”, więc model nie umie jej uogólnić. Wyjście: dodaj do każdej reguły jednolinijkowe uzasadnienie; prompty szkicujący i zapisujący decyzję już o nie proszą.

Prywatny nawyk staje się regułą zespołu. Objaw: w rdzeniu są reguły, na które nikt nie pamięta, żeby się umawiał. Przyczyna: ktoś zatwierdził własne przyzwyczajenia. Wyjście: każda zmiana reguły podaje swój powód, a właściciel harnessu odrzuca reguły bez niego.

Reguła jest traktowana jak zabezpieczenie. Objaw: agent czyta .env, chociaż rdzeń tego zabrania. Przyczyna: instrukcje sterują modelem, ale go nie wiążą. Wyjście: twarde ograniczenia egzekwuj regułami uprawnień, sandboksami, CI i ochroną gałęzi, przeglądanymi w ramach zarządzania wspólnymi hookami, a zdanie w rdzeniu zostaw tylko jako wyjaśnienie tej kontroli.

Co dalej ze wspólnym kontekstem zespołu

Przed tą stroną przygotuj bazę kodu dla agentów. Następnie skonfiguruj przetestowany układ plików opisany we wspólnych regułach agentów, a potem przejdź do przeglądania pracy agentów bez czytania każdej linii. Konfiguracja dla konkretnych narzędzi: współpraca zespołowa w Claude Code i współpraca zespołowa w Cursorze.

Wspólne reguły agentów Jeden rdzeń AGENTS.md, cienkie adaptery, kontrola CI i sonda dla każdego narzędzia.

Treść AGENTS.md i CLAUDE.md Co zasługuje na linię w rdzeniu, a co pominąć.

Wspólne skille Procedury zespołu ładowane na żądanie, a nie w każdej sesji.

Przegląd PR przez agentów Agenci do review, którzy czytają te same reguły zespołu.

Onboarding i adopcja w zespole Wdróż wspólny sposób pracy w całym zespole.

Jak przestać czytać każdy diff Przenieś review z linii kodu na dowody.