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.
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.
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.
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át | Kdy se hodí | Co zachycuje |
|---|---|---|
| Design doc | Větší funkce, nový systém nebo změna více částí | Navrhované řešení, alternativy, rizika a plán dodání |
| ADR | Jedno významné a dlouhodobé rozhodnutí | Kontext, rozhodnutí, důsledky a stav |
| arc42 | Průběžná dokumentace architektury celého systému | Více pohledů od cílů a kontextu po provozní rizika |
| IEEE 1016 | Smlouva nebo proces výslovně požaduje formální SDD | Formá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.
# <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 API4. 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
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
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
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
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
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
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.
# 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-0016. 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.
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.
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.
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.