Spec-driven development: czym jest i nasz kontrakt issue

Spec-driven development (SDD) oznacza, że zapisują Państwo, co zbudować i po czym poznać, że jest gotowe, zanim agent AI napisze pierwszą linię kodu. Spec Kit od GitHuba ujmuje to tak: "Define what to build and why, then turn the specification into a plan, tasks, and working code." Czyli: proszę określić, co i dlaczego zbudować, a potem zamienić specyfikację w plan, zadania i działający kod. My używamy lżejszej wersji: specyfikacją jest issue na GitHubie z typem zadania i kryteriami akceptacji, a automatyczna bramka sprawdza, czy obiecany wynik istnieje.

Pracujemy jak fabryka oprogramowania: agenci AI wykonują rutynową pracę, seniorzy decydują, co się buduje, i sprawdzają każdą zmianę. Nasza praca przeniosła się więc do specyfikacji i kontroli wokół niej. Poniżej nasz kontrakt issue, kod, który go czyta, i to, czego się nauczyliśmy, gdy specyfikacja była błędna.

Czym jest spec-driven development z agentami AI?

Krótka definicja jest w naszym słowniku pojęć. Idea jest stara: uzgodnić, co znaczy gotowe, zanim zacznie się budować. Przy agentach AI ma to większe znaczenie, bo agent i tak coś zbuduje. Bez specyfikacji wypełnia luki domysłami, a domysły wyglądają na skończone.

Spec Kit uruchamia to jako komendy w czacie agenta: zasady projektu, specyfikacja, plan, zadania, implementacja. Inne narzędzia mają własne warianty. Łączy je jedno. Specyfikacja jest przed kodem i pozostaje punktem odniesienia przy review.

Gdzie pasuje context engineering: wszystko, co widzi agent, to kontekst, od plików z regułami po wyniki narzędzi. Specyfikacja to ta część kontekstu, która mówi, co znaczy gotowe. Więcej kontekstu bez niej daje tylko pewniejszy siebie błędny wynik.

Dlaczego issue na GitHubie zamiast długiego dokumentu specyfikacji?

Nasze issues to kolejka, którą ludzie czytają każdego ranka. Nasza reguła dla nich zaczyna się od trzech słów: "Queue items, not specs." Pozycje w kolejce, a nie specyfikacje. Długa specyfikacja trafia do podlinkowanego dokumentu. Issue to to, co jedna osoba albo jeden agent bierze i kończy.

Mniej, ale większych issues lepiej sprawdza się też u agentów. Nasza reguła to jeden skończony wynik na issue i na pull request. Duży to wciąż jeden PR, z jednym commitem na warstwę, żeby człowiek mógł go przeczytać w kolejności budowania.

Co zawiera nasz kontrakt issue?

Trzy rzeczy są obowiązkowe: tytuł z czasownikiem i konkretnym obiektem, jedna etykieta priorytetu i to, co trzeba zrobić. Przy prostej pracy wystarczy sam tytuł. Sekcje takie jak ## What, ## Acceptance i ## Output pojawiają się tylko wtedy, gdy mają treść. Puste ## Acceptance: TBD jest zabronione.

Typ zadania decyduje, co musi istnieć na końcu:

Nikt nie dodaje etykiety dla typu. Kto bierze issue, ten go wnioskuje. Brakujące ## Output albo ## Acceptance uzupełnia się jako jawne założenie, nigdy po cichu.

Jak maszyna sprawdza specyfikację?

Dwa razy: przed pracą i po niej.

Przed pracą: READY. Wywołanie modelu tylko do odczytu czyta issue i kod i zwraca typowaną odpowiedź. Skrót z naszego schematu:

{
  "ready": true,
  "type": "code",
  "done_when": ["criteria a reviewer can answer yes or no"],
  "verifiable": "test",
  "confirmation": ["the test that carries the proof"],
  "premise": "verified against <file:line>",
  "question": ""
}

premise oszczędza nam najwięcej czasu. Kontrola porównuje każde twierdzenie issue o dzisiejszym działaniu z kodem, z plikiem i linią. Jeśli nic z issue już nie obowiązuje, proponuje jego zamknięcie. verifiable mówi, czy najbardziej ryzykowne kryterium może udowodnić test, czy tylko człowiek, który na to spojrzy. Jeśli brakuje decyzji produktowej, question zadaje jedno pytanie z dwiema opcjami i rekomendacją, a praca się nie zaczyna.

Po pracy: bramka. Zwykły bash z kodami wyjścia, jedna gałąź na typ zadania. Dla kodu uruchamia typecheck, lint, testy i build samego repozytorium, plus red-proof: zmieniony kod źródłowy wymaga zmienionego testu, a ten test musi nie przechodzić na gałęzi bazowej. Dla researchu otwiera każdy URL źródła i szuka cytatu na stronie. Parafraza nie przechodzi. Tej części nigdy nie ocenia model.

Co się zmieniło, gdy przestaliśmy szacować wielkość zadań?

Kiedyś ocenialiśmy zadania według wielkości i według niej je przydzielaliśmy. Zastąpiliśmy to gotowością: czy założenie jest sprawdzone względem kodu, czy dowód jest nazwany, czy coś zostało do rozstrzygnięcia.

Bramki to druga połowa specyfikacji. Issue mówi, co znaczy gotowe. Kontrole pilnują, żeby nikt, człowiek ani agent, nie mógł uznać tego za gotowe inaczej.

Co poszło nie tak z naszymi specyfikacjami?

• Kontrola gotowości przyszła za późno. Na początku agent brał issue tak, jak było napisane. Kontrolę założenia względem kodu dodaliśmy później. Dziś to pierwszy etap i od niego byśmy zaczęli.
• Błędny komentarz to nie błędne issue. Stary plan w komentarzu sprawiał, że kontrola obalała dobre issues. Teraz liczy się tylko twierdzenie w treści issue. Obalona treść trafia do człowieka, który odpowiada OK, zanim zacznie się praca.
• Zielona bramka, która niczego nie dowodziła. W jednym monorepo red-proof uruchamiał testy bez właściwego środowiska. Każde „nie przechodzi na gałęzi bazowej” było testem, który w ogóle nie wystartował, a nie prawdziwą czerwienią. Przez kilka dni każdy red-proof w tym repozytorium przechodził fałszywie. Teraz testy uruchamia menedżer pakietów repozytorium, dla każdego pakietu osobno, na przypiętej wersji Node.

Ostatnia to lekcja, którą powtarzamy najczęściej: kontrola, która nie może się nie udać, nie jest kontrolą. Więcej w Red-green TDD z agentami AI.

Jak napisać issue, które agent może skończyć?

Ostatni krok zespoły pomijają. A jest najtańszy: jedno wywołanie modelu tylko do odczytu, zanim powstanie choćby linia kodu.

Jak wygląda reszta konfiguracji agenta, od reguł po hooki, opisujemy w Harness engineering w praktyce: od issue do PR. Kiedy zamiast specyfikacji wystarczy wbudowany tryb planowania, wyjaśniamy w Claude Code plan mode.

Czy Państwa issue jest gotowe dla agenta?

Chcą Państwo pętli od specyfikacji do PR w swoim zespole?

Ten kontrakt i stojące za nim kontrole budujemy bezpośrednio w repozytorium zespołu w ramach AI-native SDLC dla zespołów deweloperskich. Brakuje bardziej rąk niż procesu? Proszę zobaczyć senior developer dla Państwa zespołu. Od 2023 roku dostarczyliśmy ponad 15 projektów produkcyjnych.

Odezwiemy się w ciągu dwóch dni roboczych z kilkoma pytaniami o Państwa pracę. Potem ustalimy, co zrobimy najpierw.

Jeśli wolą Państwo najpierw porozmawiać, proszę zarezerwować 15-minutową rozmowę wstępną.

Co znaczyło „gotowe” w ostatnim issue Państwa zespołu i kto to sprawdził?

Najczęstsze pytania

Czym jest spec-driven development?

To zapisanie, co zbudować, dlaczego i po czym poznać, że jest gotowe, zanim ktokolwiek napisze kod, a następnie zamiana tego w plan, zadania i kod. Przy agentach AI specyfikacja jest też kontekstem, z którym agent pracuje.

Czy potrzebuję długiego dokumentu specyfikacji?

Nie. Do większości pracy używamy issue na GitHubie: tytuł, typ zadania, kryteria akceptacji i miejsce, gdzie trafi wynik. Długa specyfikacja żyje w podlinkowanym dokumencie, nie w issue.

Czym spec-driven development różni się od context engineeringu?

Context engineering to wszystko, co widzi agent: reguły, pliki, narzędzia, historia. Specyfikacja to ta jego część, która mówi, co znaczy gotowe. Bez specyfikacji więcej kontekstu daje tylko pewniejszy siebie błędny wynik.

Jak sprawdzają Państwo, że agent spełnił specyfikację?

Kodem, nie opinią. Przed pracą kontrola tylko do odczytu porównuje issue z kodem. Po pracy bramka sprawdza, czy obiecany wynik istnieje: PR z testem, który przed zmianą nie przechodzi, a po niej przechodzi, źródła z dosłownymi cytatami, raport QA.

Kiedy specyfikacja się nie opłaca?

Przy poprawce w jednej linii specyfikacją jest tytuł. Tam, gdzie wynik może ocenić tylko człowiek, na przykład tekst albo wrażenie wizualne, specyfikacja to mówi, a praca trafia do tej osoby.