Szablon dokumentu projektu technicznego
Sześć połączonych dokumentów, które prowadzą system od wymagań do wdrożenia: kontekst, architektura, dane i interfejsy, jak działa i jak się psuje, oraz odrzucone opcje. Pobierz je jako pliki Markdown: otworzysz je w dowolnym edytorze, mogą leżeć obok kodu w repozytorium, rysują diagramy na GitHubie i w Obsidianie, a do Nodary zaimportujesz je jako mapę.
6 plików Markdown w archiwum .zip, 6 kB
Za darmo, bez konta, bez e-maila. Używaj, zmieniaj, udostępniaj.
Przeczytaj każdą stronę przed pobraniem
Przegląd mieści się na jednym ekranie i linkuje do pięciu części: recenzent czyta podsumowanie, a potem idzie prosto do części, która go dotyczy. Kursywa mówi, co napisać; przykłady dotyczą jednej przykładowej funkcji, linków udostępniania, które wygasają.
Dokumenty
Plik Szablon dokumentu projektu technicznego/Dokument projektu technicznego.md
Dokument projektu technicznego
Jak korzystać z szablonu: wiersze kursywą to wskazówki. Zastąp je własnymi słowami, a potem usuń. Wartości w nawiasach kwadratowych uzupełniasz sam. Utrzymaj tę stronę na jednym ekranie: recenzent powinien z niej wiedzieć, co zatwierdza.
W skrócie
| Pole | Ten projekt |
|---|---|
| System lub funkcja | [Nazwa] |
| Autor | [imię i nazwisko] |
| Recenzenci | [nazwiska] |
| Status | [szkic, w przeglądzie, zatwierdzony, zrealizowany] |
| Wymagania | [link do PRD] |
| Docelowe wydanie | [data lub wersja] |
Podsumowanie
Trzy zdania: co zbudujesz, dlaczego i jedna decyzja, którą recenzent powinien obejrzeć najpierw.
Przykład (przykładowa funkcja): Linki udostępniania dostają opcjonalną datę końcową. Każde żądanie sprawdza datę, więc link przestaje działać dokładnie w chwili, gdy wygasa. Zaplanowane zadanie co minutę unieważnia wygasłe linki; tylko sprząta, więc jego opóźnienie niczego nie zmienia dla osoby, która otwiera link.
[Twoje podsumowanie]
Cele i nie-cele
- Cel: [...]
- Cel: [...]
- Nie-cel: [...]
- Nie-cel: [...]
Reszta projektu
Każda część to osobny dokument. Linkuj do niej, zamiast kopiować, żeby każdy fakt żył w jednym miejscu.
- Kontekst i wymagania: co istnieje dziś, wymagania i ograniczenia
- Architektura: komponenty, droga żądania i kluczowe decyzje
- Dane i interfejsy: model danych, API, zdarzenia i migracja
- Utrzymanie: wdrażanie, monitorowanie, bezpieczeństwo i rodzaje awarii
- Alternatywy i ryzyka: odrzucone opcje, ryzyka, wdrożenie i otwarte pytania
Z tego szablonu możesz swobodnie korzystać, a także go zmieniać i udostępniać. Pochodzi z Nodary, gdzie te pliki importują się jako mapa połączonych dokumentów.
Plik Szablon dokumentu projektu technicznego/Dokument projektu technicznego/01 Kontekst i wymagania.md
Kontekst i wymagania
Stan obecny
Co istnieje dziś i co z tym nie tak, w kilku zdaniach. Podlinkuj kod, pulpity i wcześniejsze projekty.
[Stan obecny]
Wymagania
Wymagania, które kształtują projekt, każde połączone ze swoim źródłem. Pomiń te, których projekt nie dotyczy.
| ID | Wymaganie | Źródło |
|---|---|---|
| [W1] | [...] | [PRD, incydent, przepis] |
| [W2] | [...] | [...] |
Przykład (przykładowa funkcja): W1: link przestaje się otwierać najpóźniej minutę po dacie końcowej. Źródło: kryteria akceptacji w PRD.
Ograniczenia
- Wydajność: [...]
- Bezpieczeństwo i prywatność: [...]
- Zgodność: [...]
- Zespół i czas: [...]
Założenia
- [Założenie], sprawdza [imię i nazwisko]
- [...]
Plik Szablon dokumentu projektu technicznego/Dokument projektu technicznego/02 Architektura.md
Architektura
Komponenty
Zastąp te prostokąty własnymi. Zaznacz, co jest nowe, co się zmienia, a co zostaje bez zmian.
- KlientAPI
- APIUsługa
- UsługaBaza danychKolejka zadańMagazyn plików
- Kolejka zadańBaza danych
Mermaid
flowchart TD n0["Klient"] n1["API"] n2["Usługa"] n3["Baza danych"] n4["Kolejka zadań"] n5["Magazyn plików"] n0 --> n1 n1 --> n2 n2 --> n3 n2 --> n4 n4 --> n3 n2 --> n5
| Komponent | Odpowiedzialność | Zespół | Nowy czy zmieniony |
|---|---|---|---|
| [API] | [...] | [zespół] | [nowy, zmieniony, bez zmian] |
| [...] | [...] | [...] | [...] |
Droga żądania
Prześledź jedno żądanie od akcji użytkownika do odpowiedzi. Numeruj kroki: recenzenci komentują je po numerach.
- [Użytkownik robi ...]
- [API sprawdza ...]
- [Usługa zapisuje ...]
- [Odpowiedź mówi ...]
Kluczowe decyzje
Wybory, z którymi recenzent musi się zgodzić. Każdemu ważnemu daj wpis w rejestrze decyzji zespołu i podlinkuj go tutaj.
| Decyzja | Dlaczego | Wpis |
|---|---|---|
| [...] | [...] | [link] |
Plik Szablon dokumentu projektu technicznego/Dokument projektu technicznego/03 Dane i interfejsy.md
Dane i interfejsy
Model danych
| Encja | Pole | Typ | Uwagi |
|---|---|---|---|
| [...] | [...] | [...] | [opcjonalne, indeksowane, dane osobowe] |
| [...] | [...] | [...] | [...] |
Przykład (przykładowa funkcja): sharelink.expiresat: znacznik czasu ze strefą czasową, pusty, gdy link nie ma końca, indeksowany dla zadania, które unieważnia wygasłe linki.
API
| Metoda | Ścieżka | Cel | Kto może wywołać |
|---|---|---|---|
| [POST] | [/...] | [...] | [...] |
| [...] | [...] | [...] | [...] |
Zdarzenia
| Zdarzenie | Wysyłane, gdy | Czytane przez |
|---|---|---|
| [...] | [...] | [...] |
Migracja
Jak istniejące dane przejdą do nowej postaci bez przestoju i jak to cofnąć.
- [Dodać nowe pola, puste]
- [Zapisywać do starego i nowego]
- [Uzupełnić historię]
- [Czytać z nowego]
- [Usunąć stare]
Plik Szablon dokumentu projektu technicznego/Dokument projektu technicznego/04 Utrzymanie.md
Utrzymanie
Wdrażanie
- Gdzie działa: [...]
- Jak jest wydawany: [pipeline, flagi]
- Konfiguracja i sekrety: [...]
Monitorowanie i alerty
| Sygnał | Norma | Alert, gdy | Alert trafia do |
|---|---|---|---|
| [odsetek błędów] | [...] | [...] | [zespół] |
| [...] | [...] | [...] | [...] |
Bezpieczeństwo i prywatność
- Każde żądanie sprawdza, kto pyta i co mu wolno
- Dane osobowe wypisane, z miejscem i czasem przechowywania
- Sekrety poza kodem i logami
- Dane wejściowe sprawdzane tam, gdzie wchodzą do systemu
- Nadużycia i limity zapytań przemyślane
Rodzaje awarii
| Awaria | Co widzą użytkownicy | Jak to zauważamy | Jak wracamy do normy |
|---|---|---|---|
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |
Przykład (przykładowa funkcja): Zadanie unieważniające staje: wygasłe linki nadal są odrzucane, bo każde żądanie sprawdza datę; opóźnia się tylko sprzątanie. Alert włącza się, gdy zadanie nie działało przez pięć minut.
Plik Szablon dokumentu projektu technicznego/Dokument projektu technicznego/05 Alternatywy i ryzyka.md
Alternatywy i ryzyka
Rozważane alternatywy
| Opcja | Za | Przeciw | Dlaczego nie |
|---|---|---|---|
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |
Ryzyka
| Ryzyko | Wpływ | Co z tym robimy | Właściciel |
|---|---|---|---|
| [...] | [niski, średni, wysoki] | [...] | [imię i nazwisko] |
Stopniowe wdrażanie
- Za flagą, dla [zespołu]
- [Niewielka część] [użytkowników]
- Wszyscy
- Flaga usunięta
Otwarte pytania
- [Pytanie], [kto odpowiada], [do kiedy]
Jak z niego korzystać
Zacznij od wymagań
Podlinkuj wymagania produktowe na stronie kontekstu i wypisz te, które kształtują projekt. Projekt, który nie odpowiada na żadne wymaganie, to przebrany refaktoring.
Najpierw rysuj, potem pisz
Narysuj komponenty i wywołania między nimi przed tekstem. Recenzent szybciej zauważy brakujący prostokąt niż brakujący akapit.
Zapisz, co odrzuciłeś
Wypełnij alternatywy opcjami, które naprawdę rozważałeś. Przegląd nie będzie ich otwierał po kolei na nowo.
Zaktualizuj go po realizacji
Gdy kod zostanie wydany, zaznacz, co zmieniło się względem planu. Następna osoba czyta projekt, żeby zrozumieć, jak system działa, a nie jak go sobie wyobrażono.
Zaimportuj go do Nodary jako mapę
Nodary to przestrzeń robocza oparta na AI, w której dokumenty zespołu łączą się ze sobą, zamiast się piętrzyć. Zaimportuj .zip, a projekt pojawi się z pięcioma częściami pod sobą, z zachowanymi linkami i diagramem narysowanym jako edytowalny diagram Mermaid. Recenzenci komentują fragment albo element diagramu, autorka prosi o zatwierdzenie, a agenci do programowania, tacy jak Cursor, Claude Code czy VS Code, połączeni przez MCP, czytają projekt, zanim napiszą kod.
- Otwórz mapę projektu i wybierz „Importuj”.
- Wybierz kartę „Folder lub ZIP”, a potem „Wybierz plik ZIP”.
- Wskaż pobrany plik, sprawdź drzewo i zaimportuj.
Plan Free mieści dziesięć dokumentów na przestrzeń roboczą, wliczając stronę samego projektu: sześć dokumentów szablonu zostawia miejsce na trzy kolejne. Nodary ma też wbudowany jednostronicowy szablon projektu technicznego.
Połącz Cursor, Claude Code lub VS Code z Nodary
Jak pisać projekt, który recenzenci mogą zatwierdzić
Dokument projektu technicznego zawodzi, gdy recenzenci nie wiedzą, co zatwierdzają, albo gdy opisany system nie jest tym, który wydano. Te nawyki zapobiegają obu sytuacjom.
Zacznij od decyzji
Napisz w podsumowaniu, co zbudujesz i który wybór recenzent powinien obejrzeć najpierw. Nikt nie powinien szukać go na trzeciej stronie.
Rysuj przed pisaniem
Diagram sześciu prostokątów i ich wywołań zastępuje sześć stron tekstu i od razu pokazuje brakujący element.
Powiedz, czego nie zrobisz
Nie-cele trzymają przegląd przy przedstawionym projekcie, a nie przy tym, który ktoś wolałby przeczytać.
Pokaż odrzucone opcje
Przy każdym ważnym wyborze napisz, co jeszcze rozważałeś i dlaczego nie. Recenzenci dyskutują wtedy z twoimi powodami, a nie z wnioskiem.
Zaplanuj awarię
Napisz, co się dzieje, gdy każda część przestaje działać, jak to zauważysz i jak wrócisz do normy. Utrzymanie jest częścią projektu, nie załącznikiem.
Utrzymuj go w zgodzie z kodem
Zaznacz, co zmieniło się podczas realizacji, i podlinkuj decyzje, które to wyjaśniają. Projekt zgodny z kodem to dokumentacja; niezgodny to pułapka.
Pytania o dokument projektu technicznego
Czym jest dokument projektu technicznego?
Dokument projektu technicznego (technical design document, TDD) opisuje, jak zostanie zbudowany system lub funkcja, zanim powstanie kod: kontekst i wymagania, architekturę, dane i interfejsy, wdrażanie i monitorowanie, ryzyka i rozważane alternatywy. Piszą go inżynierowie, żeby inni mogli ocenić podejście, póki jego zmiana jest tania.
Co powinien zawierać dokument projektu technicznego?
Podsumowanie z celami i nie-celami, stan obecny i wymagania, komponenty i sposób ich komunikacji, model danych i API, wdrażanie, monitorowanie, bezpieczeństwo i rodzaje awarii, rozważane alternatywy, ryzyka, plan wdrożenia i otwarte pytania. Ten szablon ma dokument dla każdej grupy.
Czym różni się od PRD?
Dokument wymagań produktowych mówi, co funkcja musi robić i dlaczego. Dokument projektu technicznego mówi, jak zrobi to system. Najpierw napisz PRD, a potem podlinkuj go z projektu, żeby każde wymaganie dało się prześledzić.
Kiedy zmiana potrzebuje dokumentu projektu?
Gdy dotyczy kilku komponentów lub zespołów, zmienia istniejące dane, trudno ją cofnąć albo niesie ryzyko warte drugiej pary oczu. Mała zmiana w jednym komponencie zwykle potrzebuje dobrego pull requesta, a nie dokumentu projektu.
Kto powinien recenzować dokument projektu technicznego?
Inżynierowie, którzy go zbudują i będą utrzymywać, po jednym inżynierze z każdego dotkniętego systemu oraz osoba odpowiedzialna za bezpieczeństwo, gdy w grę wchodzą dane osobowe lub dostępy. Poproś o recenzję wcześnie, zanim powstanie większość kodu.
Czy zespoły tworzące gry też piszą dokumenty projektu technicznego?
Tak. Szablon dokumentu projektowego gry ma część o projekcie technicznym dla silnika, platform docelowych i pipeline’u; duży system, taki jak sieć, zapisy gry czy narzędzia, zasługuje na własny dokument projektu technicznego, podlinkowany z GDD.
Trzymaj projekt przy ludziach i agentach, którzy go budują.
Zaimportuj szablon do Nodary, a projekt stanie się mapą, którą twój zespół i twoi agenci do programowania czytają, zanim zmienią system. Za darmo dla dwóch członków, jednego projektu i dziesięciu dokumentów, bez karty.