Concepten
Deze gids legt de kernideeën achter OpenSpec uit en hoe ze samenwerken. Voor praktisch gebruik, zie Aan de slag en Werkstromen.
Filosofie
OpenSpec is gebaseerd op vier principes:
flexibel, niet rigide — geen fasepoorten, werk aan wat zinvol is
iteratief, niet waterval — leer terwijl je bouwt, verfijn gaandeweg
eenvoudig, niet complex — lichte opzet, minimale ceremonie
brownfield-eerst — werkt met bestaande codebases, niet alleen greenfieldWaarom deze principes ertoe doen
Flexibel, niet rigide. Traditionele specificatiesystemen dwingen je in fases: eerst plannen, dan implementeren, dan ben je klaar. OpenSpec is flexibeler – je kunt artefacten in elke volgorde creëren die zinvol is voor jouw werk.
Iteratief, niet waterval. Vereisten veranderen. Inzicht verdiept. Wat aan het begin een goede aanpak leek, houdt misschien geen stand nadat je de codebase hebt gezien. OpenSpec omarmt deze realiteit.
Eenvoudig, niet complex. Sommige specificatieframeworks vereisen uitgebreide setup, rigide formaten of zware processen. OpenSpec zit je niet in de weg. Initialiseer in seconden, begin meteen met werken, pas alleen aan als het nodig is.
Brownfield-eerst. Het meeste softwarewerk is niet vanaf nul bouwen – het is het aanpassen van bestaande systemen. OpenSpecs delta-gebaseerde benadering maakt het eenvoudig om wijzigingen in bestaand gedrag te specificeren, niet alleen om nieuwe systemen te beschrijven.
Het Grote Beeld
OpenSpec organiseert uw werk in twee hoofdgebieden:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Bron van waarheid │◄─────│ Voorgestelde wijzigingen │ │
│ │ Hoe uw systeem │ merge│ Elke wijziging = één map │ │
│ │ momenteel werkt │ │ Bevat artefacten + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specificaties zijn de bron van waarheid — ze beschrijven hoe uw systeem momenteel werkt.
Wijzigingen zijn voorgestelde aanpassingen — ze bevinden zich in aparte mappen totdat u klaar bent om ze te integreren.
Deze scheiding is cruciaal. U kunt parallel aan meerdere wijzigingen werken zonder conflicten. U kunt een wijziging beoordelen voordat deze de hoofdspecificaties beïnvloedt. En wanneer u een wijziging archiveert, worden de deltas ervan netjes geïntegreerd in de bron van waarheid.
Specificaties
Specificaties beschrijven het gedrag van uw systeem met behulp van gestructureerde eisen en scenarios.
Structuur
openspec/specs/
├── auth/
│ └── spec.md # Authenticatiegedrag
├── payments/
│ └── spec.md # Betalingsverwerking
├── notifications/
│ └── spec.md # Notificatiesysteem
└── ui/
└── spec.md # UI-gedrag en thema'sOrganiseer specificaties per domein — logische groeperingen die zinvol zijn voor uw systeem. Veelvoorkomende patronen:
- Per functiegebied:
auth/,payments/,search/ - Per component:
api/,frontend/,workers/ - Per begrensd context:
ordering/,fulfillment/,inventory/
Specificatieformaat
Een specificatie bevat eisen, en elke eis heeft scenarios:
# Auth Specificatie
## Doel
Authenticatie en sessiebeheer voor de applicatie.
## Eisen
### Eis: Gebruikersauthenticatie
Het systeem SHALL een JWT-token uitreiken bij succesvolle inlogging.
#### Scenario: Geldige inloggegevens
- GIVEN een gebruiker met geldige inloggegevens
- WHEN de gebruiker het inlogformulier indient
- THEN wordt een JWT-token teruggegeven
- AND de gebruiker wordt doorgestuurd naar het dashboard
#### Scenario: Ongeldige inloggegevens
- GIVEN ongeldige inloggegevens
- WHEN de gebruiker het inlogformulier indient
- THEN wordt een foutmelding weergegeven
- AND er wordt geen token uitgereikt
### Eis: Sessieverval
Het systeem MUST sessies laten verlopen na 30 minuten inactiviteit.
#### Scenario: Inactiviteitstimeout
- GIVEN een geauthenticeerde sessie
- WHEN 30 minuten verlopen zonder activiteit
- THEN wordt de sessie ongeldig verklaard
- AND de gebruiker moet zich opnieuw authentifierenBelangrijke elementen:
| Element | Doel |
|---|---|
## Doel | Overkoepelende beschrijving van het domein van deze specificatie |
### Eis: | Een specifiek gedrag dat het systeem moet hebben |
#### Scenario: | Een concreet voorbeeld van de eis in actie |
| SHALL/MUST/SHOULD | RFC 2119-trefwoorden die de sterkte van de eis aangeven |
Waarom Specificaties Zo Structureren
Eisen zijn het "wat" — ze stellen wat het systeem moet doen zonder de implementatie te specificeren.
Scenarios zijn het "wanneer" — ze bieden concrete voorbeelden die geverifieerd kunnen worden. Goede scenarios:
- Zijn testbaar (u kunt er een geautomatiseerde test voor schrijven)
- Dekken zowel de happy path als edge cases
- Gebruiken Given/When/Then of een vergelijkbaar gestructureerd formaat
RFC 2119-trefwoorden (SHALL, MUST, SHOULD, MAY) communiceren intentie:
- MUST/SHALL — absolute eis
- SHOULD — aanbevolen, maar uitzonderingen bestaan
- MAY — optioneel
Wat Een Specificatie Is (en Niet Is)
Een specificatie is een gedragscontract, geen implementatieplan.
Goede specificatie-inhoud:
- Waarneembaar gedrag waar gebruikers of downstream-systemen op vertrouwen
- Inputs, outputs en foutcondities
- Externe beperkingen (beveiliging, privacy, betrouwbaarheid, compatibiliteit)
- Scenarios die getest of expliciet gevalideerd kunnen worden
Vermijd in specificaties:
- Interne klasse-/functienamen
- Keuzes van bibliotheken of frameworks
- Stap-voor-stap implementatiedetails
- Gedetailleerde uitvoeringsplannen (die horen in
design.mdoftasks.md)
Snelle test:
- Als de implementatie kan veranderen zonder dat extern zichtbaar gedrag verandert, hoort het waarschijnlijk niet in de specificatie.
Houd Het Licht: Progressieve Strengheid
OpenSpec streeft ernaar bureaucratie te vermijden. Gebruik het lichtste niveau dat de wijziging nog steeds verifieerbaar maakt.
Lite-specificatie (standaard):
- Korte, gedrag-gerichte eisen
- Helder bereik en niet-doelen
- Een paar concrete acceptatiechecks
Volledige specificatie (voor hoger risico):
- Wijzigingen die meerdere teams of repositories betreffen
- API-/contractwijzigingen, migraties, beveiligings-/privacyzorgen
- Wijzigingen waarbij onduidelijkheid waarschijnlijk dure herwerking zal veroorzaken
De meeste wijzigingen moeten in Lite-modus blijven.
Mens + Agent Samenwerking
In veel teams verkennen mensen en stellen agents artefacten op. De beoogde lus is:
- Mens levert intentie, context en beperkingen.
- Agent zet dit om in gedrag-gerichte eisen en scenarios.
- Agent houdt implementatiedetails in
design.mdentasks.md, niet inspec.md. - Validatie bevestigt structuur en helderheid vóór implementatie.
Dit houdt specificaties leesbaar voor mensen en consistent voor agents.
Wijzigingen
Een wijziging is een voorgestelde aanpassing aan uw systeem, verpakt als een map met alles wat nodig is om deze te begrijpen en te implementeren.
Structuur van een Wijziging
openspec/changes/add-dark-mode/
├── proposal.md # Waarom en wat
├── design.md # Hoe (technische aanpak)
├── tasks.md # Implementatiechecklist
├── .openspec.yaml # Wijzigingsmetadata (optioneel): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta-specificaties
└── ui/
└── spec.md # Wat er verandert in ui/spec.mdElke wijziging is zelfstandig. Het bevat:
- Artefacten — documenten die intentie, ontwerp en taken vastleggen
- Delta-specificaties — specificaties voor wat wordt toegevoegd, gewijzigd of verwijderd
- Metadata — optionele configuratie voor deze specifieke wijziging
Waarom Wijzigingen Mappen Zijn
Het verpakken van een wijziging als map biedt meerdere voordelen:
Alles bij elkaar. Voorstel, ontwerp, taken en specificaties bevinden zich op één plek. Geen zoeken door verschillende locaties.
Parallel werk. Meerdere wijzigingen kunnen tegelijkertijd bestaan zonder conflicten. Werk aan
add-dark-modeterwijlfix-auth-bugook in uitvoering is.Schoone geschiedenis. Wanneer gearchiveerd, verhuizen wijzigingen naar
changes/archive/met hun volledige context behouden. U kunt terugkijken en niet alleen begrijpen wat er veranderd is, maar ook waarom.Beoordelingsvriendelijk. Een wijzigingsmap is makkelijk te beoordelen — open het, lees het voorstel, controleer het ontwerp, bekijk de delta-specificaties.
Artefacten
Artefacten are de documenten binnen een wijziging die het werk begeleiden.
De Artefactenstroom
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
waarom wat hoe stappen
+ bereik wijzigingen aanpak te nemenArtefacten bouwen op elkaar. Elk artefact biedt context voor het volgende.
Artefacttypes
Voorstel (proposal.md)
Het voorstel vangt intentie, bereik en aanpak op een hoog niveau.
# Voorstel: Donker Modus Toevoegen
## Intentie
Gebruikers hebben een donker modus-optie aangevraagd om oogvermoeidheid
tijdens nachtelijk gebruik te verminderen en systeemvoorkeuren te matchen.
## Bereik
In bereik:
- Thematoschakelaar in instellingen
- Systeemvoorkeur detectie
- Voorkeur opslaan in localStorage
Buiten bereik:
- Aangepaste kleurenthema's (toekomstig werk)
- Per-pagina thema-overrides
## Aanpak
Gebruik CSS custom properties voor theming met een React context
voor statusbeheer. Detecteer systeemvoorkeur bij eerste laden,
sta handmatige override toe.Wanneer het voorstel bij te werken:
- Bereik verandert (vernauwen of uitbreiden)
- Intentie wordt helderder (beter begrip van het probleem)
- Aanpak fundamenteel verschuift
Specificaties (delta-specificaties in specs/)
Delta-specificaties beschrijven wat er verandert ten opzichte van de huidige specificaties. Zie Delta-Specificaties hieronder.
Ontwerp (design.md)
Het ontwerp vangt de technische aanpak en architectuurbeslissingen.
# Ontwerp: Donker Modus Toevoegen
## Technische Aanpak
Themastatus beheerd via React Context om prop drilling te vermijden.
CSS custom properties maken runtime-wisseling mogelijk zonder class toggling.
## Architectuurbeslissingen
### Beslissing: Context in plaats van Redux
React Context gebruiken voor themastatus omdat:
- Eenvoudige binair status (licht/donker)
- Geen complexe statusovergangen
- Voegt geen Redux-afhankelijkheid toe
### Beslissing: CSS Custom Properties
CSS variabelen gebruiken in plaats van CSS-in-JS omdat:
- Werkt met bestaande stylesheet
- Geen runtime overhead
- Browser-native oplossing
## Datastroom
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (toegepast op :root)
```
## Bestandswijzigingen
- `src/contexts/ThemeContext.tsx` (nieuw)
- `src/components/ThemeToggle.tsx` (nieuw)
- `src/styles/globals.css` (gewijzigd)Wanneer het ontwerp bij te werken:
- Implementatie onthult dat de aanpak niet werkt
- Beter oplossing ontdekt
- Afhankelijkheden of beperkingen veranderen
Taken (tasks.md)
Taken zijn de implementatiechecklist — concrete stappen met selectievakjes.
# Taken
## 1. Thema-infrastructuur
- [ ] 1.1 ThemeContext aanmaken met licht/donker status
- [ ] 1.2 CSS custom properties toevoegen voor kleuren
- [ ] 1.3 localStorage-persistentie implementeren
- [ ] 1.4 Systeemvoorkeur detectie toevoegen
## 2. UI-componenten
- [ ] 2.1 ThemeToggle-component aanmaken
- [ ] 2.2 Schakelaar toevoegen aan instellingenpagina
- [ ] 2.3 Header bijwerken met snelle schakelaar
## 3. Stijling
- [ ] 3.1 Donker thema kleurenpalet definiëren
- [ ] 3.2 Componenten bijwerken om CSS variabelen te gebruiken
- [ ] 3.3 Contrastverhoudingen testen voor toegankelijkheidTaken best practices:
- Groepeer gerelateerde taken onder koppen
- Gebruik hiërarchische nummering (1.1, 1.2, etc.)
- Houd taken klein genoeg om in één sessie te voltooien
- Vink taken af zodra u ze voltooit
Delta-Specificaties
Delta-specificaties zijn het kernconcept dat OpenSpec geschikt maakt voor brownfield-ontwikkeling. Ze beschrijven wat er verandert in plaats van de volledige specificatie opnieuw te stellen.
Het Formaat
# Delta voor Auth
## TOEGEVOEGDE Eisen
### Eis: Tweefactorauthenticatie
Het systeem MUST TOTP-gebaseerde tweefactorauthenticatie ondersteunen.
#### Scenario: 2FA inschrijving
- GIVEN een gebruiker zonder 2FA geactiveerd
- WHEN de gebruiker 2FA activeert in instellingen
- THEN wordt een QR-code weergegeven voor authenticator app setup
- AND de gebruiker moet verifiëren met een code vóór activering
#### Scenario: 2FA inloggen
- GIVEN een gebruiker met 2FA geactiveerd
- WHEN de gebruiker geldige inloggegevens indient
- THEN wordt een OTP-uitdaging gepresenteerd
- AND inloggen voltooit alleen na geldige OTP
## GEWIJZIGDE Eisen
### Eis: Sessieverval
Het systeem MUST sessies laten verlopen na 15 minuten inactiviteit.
(Vroeger: 30 minuten)
#### Scenario: Inactiviteitstimeout
- GIVEN een geauthenticeerde sessie
- WHEN 15 minuten verlopen zonder activiteit
- THEN wordt de sessie ongeldig verklaard
## VERWIJDERDE Eisen
### Eis: Onthoud Me
(Gedepriveerd ten gunste van 2FA. Gebruikers moeten zich elke sessie opnieuw authentifieren.)Delta-Secties
| Sectie | Betekenis | Wat Er Gebeurt Bij Archiveren |
|---|---|---|
## TOEGEVOEGDE Eisen | Nieuw gedrag | Toegevoegd aan hoofdspecificatie |
## GEWIJZIGDE Eisen | Gewijzigd gedrag | Vervangt bestaande eis |
## VERWIJDERDE Eisen | Gedepriveerd gedrag | Verwijderd uit hoofdspecificatie; het verwijderen van de laatste eis retireert de capaciteit en verwijdert het specificatiebestand, wanneer de wijziging retire_capabilities: true declareert |
## Doel | Waarvoor een nieuwe capaciteit is | Zaait het Doel van de te maken hoofdspecificatie; genegeerd wanneer de specificatie al bestaat |
Waarom Deltas in Plaats van Volledige Specificaties
Helderheid. Een delta toont precies wat er verandert. Bij het lezen van een volledige specificatie zou u mentaal een diff moeten maken tegenover de huidige versie.
Conflictvermijding. Twee wijzigingen kunnen hetzelfde specificatiebestand raken zonder conflicten, zolang ze verschillende eisen wijzigen.
Beoordelings-efficiëntie. Beoordelaars zien de wijziging, niet de ongewijzigde context. Focus op wat belangrijk is.
Brownfield-fit. Het grootste deel van het werk wijzigt bestaand gedrag. Deltas maken wijzigingen first-class, niet een afterthought.
Schemas
Schemas definiëren de artefacttypes en hun afhankelijkheden voor een workflow.
Hoe Schemas Werken
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Geen afhankelijkheden, kan als eerste worden aangemaakt
- id: specs
generates: specs/**/*.md
requires: [proposal] # Vereist proposal voordat het kan worden aangemaakt
- id: design
generates: design.md
requires: [proposal] # Kan parallel met specs worden aangemaakt
- id: tasks
generates: tasks.md
requires: [specs, design] # Vereist zowel specs als design eerstArtefacten vormen een afhankelijkheidsgrafiek:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(vereist: (vereist:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(vereist:
specs, design)Afhankelijkheden zijn mogelijkmakers, geen poorten. Ze tonen wat er mogelijk is om te maken, niet wat je als volgende stap moet maken. Je kunt design overslaan als je het niet nodig hebt. Je kunt specs vóór of ná design maken — beide hangen alleen af van proposal.
Ingebouwde Schemas
spec-driven (standaard)
De standaardworkflow voor spec-gedreven ontwikkeling:
proposal → specs → design → tasks → implementBest voor: De meeste functionaliteitswerk waar je eerst overeenkomt over specificaties voordat je implementeert.
Aangepaste Schemas
Maak aangepaste schemas voor de workflow van je team:
# Maak van schone lei
openspec schema init research-first
# Of fork een bestaand schema
openspec schema fork spec-driven research-firstVoorbeeld aangepast schema:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Doe eerst onderzoek
- id: proposal
generates: proposal.md
requires: [research] # Proposal geïnformeerd door onderzoek
- id: tasks
generates: tasks.md
requires: [proposal] # Sla specs/design over, ga direct naar takenZie Customization voor volledige details over het maken en gebruiken van aangepaste schemas.
Archive
Archiveren voltooit een wijziging door de delta-specificaties te samenvoegen met de hoofdspecificaties en de wijziging voor de geschiedenis te bewaren.
Wat Er Gebeurt Bij Archiveren
Vóór archiveren:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Na archiveren:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Bevat nu 2FA-eisen
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Bewaard voor de geschiedenis
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdHet Archiveerproces
Delta's samenvoegen. Elke delta-specificatie-sectie (ADDED/MODIFIED/REMOVED) wordt toegepast op de bijbehorende hoofdspecificatie.
Verplaatsen naar archief. De wijzigingsmap wordt verplaatst naar
changes/archive/met een datumvooraanvoegsel voor chronologische volgorde.Context bewaren. Alle artefacten blijven intact in het archief. Je kunt altijd terugkijken om te begrijpen waarom een wijziging is doorgevoerd.
Waarom Archiveren Belangrijk Is
Schoone staat. Actieve wijzigingen (changes/) toont alleen werk in uitvoering. Voltooid werk wordt uit de weg geruimd.
Audit trail. Het archief bewaart de volledige context van elke wijziging — niet alleen wat er is veranderd, maar ook het voorstel dat uitlegt waarom, het ontwerp dat uitlegt hoe, en de taken die het uitgevoerde werk tonen.
Specificatie-evolutie. Specificaties groeien organisch naarmate wijzigingen worden gearchiveerd. Elk archief voegt zijn delta's samen en bouwt zo een uitgebreide specificatie op over de tijd.
Hoe Het Alles Samen Past
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) of /opsx:new (expanded) │
│ │ WIJZIGING │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. MAAK │ /opsx:ff of /opsx:continue (expanded workflow) │
│ │ ARTEFACTEN │ Maakt proposal → specs → design → tasks │
│ │ │ (op basis van schema-afhankelijkheden) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENTEER│ /opsx:apply │
│ │ TAKEN │ Werk door de taken heen, vink ze af │
│ │ │◄──── Werk artefacten bij naarmate je leert │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFICEER │ /opsx:verify (optioneel) │
│ │ WERK │ Controleer of implementatie overeenkomt met specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVEER │────►│ Delta-specificaties samenvoegen met hoofdspecs│ │
│ │ WIJZIGING │ │ Wijzigingsmap verplaatst naar archive/ │ │
│ └────────────────┘ │ Specs zijn nu de bijgewerkte bron van waarheid│ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘De deugdzame cyclus:
- Specificaties beschrijven het huidige gedrag
- Wijzigingen stellen aanpassingen voor (als delta's)
- Implementatie maakt de wijzigingen werkelijkheid
- Archiveren voegt delta's samen met specificaties
- Specificaties beschrijven nu het nieuwe gedrag
- De volgende wijziging bouwt voort op de bijgewerkte specificaties
Woordenlijst
| Term | Definitie |
|---|---|
| Artefact | Een document binnen een wijziging (proposal, design, tasks of delta-specificaties) |
| Archiveren | Het proces van het voltooien van een wijziging en het samenvoegen van de delta's met de hoofdspecificaties |
| Wijziging | Een voorgestelde aanpassing aan het systeem, verpakt als een map met artefacten |
| Delta-specificatie | Een specificatie die wijzigingen beschrijft (ADDED/MODIFIED/REMOVED) ten opzichte van de huidige specificaties |
| Domein | Een logische groepering voor specificaties (bijv. auth/, payments/) |
| Eis | Een specifiek gedrag dat het systeem moet hebben |
| Scenario | Een concreet voorbeeld van een eis, meestal in Given/When/Then-formaat |
| Schema | Een definitie van artefacttypes en hun afhankelijkheden |
| Specificatie | Een specificatie die systeemgedrag beschrijft, met eisen en scenario's |
| Bron van waarheid | De openspec/specs/-map, die het huidige overeengekomen gedrag bevat |
Volgende Stappen
- Getting Started - Praktische eerste stappen
- Workflows - Veelvoorkomende patronen en wanneer je welke gebruikt
- Commands - Volledige commandoreferentie
- Customization - Maak aangepaste schemas en configureer je project