This is a viewer only at the moment see the article on how this works.
To update the preview hit Ctrl-Alt-R (or ⌘-Alt-R on Mac) or Enter to refresh. The Save icon lets you save the markdown file to disk
This is a preview from the server running through my markdig pipeline
Tuesday, 11 November 2025
Gedurende de jaren heb ik ' honderden kenmerkenspecificaties geschreven, sommige waren briljant, de meeste verschrikkelijk, . Het verschil tussen een goede en een slechte spec is niet over lengte of formaaliteit, maar over het feit dat het ontwikkelaars helpt om het juiste ding te bouwen zonder ze in het proces te verwarren.
Hier is iets wat ik bij Microsoft geleerd heb dat mijn mening veranderde over specs. Een gespesif is geen bijbel. Zoals elke tool, gebruik je het om een werk gedaan te krijgen.1 Je voegt zoveel detail toe als jij.2 De belanghebbenden en ontwikkelaars moeten verdergaan.4 Dan pas je het aan.5 Verander het.6 Dateer het op terwijl de functie zich ontwikkelt.7
Beschouw een sleutel als een heilige document en je bouwt het verkeerde ding perfect op. (', het loopt heel erg snel in de verkeerde richting.')., Beschouw het als een levend gereedschap en je build iets dat echt problemen oplost.
Deze agile aanpak van specs creëert een specifiek probleem: als de eigenschap kan evolueren terwijl je leert, hoe de hel je het schatt ? Hoe weet je wanneer je klaar bent?
In het algemeen is een principe waar ik mee heb geleefd in mijn carrière; Alle processen, of het nu specs zijn / het invulen van rapporten / zelfs codebeoordelen etc.
In principe is een eigenschapsspeciek een gespreksmiddel om het eigenschap beter te maken NICHT een dogmatisch.
Agile is: ‘’’, ‘-’ en ‘sticky notes’. Economische strategie om het juiste ding te bouwen onder onzekerheid.. Species leven in die onzekerheid , Dus ze moeten ook agil zijn. Agile Manifesto, laat het worden hoe je denkt over het bouwen van EVERYTHING . Denk ernaar als een ontwerppatroon voor de ontwikkeling van een product.
Elke loop verkort de afstand tussen “idee” en “bruikbaarM SK3.
Dateer de spec op na elke loop. De verandering log is de Het verhaal van wat je geleerd hebt..
Het belangrijkste principe voor het schrijven van specs: Begin altijd met het probleem, niet de oplossing.
Dit patroon is eenvoudig:
I' heb ontelbare specs gezien die recht in "User klikt op de X-knop, die API Y roept, zonder ooit te verklaren wat de gebruiker eigenlijk probeert te bereiken.
Vergeet niet dat ontwikkelaars eigenschappen bouwen machines echt (code is het gereedschap om eigenschappen te leveren); zeg hen wat Er is veel aan te doen. Niet hoe het te doen. als je een UX persoon hebt die voor de UX-specific verantwoordelijk is, dan moet de dev en zij samenwerken. Het punt is om de beste eigenschap te maken. voor de gebruiker. Dat kan veranderen en iedereen heeft de macht om de verandering te dwingen (in het spec ) en dat hersieningsproces te laten testen op het idee.
flowchart TD
A[Feature Idea] --> B[Spec / Proposal]
B --> C[Visuals: Flowcharts, Figma, UI Mockups]
C --> D[Implementation]
D --> E[Internal Testing]
E --> F[Feedback Loop]
F -->|Refine| B
F -->|Ship| G[Release to Users]
G --> H[User Feedback]
H -->|Iterate| B
Voor je een woord over de implementatie schrijft, moet je één vraag beantwoorden Waarom?
Waarom bouwen we dit?
Een goede spec begint met:
Dit is waar de meeste specs naartoe gaan.
De truc is om te bepalen hoe het werkt. Wat? Het moet zonder voorschrift gebeuren. Hoe? Het gebeurt.
**Goed.**Als een gebruiker probeert een formulier te versturen met ongeldige gegevens, moet hij onmiddellijk feedback krijgen om aan te geven welke velden een correctie nodig hebben.
Slechts.: "Op vormsubmissie, moet de submit-knopM SK3s opClick-handhakker validateForm callenMSC4 die door het formaat herhaaltFields array elke veld controleertMST5waarde tegen zijn validatieMst6regex-eigenschap en als er een fout is, moet showError callnM ST7 met het veldM st8naam en validatieM st9message parametersM ST10
De eerste vertelt me wat de gebruikerservaring zou moeten zijn; Ik kan het implementeren in React, VueM SK2 vanilla JavaScript , of carrier pigeon voor alles wat er aan toe doetMSC4 De tweede veronderstelt implementatiedetails die helemaal verkeerd kunnen zijn voor de technische stapel of onnecessaire beperkingen introduceren.
## Gebruik foto's / stromingendiagrammen; Het punt overstijgen
Denk aan jou, ', je probeert mensen te laten begrijpen wat jij suggereert.', je suggereert ., sommige teams hebben Figma-documenten, (, een verhaalbord, ux, ', specificaties of beelden van de UI die de ontwerper heeft gebouwd, ., zoals alles anders, maar dit zijn: ', tot we het proberen, M SK9, suggesties tot ze ', een feedback loop doorlopen, MSC11, Het is allemaal over We zorgen dat je, ', begrepen wordt.. Gebruik alle gereedschappen die je nodig hebt
In een Wiki-zeemeermin zijn diagrammen GREAT voor dit. ; onthoud AI is GREAT in het genereren van deze ook met een textuele beschrijving
Sommige mensen kunnen geschreven beschrijvingen analyseren, sommigen hebben foto's en films nodig
flowchart LR
A[User on Profile Page] --> B[Click 'Add Profile Picture']
B --> C[Upload Dialog Opens]
C --> D[Select Image File]
D --> E[Preview + Crop Options]
E --> F{User Confirms?}
F -->|Yes| G[Profile Updated with New Picture]
F -->|No| C
G --> H[User Sees Updated Profile]
Als er één ding is, heb ik het geleerd. Gebruikers zullen manieren vinden om je shit te breken die je nooit had gedacht.
Een goede spec beschrijft niet alleen de gelukkige weg, maar ook ;.
Je hoeft dit allemaal niet in de spec op te lossen, maar je moet erkennen dat het bestaat.
Voor velen is het ' Waarschijnlijk niet bruikbaar voor deze specificatie . Je hebt misschien 'technische specificaties' die de details van de implementatie en de technische oplossingen van M'technicieke kwesties detailliëren.
Deze zouden niet moeten worden nagedacht tijdens de code-overprüfung. Als er specifieke beveiligingsbehoeften zijn (beanthenticatieniveausM SK3data-encryptie ,audit-loggingMSC5 ze uitschrijven in het specMske6
Als er performance beperkingen zijn die belangrijk zijn, moet deze zoekopdracht onder 200ms voltooid worden voor datasets van tot aan 1 miljoenen opnames.
Hier is het werkvoorbeeld dat ik gebruik om de eigenschappen te bepalen.
Een paar regels om samen te vatten wat we bouwen en waarom het belangrijk is.
Wat is de huidige stand van zaken?What prompted this feature?What have users been asking for?What would help us make more money?This helps developers understand the problem space without having been in every product meeting.
Got it—let’s vergroot je sectie op Gebruikerverhalen Met personages gevouwen in,, zodat het niet alleen een checklist is maar ook een levende kaart van hoe verschillende soorten gebruikers met het systeem communiceren.
Gebruikersverhalen zijn niet alleen een doos, maar ook een oefening. Echte mensen belichamen. en hun doelen. Jullie kennen, jullie gebruikers Het hele punt van dit sjaap bouwen.. Door elk verhaal aan een persoon vast te leggen, dwing je jezelf om na te denken over echte gebruikspatronen, motivaties en beperkingen.
Uiteindelijk zijn mensen een leuke manier om te bepalen hoe je software kan dienen aan verschillende typen van gebruikers. Misschien heeft Alex een dashboard nodig om de veiligheidsproblemen in jouw functie te bekijken, misschien heeft Morgan zijn vergunningen beperkt om hem niet meer te laten breken.
Als een [persoon / gebruikertype] Ik wil [om iets te doen. [Ik bereik een bepaald doel].
De gemeenschappelijke wetgeving van het land. “zodat” De clause is de beveiliging tegen bouwfuncties die niemand nodig heeft.
| Persoon | Geschiedenis | Waarom het belangrijk is M |
|---|---|---|
| Alex Administrateur, Ik wil rollen en toestemming geven. Zodat Ik kan de data-veiligheid en -compliëntie verzekeren. | Behoedt onautoriseerde toegang tot het systeem en houdt het betrouwbaar. | |
| Jamie ( Gewone gebruiker Gewone gebruiker, Ik wil een eenvoudig dashboard. Zodat Ik kan snel de belangrijkste informatie zien zonder overweldigd te worden.. | Verlaagt frictie en verhoogt adoptie. | |
| Priya (Gebruiker van elektriciteit) | Als een Kraggebruiker, Ik wil custom workflows maken. Zodat Ik kan repetitieve taken automatiseren en tijd sparen. | |
| Morgan Nieuwkomer, Ik wil begeleide tutorialen en gereedschaptips. Zodat Ik kan het systeem leren zonder te voelen dat ik verloren ben. | verbetert aan- en opbehoeftingsvermogen | |
| Taylor Stakeholders, Ik wil regulare rapportjes per e-mail. Zodat Ik kan de vooruitgang volgen zonder in te loggen. |
Dit is je vlees en aardappelen. Breek het op volgens functionaliteitsgebieden . Gebruik subheadings vrijelijk. Sluit er kopieën of draadframes in als je ze hebtM SK3 een foto is duizend woorden waard om te beschrijven
Voor elke vereiste , spesifiseer :
Performance-doelen, veiligheidsbehoeften, toegankelijkheidsstandaardgevingenM SK2 browser / toediening van de apparatuur . Doe niet aannemen dat dit duidelijk isMSC6 Maar in sommige teams zijn het wel alle andere TEAMS... maar doe nietMska8 verlies je focusM Ska9 Als een deel van je fiets een waterval wordt, dan ben jij volgens definitie agiliteit kwijtgeraakt.
Deze afdeling is net zo belangrijk als wat je doet.
Waarom dit belangrijk is:
Voorbeelden van goede Items uit de scope:
Als iemand betoogt dat een item buiten de scope van -, - en , in scope moet zitten, dan is ' een gesprek die het waard is voordat de ontwikkeling begint, ,, niet halverwege de implementatie.
Wees eerlijk over wat je niet weet.
Welke andere systemen afhankelijk zijn van deze eigenschappen?
Hoe zal QA dit testen?? Deze zouden concreet moeten zijnM SK1 toetsbare uitspraken. Bonuspunten als ze ' in een formaat zijn geschreven dat automatiseerde tests zou kunnen worden.
Hier is iets waar niet genoeg over wordt gesproken. Specs kan ook fouten hebben.
Een specifiek fout is wanneer de specificatie zelf verkeerd is.
Als je een specifiek fout vindt als ontwikkelaar, heb je een paar opties:
Dit is bijna altijd het juiste antwoord.
Stuur een duidelijke boodschap aan de eigenaar van het spec:
Doe dit op schrift.
Soms heb je de neiging om gewoon te bouwen wat je specifiek hebt, hoewel je het weet. Doe dit.
Ik heb ontwikkelaars gezien die specs implementeren, waarvan ze wisten dat ze fout waren omdat "dat'is wat het zei om te doen " en dan verbaasd zijn als QA het verwerpt of gebruikers klagen.
De uitzondering is als je de kwestie hebt opgelost, zei dat je er toch mee zou gaan, en dat in het schrift had gekregen.
Als je' zeker bent dat je weet wat de specificatie moet zeggen, zou je misschien verleid worden om het zelf te corrigeren.. Dit is prima voor duidelijke typo's of formateringsproblemen, maar voor substantieve veranderingen moet je een akkoord van de belanghebbenden krijgen.
Moet je nooit stilletjes de eisen veranderen. Dat is hoe je bouwfuncties bouwt die niemand heeft gevraagd.
De beste aanpak is het voorkomen van spec bugs in de eerste plaats:
Sommige mensen denken dat meer detail altijd beter is.
Als je spec verandert in oorlog en vrede, dan ben jij ofwel:
Het tegenovergestelde probleem: Build een rapportsysteem.
Als je spec in één zin volledig kan worden vastgelegd.
"We hebben een dashboard nodig " is het niet' is geen vereiste ; het is een voorgedachte oplossing M SK5 Misschien heb je wel een dashboard, maar misschien heb je iets heel anders nodig.
Bedingingen die elke dag veranderen zijn't-behoeften; zeM SK2het is chaos . Als dingen zo snel veranderenMST4 snap je het probleem nog niet goed genoegM ST6 Stop en meer ontdekkingen doen voordat je specs schrijftM st7
"Als we in ' zijn, kunnen we ook naar ,..." Nee. NeeWe zouden het niet kunnen,'t. Elke functie heeft een prijs.
Dit is de mindsetsverschuiving die veranderde hoe ik specs schreef. Behandel je spec precies zoals je sourcecode behandelt.
Je specs zouden in versiecontrole moeten leven naast je code. Bevestig ze in. Veranderingen volgenM SK2 betekenisvolle commit-berichten schrijven als je ze aanpast . Dit creëert een geschiedenis van hoe de evolutionaire behoeften evolueerden.
Bij Microsoft , hielden we specs in dezelfde repositories als code . Als een specifiek veranderd was, ging het door hetzelfde beoordelingsproces als code\ . Dit was niet de bureaucratie van '; Het zorgde ervoor dat iedereen begreep wat er aan de hand was en waarom.
Net zoals code refactoring nodig heeft, zo doen ook specs. Terwijl je meer leert tijdens de implementatie , moet het spec evolueren om dat leren te weerspiegelen.
We vonden een betere manier om het probleem op te lossen? Dateer de spec op om de nieuwe aanpak weer te geven en te verklaren waarom je de richting veranderde. Ik ontdekte een randgeval dat je niet had gevondenM SK2 heb het niet beschouwd
De spec na de ontwikkeling moet verfijnd zijn dan de spec voor de ontwikkeling.. Als het niet ' is, maar ,, heb je de kans vermist om te documenteren wat je geleerd hebt.
Een specificus is: 't "" is gedaan, "", wanneer de ontwikkeling begint.,, het is ', maar ', klaar voor die fase.., Het is gedaan als de functie schip en het onderhoudsmodus wordt. . Tot dan toe is het een levend document dat evolueert met je begrip van het probleem.
Dit betekent niet' dat de specificatie elke dag moet veranderen. Grote veranderingen in de eisen moeten onderhandeld worden en onderhandelt worden . Maar clarificatiesM SK3 bijgevoegde voorbeeldenMSC4 nieuw ontdekte randgevallen moeten allemaal teruggevouwen worden naar de specificaties als je ze vindtMska5
Denk er zo over na: als je het niet zou doen.
Hier is iets dat niet genoeg wordt besproken. Je spec wordt de basis voor alles wat na . komt.
Toetsplans: QA schrijft testcases op basis van de spec. Als de spec verouderd isM SK2 testen ze het verkeerde dingMSC3 Je krijgt valse positieven ( testen voorbij, maar het kenmerk is gebrokenMST5 of valse negatieven | MST6 testen mislukken, maar de kenmerk werkt goedMst7
Dokumentatie: Gebruiker-documentatie, API docsM SK2 hulpsystemen , je fantastische RAG AI-ondersteuneragent | - ze beginnen allemaal van de spec |. Als het spec kenmerken beschrijft die niet bestaan |' | of features misses die doen | , | jouw docs zijn fout vanaf dag één |
Toekomstige ontwikkeling: Als iemand zes maanden later de functie moet uitbreiden, zal hij het spec lezen om te begrijpen hoe het werkt.
Opboarden: Nieuwe teamleden leren het systeem deels door specs te lezen.
Daarom moet de spec aanpast blijven.. Het is niet alleen de eerste implementatie, maar het is ook fundamenteel voor alles.
Bij Microsoft , behandelden we spec-updates met dezelfde belang als code-updaten . Spec-wijzigingen werden nageboekt | . Ze werden naast de code geversioneerd |. Als een eigenschap veranderd was ♫ , het update van de spec ♫' ♫ niet optioneel ♫
Als je de code verandert, maar niet het spec opdateert, heb je TECHNICAL DEBT gecreëerd.
# De relatie tussen spec en implementatie
Dit is iets dat junior ontwikkelaars vaak niet begrijpen. De spec is niet de bron van waarheid.
De spec vertelt je wat je probeert te bouwen.
Dit betekent:
Verschillende mensen hebben verschillende dingen nodig van specs:
Uitvoerders - Je wil de bedrijfswaarde en de ruwe tijdslijn kennen.
Product Managers - Je moet begrijpen hoe het past in de bredere productstrategie en roadmap.
Ontwikkelaars - Behoeft genoeg detail om correct te implementeren zonder te worden verteld hoe ze hun werk moeten doen.
QA - Moeten weten hoe het werkt te verifiëren . Geef ze de aanvaardingskritieken
Ontwerpers - Je moet weten wat de gebruikerservaring zou moeten zijn . Geef hen de gebruikersverhalen en interactiestromen. Het is nog beter dat ze een UX-speciek ontwikkelen / verhaalborden in parallel terwijl ze met de dev werken.
Een goede spec bedient al deze publieken zonder te worden opgeblazen.. Gebruik delen en structuur zodat mensen kunnen lezen wat voor hen belangrijk is.
Voordat je een spec doet roepen, vraag jezelf af.
Maar we zijn agile. We hebben geen specs nodig. Ik hoor dit vaak. Het is nonsens.
Agile betekent niet: ' geen planning, " of " geen dokumentatie, ." Het betekent het reageren op verandering in plaats van een plan te volgen. Specificaties zijn gereedschap, geen contracten. Je creëert ze met enkel genoeg detail om te beginnen, dan ontwikkel je ze zoals je leertM SK1 Mijn 'Agile reis ' was nog extreemderMSC4 als je super goed bent in specs, zelfs die worden nog agilerMST5 je wil aanpassen en verbeteren op basis van wat je team wil | MST6 | behoeften |MST7
De fundamentele verschillen zijn het format of de lengte van ;, het denken en het proces.
Watervalspecies:
Agile Specs:
De waterval-aanpak veronderstelt dat je alles perfect kunt bepalen voordat je een lijn code schrijft. Dat'is een mooie fantasieM SK2 In werkelijkheidMSC3 ontdek je de helft van de eisen als de gebruikers het feature daadwerkelijk uitproberen . Plan voor dat,, omarm het,. Gebruikers zijn de ULTIMATE testersMST7 Ze kunnen spul breken die je niet had,MST8 niet eens weten dat je bent,Mst9 is gemaakt met een tempo dat de causaliteit lijkt te overtreden,MSt10 verwacht het, MST11 plan het,mST12 registreer en repareer het, mst13 en voeg het toe aan een toekomstige spec Mst14 deze, als jeMst15 nog steeds in de spec zit,Mstr16s, Mst17 levensduur,M st18
## Feedback Loops zijn alles
In agile specting, feedback-loops zijn je beste vriend. JeM SK2 verzamelt voortdurend input en aktualiseert de specMSC3
Ontwikkelaar Feedback: "De eerste aanpak won't werkt niet vanwege XM SK3 IMSC4m stelt Y in plaats van ." ♫→ Dateer spec op om de nieuwe aanpak te weerspiegelen en waarom het veranderde ♫ . Uiteindelijk ben je ♫
Gebruikerfeedback: Probeer de functie met echte gebruikers te gebruiken. Pivot de spec gebaseerd op wat je leert.
Implementatiefeedback: Terwijl je bouwt, ontdek je randgevallen , technische beperkingen , of betere benaderingen
QA-Feedback: "De spec zegt X, maar niet'keek geen Y-scenario aan
Elk van deze feedback-loops maakt de spec beter.
Dit is waarom watervalspecifieken vaak falen: ze overslaan de terugkoppelingsloops. Tegen de tijd dat je ontdekt dat het spec verkeerd wasMSC2 heb jeM SK3 het verkeerde ding gebouwd en MST4 het spec veranderenMst5 betekent massaal herwerkenMSt6
Big thing, feedback AS VEARLY AS FEASIBLE . It' is waarom ik bouwde LLMApi Het helpt je een BIT te bouwen, dan gebruik je valse data om nuttig feedback te krijgen.
Dit is iets dat traditionele projectmanagers zenuwachtig maakt. het' is helemaal oké als de eerste spec gaten heeft.
Merk delen als "TBD" als je het nog niet weet ' weet het nog steeds niet
Dit is niet', "t sloppiness," ;, maar ', "de eerlijkheid," ., "Je weet het niet, '", "ik weet niet alles voor ogen", ., "Dat je het doet, betekent gewoon dat je', "een overtuigende specificaties zal schrijven voor de verkeerde oplossing."
Begin met:
Dan vul je de gaten in terwijl je leert.
Aanvaar dit nu: Je spec verandert tijdens de ontwikkeling. Als het niet werkt, heb je ofwel ongelooflijk veel geluk gehad, ofwel heb je niets geleerd.
Veranderingen die je zou moeten verwachten:
Elke verandering moet zijn:
De versiegeschiedenis van de spec' wordt een opname van wat je geleerd hebt.
De agile aanpak kan falen als je één cruciale ding vergeet: " zal veranderen " betekent niet' betekent geen grenzen
Slechte agile spectering:
Goede agile spectering:
De spec is een levend document, maar het is geen chaos. Het evolueert op basis van leren.
'AGILE' doet nooit wat je wilt en roept het 'AGile'.
Het is een dynamisch proces met de SOLE GOAL om het beste materiaal zo snel mogelijk te bouwen. Agile Manifesto Het eerste principe van ' is: ..
" Onze hoogste prioriteit is de klant te bevredigen. Door vroege en continue levering. van waardevolle software."
Het is niet om de code uit te spinnen omdat je het gevoel leuk vindt.
De vraag is: "Hoe gedetailleerd moet de spec zijn?"
Voor sommige functies die kunnen zijn:
Voor anderen kan het zijn::
Voeg details toe waar onzekerheid bestaat. Als iedereen het eens is over hoe iets moet werken, hoef je het niet in ongrijpelijke details op te schrijven.
Maar uiteindelijk is er genoeg detail om de terugkoppelingslus te starten.
## Templates en AI: snel beginnen
Denk niet over het beginspectief na. De bedoeling in het begin is genoeg te hebben om je onmiddellijke behoeften aan te kunnen voldoen.
Gebruik werkvoorbeelden: Heb een basis-template met de sleutelsequenties.
Een eenvoudige werkvoorbeeld zou kunnen zijn:
# [Feature Name]
## Problem
[What's broken? What pain exists?]
## Proposed Solution
[High-level approach]
## What "Done" Looks Like
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
- [ ] Specific, testable criterion 3
## In Scope
-
-
## Out of Scope
-
-
## Open Questions
-
-
Dat is het. 5 minuten om dat in te vullen en je hebt genoeg om te praten of zelfs te bouwen.
AI gebruiken voor het tekenen van specs: gereedschappen als Claude of ChatGPT kunnen briljant zijn om een eerste tekening te krijgen . Voeg het het probleem en een bepaalde context toe , vraag het om een spec te schetsen M SK3
Maar - en dit is cruciaal - Laat de AI's grondigheid je verleiden om alles te toevoegen.
AI houdt ervan om uitgebreid te zijn. Het' zal je delen geven over veiligheidsbeoordelingen , Performentiebehoeften , Toegankelijkheid M SK4 Internationalisering Mske5 Foutbewerking M Ske6 LoggingMske7 Monitoring Msche8 Deployment Strategy M Schepback Plans Msko10 en zeventien andere dingen die je nodig zou kunnen hebben.
Strip de meeste daarvan uit. Hou wat je nu nodig hebt. De rest kan later toegevoegd worden als je het echt nodig hebt
Denk aan de AI-gegenereerde spec als een menu. Kies de bits die ertoe doen dat je begint te beginnen.
Het doel is: ' is geen volledige spec, maar ;, het is genoeg spec om te beginnen met werken, ., of dat een snelle schatting is, ,, een beslissing over prioriteit, or gewoon duidelijkheid over wat je zelf bouwt.
Hier is wat er verandert in agile. Je schrijft geen spec en gooit hem over de muur naar ontwikkelaars. De spec is een samenwerkingswerk.
De beste aanpak die ik gezien heb.
Iedereen draagt bij aan de spec.
Nog belangrijker: , betekent dat de spec weerspiegelt wat ' werkelijk mogelijk is, niet wat iemand alleen maar wilde.
Hier' waar agile specs verschillen van traditionele specs Het kenmerk kan evolueren terwijl je het bouwt.
Je ontdekt dat je oorspronkelijke aanpak won' niet werkt? Dateer de spec op om de nieuwe aanpak te weerspiegelenM SK2
Je probeert het feature en realiseert je dat het het probleem niet oplost.
Gebruikerfeedback toont aan een betere oplossing? Inkorporeren en de verandering verklaren
Deze evolutie is een eigenschap.
Maar dit creëert een probleem.
Dit is het vuile geheim van agile: Evalueren is bloederig moeilijk als eigenschappen kunnen evolueren.
Traditionele schatting stelt voor dat je weet wat je bouwt.
Agile schatting erkent dat je het niet weet.
Je schat de afstanden, geen absolutes. In plaats van " zal dit 3 weken duren", zeg je ", ergens tussen 2 en 5 weken afhankelijk van wat we ontdekken.
Je schat in iteraties. We zullen een sprint doorbrengen om dit te onderzoeken en terug te geven wat we geleerd hebben. Dan kunnen we de rest nauwkeuriger beoordelen.
Je tijd-box in plaats van scope-boxingM SK2 We zullen er 2 weken aan besteden.
Maar al deze benaderingen hebben één cruciale vereiste: : Je moet weten wat " betekent. Zonder een duidelijke definitie van gedaan, kan een eigenschap eeuwig metastaseren.
Het is een gemeenschappelijke kritiek op Agile vergeleken met Waterfall-aanpakken. Zonder een concrete specificatie kunnen er geen goede schattingen zijn.
Dit is waar veel agile specs uit elkaar vallen.
Zonder een duidelijke definitie van gedaan , featuren doen het niet af' ze meten niet af, ; ze metastasiseren, MSC3 ze verspreiden zich, . ze groeien naar andere delen van het systeem, . Voordat je het weet,, je " eenvoudige commentaarsysteem, " is veranderd in een volledig sociaal netwerk met boodschappen, msc9 profielen, m sc10 en vriendelijke verzoeken.
I' heb specs gezien met aanvaardingskriterien zoals:
Dit zijn geen definities van gedaan, maar vage ambities.
De ontwikkelaar moet het weten: Wat betekent het dat ik niet meer aan deze functie kan werken?
Goede "doneM SK1 criteria zijn:
Slechts.: "Comments should be moderatedM SK2 Goed.: "Admin-gebruikers kunnen de opmerkingen goedkeurenMSC2 afwijzen, of uit het adminpanel verwijderenM SK4 NietMST5Geapproofde opmerkingen zijn niet zichtbaar voor gewone gebruikersM ST6 E-mail-notification gestuurd aan admin wanneer een nieuw commentaar wordt gestuurtM st7
Slechts.: "De zoekopdracht moet snel zijn" Goed.: "De zoekopdracht gee terug resultaten binnen 200ms voor het m95ste percentiel van vragen in vergelijking met een dataset van M100,000posities. De resultaten worden rangschikt volgens relevantie.
Slechts.: "Dashboard toont nuttige metingen" Goed.: "Dashboard-displays: totale pagina-aansigten |( laatste | 30 dagenM SK5 unieke bezoekers |( |last | 30 | dagen ), bovenste |M5 posten per aansigte ♫( | laatste ♫ 7 ♫ dagen |МSK12 | en visioenverdeling per land |m. | Alle metingen worden één keer per uur opgedateer |
Let op het verschil? De goede voorbeelden vertellen je precies wat er moet zijn en wanneer je dingen kan stoppen te toevoegen.
Herinner je nog eens dat ik zei dat de 'Out of Scope'- sectie net zo belangrijk is als wat ' in het bereik heeft.
Voor elke functie is er tientallen dingen die je zou kunnen toevoegen. De 'Out of Scope'- sectie roept expliciet uit wat jij niet doet' Dit voorkomt de M SK4 terwijl wij in de ruimte zijn, en ook de gesprekken die de metastase van een functie veroorzaken.
In scope: Ingebedde opmerkingen (een niveau van antwoorden) Uit de scope: Onbegrensde commentaarstrooiing, commentaar stemmenM SK2 commentairstrooien , beste commentaarsorteringMSC4 commentaren permalinks
Als iemand nu suggereert dat "shouldn't commentaties een upvote hebben ?", kun je naar de spec wijzen en zeggen: """dat" '" buiten het bereik is voor deze iteratie"."Laten we dit als een aparte eigenschap bespreken zodra de basiscommentaties werken".
Oh en de volgende spec? Nou, je hebt al een hoop ongebruikte goede ideeën vastgevangen.
Soms weet je echt niet hoe het eruit ziet als je begint.
We zullen 2 weken ( of tot het backend klaar is ) verschillende benaderingen van de recommendedie-algoritme prototyperen.
Maar let op, je hebt nog steeds een betonnen "gediend"conditie (2 wekenM SK4 en dan beoordeelt je ). Je ' bouwt niet zomaar onbepaald . Deze verkenningen worden vaak gedaan in een context zoals een Sprint in SCRUM
Een Spike is een van deze 'ga een spelletje spelen en uitzoeken hoe deze technologie werkt' het kan zo lang duren als een Sprint ( of langer ) maar het duurt meestal slechts een paar dagenM SK4 Als ik dit devs heb, vraag ik meestal naar een mail aan het einde
Een Sprint moet aan het eind deliverables hebben. (iets dat iemand anders dan de persoon die erin betrokken is, kan testen voor de loop.
Ze zijn ook leuk voor werknemers en helpen het team Ik verzamel vaak Spike-ideeën tijdens een project en als er ' een tijdje is, laat ik de werknemer één kiezen om te verkennen.
Zelfs met een duidelijke "doneM SK1 criteria , kan de schaal glijpen. Je ontdekt randgevallenMSC4 Je realiseert je dat gebruikers iets nodig hebben wat je niet had gehadMST5 niet beschouwdMst6 Hoe kan je dit aanpakken zonder je definitie van gedaan te breken?
Dokumenteer het. Als je iets nieuws ontdekt dat moet worden toegevoegd, Dateer het spec op. Laat duidelijk zijn dat de scope veranderd is . Besloten van belanghebbendenM SK3
Dit dient twee doelen:
Als je spec blijft groeien, dan is dat een signaal. Ofwel bouw je het verkeerde ding, ofwel moet je terugkijken en opnieuw nadenken, of dit meerdere functies moeten zijn, of je moet de scope verkleinen om iets nuttigs sneller te verzenden.
Op een bepaald moment moet je het verzenden.
Een goede test: Kunnen gebruikers waarde van deze functie krijgen zoals ze standt?
Als ja, stuur het naartoe. Je kan altijd herhalen in de volgende versieM SK2 Klaar is niet ' betekent geen verbetering van ♫" zal nooit worden verbeterd ♫ ." Het betekent dat ♫" het probleem goed genoeg oplost zodat de gebruikers er baat bij hebben en we kunnen verdergaan met andere werk ♫
Als nee, uM SK1 is nog niet klaar, ongeacht wat je specifiek zegt .
Het moeilijkste deel van agile is: ', 't beginnen met het werk', ;, 'het stoppen met het werken' en ., 'onduidelijk'.
Maar onthoud dat je moet weighen of je het aan iedereen laat vrijgeven, een nauwe groep voor A has/B M SK2 UAT ( gebruiker aanvaardingstestsMska4 DatMske5 vaak een zakelijke beslissing is om risico's te beoordelenMsek6 Soms is het publiek gek en ziet een gedeeltelijk klaar voorskou als de GOSPEL voor jouw systeemkwaliteitMsku7 Als dat een probleem is, is een gecontroleerde groep veiligerMsko9
# Het proces van spec-beoordeling
Een spec is niet gedaan wanneer je het klaar hebt te schrijven.
De beste praktijk die ik geleerd heb bij Microsoft: spec reviews werken precies zoals code reviews. Ze zijn samenwerkend, niet tegenstrijdig, hoewel de jongensclub van Microsoft vaak de spec-beoordelingen als gladiatoriaal gevecht maakten als iemand een kerel was.
Bij het herzien van specs:
Wanneer je spec wordt bekeken:
De beste spec-beoordelingen zijn gesprekken. Je gaat heen en weer. Je leert van elkaarM SK2 De spec die ontstaat is beter dan wat een of andere persoon alleen zou kunnen hebben geschreven.
Kry recensies van alle relevante perspectieven:
Ontwikkelaar Review - Gaat dit echt werken ? Zijn er technische beperkingen die we nog niet hebben overwogen ' niet beschouwd M SK3 Is er genoeg detail om te implementeren MSC4 Welke vragen zou je hebben als je deze bouwde?
Product Review - Heeft dit het juiste probleem opgelost ? alignt het zich op de productstrategie ? Wat is er mis met '?
Design Review - Makt het gebruikerervaring zinvol? Hebben we de toegankelijkheid in beschouwing genomenM SK2 Wat is met mobiels ? Behandelen we het probleem van de gebruiker of bouwen we alleen functies op?
QA-bespreking - Kunnen we dit testen? Zijn de aanvaardingskriterien duidelijk genoeg ? Hoe zit het met randgevallen?
Je hebt geen formaliteit nodig'we hebben geen formele tekens nodig -uit iedereen af te trekkenM SK2Je hebt hun input nodig om de spec beter te maken. Zie het als MSC4op verzoek tot opmerkingenMska5 niet mska6op vraag naar goedkeuringMske7
Goede reviewers stellen vragen die het spec verbeteren:
Geen van deze vragen zijn geprobeerd. Ze zijn echte vragen die het spec helpen uit te vissen.
Je wint niet elke suggestie te accepteren.
De spec zou beter moeten worden met elke ronde van de beoordeling. Als het niet klopt't , ben je niet aan het luisteren of zijn jullie beoordelaars niet betrokkenM SK4.
Kry een overzicht van al deze perspectieven voordat je de implementatie begint. Problemen vinden in de speckostenminutes; ze vinden in productiekosten wekenM SK2
Om dit allemaal minder abstract te maken, zie je hier ,' hoe een spec eruit zou kunnen zien voor de automatische markdown-overdrachtsfunctie die ik heb gebouwd voor deze blog.
Blogposts die in het Engels zijn geschreven, sluiten alleen niet uit-English-sprekende lezers. Handmatige vertaling van elke post naar meerdere talen is tijdM SK2 Beperkt en vertraagt de publicatie . We hebben een automatiseerde oplossing nodig om markdown-blogposts te vertalen naar meerdere doeltalige talen zonder de manuelle interventie voor elke post te hoeven te betrekken.
Implementeer een achtergronddienst die automatisch markerdown-bestanden vertaalt naar geconfigureerde targettalige talen met behulp van de EasyNMT machine-overdrachtsdienst.
Deze criteria vertellen ons precies wanneer we kunnen stoppen met werken aan deze feature:
Let op dat ze specifiek en testbaar zijn. We kunnen elk ervan verifiëren. Als alle overeenkomsten zijn bereikt , weMSC3 zijn klaarM SK4 We blijven niet toepassen van functies als Mska6vertalingkwaliteitscoreringMske7 of mska8bewerking van de handmatige vertalingMsek9 tenzij we de scope expliciet uitbreiden.
Er ontstonden verschillende dingen tijdens de ontwikkeling die het spec verfijnden.
Batch grootte aanpassing: Gestart met 20-lijnenblokkies, maar vond dat 10 lijnen betrouwbaarder waren om onder EasyNMT te blijvenM SK4s woordlimiet te houden terwijl je de context bijhoudt
Beeld Ontdekking: In het begin, werden beeld-filenames in markdown naar de vertalingsdienst gestuurd , fragbrekende zinsverwerkingM SK3 Lêerverlengingherkenning toegevoegd om beeldpaadjes te overslaanMSC4
Beskikbaarheid van de dienst: EasyNMT kan temperamentaal zijn bij het opstarten. Gevoegde gezondheidscontrole die de /model_name Endpunt voor het proberen van vertalingen.
Hash-opslag: Oorspronkelijk gepland databasisopslag voor file hashes, maar op lêersysteemM SK2 gebaseerd .hash Lêers werden eenvoudiger en database-afhankelijkheid voor deze dienst werd vermijden.
Deze lessen werden teruggevouwen in documentatie en later geïnformeerd met vergelijkbare kenmerken.
Deze specificatie volgde de besproken principes:
Het resultaat was::, een functie die al maanden in productie is, ', die elke blogpost automatisch vertaalt met minimale interventie.
Op basis van wat we hebben behandeld, zijn hier vaak gestelde vragen.
Het hangt af van: "small." Als het' echt triviaal is.
Dan ja, zelfs een snelle spec helpt. Het is niet nodigM SK2 het hoeft niet formeel te zijn . Een paar buletpoints in een kaartje die het probleem bedekt ProblemMST4 oplossingMst5 en Klaardoende criteria zijn vaak genoegMSt6
De test : als je kan ' niet uitleggen hoe het eruit ziet in twee zinnen.
Point to the Out of Scope section. Vertel dat
Als ze beweren dat alles even kritisch is, suggereren ze om te kiezen welke andere werk dan te vertragen.
Dat's fine, zo lang alsM SK2
Als de spec onherkenbaar is omdat je het probleem in het begin helemaal verkeerd begrepen hebt, dan is dat een teken om meer ontdekkingen te doen voordat je de volgende keer begint.
De versiegeschiedenis van de spec' moet je vertellen wat je geleerd hebt.
In Startups heet dit een 'Pivot' waar je begint met het bouwen van een spel en uiteindelijk een verbazingwekkend messagingsysteem bouwt.
Don' niet te verstopt in de . Als er ' kansen zijn door om te draaien, neem ze.
Voor kritische bugs: nee, stel ze gewoon op.
Voor complexe bugs die veelvuldige systemen beïnvloeden of architecturale veranderingen nodig hebben.: ja, . Behandel het als een eigenschap.. Wat?' is gebroken.
Voor alles tussenin:: gebruik je oordeel. Als de oplossing niet duidelijk is, of als er bijwerkingen kunnen zijn.
Dit geldt vooral voor beveiligingsbugs. Je moet EXACT weten wat je fixeert en hoe je het zal verifiëren.
Zo formeel als je team nodig heeft. Sommige teams zijn goed met gedetailleerde JIRA-tickets. Anderen willen goede documenten in versiecontroleM SK2
De formaliteit is minder belangrijk dan de inhoud:
Je kunt dat in Markdown schrijven.
Dit is de vaak onbenoemde Sleutel tot agile ontwikkeling; en waarom ik Agile Frameworks haat (en SCRUMM SK2 Het hele punt is dat je proces, net als een agile spec, ook aanpassingsvermogen moet hebben. Als 5 dagcycli voor één team werken, maar 2 weeksprinten voor een ander, dan doen ze dat. Het hele idee is om het beste product te maken; je team is de machine die dat product maakt
Als manager kijk je naar wat je uitgaven zijn; als het bord een verbrand grafiek nodig heeft, hoe kan je dan de huidige data gebruiken om er één te bouwen.
Als je de impact op het team kunt verminderen, dan is dat jouw deel.
Je hebt nog steeds specs nodig, misschien meer dan dat. In zes maanden tijd wanneer je deze functie moet uitbreiden , won jeM SK3 je herinnert je niet waarom je bepaalde beslissingen hebt genomen. De spec is je verleden zelf die met je toekomstige zelf praat.
Plus je moet nog steeds:
Spezifikationen schrijven voor jezelf is net als het schrijven van eenheidstests: het voelt trager nu, maar het spaart later tijd ( zoals ik , IM SK3m in mijn 50s MSC5 Ik vergaat heutzutage SHITMスク6 schrijven ze op zodat het gedaan wordtMska7 zelfs als hetM Ska8 alleen een github-uitdaglijst isMske9
Als iemand zegt: " Oh, ,", vergeet ik te vermelden dat het ook zou moeten doen.
Antwoord: M SK1Dat'is een goede vereisteMST3 maar hetMst4 is niet wat we in de specificatie hadden toegekendMSt5Laten we dit nu toevoegen aan de Afzonderlijk bereik sectie en discussiëren of het inbegrepen moet worden, of het voor versies bewaard moet worden.
Als het echt een vereiste is (niet een mooi-toM SK2haveMSC3 danMST4
Moet nooit stil de schaalkraep absorberen. Het' zal je schattingen en geloofwaardigheid vernietigen
Ja, als je' een prototype maakt om open vragen te beantwoorden.
Prototyperen om te leren, is goed: "We hebben drie benaderingen . Laat me elk uitsplitsen om te zien welke het beste werkt ." Dat informeert de spec
Het bouwen van productiecode voordat de spec klaar is, betekent dat je'we raden naar de eisen. JeM SK2 zal waarschijnlijk het verkeerde ding bouwen.
Uitsondering: als jeM SK1 de producteigenaar en ontwikkelaar bent (soloproject), kan je tegelijkertijd specificeren en coderenMSC4 Maar documenteer toch je beslissingen terwijl je verdergaat.
De ' tot de spec klaar is ' is een GREAT manier om de werknemers te laten opladen voor het begin . Evaluatie van technologie-aanpakkingen M SK3 schrijven van een gemeenschappelijke boilerplaat etc.
Zoek uit waarom:
Als mensen spec-beoordelingen overslaan en dan het verkeerde ding bouwen, maakt de pijn zichtbaar.
Als ze in een obscure wiki begraven zijn, zal niemand ze lezen.
Duimregel: 5-10% van de ontwikkelingstijdM SK2
Voor een 2-weeksfunctieM SK1 1-2 dagen op de spec. Voor een 1-weeks-functie: een halve dag op de specM SK2 Voor een 2-dag-functie: een uur of twee op de specM SK2
Maar wees er niet religieus over. Sommige kenmerken hebben meer nodig.-, voorzichtig denken.., andere zijn duidelijk en het spec duurt maar een paar minuten.
Als je' meer tijd besteedt aan het spec dan aan de implementatie ,, denk je erover teveel over na.
Omdat software-estimatie fundamenteel moeilijk is. schattingen werken alleen als je EXACT die taak eerder gedaan hebt in die omgeving.
Wat bijna nooit gebeurt.
Elke keer als je schatt,,, heb je met ' te maken.
Dit is waarom:
Hoe nieuwsgieriger het werk is, hoe slechter je schattingen zijn.. Het bouwen van dezelfde CRUD-vorm die jij hebt gemaakt, ' heb je gebouwd, 50 keer,? Je zal dichtbij zijn, ' Integratie met een nieuw service met behulp van een onbekend protocol.
Daarom hebben specs een duidelijke "doen"kritieken . Je kuntM SK3 geen nauwkeurige schatting makenMSC4 maar je kan bepalen wanneer je moet stoppen.
Deze hebben verschillende criteria nodig. "done" criteriaM SK2 In plaats van "functie X werktMST4 het isMst5s mst6 wijMSt7we hebben de vraag beantwoord YM st8
Voorbeeldspectief voor verkenning:
Tijd-boxen is essentieel voor de verkenning. Zonder het zou onderzoek nooit eindigen.
Begin met wat je weet:
Merk delen als "TBD." Wees eerlijk over onzekerheid
Gebruik dan het spec-beoordelingsproces om gaten te vullen. De gesprekken tijdens de beoordeling verklaren vaak wat je niet verstandigde.
Onthoud: onvolledig-maar -honest beats completeM SK3maardMSC4 verkeerdMST5
Absoluut. De spec hoeft geen aparte document te zijn ' Een goed geschreven GitHub-uitgave of JIRA-ticket kan als spec perfect goed dienen.
Wat er aan de hand is, is de inhoud.
De voordelen van het gebruik van uitgaven:
Tips om problemen als specs te gebruiken:
De test: zou iemand het probleem kunnen lezen en weten wat hij moet bouwen, wat "doeM SK3 betekent , en wat' buiten de scope isMSC6 Als ja, , is het een goed spec, ongeacht het formaat.
Als je in de gezondheidszorg bent, ,, financiën, ,, lucht- en ruimtevaart,,, of andere gereguleerde gebieden, ,, dan heb je misschien meer formele specificaties nodig voor conformiteit.
Maar je zal ook moeten.
Zelfs in gereguleerde omgevingen.
Goede eigenschapsspecifieken schrijven in een agile omgeving is een vaardigheid die met de praktijk verbetert.. Het doel is niet perfect specs te schrijven voorhanden.
De belangrijkste principes:
Het moeilijkste deel is:"', niet het eerste spec schrijven, ., het weten wanneer je moet stoppen met werken aan een functie, ., zonder duidelijke criteria.
Daarom is het zo moeilijk om 'agile' te schatten.. U' schat niet alleen de implementatietijd, maar ook de leertijd.
Het beste wat je kunt doen, is: : duidelijk zijn over wat "doe, " betekent,, tijd,-box oncertainty en het spec opdateer zoals je leert.
Een goede spec geeft ontwikkelaars de macht om problemen intelligent op te lossen terwijl ze precies weten wanneer ze kunnen stoppen.
Als je een ontwikkelaar bent die een spec leest dat geen zin heeft of geen duidelijke criteria heeft, dan is het beter om het nu te sorteren dan een eigenschap te bouwen die blijft groeien tot het de hele toepassing overneemt.
© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.