Ako napísať technické špecifikácie, ktoré skutočne lode

Ak čítate toto, je pravdepodobné, že ste sa pozreli na polovične dokončenú technickú špecifikáciu o 2am, zúfalo sa snažia zabaliť pred vystúpením. alebo možno ste boli na prijímacom konci - sloging cez niekoho iného 47-stránkového opusu, premýšľajúc o tom, či neobmedzený PTO stojí za to. Ale tu je vec: keď je to dobre vykonané, technické špecifikácie nie sú domáce úlohy z vášho tech vedúceho. Sú jedným z najsilnejších nástrojov, ktoré musíte previesť funkcie z myšlienky do výroby. Ukážem vám, ako ich pristupujem k písaniu, na základe mojich skúseností v Monzo a lekcií, ktoré som si vybral od inžinierov v AWS, Google a Meta. My background is software engineering, but a lot of this transfers to other technical disciplines. Let's dive in. Prečo písať technické špecifikácie tak či tak? Písanie dokumentácie sa cíti ako buswork, keď by ste mohli byť prepravný kód. ale držte sa ma tu, pretože dobrý technický špecifikácia robí viac ako uspokojiť niektoré procesné požiadavky. Pri dobrom používaní vám technické špecifikácie pomôžu: Overte myšlienku skôr, než strávite týždne budovaním - zabila som viac zlých myšlienok počas fázy špecifikácie, než mi záleží priznať. Získajte buy-in od ľudí, ktorí skutočne záleží - váš personálny inžinier, váš produktový manažér, ten hlavný inžinier, ktorý to všetko videl. Iterujte na vysokej úrovni s inteligentnejšími ľuďmi ako vy - nie som najinteligentnejší človek v miestnosti, a ak ste úprimní so sebou, ani vy. Zdieľajte svoje vedomosti so svojím tímom – prijímanie nových inžinierov sa stáva „prečítajte si túto špecifikáciu“ namiesto „dovoľte mi vysvetliť túto architektúru tretíkrát tento týždeň“. Zdieľajte vedomosti so zainteresovanými stranami mimo inžinierstva - Váš produktový manažér, tím zhody alebo ľudia z oblasti financií potrebujú pochopiť, čo budujete a prečo. Používať ako overenie, keď je práca dokončená – V skutočnosti ste vyriešili to, čo ste sa rozhodli vyriešiť? Spec-Driven vývoj a LLMs LLM zmenili spôsob, akým si myslím o technických špecifikáciách. LLM funguje najlepšie s prísnymi technickými špecifikáciami. Čím menej necháte na fantáziu, tým lepšie. Dobre definované špecifikácie môžu byť podávané do LLM pre automatické vytváranie lístkov alebo dokonca technickú implementáciu. Môžete generovať testy z vašich špecifikácií. Môžete použiť LLM na vymyslenie častí vášho návrhu, požiadať ich, aby vykonali výskum alebo dokonca pomôcť identifikovať chyby vo vašej logike. I have another article coming in the next few weeks dedicated to spec-driven development with LLMs. Keep an eye out for it — I've been experimenting with this at scale and the results are genuinely impressive. Ale aj keď sa nikdy nedotknete LLM, disciplína písania prísneho špecifikácie vypláca dividendy. núti jasnosť. Anatómia dobrého technického návrhu (časť 1) Dobrá technická špecifikácia je dobre štruktúrovaná, ľahko pochopiteľná a použiteľná. mala by byť skimmable pre manažérov a dostatočne podrobná pre inžiniera, ktorý ju implementuje. Tu je prvá polovica anatómie.To je to, čo píšete predtým, než sa dostanete do nákupu. What are you trying to solve? Začnite s tvrdením o probléme.Nie riešenie - problém.Videl som toľko špecifikácií, ktoré skočia rovno do Nikdy nevysvetlím, čo je zlomené. "we should build a microservice with GraphQL" Na mojom štarte, Tandem, mám jednoduchý test: mohol Jack, môj non-technický spoluzakladateľ pochopiť problém, len čítaním? Niektoré techniky, ktoré fungujú: Použite konkrétne príklady: Nie "užívateľ zažíva latenciu", ale "užívateľ čaká v priemere 8 sekúnd na ich históriu transakcií na načítanie a na tejto obrazovke vidíme 23% pokles." Ukážte obchodný vplyv: „To nás stojí približne 2,3 milióna libier ročne v stratených konverziách“ je oveľa presvedčivejšie ako „to je pomalé“. Zahrňte citácie alebo údaje: Ak máte prieskum používateľov, sťažnosti zákazníkov alebo údaje o monitorovaní, vložte ich. Čo sa nesnažíš vyriešiť? Scope creep je skutočný, a ak nebudete výslovne hovoriť o tom, čo je mimo rozsahu, strávite nasledujúci mesiac argumentovaním o prípadoch, ktoré nemajú význam. Predstavte si toto: dostanete návrh od tímu platformy na upgrade na svoju žiarivú novú knižnicu zdieľaného používateľského rozhrania. Zdá sa to jednoduché, správne? Stačí vymeniť niektoré importy, aktualizovať niekoľko komponentov. Ale potom zistíte, že nová knižnica používa úplne iný smerovací systém pod ním. Teraz potrebujete prepracovať každú trasu vo vašej aplikácii. Potom si uvedomíte, že navigačné vzory vášho tímového produktu sa úplne nezhodujú s novým modelom, takže potrebujete vlastné obaly. produktový tím, ktorý závisí od tejto zdieľanej knižnice?Všetci sú zablokovaní na rovnakých zmenách. Práve sa premenil na šesťmesačné migračné úsilie, ktoré udržiava funkčnú prácu v celej organizácii. Ďalšie „Jednoduchá aktualizácia“ Explicitný section could have caught this early. It gives you permission to say no. It keeps the culture of A chráni váš čas od tých zdanlivo nevinných návrhov, ktoré balón do organizačných nočných morí. „Čo neriešime“ "why-notism" Prečo by mal byť tento problém vyriešený? Nie všetky problémy potrebujú riešenie. Niektoré môžu žiť s problémami. Niektoré nie sú v skutočnosti problémy, len drobné nepríjemnosti. Prečo by tento mal získať pozornosť a inžiniersky čas? Uveďte prípad jasne: Vplyv na užívateľov: Koľko ľudí to ovplyvňuje? : Revenue, retention, conversion, operational costs? Impact on business Vplyv na inžinierstvo: Je to technologický dlh, ktorý spomaľuje každý iný projekt? Vplyv na dodržiavanie alebo riziko: Bude to explodovať za šesť mesiacov, ak to neurobíme? Som veľký veriaci v ukázať svoju prácu tu. Raz sme založili návrh na zmenu textu na tlačidle na experimente, ktorý preukázal 23% nárast konverzie, čo sa prekladá na +£12k ARR. „To je dôležité.“ "Táto tlačidlová kópia by mohla byť lepšia." Prečo práve teraz? Časovanie je dôležitejšie, než si ľudia myslia.Videl som, že sa dokonale dobré návrhy dostávajú na police, pretože to nebol ten správny čas.A videl som, že priemerné návrhy sa dostávajú do zeleného svetla, pretože časovanie bolo perfektné. Prečo je teraz najlepší čas na vyriešenie tohto problému? Externé lehoty: regulačné zmeny, marketingové kampane, demonštrácie konferencií Interná pripravenosť: Máte na mieste správnu infraštruktúru? správnu kapacitu tímu? Závislosť: Existujú iné projekty, ktoré potrebujú najprv loď? Okná príležitostí: Niekedy je tu úzke okno, keď je riešenie niečoho jednoduchšie, ako to bude niekedy znova. Tu je konkrétny príklad. Mali sme návrh na použitie miestnych časových pásiem na výkazoch bankového účtu namiesto UTC. Časovanie bolo kritické – chceli sme to urobiť hneď po tom, čo sa v Spojenom kráľovstve skončilo šetrenie denného svetla. To nám dalo šesť mesiacov, keď bol UTC a miestny čas rovnaký. Museli sme tiež udržať historické výkazy v ich pôvodnom časovom pásme z právnych dôvodov. Začatie hneď po zmene hodín znamenalo, že sme mali maximálne okno pred ďalším prechodom, čo výrazne znížilo šance niekoho, kto potrebuje generovať vyhlásenie s viacerými logickými konverziami časového pásma. Keby sme to urobili v marci namiesto novembra, zaviedli by sme viac zložitých a okrajových prípadov.Timing nebol len dôležitý - bol to rozdiel medzi čistou migráciou a nočnou morou. Požiadavky Aké sú absolútne minimá, ktoré nemožno vylúčiť? Nemyslite na požiadavky ako na to, čo je potrebné mať.Nie na to, čo je dobré mať, ani na to, čo by sme mali mať, ale na základné veci, ktoré musia byť pravdivé, aby sa to vôbec oplatilo. Požiadavky na štruktúru ako testovateľné vyhlásenia: "História transakcií sa musí načítať za menej ako 2 sekundy na p95" "Riešenie musí fungovať pre používateľov iOS 14 a vyššie" "Data musia byť šifrované v pokoji a v tranzite" "Must not require any customer to re-authenticate" Všimnite si, že tieto sú špecifické a overiteľné. Môžete otestovať, či ste ich splnili. alebo sú zbytočné. pin ich dole. „Musíš byť rýchly“ „Malo by byť bezpečné“ Vtáčí pohľad na riešenie Ihneď sa ponoria do detailov implementácie - ktorá databáza, ktoré API, ktorá služba mesh. Vtáčí pohľad by mal byť zrozumiteľný pre netechnických zainteresovaných strán. Hovorím produktovým manažérom, ľuďom v oblasti operácií, možno dokonca aj financiám. Ak nemôžete vysvetliť svoje riešenie niekomu, kto nevie, čo Kubernetes je, nerozumiete tomu dosť dobre sami. Niektoré pravidlá pre túto sekciu: Ešte nie, ale namiesto povedať No tech talk. "Budeme nasadzovať novú mikroslužbu s vyrovnávacou pamäťou Redis a vystavíme ju prostredníctvom GraphQL." "Budeme ukladať často prístupné dáta bližšie k používateľovi, aby sa nahrali okamžite namiesto toho, aby sa zakaždým pomaly dostali do databázy." Čo sa mení z pohľadu užívateľa? ako vyzerá úspech pre nich? Think user-centric. Začať s and then explain at a high level how you'll achieve that. Anchor on outcomes, work backwards. "users will see their transaction history load in under 1 second" Niekedy existujú skutočne odlišné prístupy. Umiestnite dve alebo tri možnosti s výhodami a nevýhodami. To ukazuje, že ste to premýšľali a dáva zainteresovaným stranám skutočnú voľbu. If possible, offer multiple potential solutions. V tomto bode by ste sa mali zastaviť a prehodnotiť.Tu je môj kontrolný zoznam predtým, než pôjdete ďalej: [ ]Problémové vyhlásenie je jasné a konkrétne [ ]Podnikateľský vplyv je kvantifikovaný [ ]Nie ciele sú výslovne uvedené [ ] Požiadavky sú testovateľné [ ]Riešenie na vysokej úrovni má zmysel pre neinžiniera [ ] Som si istý, že to stojí za to urobiť Ak nemôžete skontrolovať všetky tieto polia, neprejdite na časť 2 ešte. vážne. Strácal som týždne písaním podrobných plánov implementácie pre nápady, ktoré neboli naozaj stojí za to robiť. Getting buy-in and collaboration Vaším ďalším krokom je získať spätnú väzbu od kľúčových zainteresovaných strán. Toto nie je formalita. To je miesto, kde sa vaše špecifikácie buď zlepšujú, alebo sa rozpadajú. Some hard-won tips for a successful pitch: Som fanúšikom Notion kvôli komentárom a spolupráci v reálnom čase, ale Google Docs funguje tiež. Dokonca som videl, že niektorí skutoční priekopníci používajú Figma na tento účel raz! Dôležitou vecou je, že ľudia môžu zanechať komentáre v riadku a navrhnúť zmeny. Vyhnite sa PDF alebo Word doklady pripojené k e-mailom - chcete, aby to bol živý dokument. Use a platform that makes collaboration easy. Ak navrhujete zmeny v užívateľskej ceste, vytvorte mockupy alebo drôtové rámce. Ak optimalizujete službu, zobrazte aktuálne metriky s screenshotmi z vášho monitorovania. Odporúčam Figma (vysoká vernosť) alebo Excalidraw (nízka vernosť) pre užívateľské cesty a screenshoty z Grafany alebo Datadogu pre metriky. Illustrate your points. Nechajte svoje ego pri dverách. Každý kúsok kritiky, ktorú teraz dostanete, je výrobný problém, ktorý nebudete mať neskôr. Mal som špecifikácie roztrhané v recenzii, a to sa suší. Ale viete, čo je horšie? Budovanie niečoho po dobu troch mesiacov len aby to zlyhalo vo výrobe, pretože ste vynechali niečo zrejmé. Getting feedback should be your main objective. Ak niekto napíše komentár ako kindly ask them to explain why and suggest an alternative. Vague negativity doesn't help anyone. But genuine concerns with reasoning? That's gold. Guide your contributors. „Nepáči sa mi tento prístup,“ Niekto sa bude pýtať Potrebujete odpoveď, najlepšie odpovede majú čísla. Je to oveľa presvedčivejšie ako Be ready to defend your value proposition. "is this worth the engineering time?" To môže viesť k zníženiu nákladov na hosting databáz o 27%, čo vedie k ročným úsporám vo výške 1,5 milióna libier. To všetko urobí veci efektívnejšími.“ Plán, ktorý sa oplatí realizovať (časť 2) Zaobchádzate s technickými špecifikáciami ako so samostatným úsilím? Napíšte to sami, zdieľajte ho na preskúmanie, získajte nejaké komentáre, odošlite ho? Najlepšie technické špecifikácie sú výsledkom silnej spolupráce. Píšete prvý návrh, určite. Ale potom pozývate inteligentných ľudí, aby to zlepšili. Zahrňujete ich spätnú väzbu. Prispôsobujete sa na základe toho, čo sa naučíte. Špecifikácia sa vyvíja. Táto druhá časť anatómie je dynamickejšia. líši sa v závislosti od kultúry vašej spoločnosti, postupov vášho tímu a typu projektu. Best practices and company standards Ak používate React a Next.js pre webové frontendy, vaše špecifikácie by mali používať React a Next.js. Ak vaša spoločnosť má štandardný CI / CD potrubie, použite to. The exception is when you're explicitly proposing to change an established practice. Maybe you want to introduce a new framework or migrate to a different database. That's fine — but make your case with evidence. Keď som navrhol zmeny v zavedených postupoch, vždy zahŕňam: Mimo dôkaz konceptu: Urobil to úspešne iná spoločnosť? Predchádzajúce umenie z priľahlých domén: Použili sme podobné prístupy v rôznych kontextoch? Jasné zdôvodnenie, prečo súčasný prístup nefunguje: Nehovorte len „to je lepšie.“ Ukážte, kde súčasný prístup zlyhá. Migračná cesta: Ako sa dostať odtiaľto tam bez toho, aby sme všetko rozbili? V Superbet som viedol tím, ktorý vybudoval dedikovanú knižnicu používateľského rozhrania, aby nahradil neustále problematický Ant Design, ktorý sme používali predtým. Urobili sme z neho 100% drop-in nahradenie prostredníctvom vrstvy kompatibility – technicky dokonalé. Ale stále som nedokázal presvedčiť väčšinu tímov, aby ju prijali, pretože som nemohol riadiť obchodný prípad domov. To je lekcia tu: nahradenie zavedených technológií je ťažké aj keď je vaše riešenie objektívne lepšie. Potrebujete čísla, prípadové štúdie, migračnú cestu. Prior art and alternatives considered Existuje niečo podobné, čo už existuje?V minulosti ste implementovali funkcie s podobnými atribútmi?To všetko stojí za zmienku. Najlepší scenár: zistíte, že nemusíte stavať nič nové. Pripojte ho k vedomostnej základni týkajúcej sa riešenia, ktoré ste našli. Pomáha udržiavateľom pochopiť, kto sú ich zainteresované strany a prečo to ľudia potrebujú.Ak chcú nastaviť západ slnka, preniesť vlastníctvo alebo prepracovať svoj softvér, budú vedieť, s kým hovoriť. If this happens, don't throw away your spec. I've saved months of engineering time by finding prior art. We used Statsig to ship experiments, but we'd written our own SDK on top of it instead of using the official one. Our implementation didn't support persisting allocations, which meant we couldn't run sticky experiments. I started speccing out how to add this feature — thinking I'd need to build it from scratch — and went on a bit of a wild goose chase. Then I found an existing, domain-specific service that already solved persistence for a different use case. I just copied the implementation pattern. What I thought would take weeks, only took two days. What other approaches did you evaluate? Why didn't they make the cut? To tiež zabraňuje ľuďom navrhovať alternatívy, ktoré ste už zvážili a odmietli. Approach Pros Cons Why we rejected it Use existing service X Fast, proven Doesn't support feature Y Missing critical functionality Build custom solution Perfect fit High maintenance cost Not worth the ongoing burden Third-party API Easy integration Vendor lock-in, high cost £250K annually vs £30K to build Použitie existujúcej služby X Rýchle, osvedčené Nepodporuje funkciu Y Chýbajúce kritické funkcie Build custom solution Perfektné fit Vysoké náklady na údržbu Nestojí za to pretrvávajúca záťaž Third-party API Easy integration Vendor lock-in, high cost £250K ročne vs £30K stavať The technical approach Teraz - konečne - môžete sa dostať do detailov.Tu vysvetľujete skutočnú implementáciu, rozhodnutia o architektúre a možnosti tech stack. Architecture diagrams, sequence diagrams, data flow diagrams. I recommend (Teraz už Nevýhodou je, že neexistuje žiadna živá zdieľanie ako Figma, takže budete musieť exportovať a vložiť obrázky. Use diagrams. Draw.io Diagramy.net For sequence diagrams, I like Mermaid because you can write them in markdown and they render automatically in most tools. Here's a simple example: sequenceDiagram User->>API: Request transaction history API->>Cache: Check cache Cache-->>API: Cache miss API->>Database: Query transactions Database-->>API: Return results API->>Cache: Store in cache API-->>User: Return results Don't just say Say Explain the "why" behind technical decisions, not just the "what." "we'll use Redis for caching." "Použijeme Redis pre vyrovnávanie, pretože naše prístupové vzory sú veľmi čitateľné (95% čítanie oproti 5% písanie) a potrebujeme sub-milisekundovú latenciu. Buďte úprimní o tom, kde sa to rozpadne. That's way more useful than pretending your solution scales infinitely. Call out performance characteristics and scalability limits. "Tento prístup funguje až do približne 100 000 požiadaviek za sekundu. Show what the data looks like. Show what the API requests and responses look like. I usually include JSON examples: Mention data models, API contracts, key interfaces. { "transaction_id": "tx_123", "amount": 1250, "currency": "GBP", "timestamp": "2025-01-15T14:30:00Z", "category": "groceries" } A benefit of embedding models in a transferrable format, like JSON is that this can then be copy/pasted into a test or mock service later on. Saves some time and cuts down on ambiguity. Výhodou vložených modelov v prenosnom formáte, ako je JSON, je to, že sa potom môžu neskôr skopírovať / preniesť do testovacej alebo podvádzacej služby. Ak to vyžaduje spínanie nových služieb, databáz alebo integrácií tretích strán, zavolajte to. Highlight any new infrastructure or services needed. Rozbiť prácu How do you decompose this solution into milestones and tasks that can be tracked? This is project management, but it's your job to provide the structure. Som veľký fanúšik MVP → MLP → Plný produkt progresie: Split into phases that deliver incremental value. MVP (Minimum Viable Product): Absolútna najmenšia vec, ktorú môžete vybudovať na overenie prístupu.Zvyčajne len interné alebo obmedzené na malé percento používateľov. : The smallest version that's actually good enough for real users to use and enjoy. MLP (Minimum Lovable Product) Celý produkt: Všetky zvony a píšťalky. To je ťažké priznať, ale v mnohých prípadoch sme skončili udržiavať MLP ako konečný výsledok, pretože to bolo . „Dostatočne dobré“ Čo je potrebné na to, aby to fungovalo? Čo je voliteľné? Použite prioritizačný rámec. Páči sa mi MoSCoW (Must Have, Should Have, Could Have, Won't Have). Identify critical path items vs nice-to-haves. Can the backend and frontend teams work simultaneously? Or does the backend need to ship first? Making dependencies explicit helps with planning. Call out what can be parallelised vs must be sequential. V skutočnosti nenávidím rozmery a tiež som na tom zle. uprednostňujem vývojárske hodiny, vývojárske dni, vývojárske týždne ako jednotky merania, keď diskutujete o časových riadkoch. Ak si nie ste istí, prejdite na jedno meranie, napr.: nie ste si istí, či 3 alebo 4 vývojárske dni? Použite 1 vývojársky týždeň. Assign rough t-shirt sizes or story points if your team uses them. Použite jednoduchý graf závislostí alebo ich jednoducho uveďte: Make dependencies between tasks explicit. "Úloha B závisí od dokončenia úlohy A. Úloha C môže začať súbežne s úlohou B." Metriky úspechu How will you measure if the implementation actually worked? What are the KPIs? To je miesto, kde definujete podmienky víťazstva a musíte byť konkrétni. Nie je to metrika úspechu. Je to úspešná metóda. "Make it faster" "Reduce p95 API latency from 500ms to under 200ms" Examples: Define measurable outcomes. Latency reduction: "p95 latency drops from 800ms to 200ms" Zníženie miery chybovosti: "5xx chyby klesli z 0,3% na menej ako 0,1%" Conversion improvement: "checkout completion rate increases from 73% to 80%" Cost savings: "database costs decrease by £40K annually" Musíte vedieť, kde začínate. vezmem screenshoty dosiek zobrazujúcich aktuálny výkon a pripojím ich k špecifikácii. Set baseline metrics before implementation. Budete vytvárať prístrojovú dosku? nastaviť upozornenia? spustiť A/B test? byť explicitný o metodike merania. Specify how you'll track these metrics. Product managers care about revenue and engagement. Engineers care about latency and throughput. Your spec should speak both languages. Include both business metrics and technical metrics. Hodnotenie rizika, závislosti a zmierňovanie rizika Čo môže ísť zle? o čo sa obávate? čo potrebujete od ostatných tímov? I've learned to be brutally honest in this section. Pretending risks don't exist doesn't make them go away. It just means you won't have a plan when they materialise. Do you need another team to ship something first? Do you rely on a third-party service that might have rate limits or downtime? Call it out. I've had projects delayed by weeks because of dependencies I didn't flag early enough. List external dependencies. Čo sa stane, ak táto kritická služba zlyhá?Ak zavádzate novú databázu, čo sa stane, ak zlyhá? Call out single points of failure in your design. Používate technológiu po prvýkrát? je to oblasť kódovej základne, ktorej už nikto naozaj nerozumie? robíte predpoklady o správaní používateľov, ktoré môžu byť nesprávne? Identify areas with high uncertainty. Don't just list risks — show how you'll handle them. Example: For each major risk, propose a mitigation strategy or fallback plan. : Third-party API might have downtime Risk Zmierňovanie: Implementácia spínača s exponenciálnym spustením; vyrovnávanie odpovedí po dobu 5 minút; majú degradovaný režim, ktorý funguje bez API To buduje dôveru a vyzýva na pomoc. is way better than pretending you have it all figured out. Be honest about what you don't know yet. "I'm not sure how we'll handle the migration of 500GB of existing data — looking for input here" Don't wait until security review to discover you need a whole privacy impact assessment. If you're touching user data, call it out. If this needs SOC2 compliance, mention it. Mention compliance, security, or data privacy concerns early. Rollout strategy How will this actually get deployed? Phased rollout? Feature flags? Canary deployments? Nikdy neposkytujem veľké zmeny 100% používateľov v prvý deň. Ak máte iba dvoch používateľov, odoslať len jeden. If you only have two users, ship to just one. My usual progression: 5% → 10% → 50% → 100%. At each stage, you monitor metrics and watch for issues. If something breaks, you're only affecting a small subset of users. Plan for gradual rollout. Rozmiestnite kód do výroby, ale ponechajte ho za vlajkou. To vám umožní ovládať, kto vidí novú funkciu nezávisle od procesu rozmiestnenia. Použil som LaunchDarkly, Statsig a vybudoval domáce riešenia. Všetky fungujú. Vyberte si jednu a použite ju nábožensky. Use feature flags to decouple deploy from release. What conditions trigger a rollback? Be specific: Define rollback criteria. Ak je miera chybovosti vyššia ako 0,5%, prejdite späť Ak je latencia p95 dlhšia ako 1 sekunda, otočte Ak dostaneme viac ako 10 sťažností zákazníkov za hodinu, vráťte sa späť Having these criteria defined in advance means you won't be making emotional decisions during an incident. Odosielajte skutočnú návštevnosť cez novú cestu kódu, ale nezobrazujte používateľom výsledky. Porovnajte výstup so starou cestou kódu (nazývanou aj: tieňové testovanie). Consider dark launching to test in production without user impact. Migrácia miliónov databázových záznamov je riskantná. Robte to oddelene od odosielania nových funkcií. V ideálnom prípade najprv migrujte údaje, potom nasadzujte kód, ktorý používa novú schému, a potom vyčistite starú schému (rozšírenie-migrácia-zmluva). Plan for data migrations separately from code deploys. Kto potrebuje vedieť, kedy táto loď? tím zákazníckej podpory? marketing? externí partneri? Napíšte plán príkazov do špecifikácie. Have a communication plan for internal stakeholders and customers. Rollback strategy Čo sa stane, ak sa náhle stanete nedostupnými, keď je všetko v plameňoch? Premýšľajte o tom ako o predletovom kontrolnom zozname pre pilotov. Keď je stres vysoký a adrenalín sa čerpá, nechcete zistiť veci. Chcete zoznam, ktorý môžete mechanicky sledovať: Disable feature flag X Or: roll back to commit abc123 and deploy Run database script Y to revert schema changes Clear cache Z to remove stale data Monitorové metriky A, B, C na potvrdenie úspešného rollbacku Post in #incidents channel with status This keeps stress to a minimum in incident scenarios. Testovací prístup Unit tests, integration tests, load testing, edge cases — how will you validate this actually works? Critical paths need extensive tests. Nice-to-have features can have lighter coverage. Be explicit about what needs what level of testing. Define test coverage expectations. Ak to bude slúžiť miliónom požiadaviek, musíte ho otestovať v rozsahu. Používam nástroje ako k6 alebo Locust na simuláciu zaťaženia. Nečakajte, kým produkcia zistí, že vaša databáza klesne na 10 000 QPS. Plan load/performance testing for high-traffic features. Zabiť závislosti. Injekcia latencie. Simulácia sieťových oddielov. Pozrite sa, čo praskne. Netflix Chaos Monkey je kanonický príklad, ale nepotrebujete nič, čo je sofistikované. Len zámerne rozbiť veci a vidieť, čo sa stane. Consider chaos engineering for critical systems. Čo sa stane, keď je databáza pomalá? keď je vyrovnávacia pamäť prázdna? keď používateľ odošle nesprávny vstup? Test edge cases and failure modes, not just happy paths. Automated tests are great, but they only catch what you thought to test for. A human clicking around can find the weird stuff. Plan for manual QA/exploratory testing where needed. Pen testing, OWASP Top 10 checks, dependency scanning. If you're touching authentication, payments, or personal data, you need security review. Include security testing for sensitive features. Timeline and milestones Realistické odhady, vyrovnávacia pamäť pre neznáme, kľúčové dátumy dodania. Here's an uncomfortable truth: your initial estimates will be wrong. They're always wrong. The question is how wrong. If there's a regulatory requirement or a conference demo, start there and work backwards to figure out if it's feasible. Work backwards from hard deadlines if they exist. Ak pracujete na známom území so známou technológiou, vynásobte odhady 1,2x. Ak ste na neznámom území alebo používate novú technológiu, vynásobte 1,5x až 2x. Viem, že sa to zdá byť nadmerné, ale nikdy som neľutoval odhady a vždy som ľutoval, že som príliš optimistický. Pad estimates for unknowns. Every two weeks, you should be able to show something. It keeps momentum and surfaces problems early. Define clear milestones with demos or checkpoints. Prázdniny, konferenčná sezóna, termíny dodržiavania predpisov, marketingové spustenia.Ak polovica vášho tímu príde na týždeň, uveďte to. Call out external constraints. Account for on-call rotations, other commitments, the fact that nobody is productive 8 hours a day. I usually assume 6 productive hours per engineer per day, and that's being generous. Be realistic about team capacity. Initial estimates are educated guesses. As you get into implementation, you learn things. Update your timeline accordingly. A spec should be a living document, not a contract written in stone. Update estimates as you learn more. Otvorené otázky What still needs to be figured out? What requires more investigation? This section should shrink over time as you get answers, but it's crucial to have it. It shows intellectual honesty and invites collaboration. "Musíme overiť, že prístup X dokáže zvládnuť objem nášho dotazu" alebo "Najprv by sme mali prototypovať migračný skript na testovacej databáze." List unknowns that need research or prototyping before committing. "Need security team review on encryption approach" or "Need product input on what the fallback behavior should be." Call out decisions that need input from specific people or teams. "We're assuming users will click this button, but we should A/B test to confirm" or "We think this cache hit rate will be 80%, but we should measure real traffic patterns first." Highlight areas where you need to validate assumptions with data. "Mohli by sme optimalizovať latenciu alebo priepustnosť, ale nie oboje - musíme sa rozhodnúť, čo je pre tento prípad použitia dôležitejšie." Be explicit about trade-offs you haven't resolved yet. Don't let open questions languish. Someone needs to be responsible for getting an answer, and there needs to be a deadline. Assign owners to each open question with target resolution dates. Ako kultúra zohráva úlohu Pracoval som v spoločnostiach, kde sa s špecifikáciami zaobchádzalo ako s byrokratickými cvičeniami, a pracoval som v spoločnostiach, kde boli skutočne cenené ako nástroje myslenia. To znižuje kognitívne zaťaženie a zabezpečuje, že všetci sú na rovnakej stránke. Nemali by ste musieť vynájsť štruktúru zakaždým. Mali sme šablónu v Notion. Pre Tandem používame šablóny Google Docs a v Docler sme mali Confluence. Nástroj nezáleží na konzistencii. Technical specifications should be based on a standard template. Mať štandardnú šablónu tiež znamená, že preskúmanie špecifikácií je jednoduchšie. Viete, kde hľadať problémové tvrdenie, požiadavky, riziká. Don't be afraid to share yours with a broader audience. I know it's scary putting your ideas out there, but transparency has massive benefits. Other teams might discover they're solving similar problems. Someone from a different vertical might have crucial context you're missing. Serendipity happens when information is public. Make all proposals publicly available. Všetky špecifikácie boli v zdieľanom priestore Notion, ktorý si mohol prečítať ktokoľvek v inžinierstve.Počet prípadov, keď niekto z úplne iného tímu spustil komentár, ktorý zmenil celý prístup, bol pozoruhodný. To slúži viacerým účelom: pomáha iným učiť sa, podporuje spoluprácu, dáva ľuďom vedomosti o tom, čo sa buduje v celej organizácii. stretnutia, kde by ľudia predložili návrhy v priebehu a dostali spätnú väzbu od cezfunkčnej skupiny. Schedule regular review sessions of critical proposals. „Architektonická revízia“ Chváľte skvelé návrhy verejne. Uznávajte všetkých účastníkov, aj keď zanechali jediný komentár. To podporuje kultúru spolupráce. Videl som tímy, kde sa ľudia báli komentovať špecifikácie, pretože si mysleli, že budú vnímaní ako obštrukcionisti. To je jed. Chcete, aby sa ľudia cítili, že ich príspevok je cenený, aj keď je to kritická spätná väzba. Tell people they're doing great. Keď niekto napíše obzvlášť dobrú špecifikáciu, nazývam to na verejnom kanáli. Trvá to päť sekúnd a ľudia sa cítia dobre o práci, ktorú robia. "Táto špecifikácia od Alex je vynikajúcim príkladom toho, ako štruktúrovať komplexný návrh - skontrolujte ho pre referenciu." The spec is the work Tu je moja posledná myšlienka, a to je pravdepodobne najdôležitejšia vec v celom tomto článku: písanie špecifikácie robí prácu. Príliš veľa inžinierov zaobchádza so špecifikáciou ako s nadprirodzenou pred of coding begins. That's backwards. The spec is where you do the hardest thinking. It's where you discover what you don't know. It's where you find the fatal flaws before they become production incidents. „Skutočná práca“ The best specs I've written have been collaborative, iterative, and occasionally contentious. They've been marked up with dozens of comments. They've gone through multiple revisions. They've forced me to reconsider assumptions I didn't even know I was making. A každý z nich urobil implementáciu hladšou, rýchlejšou a úspešnejšou, než by to bolo inak. Takže nabudúce, keď ste v pokušení vynechať špecifikácie a len začať kódovanie, odpor. Otvorte tento dokument. Začnite s problémom. Pracujte cez detaily. Pozvite inteligentných ľudí, aby zakopali diery vo vašej logike. Iterovať. Vaše budúce ja - a vaša rotácia na volanie - vám poďakuje. Moja šablóna návrhu produktu je k dispozícii na GitHub. Zachytáva väčšinu tu diskutovaných myšlienok. Ak vaša organizácia ešte nemá šablónu technického návrhu, použite to ako východiskový bod. Šablóna návrhu produktu je k dispozícii na GitHub