# 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ę.

Za darmo, bez konta, bez e-maila. Używaj, zmieniaj, udostępniaj.

[Pobierz szablon (.zip)](https://nodary.ai/downloads/szablon-dokumentu-projektu-technicznego.zip)

## 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ą.

- Dokument projektu technicznego: Strona, którą wszyscy czytają najpierw: podsumowanie, cele i nie-cele oraz link do każdej części.
- Kontekst i wymagania: Co istnieje dziś, wymagania, które projekt musi spełnić, i ograniczenia wokół niego.
- Architektura: Komponenty, jak się ze sobą komunikują, jaką drogę przechodzi żądanie i kluczowe decyzje.
- Dane i interfejsy: Model danych, API i zdarzenia oraz to, jak istniejące dane przechodzą do nowej postaci.
- Utrzymanie: Jak system jest wdrażany i monitorowany, jak pozostaje bezpieczny i co się dzieje, gdy coś przestaje działać.
- Alternatywy i ryzyka: Odrzucone opcje i powody, ryzyka, plan wdrożenia i otwarte pytania.

### 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](https://nodary.ai/pl/templates/technical-design-document#doc-context): co istnieje dziś, wymagania i ograniczenia
- [Architektura](https://nodary.ai/pl/templates/technical-design-document#doc-architecture): komponenty, droga żądania i kluczowe decyzje
- [Dane i interfejsy](https://nodary.ai/pl/templates/technical-design-document#doc-data): model danych, API, zdarzenia i migracja
- [Utrzymanie](https://nodary.ai/pl/templates/technical-design-document#doc-operations): wdrażanie, monitorowanie, bezpieczeństwo i rodzaje awarii
- [Alternatywy i ryzyka](https://nodary.ai/pl/templates/technical-design-document#doc-alternatives): 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](https://nodary.ai/pl)_, gdzie te pliki importują się jako mapa połączonych dokumentów._

### Kontekst i wymagania

**Właściciel:** [imię i nazwisko] · **Status:** szkic · **Ostatni przegląd:** [data]

#### 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]
- [...]

Zobacz też: [Dokument projektu technicznego](https://nodary.ai/pl/templates/technical-design-document#doc-overview) · [Architektura](https://nodary.ai/pl/templates/technical-design-document#doc-architecture)

### Architektura

**Właściciel:** [imię i nazwisko] · **Status:** szkic · **Ostatni przegląd:** [data]

#### Komponenty

_Zastąp te prostokąty własnymi. Zaznacz, co jest nowe, co się zmienia, a co zostaje bez zmian._

```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
```
_Główne komponenty i wywołania między nimi_

| 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._

1. [Użytkownik robi ...]
2. [API sprawdza ...]
3. [Usługa zapisuje ...]
4. [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] |

Zobacz też: [Kontekst i wymagania](https://nodary.ai/pl/templates/technical-design-document#doc-context) · [Dane i interfejsy](https://nodary.ai/pl/templates/technical-design-document#doc-data) · [Utrzymanie](https://nodary.ai/pl/templates/technical-design-document#doc-operations)

### Dane i interfejsy

**Właściciel:** [imię i nazwisko] · **Status:** szkic · **Ostatni przegląd:** [data]

#### Model danych

| Encja | Pole | Typ | Uwagi |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [opcjonalne, indeksowane, dane osobowe] |
| [...] | [...] | [...] | [...] |

_Przykład (przykładowa funkcja): share__link.expires__at: 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ąć._

1. [Dodać nowe pola, puste]
2. [Zapisywać do starego i nowego]
3. [Uzupełnić historię]
4. [Czytać z nowego]
5. [Usunąć stare]

Zobacz też: [Architektura](https://nodary.ai/pl/templates/technical-design-document#doc-architecture) · [Utrzymanie](https://nodary.ai/pl/templates/technical-design-document#doc-operations)

### Utrzymanie

**Właściciel:** [imię i nazwisko] · **Status:** szkic · **Ostatni przegląd:** [data]

#### 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._

Zobacz też: [Architektura](https://nodary.ai/pl/templates/technical-design-document#doc-architecture) · [Alternatywy i ryzyka](https://nodary.ai/pl/templates/technical-design-document#doc-alternatives)

### Alternatywy i ryzyka

**Właściciel:** [imię i nazwisko] · **Status:** szkic · **Ostatni przegląd:** [data]

#### 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

1. Za flagą, dla [zespołu]
2. [Niewielka część] [użytkowników]
3. Wszyscy
4. Flaga usunięta

#### Otwarte pytania

- [ ] [Pytanie], [kto odpowiada], [do kiedy]

Zobacz też: [Dokument projektu technicznego](https://nodary.ai/pl/templates/technical-design-document#doc-overview) · [Kontekst i wymagania](https://nodary.ai/pl/templates/technical-design-document#doc-context) · [Utrzymanie](https://nodary.ai/pl/templates/technical-design-document#doc-operations)

## 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.

1. Otwórz mapę projektu i wybierz „Importuj”.
2. Wybierz kartę „Folder lub ZIP”, a potem „Wybierz plik ZIP”.
3. 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.

## 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.

Strona: https://nodary.ai/pl/templates/technical-design-document