Budowanie z agentami: przepływ pracy dla twojej bazy kodu

Budowanie z agentami AI polega na implementowaniu zaakceptowanej specyfikacji małymi wycinkami: agent przygotowuje plan w trybie tylko do odczytu, implementuje po jednym wycinku w izolowanym worktree i kończy, gdy przechodzą bramki jakości. Pętla jest taka sama w Claude Code, Codeksie i Cursorze; od kształtu bazy kodu zależą kontekst, zasięg zmian i kontrole.

Ta sekcja jest dla programistów, którzy uruchamiają agenta, i dla tech leadów, którzy decydują, czego musi dowieść gotowa zmiana. Kierujesz agenta na zgłoszenie w monolicie na 2 miliony linii, a on przepisuje wspólną funkcję pomocniczą importowaną przez 40 serwisów. Testy jednostkowe są zielone, a pull requestu nie da się sensownie zrecenzować. Przewodniki poniżej zapobiegają temu dla każdego rodzaju systemu.

Który przewodnik po budowaniu pasuje do twojej bazy kodu?

Twoja sytuacja	Zacznij od
Agent nie ogarnia bazy kodu i zmienia rzeczy, których nie przeczytał	Strategie dla milionowych linii kodu
Jedna zmiana rozlewa się po pakietach budowanych i wydawanych razem	Przepływy pracy w monorepozytoriach
Musisz zastąpić stary kod, którego zachowania nikt nie spisał	Modernizacja legacy
Zmiana obejmuje wiele serwisów, kolejek i repozytoriów	Rozwój systemów rozproszonych
Konsumenci zależą od kontraktu API, którego agent nie może złamać	Tworzenie API
Zmiana wymaga migracji schematu albo naprawy wolnego zapytania	Projektowanie baz danych i zapytania

Nowej funkcji w małym, dobrze przetestowanym repozytorium wystarczy podstawowa pętla budowania.

Co jest wspólne dla każdego przepływu budowania?

Każdy przewodnik adaptuje tę pętlę; szablon plan.md i hooki są na stronie etapu Build w cyklu życia.

1. Zacznij od zaakceptowanego kontraktu. To spec.md z numerowanymi wymaganiami i testami akceptacyjnymi, które dziś są czerwone. Jeśli go nie masz, wróć do planowania i specyfikacji.
2. Planuj w trybie tylko do odczytu. Agent zapisuje w plan.md pliki, których dotknie, i zasięg zmiany. Wskazany z imienia inżynier akceptuje plan, zanim zmieni się kod.
3. Potnij pracę na wycinki. Każdy wycinek to jeden pull request, który da się zrecenzować i który zostawia zielony build. Duży i stary kod potrzebuje mniejszych wycinków, a nie dłuższych promptów.
4. Implementuj w izolacji. Jeden wycinek na jeden worktree, żeby równoległe sesje nie nadpisywały sobie pracy. Zobacz, jak uruchamiać równoległe agenty w izolowanych worktree.
5. Kończ na bramkach, nie na słowie agenta. Testy, typy, lint i kontrole właściwe dla danej sekcji przechodzą w CI, a pull request zawiera pakiet dowodów.

Jak zacząć sesję budowania w każdym narzędziu?

Polecenia sprawdzone w Claude Code 2.1.286 i Codex CLI 0.157.1; Cursor według jego dokumentacji z 2026-08-28.

Claude Code

# Terminal: plan without editing files
claude --permission-mode plan

# Terminal: implement the accepted plan in a new git worktree
claude --worktree pay-412-refunds

W otwartej sesji /plan przełącza w tryb planowania; Shift+Tab przechodzi kolejno przez tryby uprawnień, aż włączy się tryb planowania. Przy wielu niezależnych wycinkach wbudowany skill /batch rozdziela je na osobne worktree. Przed wypchnięciem zmian uruchom /code-review, żeby dostać lokalną recenzję diffa.

Codex

# Terminal: start a session in a new managed git worktree
codex --worktree

# Terminal: non-interactive review of the branch against main
codex review --base main

W sesji wpisz /plan, żeby Codex zaplanował pracę przed pisaniem kodu.

Cursor

Plan Mode daje plan przed kodem, Worktree (izolowana kopia repozytorium gita) izoluje implementację, a Bugbot recenzuje pull request.

Prompt do skopiowania: zasięg zmiany i podział na wycinki

Read spec.md and the code it touches. Do not edit any files.
1. List every file, public function, and exported type the change
   must modify, and every caller of each one (search the whole repo,
   including other packages and services).
2. Mark which callers have tests that would fail if behavior changed,
   and which have none.
3. Propose an ordered list of slices. Each slice must be one pull
   request under ~400 changed lines that leaves the build green, and
   must name the acceptance tests it makes pass.
4. List what you could not determine from the code and who should
   answer it.
Write the result to plan.md and stop for my review.

Prompt do skopiowania: implementacja jednego wycinka z dowodem

Implement slice 1 from plan.md and nothing else.
Rules:
- Do not edit test files under tests/acceptance/ or any file outside
  the slice's file list. If you need to, stop and explain why.
- After each change, run the test, typecheck, and lint commands from
  AGENTS.md (or CLAUDE.md) and fix failures before moving on.
- Stop when slice 1's acceptance tests pass and the full suite is green.
Finish with a report: files changed, commands run with their exit
codes, acceptance tests now passing, anything in plan.md that turned
out to be wrong.

Skąd wiadomo, że zmiana jest gotowa, bez czytania każdej linii?

Ufaj kontrolom, których agent nie zmieni; uwagę człowieka zostaw na decyzje.

• Testy akceptacyjne wcześniej były czerwone, a teraz są zielone. Test, który nigdy nie padł, niczego nie dowodzi; zobacz jak silna jest twoja wyrocznia.
• Agent nie może edytować wyroczni. CI odrzuca zmiany testów akceptacyjnych w pull requeście z implementacją; zobacz ochronę wyroczni.
• Strukturę sprawdza maszyna. Typy, lint i funkcje dopasowania architektury wyłapują złamane warstwy.
• Każdy przewodnik dokłada własną bramkę: testy kontraktowe dla API, próbny przebieg migracji dla baz danych, testy charakteryzacyjne dla legacy, build tylko zmienionych projektów w monorepo.
• Drugi agent recenzuje, człowiek zatwierdza. Inżynier, który zaakceptował plan.md, zatwierdza pull request względem tego planu i jego dowodów; zobacz code review PR-a agenta.

Co się psuje przy budowaniu z agentami i jak z tego wyjść?

Awaria	Sygnał	Wyjście
Agent zmienia kod, którego nie przeczytał	Zmiany w plikach, których nie ma w plan.md	Odrzuć pull request, uruchom ponownie prompt o zasięgu zmiany i dopisz pominięte wywołania
Jeden wycinek rozrasta się do całej funkcji	Pull request za duży na recenzję	Wróć do ostatniego zielonego commita i podziel resztę na nowe wycinki
Testy przechodzą, bo agent je zmienił	Pliki testów zmieniają się w PR z implementacją	Chroń testy akceptacyjne w CI i powtórz wycinek w czystym worktree
Równoległe sesje wchodzą sobie w drogę	Konflikty scalania albo nadpisana praca	Jeden wycinek na worktree i gałąź; scalaj w kolejności z planu
Plan okazuje się błędny w trakcie budowania	Agent łata kod wokół fałszywego założenia	Zatrzymaj sesję, popraw plan.md i zacznij wycinek od nowa w świeżej sesji

Dokąd dalej po sekcji o budowaniu

• Wcześniej: planowanie i specyfikacja oraz repozytorium gotowe dla agentów.
• Później: testowanie i weryfikacja, potem code review i wdrożenie.
• Dlaczego bramki pozwalają wyjść z pętli: Poziom 4: piszesz specyfikacje.