Współpraca zespołowa: wspólny kontekst i zasady

Dwóch inżynierów w twoim zespole prosi swojego asystenta AI o dodanie nowego endpointu API. Jeden dostaje kontroler z try/catch i własną klasą błędu; drugi — goły asynchroniczny handler, który rzuca surowymi błędami. Układ folderów się różni. Nazewnictwo się różni. Przegląd pull requestu zamienia się w 40-komentarzową debatę o stylu, która nie ma nic wspólnego z tym, czy funkcja działa — bo wasze konwencje żyją w głowach ludzi, a nie w repozytorium.

Rozwiązaniem nie są kolejne komentarze w review. Jest nim przeniesienie standardów do wersjonowanych plików zasad, które AI każdego członka zespołu ładuje automatycznie. Gdy konwencje żyją obok kodu, agent każdego inżyniera generuje kod, który od razu wygląda jak twoja baza kodu.

Czego się nauczysz

Wersjonowanego pliku zasad dla każdego narzędzia (.cursor/rules/, CLAUDE.md, AGENTS.md), który egzekwuje wasze konwencje dla całego zespołu
Gotowego promptu, który tworzy szkic tego pliku zasad na podstawie istniejącego kodu, więc nie piszesz go od zera
Procesu zamiany decyzji z code review w trwałe, egzekwowane maszynowo zasady
Promptu wdrożeniowego, który nowa osoba wkleja pierwszego dnia, by samodzielnie zmapować bazę kodu
Trybów awarii (rozjazd zasad, sprzeczne pliki, rozdęty kontekst) i jak ich unikać

Fundament: zasady kontrolowane wersją

Najważniejszą praktyką dla wyrównania zespołu jest zdefiniowanie standardów projektu we wspólnych, kontrolowanych wersją plikach zasad, które są dostarczane razem z repozytorium. Wszystkie trzy narzędzia czytają pliki instrukcji na poziomie projektu; różni je tylko nazwa pliku i kilka szczegółów działania.

Cursor czyta zasady z katalogu .cursor/rules/ (jeden lub więcej plików .mdc). Zatwierdź ten katalog w repozytorium, aby Cursor każdego członka zespołu pobierał te same zasady. Każdy plik zasad można zawęzić za pomocą frontmatter: alwaysApply: true ładuje go do każdego żądania, a wzorzec globs (np. src/api/**) ładuje go tylko wtedy, gdy w kontekście znajdują się pasujące pliki.

---
description: API conventions
globs: src/api/**
alwaysApply: false
---
- All route handlers live in src/api/<resource>/route.ts
- Wrap handlers in our asyncHandler() from src/lib/http.ts
- Throw AppError (src/lib/errors.ts), never raw Error
- Validate input with the matching Zod schema before any DB call

Claude Code czyta CLAUDE.md z katalogu głównego projektu (oraz z katalogów zagnieżdżonych). Zatwierdź go w repozytorium. Możesz dołączać inne pliki za pomocą importów @path, dzięki czemu pojedynczy CLAUDE.md pozostaje krótki, odwołując się do szczegółowych standardów.

# Project conventions

## API endpoints
- Route handlers live in src/api/<resource>/route.ts
- Wrap handlers in asyncHandler() from src/lib/http.ts
- Throw AppError (src/lib/errors.ts), never raw Error
- Validate input with the matching Zod schema before any DB call

See @docs/architecture.md for the full request lifecycle.

Codex czyta pliki AGENTS.md, zaczynając od katalogu głównego repozytorium i schodząc w dół do bieżącego katalogu. Zatwierdź AGENTS.md w katalogu głównym dla zasad obowiązujących cały zespół. Dla podzespołu z innymi konwencjami umieść AGENTS.override.md w jego katalogu — pliki bliższe katalogowi roboczemu nadpisują ogólniejsze wytyczne, ponieważ Codex łączy je w kolejności od katalogu głównego.

## API endpoints
- Route handlers live in src/api/<resource>/route.ts
- Wrap handlers in asyncHandler() from src/lib/http.ts
- Throw AppError (src/lib/errors.ts), never raw Error
- Validate input with the matching Zod schema before any DB call

Codex przestaje dodawać pliki, gdy łączny rozmiar osiągnie project_doc_max_bytes (domyślnie 32 KiB), więc rozdziel duże wytyczne na zagnieżdżone katalogi zamiast jednego wielkiego pliku w katalogu głównym.

Gdy te pliki są już zatwierdzone, developer, który sklonuje repozytorium, dostaje konwencje za darmo — jego AI ładuje zasady i od pierwszego promptu generuje kod spójny z istniejącymi wzorcami. O to właśnie chodzi: przeglądy przestają dotyczyć stylu, bo styl jest egzekwowany jeszcze zanim kod powstanie.

Proces: od pustego pliku do egzekwowanego standardu

Pliku zasad nie piszesz od zera. Pozwalasz AI stworzyć jego szkic na podstawie kodu, który już masz, a potem go edytujesz i zatwierdzasz.

Wygeneruj pierwszy szkic na podstawie bazy kodu. Skieruj agenta na reprezentatywne katalogi i niech wywnioskuje wasze rzeczywiste konwencje — te z kodu, a nie te z wiki, którego nikt nie czyta.

Inspect this codebase and draft a team rules file that captures our
real, current conventions. Read enough to be accurate, not exhaustive:

- 3-4 files under src/api/ for our endpoint/error-handling pattern
- 2-3 React components for naming, file structure, and state patterns
- Our test files for how we name and structure tests
- package.json and tsconfig.json for tooling and strictness

Output a concise rules file with these sections: Project structure,
Naming, Error handling, Testing, and "Do NOT" (anti-patterns you see
us avoiding). Quote the real file paths and helper names you found.
Keep it under 150 lines. Flag anything inconsistent so I can pick the
canonical version instead of you guessing.

Przejrzyj i wybierz kanoniczny wzorzec. Szkic ujawni niespójności (“dwa style obsługi błędów w src/api”). To jest najcenniejsza część — zdecyduj, który wygrywa, i spraw, by plik zasad nie pozostawiał wątpliwości.
Zatwierdź go pod właściwą nazwą pliku. Zapisz jako .cursor/rules/conventions.mdc, CLAUDE.md lub AGENTS.md zgodnie z zakładkami powyżej (albo wszystkie trzy, opakowując wspólny dokument). Zatwierdź i wypchnij, aby cały zespół dostał to przy następnym pullu.

Kodyfikuj decyzje z review na bieżąco. Plik zasad to żywy dokument. Gdy code review ustanawia nowy standard, nie zostawiaj go w komentarzu do PR-a, gdzie obumrze — dodaj go do pliku zasad w tym samym PR-ze.

We just decided in code review: every database query that can return
zero rows must handle the empty case explicitly and return a typed
Result, never null.

Add this as a rule to our rules file. Write it as an imperative bullet
with a one-line "why", and include a tiny before/after example using
our actual Result type from src/lib/result.ts. Place it under the
Error handling section. Show me only the diff.

Wdrożenie: niech nowe osoby same zmapują bazę kodu

Najszybsze wdrożenie to nie starszy developer odpowiadający co kwartał na te same pytania. To nowa osoba, która wkleja prompt i dostaje na żądanie dokładne, świadome zasad oprowadzanie po kodzie. Ponieważ agent czyta zatwierdzone zasady, odpowiedzi odzwierciedlają wasze konwencje, a nie ogólne porady.

I'm new to this codebase. Using our committed rules file and the code
itself, give me an orientation, not a lecture:

1. Where is authentication handled, and what is the request lifecycle
   for a logged-in API call (entry point to response)?
2. What are our error-handling and validation conventions, with the
   actual helper/util names I should reuse?
3. What naming and file-structure patterns should I follow for a new
   feature module?
4. Which directories are off-limits or auto-generated?

For each point, cite the specific files I should read next. End with a
"first PR checklist" of conventions reviewers will expect me to follow.

AI jako centrum współpracy

Wspólne zasady wyrównują kod; integracje wyrównują ludzi. Najlepiej pasuje tu wielopowierzchniowa konstrukcja Codeksa: łączy się z GitHubem, Slackiem i Linearem, więc agent może działać tam, gdzie twój zespół już rozmawia.

Odpowiadaj na pytania o produkt otwarcie. PM pyta na kanale Slacka, jak zachowuje się dana funkcja. Zamiast przełączać kontekst, żeby czytać kod, Codex (połączony z repozytorium i Slackiem) może odpowiedzieć w wątku wyjaśnieniem opartym na kodzie, które widzą wszyscy — zamieniając prywatną wiadomość we wspólną wiedzę zespołu.
Wiąż pracę z zadaniami. Dzięki integracjom z GitHubem i Linearem Codex może otworzyć PR z zadania albo podsumować zmianę z powrotem na zgłoszeniu, więc uzasadnienie żyje tam, gdzie śledzona jest praca, a nie w czyimś logu z terminala.

Agent w tle w Cursorze i tryb headless w Claude Code (claude -p "..." w CI) pokrywają stronę automatyzacji: uruchom tego samego, świadomego zasad agenta w pipelinie, aby wychwytywał naruszenia konwencji w każdym PR-ze. Zasada jest identyczna we wszystkich trzech narzędziach — agent jest tylko tak wyrównany, jak zatwierdzone zasady, które czyta, więc plik zasad pozostaje źródłem prawdy.

Gdy coś nie działa

Plik zasad rozjeżdża się z rzeczywistością. Zespoły piszą plik zasad raz, baza kodu ewoluuje, a pół roku później zasady opisują wzorzec, który porzuciłeś. Uruchamiaj prompt “stwórz szkic pliku zasad z istniejącego kodu” co kwartał i porównuj wynik z zatwierdzonym plikiem — pokaże dokładnie, gdzie rzeczywistość poszła naprzód.

Sprzeczne pliki instrukcji. Główny CLAUDE.md mówi jedno, a zagnieżdżony co innego; AGENTS.override.md po cichu wygrywa z głównym AGENTS.md. Gdy AI ignoruje zasadę, sprawdź, czy nie nadpisuje jej plik o węższym zakresie. Codex łączy pliki w kolejności od katalogu głównego (najbliższy wygrywa); trzymaj nadpisania świadome i udokumentowane.

Plik zasad jest za długi, więc jest ignorowany albo zżera kontekst. 600-linijkowy plik zasad zarówno spala kontekst, jak i grzebie zasady, które się liczą. Codex domyślnie twardo ogranicza się do 32 KiB. Trzymaj plik najwyższego poziomu szczupły i przerzucaj szczegóły do dokumentów, do których się odwołujesz, albo plików o zawężonym zakresie (globs w Cursorze, zagnieżdżone pliki w Codeksie, importy @imports w Claude Code).

Zasady opisują styl, ale nie “dlaczego”. “Użyj AppError” bez uzasadnienia jest przestrzegane niespójnie. Jednolinijkowe uzasadnienia sprawiają, że zasady się przyjmują, i pomagają AI uogólniać je na przypadki, których nie wymieniłeś.

Traktowanie wspólnej pamięci lub wspólnego indeksu jako zamiennika zasad. Cursor utrzymuje semantyczny indeks per projekt (a plany zespołowe pozwalają go współdzielić), ale Claude Code i Codex nawigują w czasie rzeczywistym, bez gotowego wspólnego indeksu — więc nie polegaj na tym, że “AI już zna nasze wzorce”. Zatwierdzone pliki zasad są przenośnym, niezależnym od narzędzia źródłem prawdy. Zobacz poniższe przewodniki o indeksowaniu i pamięci, by dowiedzieć się, co faktycznie utrwala każde narzędzie.

Co dalej

Techniki promptowania Pisz prompty, które wydobywają produkcyjnej jakości wyniki z agentów twojego zespołu świadomych zasad.

Zarządzanie dużymi bazami kodu Utrzymaj skuteczność agentów, gdy repozytorium rośnie ponad to, co mieści się w jednym oknie kontekstu.

Prywatność i bezpieczeństwo Zdecyduj, co należy do zatwierdzonych zasad, a co nigdy nie może trafić do dostawcy AI.

Wzorce pamięci Co każde narzędzie utrwala między sesjami dzięki auto-pamięci i zasadom projektu.

Indeksowanie bazy kodu Czym wspólny indeks semantyczny Cursora różni się od nawigacji w czasie rzeczywistym w Claude Code i Codeksie.