Een duidelijke, nauwkeurige en effectieve specificatie genereren

14 minuten

Het specificatiebestand (spec.md) is de enige bron van waarheid voor wat uw software moet doen. In deze les worden geavanceerde technieken behandeld voor het schrijven van specificaties op ondernemingsniveau.

Basisbeginselen van specificaties bekijken

Bij specs-gedreven ontwikkeling definieert de specificatie precies wat de software moet doen, en elke implementatiebeslissing is daarop gebaseerd. Een goed gestructureerde specificatie omvat:

Samenvatting: Beknopte beschrijving van de toepassing (of nieuwe functie) vanuit het perspectief van de eindgebruiker.
Gebruikersverhalen: Korte verhalen over de interactie van gebruikers met de toepassing.
Acceptatiecriteria: specifieke, testbare voorwaarden die waar moeten zijn voor voltooiing.
Functionele vereisten: gedetailleerde beschrijvingen van systeemgedrag.
Niet-functionele vereisten: kwaliteitskenmerken zoals prestaties, beveiliging en schaalbaarheid.
Edge-gevallen: Ongebruikelijke scenario's, foutvoorwaarden en grensgedrag.

De specificatie als de enige bron van waarheid

Bij specs-gedreven ontwikkeling definieert de specificatie precies wat de software moet doen, en elke implementatiebeslissing is daarop gebaseerd. Als de functionaliteit niet in de specificatie wordt weergegeven, wordt deze niet weergegeven in het uiteindelijke product, tenzij iemand de specificatie bijwerkt en artefacten opnieuw genereert.

Deze benadering vertegenwoordigt een mindset-verschuiving: het schrijven van de specificatie is net zo belangrijk als het schrijven van code. De specificatie is geen formaliteit om te voldoen aan projectbeheer. Het is het artefact dat het genereren van AI-code aanstuurt. Investeer dezelfde zorg bij het maken van specificaties zoals u zou doen bij het handmatig implementeren van functies.

Denk aan de specificatie als uitvoerbare documentatie. Wanneer u vereisten wijzigt, werkt u de specificatie bij en genereert u het plan en de taken opnieuw. De specificatie, die versiebeheerd is in Git, wordt de gezaghebbende record van wat elke functie moet bereiken.

Voor bedrijfsontwikkelaars die gewend zijn aan agile werkstromen, dient de specificatie hetzelfde doel als gedetailleerde gebruikersverhalen en acceptatiecriteria, maar met machineleesbare structuur die AI-assistenten rechtstreeks kunnen gebruiken.

Specificatiestructuur

GitHub Spec Kit organiseert specificaties in gestandaardiseerde secties die betrekking hebben op functioneel gedrag, kwaliteitsvereisten en edge-zaken.

Overzichtsgedeelte

Een beknopte beschrijving van de functie vanuit het perspectief van de eindgebruiker. In deze sectie moet u antwoorden op 'Wat doet deze functie?' in een of twee zinnen.

Voorbeeld:

## Summary

This feature enables employees to upload PDF and DOCX documents to their personal dashboard. Files are stored securely in Azure Blob Storage and appear in the user's document list immediately after upload.

De samenvatting biedt context op hoog niveau. Iemand die niet bekend is met het project, moet het doel van de functie begrijpen nadat deze sectie is gelezen.

Sectie Gebruikersverhalen

Korte beschrijvingen van de interactie van gebruikers met de functie. Gebruikersverhalen leggen intentie en waarde vast in plaats van technische implementatie.

Voorbeeld:

## User Stories

As an employee, I want to upload documents to my dashboard so that I can access them from any device.

As an employee, I want to see upload progress for large files so that I know the system is processing my request.

As a system administrator, I want uploads to be logged so that we can audit file activity for compliance purposes.

Gebruikersverhalen helpen AI-assistenten inzicht te hebben in de menselijke motivaties achter functies, wat leidt tot intuïtievere implementaties.

Sectie Acceptatiecriteria

Specifieke, testbare voorwaarden die waar moeten zijn om de functie als voltooid te beschouwen. De acceptatiecriteria vormen een controlelijst voor het controleren van de implementatie.

Voorbeeld:

## Acceptance Criteria

- User can select PDF or DOCX files for upload
- Maximum file size is 50MB
- Files larger than 50MB display an error message
- Unsupported file types display an error message
- Successfully uploaded files appear in the document list within 2 seconds
- Upload progress is displayed for files larger than 1MB
- Only users with 'Contributor' role can upload documents
- Uploaded files are stored in user-specific folders in Azure Blob Storage

Schrijf acceptatiecriteria als waarneembare feiten. Vermijd vage instructies zoals 'systeem reageert'. Geef in plaats daarvan 'API reageert binnen 200 ms' op.

Sectie Functionele vereisten

Gedetailleerde beschrijvingen van systeemgedrag. Functionele vereisten beschrijven hoe de functionaliteit werkt.

Voorbeeld:

## Functional Requirements

### Upload interface
- Dashboard displays an "Upload Document" button in the documents section
- Clicking "Upload Document" opens a file selection dialog
- User selects a file from their local filesystem
- System validates file type and size before initiating upload

### Upload process
- Files are uploaded via multipart HTTP POST to /api/documents endpoint
- Upload includes file content and metadata (filename, size, content type)
- Server validates authentication token before accepting upload
- Server checks user has 'Contributor' role before processing

### Storage
- Files are stored in Azure Blob Storage container 'employee-documents'
- Storage path follows pattern: {userId}/{fileId}/{filename}
- Server generates unique file ID to prevent naming collisions
- File metadata (original filename, upload timestamp, user ID) stored in Azure SQL Database

### User feedback
- Upload progress bar updates every 10% completion
- Success message displays upon completion: "Document uploaded successfully"
- Error messages display for: file too large, unsupported type, network error, server error

Functionele vereisten bieden voldoende details voor AI om geschikte implementaties te genereren zonder exacte codestructuur te hoeven schrijven.

Sectie niet-functionele vereisten

Kwaliteitskenmerken zoals prestaties, beveiliging, schaalbaarheid en naleving. Deze vereisten verwijzen vaak naar de grondwet.

Voorbeeld:

## Non-Functional Requirements

### Performance
- File uploads under 5MB complete within 5 seconds on typical network
- Upload progress updates display with less than 100ms latency
- Document list refresh completes within 1 second after upload

### Security
- All uploads require valid Microsoft Entra ID authentication token
- HTTPS/TLS 1.2 enforced for all data transmission
- Files scanned for malware before storage (future enhancement)
- No sensitive data logged (filenames logged, content never logged)

### Scalability
- Support concurrent uploads (up to 5 simultaneous per user)
- Handle 1000 concurrent users uploading files

### Compliance
- Audit log records: user ID, filename, timestamp, file size, IP address
- Audit logs retained for 90 days minimum
- Support data deletion requests within the specified timeline

Niet-functionele vereisten zorgen ervoor dat door AI gegenereerde code voldoet aan kwaliteitsstandaarden van ondernemingen, niet alleen functionele juistheid.

Sectie randgevallen

Ongebruikelijke scenario's, foutvoorwaarden en grensgedrag. Als u edge-zaken expliciet documenteert, voorkomt u dat AI aannames maakt.

Voorbeeld:

## Edge Cases

### Network interruption during upload
- If connection drops, display error: "Upload failed due to network error. Please retry."
- No partial files stored in Azure Blob Storage
- User can retry upload from beginning

### Duplicate filename
- System allows duplicate filenames by generating unique file IDs
- User sees original filename in document list
- Back end uses unique IDs to prevent overwrites

### Storage capacity limits
- If Azure Blob Storage quota exceeded, display error: "Upload failed due to storage limit. Contact support."
- Log storage errors for administrator notification

### Concurrent uploads by same user
- System supports up to 5 simultaneous uploads per user
- Sixth concurrent upload queued until one completes
- Progress bars update independently for each upload

### File type detection
- System validates file type by MIME type, not just extension
- File with .pdf extension but non-PDF content rejected
- Error message: "File appears corrupted or has incorrect type"

Door edge-cases tijdens specificatie te bekijken, voorkomt u fouten die anders zouden ontstaan tijdens de implementatie of het testen.

Een specificatie maken met GitHub Spec Kit

Het schrijven van effectieve specificaties is eenvoudiger met de opdracht van /speckit.specify GitHub Spec Kit.

GitHub Spec Kit genereert specificatieconcepten op basis van beschrijvingen van natuurlijke taal, wat het maken van specificaties versnelt en tegelijkertijd een consistente structuur behoudt.

De opdracht 'specificeer' aanroepen

Ga als volgende te werk om een specificatie te maken:

Open uw project in Visual Studio Code.

Open GitHub Copilot Chat en voer de /speckit.specify opdracht uit met een prompt waarin de functie wordt beschreven die u wilt maken.

Voorbeeld:

/speckit.specify Create a new document upload feature. The feature should allow employees to upload PDF or DOCX documents through the web dashboard. Files are stored in Azure Blob Storage under the user's account folder. After upload, the file appears in the user's document list. Only users with 'Contributor' role can upload. Maximum file size is 50MB. Show error messages for oversized files or unsupported types. Display upload progress for files larger than 1MB.

In deze beschrijving wordt het volgende behandeld:

Wat: PDF-/DOCX-documenten uploaden
Waar: Webdashboardinterface
Hoe: Opgeslagen in Azure Blob Storage
Wie: Gebruikers met de rol Inzender
Beperkingen: limiet van 50 MB, specifieke bestandstypen
Gebruikerservaring: voortgangsweergave, foutberichten

GitHub Copilot genereert een gestructureerd spec.md bestand op basis van deze invoer, maakt secties voor samenvatting, acceptatiecriteria, vereisten en edge-aanvragen.

De gegenereerde specificatie controleren

Nadat GitHub Copilot de specificatie heeft gegenereerd, opent spec.md en verifieert u het volgende:

Volledigheid: Heeft de specificatie betrekking op alle vereisten die u hebt vermeld? Als u 'alleen PDF en DOCX' hebt opgegeven, bevestigt u de acceptatiecriteria voor deze bestandstypen.
Nauwkeurigheid: Zijn details juist? Als u de limiet van 50 MB hebt gezegd, controleert u of de specificatie 50 MB is, niet een andere waarde.
Consistentie: Zijn de verschillende secties op elkaar afgestemd? Als in de samenvatting voortgangsweergave wordt vermeld, moeten de acceptatiecriteria deze bevatten.
Ontbrekende elementen: Wat heeft GitHub Copilot afgeleid of weggelaten? Bekijk gegenereerde vereisten om te zien of de AI veronderstellingen heeft aangenomen waarmee u het niet eens bent.

De eerste specificatie is een sterk uitgangspunt, maar zelden perfect. U kunt het verfijnen door het te verduidelijken.

Specificaties verfijnen met /speckit.clarify

De /speckit.clarify opdracht analyseert uw specificatie en identificeert dubbelzinnigheden, hiaten of veronderstellingen waarvoor verduidelijking is vereist.

Specificatiehelderheid garanderen

Dubbelzinnigheden in specificaties leiden tot onjuiste implementaties. Gebruik /speckit.clarify dit om onduidelijke gebieden weer te geven.

Na het genereren van een eerste specificatie:

Voer in GitHub Copilot Chat het volgende uit:
```
/speckit.clarify
```

GitHub Copilot analyseert spec.md en stelt vragen over onduidelijke of ontbrekende details

Voorbeeld van vragen over verduidelijking:

I've analyzed the specification and have some questions:

1. File retention: How long should uploaded documents be retained? Forever, or is there a retention policy?

2. Duplicate filenames: If a user uploads a file with the same name as an existing file, should the system:
    - Overwrite the existing file
    - Create a new version
    - Reject the upload with an error
    - Store both with unique identifiers

3. Virus scanning: Should uploaded files be scanned for malware? If so, when—before storage or asynchronously after upload?

4. Download capability: The spec describes upload but doesn't mention download. Should users be able to download their uploaded documents?

5. File sharing: Can users share documents with other employees, or are documents private to the uploader?

Deze vragen helpen u bij het nemen van beslissingen over aspecten die u mogelijk in eerste instantie hebt gemist.

Vragen over uitleg beantwoorden

Reageren op elke vraag met specifieke beslissingen:

1. File retention: Retain documents indefinitely until user deletes them. No automatic deletion.

2. Duplicate filenames: Option d - Store both with unique identifiers. Users can have multiple files with the same name. Display upload timestamp to distinguish them in the list.

3. Virus scanning: Not required for initial release. Mark as future enhancement in the spec.

4. Download capability: Yes, users should be able to download their documents. Add this to the spec.

5. File sharing: Documents are private to the uploader for this release. Sharing is a future feature.

Nadat u het antwoord hebt beantwoord, wordt GitHub Copilot spec.md bijgewerkt om uw beslissingen op te nemen:

Acceptatiecriteria krijgen voordelen: 'Gebruikers kunnen eerder geüploade documenten downloaden'.
Functionele vereisten voegen de specificatie van het downloadeindpunt toe.
Edge-gevallen omvatten: 'Meerdere bestanden met identieke namen die zijn onderscheiden door de tijdstempel voor uploaden'.
Opmerking bij niet-functionele vereisten: "Virusscans uitgesteld tot toekomstige versie."

Herhalen totdat het is voltooid

Voer indien nodig meerdere keren uit /speckit.clarify . Elke iteratie verfijnt de specificatie verder:

Eerste evaluatie: belangrijke tekortkomingen in de functionaliteit.
Tweede wachtwoord: Details van Edge-case.
Derde pas: het afstemmen van niet-functionele vereisten.

Stop wanneer GitHub Copilot geen vragen meer heeft of alleen vraagt over functies die u wilt uitstellen.

Best practices voor het schrijven van specificaties

Duidelijke, ondubbelzinnige specificaties schrijven is essentieel voor succesvolle spec-gestuurde ontwikkeling.

Wees specifiek en meetbaar

Vervang vage termen door nauwkeurige waarden:

Niet: 'Ondersteuning voor grote bestanden'.
Ondersteunt bestanden tot 50 MB.
Niet: 'Snelle uploadprestaties'.
In plaats daarvan: 'Uploads van minder dan 5 MB worden binnen 5 seconden voltooid op een 10-Mbps verbinding'.

Met specifieke vereisten kan AI implementaties genereren die voldoen aan uw werkelijke behoeften.

Consistente terminologie gebruiken

Definieer termen eenmaal en hergebruik deze in de specificatie. Als u ze 'documenten' in de samenvatting noemt, schakelt u later niet over naar 'bestanden' of 'bijlagen'. Inconsistente terminologie verwarren zowel mensen als AI.

Gebruik voor interne bedrijfsprojecten officiële productnamen en terminologie uit de standaarden van uw organisatie.

Foutafhandeling expliciet behandelen

Neem niet aan dat AI fouten op de juiste manier verwerkt. Geef op wat er gebeurt wanneer bewerkingen mislukken:

'Als Azure Blob Storage onbereikbaar is, wordt de volgende fout weergegeven: 'Kan geen verbinding maken met de opslagservice. Probeer het later opnieuw.'
"Als de gebruiker geen vereiste rol heeft, retourneer HTTP 403 met het bericht: 'U bent niet gemachtigd om documenten te uploaden.'

Expliciete foutafhandeling voorkomt dat AI algemene foutberichten implementeert die gebruikers niet helpen.

Het juiste bereik behouden

Als voor een functie meer dan 300 regels zijn vereist om op te geven, kunt u overwegen deze op te splitsen in meerdere specificaties:

In plaats van één documentbeheersysteemspecificatie.
Maak afzonderlijke specificaties: 'Document uploaden', 'Document downloaden', 'Document delen' en 'Documenten zoeken'.

Kleinere specificaties zijn gemakkelijker te controleren, te verduidelijken en te implementeren. Ze zijn ook afgestemd op incrementele leveringsprocedures.

Details "wat", niet "hoe"

Specificaties definiëren vereisten, niet implementaties. Geef aan wat het systeem moet doen, niet hoe het moet worden gecodeerd:

Specificatie: 'Geüploade bestanden opslaan in Azure Blob Storage'.
Niet in de specificatie: 'Gebruik het NuGet-pakket Azure.Storage.Blobs met blobContainerClient-klasse'.

Implementatiebeslissingen horen bij de planfase. Als de grondwet echter specifieke technologieën verplicht stelt, is de verwijzing naar deze technologieën in de specificatie passend.

Valideren ten opzichte van de grondwet

Controleer voordat u een specificatie voltooit, of deze niet conflicteren met projectprincipes:

Systeemvereiste: Microsoft Entra ID-verificatie is vereist → De specificatie moet Microsoft Entra ID opgeven, niet aangepaste verificatie.
De grondwet verplicht een bewaartermijn van 90 dagen voor audits → De specificatie moet vereisten voor auditlogregistratie bevatten.
Grondwet beperkt de maximale bestandsgrootte tot 50 MB → Specificatie kan geen ondersteuning van 1 GB vereisen.

Inconsistenties die tijdens de specificatie worden opgemerkt, zijn veel goedkoper te verhelpen dan na de implementatie.

De voltooide specificatie wordt uw contract met GitHub Copilot. Wanneer u verdergaat met de planningsfase, verwijst GitHub Copilot naar deze specificatie om technische implementaties te ontwerpen die precies aansluiten op uw vereisten. De tijd die is geïnvesteerd in grondige specificatie betaalt dividenden gedurende de gehele ontwikkeling.

Samenvatting

Het schrijven van effectieve specificaties is fundamenteel voor succesvolle spec-driven ontwikkeling. Een goed gestructureerde specificatie fungeert als de enige bron van waarheid, het begeleiden van het genereren van AI-code en het garanderen van afstemming met projectprincipes. Met behulp van gitHub Spec Kit's /speckit.specify en /speckit.clarify opdrachten kunt u snel gedetailleerde specificaties maken en verfijnen die betrekking hebben op functioneel gedrag, kwaliteitskenmerken en randcases. Het volgen van best practices in het schrijven van specificaties verbetert de duidelijkheid, vermindert dubbelzinnigheid en leidt tot implementaties die voldoen aan zowel gebruikersbehoeften als bedrijfsstandaarden.

Feedback

Is deze pagina nuttig?