📐Dokumentace10 min čteníAktualizováno: 15. 11. 2026

Dokument návrhu softwaru: šablona a příklad

Jak napsat dokument návrhu, podle kterého lze řešení posoudit před implementací: cíle, omezení, architektura, alternativy, rizika, provoz i rollout.

👨‍💻
Roman
AboutTheApp

Shrnutí a kontext

Dokument návrhu softwaru (software design document neboli design doc) převádí požadavky do technického řešení, které lze připomínkovat dřív, než je obtížné je změnit. Dobrý návrh nepopisuje jen komponenty a API. Vysvětluje také cíle, omezení, alternativy, rizika, bezpečnost, provoz a způsob bezpečného nasazení. Tento článek nabízí praktickou šablonu, příklad a pravidla pro revizi i další život dokumentu.

Čtyři role revidují návrh z pohledu produktu, vývoje, bezpečnosti a provozu. Společná revize vede ke schválenému návrhu, ADR a navazujícím úkolům.

1. K čemu dokument návrhu slouží

Design doc odpovídá především na otázku, jak tým vyřeší konkrétní problém a jaké důsledky bude řešení mít. Na otázky co a proč obvykle odpovídá zadání produktu (PRD). Podrobné funkční požadavky a jejich ověření zachycuje specifikace softwarových požadavků (SRS). Návrh z těchto požadavků vychází, ale nesmí je jen převyprávět technickými slovy.

Hlavní hodnotou dokumentu je včasná revize. Vývoj, provoz, bezpečnost nebo datový tým mohou odhalit chybějící požadavek, nebezpečný předpoklad či levnější variantu ještě před implementací. Po schválení dokument zachycuje výchozí rozhodnutí a jejich důvody; není však automaticky přesným popisem později změněného systému.

Ne každá změna potřebuje design doc

Oprava chyby nebo malá lokální úprava obvykle vystačí s popisem v úkolu. Jedno významné rozhodnutí může mít vlastní ADR. Design doc dává smysl, když změna zasahuje více komponent, dat, týmů nebo kvalitativních požadavků a potřebuje společnou revizi.

2. Neexistuje jedna povinná šablona

IEEE 1016-2009 popisuje obsah a uspořádání Software Design Description, ale od roku 2020 má stav Inactive-Reserved. Může být užitečným zdrojem a někde jej může vyžadovat smlouva, není však současným univerzálním předpisem pro každý vývojový tým.

Platná ISO/IEC/IEEE 42010:2022 se věnuje popisu architektury. Klade důraz na zainteresované strany, jejich otázky a odpovídající pohledy na systém, ale nepředepisuje jednu sadu kapitol ani konkrétní notaci. To je užitečný princip i pro běžný design doc: dokumentujte právě ty pohledy, které lidé potřebují k posouzení daného návrhu.

Pro rozsáhlejší dokumentaci celé architektury lze použít arc42. Pro diagramy nabízí model C4 postup od kontextu systému přes kontejnery ke komponentám. Kratší design doc pro jednu změnu může z těchto přístupů čerpat, aniž by mechanicky přebíral všechny jejich části.

FormátKdy se hodíCo zachycuje
Design docVětší funkce, nový systém nebo změna více částíNavrhované řešení, alternativy, rizika a plán dodání
ADRJedno významné a dlouhodobé rozhodnutíKontext, rozhodnutí, důsledky a stav
arc42Průběžná dokumentace architektury celého systémuVíce pohledů od cílů a kontextu po provozní rizika
IEEE 1016Smlouva nebo proces výslovně požaduje formální SDDFormální obsah návrhu a pohledy pro zainteresované strany

3. Šablona dokumentu návrhu ke zkopírování

Šablonu přizpůsobte riziku a rozsahu změny. Nepotřebnou část můžete vynechat, ale u bezpečnosti, migrace nebo provozu stručně vysvětlete, proč se návrhu netýká. Revidující pak poznají rozdíl mezi vědomým rozhodnutím a opomenutím.

DESIGN.md
# <Název systému nebo změny>: návrh

Autor: <jméno nebo tým>
Revidující: <vývoj, provoz, bezpečnost, produkt podle potřeby>
Stav: Koncept | K připomínkám | Schváleno | Nahrazeno
Datum: <RRRR-MM-DD> · Zadání: <odkaz> · Implementace: <odkaz>

## 1. Shrnutí a kontext
Jaký problém řešíme, pro koho a jak vypadá současný stav.

## 2. Cíle a ne-cíle
- Měřitelný nebo ověřitelný cíl
- Co je vědomě mimo rozsah

## 3. Požadavky, omezení a předpoklady
Funkční požadavky a důležité kvalitativní cíle: dostupnost, výkon,
bezpečnost, soukromí, přístupnost, náklady nebo regulatorní povinnosti.
Technická a organizační omezení. Předpoklady, které je třeba ověřit.

## 4. Navrhované řešení
### 4.1 Kontext a hranice systému
Uživatelé, okolní systémy, vlastnictví a důvěryhodnostní hranice.
### 4.2 Komponenty a odpovědnosti
Hlavní části řešení a jejich vazby.
### 4.3 Kritické běhové scénáře
Jak systém spolupracuje při nejdůležitějších tocích a chybových stavech.
### 4.4 Data a rozhraní
Datový model, vlastnictví dat, API, události a zpětná kompatibilita.

## 5. Alternativy a kompromisy
| Varianta | Přínosy | Nevýhody a rizika | Rozhodnutí |

## 6. Bezpečnost a soukromí
Autentizace, autorizace, citlivá data, hrozby, audit a správa tajemství.

## 7. Spolehlivost a provoz
Selhání závislostí, monitoring, alerty, kapacita, zálohy, obnova a podpora.

## 8. Dodání, migrace a návrat
Pořadí změn, datová migrace, feature flags, ověření, rollout a rollback.

## 9. Testování a přijetí
Jak ověříme funkční i kvalitativní cíle a kdo výsledek přijme.

## 10. Rizika a otevřené otázky
- Riziko nebo otázka · vlastník · termín nebo způsob ověření

## 11. Rozhodnutí a navazující dokumentace
- Přijaté rozhodnutí · datum · odkaz na ADR, diagram, runbook nebo API

4. Jak návrh napsat a nechat zrevidovat

Microsoft doporučuje, aby technický návrh zahrnoval smlouvy API a dat, zpětnou kompatibilitu, bezpečnost a soukromí, rollout a rollback, testování, monitoring i alternativy. Ne každá změna potřebuje ve všech oblastech stejnou hloubku; rozsah má odpovídat riziku.

  1. 1

    Vymezte problém a hranice

    Začněte současným stavem, cíli, ne-cíli a omezeními. Uveďte měřitelné požadavky, například očekávanou zátěž nebo dobu obnovy, místo slov jako „rychlé“ a „spolehlivé“.

  2. 2

    Popište řešení od celku k detailu

    Nejprve ukažte hranici systému a okolní závislosti, potom komponenty, klíčové běhové scénáře, data a rozhraní. Každý diagram opatřete názvem, legendou a krátkým vysvětlením toho, co má čtenář posoudit.

  3. 3

    Porovnejte skutečné alternativy

    Zahrňte i variantu nic neměnit, koupit hotové řešení nebo rozšířit existující komponentu, pokud připadají v úvahu. Uveďte kompromisy v nákladech, složitosti, rychlosti dodání a provozním riziku.

  4. 4

    Navrhněte selhání, migraci a návrat

    Popište, co se stane při nedostupnosti závislosti, přerušení migrace nebo částečném nasazení. Kritické toky potřebují detekci problému, omezení dopadu a realistický návrat do bezpečného stavu.

  5. 5

    Vyberte revidující podle rizik

    Vedle vývojářů přizvěte podle dopadu také provoz, bezpečnost, správce dat, testování nebo produkt. Nečekejte nutně na hotový dokument; nejrizikovější předpoklady lze konzultovat nebo ověřit prototypem dřív.

  6. 6

    Před implementací uzavřete blokující otázky

    Dokument může být schválen i s neblokujícími úkoly, pokud mají vlastníka a termín. Nejasnosti, které mohou změnit architekturu, bezpečnost nebo proveditelnost, však vyřešte před drahou či obtížně vratnou prací.

5. Zkrácený příklad: rezervace zasedaček

Příklad ukazuje úroveň detailu pro malou interní aplikaci. Skutečný návrh by doplnil diagramy a odkazy na konkrétní požadavky, smlouvy API a provozní postupy.

DESIGN.md
# Rezervace zasedaček: návrh

Autor: tým Interní systémy · Revidující: IT provoz, bezpečnost, produkt
Stav: K připomínkám · Datum: 2026-11-15 · Zadání: PRD-014

## 1. Shrnutí a kontext
Rezervace ve sdílené tabulce se překrývají a nelze spolehlivě zjistit obsazenost.
Nová interní webová aplikace použije stávající firemní přihlášení.

## 2. Cíle a ne-cíle
- Zabránit dvěma potvrzeným rezervacím stejné místnosti ve stejný čas.
- Zobrazit denní obsazenost do 2 sekund při 200 souběžných uživatelích.
- Mimo rozsah: platby a synchronizace s externími kalendáři.

## 3. Požadavky a omezení
- Dostupnost v pracovní době 99,9 % měsíčně.
- Provoz pouze v infrastruktuře firmy; přihlášení přes OIDC.
- Jméno rezervujícího uchovávat 90 dní po skončení rezervace.

## 4. Navrhované řešení
Webový frontend volá REST API, které ukládá místnosti a rezervace do PostgreSQL.
Databázové omezení nad místností a časovým rozsahem zabrání souběžnému zápisu
překrývajících se rezervací. API při konfliktu vrátí HTTP 409.

Kritický tok: uživatel odešle rezervaci → API ověří OIDC token → databáze
potvrdí zápis nebo odmítne překryv → aplikace zobrazí aktuální stav.

## 5. Alternativy
| Varianta | Přínosy | Nevýhody | Rozhodnutí |
| Firemní kalendář | Bez vlastního vývoje | Neřeší požadovaná pravidla místností | Zamítnuto po prototypu |
| SaaS služba | Rychlé zavedení | Data mimo firmu a cena za uživatele | Zamítnuto kvůli omezením |

## 6. Bezpečnost a soukromí
Přístup jen pro firemní účty. API ověřuje oprávnění na každém požadavku.
Tajné hodnoty jsou v trezoru, ne v repozitáři ani v tomto dokumentu.

## 7. Spolehlivost a provoz
Při výpadku databáze se nové rezervace nepřijímají a uživatel dostane jasnou chybu.
Monitoring sleduje dostupnost API, chybovost a dobu odpovědi. Denní záloha,
cíl obnovy RPO 24 hodin a RTO 4 hodiny.

## 8. Dodání a návrat
Nejprve staging se syntetickými daty, potom pilot pro jedno patro.
Po ověření se aplikace otevře celé firmě. Návrat vypne přístup k nové aplikaci;
tabulka zůstane během pilotu dostupná jen pro čtení.

## 9. Testování
Test souběžných rezervací, integrační test OIDC, obnova zálohy a zátěžový test cíle 2 s.

## 10. Rizika a otázky
- Potvrdit retenční dobu se správcem osobních údajů · vlastník: produkt · do 2026-11-20
- Ověřit podporu databázového omezení na cílovém hostingu · vlastník: vývoj

## 11. Rozhodnutí
- Kontrola překryvu v databázi, ne pouze v API · ADR-001

6. Co má revidující ověřit

Revize nemá kontrolovat jen to, zda diagram vypadá správně. Má zjistit, zda návrh řeší správný problém, stojí na ověřených předpokladech a je možné jej bezpečně postavit, provozovat a případně vrátit.

Kontrolní seznamKliknutím označte

7. Co s dokumentem po schválení

Schválený návrh není neměnný slib. Během implementace mohou testy, prototyp nebo omezení dodavatele odhalit nutnou změnu. Významnou odchylku zaznamenejte v dokumentu nebo v navazujícím ADR a nechte ji znovu posoudit lidmi, kterých se týká.

Po dokončení označte skutečný stav a přidejte odkazy na implementaci, ADR, provozní postupy a aktuální diagramy. Google doporučuje používat design docs po implementaci jako archiv rozhodnutí, nikoli jako napůl platnou provozní dokumentaci. Aktuální API, nasazení a runbooky proto udržujte v jejich dlouhodobých zdrojích pravdy.

8. Kde dokument uložit

Dokument uložte tam, kde jej mohou revidující připomínkovat a kde zůstane dostupný společně s dokumentací systému. Pro návrh těsně svázaný s kódem bývá vhodný repozitář a běžná code review. Pro mezioborový návrh může být praktičtější wiki nebo dokumentový systém. Důležitější než nástroj je stabilní odkaz, historie změn, přístupová práva a jasný vlastník.

Na návrh odkazujte ze zadání, implementačních úkolů a architektonického rozcestníku. Pokud tým používá AboutTheApp jako přehled aplikací, může být odkaz na design doc jedním z odkazů u aplikace. Samotný návrh však zůstává ve svém zdroji pravdy. Více vysvětluje článek Jak vytvořit interní wiki.

Do návrhu nepatří tajné hodnoty

Popište způsob správy hesel, certifikátů a API klíčů, ale nevkládejte jejich hodnoty. Dokument bývá sdílen širšímu okruhu lidí než produkční trezor.

Časté otázky

Jaký je rozdíl mezi dokumentem návrhu a PRD?

PRD popisuje problém, očekávaný přínos a požadavky. Design doc vysvětluje technické řešení, jeho omezení, alternativy, rizika a způsob bezpečného dodání.

Je IEEE 1016 povinná norma pro design doc?

Ne obecně. IEEE 1016-2009 má stav Inactive-Reserved. Použijte ji, pokud ji vyžaduje smlouva nebo váš proces; jinak zvolte šablonu odpovídající riziku a potřebám revidujících.

Kdo má dokument návrhu psát a revidovat?

Autorem bývá člověk nebo tým odpovědný za řešení. Revidující vybírejte podle dopadu: vedle vývoje může být potřeba provoz, bezpečnost, data, testování, produkt nebo vlastník okolního systému.

Jak dlouhý má být dokument návrhu?

Tak krátký, jak je možné, a tak podrobný, aby šlo posoudit důležitá rozhodnutí a rizika. Malá změna může mít jednu stránku, složitý systém více dokumentů a pohledů. Počet stran sám o sobě kvalitu neurčuje.

Má se design doc po implementaci aktualizovat?

Významné odchylky od schváleného návrhu zaznamenejte. Po dokončení dokument označte jako implementovaný nebo nahrazený a propojte jej s aktuální architekturou, API a runbooky. Nepoužívejte starý návrh jako jedinou provozní dokumentaci.

Ve zkratce

Dokument návrhu umožňuje posoudit technické řešení dřív, než se obtížně mění. Má propojit cíle a omezení s architekturou, alternativami, bezpečností, provozem, migrací a ověřením. Po implementaci slouží jako záznam rozhodnutí, zatímco aktuální provozní informace se udržují ve svých zdrojích pravdy.

AboutTheApp

Potřebujete propojit návrh s ostatními podklady aplikace?

AboutTheApp může sloužit jako rozcestník pro zadání, návrh, diagramy, repozitář a provozní dokumentaci.