17 czerwca 2026Zaktualizowano Fathy Shalaby13 min czytania
Szablon specyfikacji technicznej: napisz spec, który inżynierowie naprawdę czytają
Szablon specyfikacji technicznej do skopiowania, praktyki design docs i RFC, z których czerpie, oraz metoda krok po kroku na spec, który inżynierowie czytają do końca.
Udostępnij
Ten artykuł został przetłumaczony z języka angielskiego. Przeczytaj oryginał
Szablon specyfikacji technicznej powinien stawiać ryzykowne decyzje na pierwszej stronie: problem i jego ograniczenia, proponowany projekt, odrzucone alternatywy i to, co może pójść nie tak – w przypadku większości zmian na jednej do trzech stronach. Design docs Google i RFC Ubera mają taką właśnie formę. Szablon do skopiowania poniżej dodaje podsumowanie w jednym zdaniu i tabelę decyzji, żeby recenzenci znajdowali trudne wybory w mniej niż minutę.
Najważniejsze wnioski
Design docs Google mają pięć głównych sekcji i liczą od 10 do 20 stron przy dużych projektach, ale tylko 1–3 strony przy pracy przyrostowej (Malte Ubl, 2020).
Czytelnicy przyswajają około 20% słów na przeciętnej stronie internetowej, najwyżej 28% (Nielsen Norman Group, 2008). Specyfikacje czyta się tak samo: skanuje się je w poszukiwaniu fragmentów, które mogą być błędne.
61% programistów spędza ponad 30 minut dziennie na szukaniu odpowiedzi (Stack Overflow, 2024). Spec, który zapisuje decyzje, odpowiada na te pytania raz.
Zespoły z dobrą dokumentacją 3,8 razy chętniej stosują najlepsze praktyki bezpieczeństwa (DORA, 2021).
„Rozważane alternatywy” to sekcja, której recenzenci ufają najbardziej, bo pokazuje, że szukałeś powodu, by nie budować tego w ten sposób.
Czym jest specyfikacja techniczna i czym różni się od PRD?
Specyfikacja techniczna (zwana też design doc lub dokumentem projektu technicznego) wyjaśnia, jak zespół zbuduje dane rozwiązanie i na jakie kompromisy się godzi. PRD wyjaśnia, jaki problem warto rozwiązać, dla kogo i jak zmierzymy sukces. Najpierw powstaje PRD; specyfikacja techniczna jest na nie odpowiedzią.
Zespoły używają czterech pokrewnych dokumentów. Mieszanie ich to najczęstszy powód, dla którego spec puchnie do 15 stron, których nikt nie dokończy.
Dokument
Na jakie pytanie odpowiada
Zwykle odpowiada
Typowa długość
PRD
Jaki problem, dla kogo i skąd będziemy wiedzieć, że się udało?
Czy szersza organizacja zgadza się z tym planem, zanim ruszy praca?
Autor oraz wskazani akceptujący
Jak spec, z terminem na review
ADR (architecture decision record)
Dlaczego podjęliśmy tę jedną decyzję i co z niej wynika?
Inżynier, który podjął decyzję
1–2 strony
Wytyczne Google opisują design doc jako miejsce na udokumentowanie ogólnej strategii wdrożenia i kluczowych decyzji projektowych, z naciskiem na kompromisy. Format ADR Michaela Nygarda, opublikowany w 2011 roku, zawęża to do jednej decyzji w pięciu częściach: tytuł, kontekst, decyzja, status i konsekwencje (Michael Nygard, 2011). Jeśli chcesz zacząć od strony produktowej, zajrzyj najpierw do poradnika pisania PRD.
Dlaczego inżynierowie pomijają większość specyfikacji technicznych?
Inżynierowie pomijają specyfikacje, które odpowiadają na pytania, których nikt nie zadał, a chowają te, które mają znaczenie. Większość przypadków tłumaczą trzy wzorce.
Są pisane z myślą o kompletności, nie o decyzjach. Analiza Jakoba Nielsena z 2008 roku wykazała, że na przeciętnej stronie liczącej 593 słowa czytelnicy mieli czas na najwyżej 28% słów, a bardziej prawdopodobne było 20%. Tylko na stronach liczących 111 słów lub mniej docierali do połowy treści. Recenzent z sześcioma specami w kolejce czyta tak samo: podsumowanie, diagram, pogrubiony tekst, a potem sekcja, z którą się nie zgadza.
Chowają ryzykowną decyzję w jednolitym tekście. Jeśli nieodwracalna decyzja siedzi w dziewiątym akapicie, każdy recenzent musi ją wyprowadzać od nowa. To dokładnie ta strata, której spec ma zapobiegać.
Starzeją się. Stack Overflow Developer Survey 2024 wykazał, że 61% respondentów spędza ponad 30 minut dziennie na szukaniu odpowiedzi, a 30% twierdzi, że silosy wiedzy szkodzą ich produktywności 10 lub więcej razy w tygodniu. Spec, który przestaje pasować do kodu, staje się kolejnym źródłem błędnych odpowiedzi.
Korzyść z robienia tego dobrze jest mierzalna. Badania DORA z 2021 roku wykazały, że zespoły z dobrą dokumentacją 3,8 razy chętniej stosowały najlepsze praktyki bezpieczeństwa i 2,5 razy chętniej w pełni korzystały z chmury.
Co powinna zawierać specyfikacja techniczna?
Uwzględniaj tylko to, co zmienia sposób, w jaki ktoś zbudowałby lub zrecenzował pracę. Dwie opublikowane praktyki dają dobrą bazę.
Sekcje design doc w Google
Tekst Malte'a Ubla z 2020 roku o design docs w Google wymienia sekcje wspólne dla większości dokumentów:
Kontekst i zakres: środowisko, w którym działa system, w kilku akapitach.
Cele i nie-cele: co system musi robić, a czego wyraźnie nie będzie robić.
Właściwy projekt: diagram systemu, API, przechowywanie danych oraz kod lub pseudokod tylko tam, gdzie wyjaśnia nowatorski algorytm.
Rozważane alternatywy: inne projekty i dlaczego przegrały.
Zagadnienia przekrojowe: bezpieczeństwo, prywatność i observability.
Sekcje RFC w Uberze
Proces RFC w Uberze rósł razem z firmą, od kilkudziesięciu inżynierów do kilku tysięcy, według Gergelya Orosza, który tam pracował (The Pragmatic Engineer, 2018). Szablon dla backendu zaczynał się od listy osób akceptujących, a potem obejmował zmiany w architekturze, SLA usług, zależności, testy obciążeniowe, kwestie wielu centrów danych, bezpieczeństwo, testowanie i wdrożenie, metryki i monitoring oraz obsługę klienta. Szablon mobilny dodawał UI i dostępność. Sekcje dodawano w miarę, jak firma uczyła się, co ciągle pomija.
Wniosek z obu: szablon specyfikacji technicznej to lista kontrolna dawnych błędów. Zacznij od małego i dodaj sekcję dopiero wtedy, gdy jej brak spowodował realny problem.
Szablon specyfikacji technicznej (skopiuj i dostosuj)
Ten szablon specyfikacji technicznej łączy sekcje Google, uberowy zwyczaj stawiania osób akceptujących na początku i format decyzji Nygarda. Usuń każdą sekcję, w której stałoby tylko „n/d”.
# [Nazwa funkcji lub systemu]: specyfikacja techniczna
**Podsumowanie:** Robimy [X], aby osiągnąć [Y], godząc się na kompromis [Z].
**Autor:** [imię i nazwisko] · **Akceptujący:** [2–3 osoby] · **Review do:** [data]
**Status:** Szkic | W review | Zatwierdzony | Zastąpiony przez [link]
**Powiązany PRD / ticket:** [link]
## 1. Problem i ograniczenia
- Co jest zepsute, kogo to dotyka i co stanie się możliwe po naprawie.
- Twarde ograniczenia: budżet opóźnień, rezydencja danych, wsteczna
kompatybilność, SLA, którego nie wolno złamać.
## 2. Cele i nie-cele
- Cele (mierzalne, gdy to możliwe).
- Nie-cele: rzeczy, których rozsądny czytelnik mógłby się spodziewać, a których nie zrobimy.
## 3. Kluczowe decyzje (przeczytaj najpierw)
| # | Decyzja | Odwracalna? | Ryzyko, jeśli błędna | Pewność |
|---|----------|-------------|---------------|------------|
| 1 | | Drzwi jednokierunkowe / dwukierunkowe | | Wysoka / Średnia / Niska |
## 4. Proponowany projekt
- Jeden diagram. Zmiany w API i modelu danych. Pseudokod tylko dla
tego, co nowatorskie.
## 5. Rozważane alternatywy
- Opcja A: dlaczego przegrała.
- Opcja B: dlaczego przegrała.
- Nie robić nic: co się stanie, jeśli tego nie zbudujemy.
## 6. Ryzyka i otwarte pytania
- Założenia, na których wszystko stoi, i jak je sprawdzimy.
- Pytania, na które potrzebujemy odpowiedzi przed budową lub w jej trakcie.
## 7. Zagadnienia przekrojowe
- Bezpieczeństwo i prywatność · Observability · Dostępność · Koszty.
## 8. Wdrożenie, walidacja i rollback
- Feature flag / plan wdrożenia etapowego.
- Metryki, które dowodzą, że działa, i próg uruchamiający rollback.
## 9. Dziennik decyzji
- [data] Zmieniono [decyzję], ponieważ [powód]. (Aktualizuj tutaj, nie w komentarzu do PR.)
Tabela decyzji w sekcji 3 to część, która sprawia, że szablon się opłaca. Oznaczenie każdej decyzji jako drzwi jednokierunkowych lub dwukierunkowych mówi recenzentom, gdzie skupić uwagę. Framework decyzji odwracalnych i nieodwracalnych wyjaśnia, jak ocenić, która jest którą.
Jak długa powinna być specyfikacja techniczna?
Tak krótka, na ile pozwala najbardziej ryzykowna decyzja. Wytyczne Google określają design docs dużych projektów na około 10–20 stron, a „mini design docs” na 1–3 strony uznają za w porządku przy pracy przyrostowej. ADR-y Nygarda mają jedną lub dwie strony. Amazon zastępuje slajdy „narracyjnie ułożonymi memosami na sześć stron”, czytanymi w ciszy na początku każdego spotkania, a Jeff Bezos napisał, że naprawdę dobry zajmuje prawdopodobnie tydzień lub dłużej (Amazon, 2018).
Praktyczna zasada kciuka, według wielkości zmiany:
Zmiana
Format
Długość
Review
Poprawka błędu, zmiana tekstu, drobna zmiana konfiguracji
Opis ticketu
Akapit
Tylko code review
Nowy endpoint lub komponent w obrębie jednej usługi
Mini spec
1 strona
Jedna osoba akceptująca, asynchronicznie
Funkcja dotykająca 2–3 usług lub publicznego API
Specyfikacja techniczna (szablon powyżej)
2–3 strony
2–3 osoby akceptujące, okno 2–3 dni
Nowy system, migracja danych lub granica bezpieczeństwa
Pełny design doc lub RFC
5–20 stron
Formalne spotkanie review
Wytyczne Google mówią też, kiedy nie pisać: gdy rozwiązanie jest jednoznaczne, a dokument byłby tylko instrukcją wdrożenia bez kompromisów do omówienia.
Jak napisać spec, który inżynierowie naprawdę czytają?
Pisz go w tej kolejności. Większość pracy polega na decydowaniu, co pominąć.
Najpierw napisz podsumowanie w jednym zdaniu. „Robimy X, aby osiągnąć Y, godząc się na kompromis Z.” Jeśli nie umiesz go napisać, nie jesteś gotowy na pisanie specu, a twoi recenzenci też nie będą mogli go streścić.
Zacznij od problemu, nie od rozwiązania. Inżynierowie nie ocenią projektu, dopóki nie znają ograniczeń, którym ma służyć. Podaj rzeczy niepodlegające negocjacji przed diagramem architektury.
Wypełnij tabelę decyzji. Wypisz każdą decyzję, z którą recenzent mógłby się rozsądnie nie zgodzić. Pogrub drzwi jednokierunkowe.
Opisz alternatywy uczciwie. Dodaj „nie robić nic”. Spec bez odrzuconych opcji wygląda jak decyzja już podjęta.
Wskaż dwie lub trzy osoby akceptujące i termin review. Uber umieszczał osoby akceptujące na górze każdego RFC. Spec bez decydenta i daty zwykle wisi w review w nieskończoność.
Rób review asynchronicznie, spotykaj się tylko przy niezgodach. Komentarze w dokumencie załatwiają większość uwag. Jeśli się spotykacie, zrób jak Amazon i przeznaczcie pierwsze dziesięć minut na ciche czytanie.
Aktualizuj spec, gdy budowa go zmienia. W cyklu życia opisanym przez Google dokument jest poprawiany w trakcie wdrożenia. Zapisuj zmiany w dzienniku decyzji, nie w komentarzu do pull requesta, którego nikt nie znajdzie.
Orosz zauważa, że gdy zespół zgodzi się co do planu, spisanie go zwykle zajmuje kilka godzin. Jeśli zajmuje dni, odkryciem jest sama niezgoda.
Przykład krok po kroku (poglądowy)
Powiedzmy, że sześcioosobowy zespół musi sprawić, by wolne webhooki klientów nie powodowały timeoutów w checkout. Ich zdanie-podsumowanie: „Przenosimy dostarczanie webhooków do kolejki, żeby checkout nigdy nie czekał na serwer klienta, godząc się na nawet 60 sekund opóźnienia w dostarczeniu.”
#
Decyzja
Odwracalna?
Ryzyko, jeśli błędna
Pewność
1
Przejść na dostarczanie at-least-once; klienci muszą deduplikować po ID zdarzenia
Drzwi jednokierunkowe (publiczny kontrakt)
Zduplikowane zamówienia w systemach klientów
Średnia
2
Użyć istniejącej bazy Postgres jako kolejki zamiast nowego brokera
Drzwi dwukierunkowe
Limit przepustowości w szczycie; migracja później
Wysoka
3
Ponawiać pięć razy w ciągu 24 godzin, potem oznaczyć jako nieudane
Drzwi dwukierunkowe
Niektórzy klienci tracą zdarzenia przy długich awariach
Wysoka
Recenzenci widzą w 30 sekund, że decyzja 1 zasługuje na debatę: zmienia publiczny kontrakt API, wymaga noty migracyjnej dla klientów i nie da się jej po cichu cofnąć. Decyzje 2 i 3 można zatwierdzić w komentarzu.
Jakie są typowe błędy w specyfikacjach technicznych?
Pisanie specu po kodzie. Spec napisany, by uzasadnić gotowy pull request, nie ma alternatyw i niczego nie wyłapuje.
Pięć diagramów zamiast jednego. Jeden diagram systemu z wyróżnioną zmianą wygrywa z pięcioma, które pokazują wszystko.
Brak właściciela otwartych pytań. Każde otwarte pytanie potrzebuje imienia i daty, inaczej zamieni się w incydent na produkcji.
Zamrożenie dokumentu. Spec, który przestał pasować do budowy, jest gorszy niż brak specu, bo ludzie mu ufają.
Pisanie specu tam, gdzie prototyp odpowiedziałby szybciej. Jeśli ryzykowne pytanie brzmi „czy ta biblioteka uniesie nasze obciążenie?”, jednodniowy spike wygrywa z pięciostronicową argumentacją.
Jak specyfikacje techniczne zmieniają się przy agentach kodujących AI?
Agenci kodujący czytają specyfikacje dosłownie. Niejednoznaczność, którą ludzki inżynier rozstrzygnąłby na Slacku, staje się kodem, który agent pewnie pisze źle. Najważniejsze dla agenta części szablonu to nie-cele, ograniczenia i testowalne kryteria akceptacji. Szablon PRD dla agentów kodujących AI pokazuje, jak je jasno wyrazić. Po zatwierdzeniu specu kolejnym krokiem jest rozbicie PRD na user stories, a pre-mortem przed premierą sprawdza plan wdrożenia pod kątem słabych punktów przed wydaniem.
Gdzie pasuje Specky?
Luka między udokumentowaną intencją a dostarczoną rzeczywistością zwykle otwiera się wtedy, gdy wymagania, decyzje i tickety żyją w różnych narzędziach. Specky pisze PRD w edytorze z cytatami w tekście odsyłającymi do dowodów od klientów, generuje tickety z testowalnymi kryteriami akceptacji i zapisuje decyzje w Product Graph, żeby „dlaczego” pozostawało przy pracy. Agenci kodujący mogą czytać ten kontekst przez serwer MCP. Projekt techniczny nadal pisze inżynier; kontekst produktowy wokół niego pozostaje aktualny. Jeśli wąskim gardłem jest znalezienie czasu na pisanie, przykładowy tygodniowy plan PM-a chroni na to blok skupienia.
Najczęstsze pytania
Jaka jest różnica między PRD a specyfikacją techniczną?
PRD definiuje problem, użytkowników i sposób pomiaru sukcesu; specyfikacja techniczna definiuje, jak zespół zbuduje rozwiązanie i na jakie kompromisy się godzi. Zwykle PRD należy do product managera, a spec do tech leada. Napisz najpierw PRD, a potem zalinkuj go ze specu, żeby recenzenci mogli porównać projekt z pierwotnym celem.
Kto powinien napisać specyfikację techniczną?
Specyfikację techniczną powinien napisać inżynier lub tech lead, który będzie odpowiadał za budowę, a product manager recenzuje ją względem PRD. Autor odpowiada za decyzje, a nie za wpisanie każdej sekcji. W małym zespole PM może naszkicować sekcje problemu, celów i nie-celów, a inżynier uzupełnia projekt, alternatywy i plan wdrożenia.
Jak długi powinien być dokument projektu technicznego?
Większość dokumentów projektu technicznego powinna mieć od jednej do trzech stron. W praktyce Google mini design docs na 1–3 strony są normą przy zmianach przyrostowych, a 10–20 stron zarezerwowano dla dużych nowych systemów. Jeśli twój spec dla funkcji w istniejących usługach przekracza trzy strony, prawdopodobnie miesza kilka decyzji, które powinny być osobnymi ADR-ami.
Czym jest RFC w inżynierii oprogramowania?
RFC (request for comments) to pisemny plan udostępniony szerszej organizacji inżynierskiej przed rozpoczęciem pracy, aby inni mogli wskazać ryzyka. Uber używał RFC, gdy rósł z kilkudziesięciu do kilku tysięcy inżynierów, wymieniając na górze każdego z nich osoby akceptujące z imienia i nazwiska. RFC to specyfikacja techniczna plus proces review, termin i decydent.
Kiedy nie pisać specyfikacji technicznej?
Pomiń spec, gdy rozwiązanie jest jednoznaczne i nie ma istotnych kompromisów do omówienia – taką granicę wyznaczają wytyczne Google. Poprawki błędów, drobne zmiany w UI i aktualizacje konfiguracji należą do ticketu. Jeśli główną niepewnością jest wykonalność techniczna, zrób najpierw spike ograniczony czasowo i napisz spec, gdy będziesz wiedzieć, co działa.
Czym jest architecture decision record (ADR)?
ADR to jedno- lub dwustronicowy zapis pojedynczej decyzji architektonicznej. Format Michaela Nygarda z 2011 roku ma pięć części: tytuł, kontekst, decyzję, status i konsekwencje. Wiele zespołów trzyma ADR-y w repozytorium kodu, aby przyszli inżynierowie widzieli, dlaczego coś zbudowano w określony sposób. Używaj ADR-ów dla decyzji, które przeżywają pojedynczy spec.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing