OpenSpec

Aan de slag ​

Deze handleiding legt uit hoe OpenSpec werkt nadat u het heeft geïnstalleerd en geïnitialiseerd. Voor installatie-instructies, zie de hoofdlezing of de installatiehandleiding. Nieuw bij de hele documentatiereeks? De documentatiehome geeft een overzicht van alles.

Waar typ ik deze commando's? Twee plekken, en ze verwisselen is de meest voorkomende beginnende fout.

  • openspec ... commando's (zoals openspec init) worden uitgevoerd in uw terminal.
  • /opsx:... commando's (zoals /opsx:propose) worden uitgevoerd in de chat van uw AI-assistent, dezelfde plek waar u hem code zou laten schrijven.

Er is geen aparte "interactieve modus" om te starten. U typt gewoon het slash-commando in de chat en uw assistent neemt het van daaruit over. Volledige uitleg: Hoe commando's werken.

Uw eerste vijf minuten ​

De volledige cyclus, met elke stap gelabeld naar waar deze plaatsvindt:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (optioneel: eerst doordenken)
AI CHAT      /opsx:propose add-dark-mode      (AI schetst het plan; u beoordeelt het)
AI CHAT      /opsx:apply                      (AI bouwt het)
AI CHAT      /opsx:archive                    (specificaties bijgewerkt, wijziging gearchiveerd)

Twee terminalstappen voor de opstart, daarna leeft u in de chat. De rest van deze handleiding legt uit wat elke stap doet en wat u zult zien.

Wilt u de terminalstappen niet zelf doen? Plak de opstartprompt in uw assistent en die behandelt beide regels, en rapporteert wat hij heeft aangemaakt.

Weet u nog niet zeker wat u wilt bouwen? Begin met /opsx:explore. Het is een risicovrije denkpartner die uw codebase leest, opties weegt en een vaag idee scherpt tot een concreet plan, alles voordat er een artefact of code bestaat. Wanneer het beeld helder is, geeft het over aan /opsx:propose. Dit is de beste gewoonte voor het werken met een AI die anders zelfverzekerd het verkeerde ding zou bouwen. Zie de Explore-handleiding.

Hoe het werkt ​

OpenSpec helpt u en uw AI-codingassistent overeenstemming te bereiken over wat er moet worden gebouwd voordat er code wordt geschreven.

Standaard snelpad (core-profiel):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (optioneel)

Begin met /opsx:explore wanneer u uitvindt wat u wilt doen, of ga direct naar /opsx:propose wanneer u het al weet. Explore zit in het standaardprofiel, dus het is altijd beschikbaar wanneer u het wilt.

Uitgebreid pad (aangepaste workflowselectie):

text
/opsx:new ──► /opsx:ff of /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Het standaard globale profiel is core, dat propose, explore, apply, update, sync en archive bevat. U kunt de uitgebreide workflowcommando's inschakelen met openspec config profile en vervolgens openspec update.

Wat OpenSpec aanmaakt ​

Na het uitvoeren van openspec init heeft uw project deze structuur:

openspec/
├── specs/              # Bron van waarheid (het gedrag van uw systeem)
│   └── <domain>/
│       └── spec.md
├── changes/            # Voorgestelde wijzigingen (één map per wijziging)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta-specificaties (wat er verandert)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Projectconfiguratie (optioneel)

Twee belangrijke mappen:

  • specs/ - De bron van waarheid. Deze specificaties beschrijven hoe uw systeem momenteel werkt. Georganiseerd per domein (bijv. specs/auth/, specs/payments/).

  • changes/ - Voorgestelde wijzigingen. Elke wijziging krijgt zijn eigen map met alle gerelateerde artefacten. Wanneer een wijziging is voltooid, worden de specificaties samengevoegd met de hoofd-specs/-map.

Artefacten begrijpen ​

Elke wijzigingsmap bevat artefacten die het werk sturen:

ArtefactDoel
proposal.mdHet "waarom" en "wat" - vangt intentie, reikwijdte en aanpak op
specs/Delta-specificaties die TOEGEVOEGDE/GEWIJZIGDE/VERWIJDERDE vereisten tonen
design.mdHet "hoe" - technische aanpak en architectuurbeslissingen
tasks.mdImplementatiechecklist met selectievakjes

Artefacten bouwen op elkaar:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            bijwerken naarmate u leert

U kunt altijd terugkeren en eerdere artefacten verfijnen naarmate u meer leert tijdens de implementatie.

Hoe delta-specificaties werken ​

Delta-specificaties zijn het kernconcept in OpenSpec. Ze tonen wat er verandert ten opzichte van uw huidige specificaties.

Het formaat ​

Delta-specificaties gebruiken secties om het type wijziging aan te geven:

markdown
# Delta voor Auth

## TOEGEVOEGDE Vereisten

### Vereiste: Tweefactorauthenticatie
Het systeem MOET een tweede factor vereisen tijdens inloggen.

#### Scenario: OTP vereist
- GIVEN een gebruiker met 2FA ingeschakeld
- WHEN de gebruiker geldige inloggegevens indient
- THEN wordt een OTP-uitdaging getoond

## GEWIJZIGDE Vereisten

### Vereiste: Sessietijd
Het systeem ZAL sessies verlopen laten na 30 minuten inactiviteit.
(Vroeger: 60 minuten)

#### Scenario: Inactiviteitstijd
- GIVEN een geauthenticeerde sessie
- WHEN 30 minuten verlopen zonder activiteit
- THEN wordt de sessie ongeldig

## VERWIJDERDE Vereisten

### Vereiste: Onthoud mij
(Verouderd ten gunste van 2FA)

Wat er gebeurt bij archiveren ​

Wanneer u een wijziging archiveert:

  1. TOEGEVOEGDE vereisten worden toegevoegd aan de hoofdspecificatie
  2. GEWIJZIGDE vereisten vervangen de bestaande versie
  3. VERWIJDERDE vereisten worden verwijderd uit de hoofdspecificatie

De wijzigingsmap verplaatst zich naar openspec/changes/archive/ voor auditgeschiedenis.

Voorbeeld: Uw eerste wijziging ​

Laten we het toevoegen van dark mode aan een applicatie doorlopen.

1. De wijziging starten (standaard) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — waarom we dit doen, wat er verandert
     ✓ specs/       — vereisten en scenario's
     ✓ design.md    — technische aanpak
     ✓ tasks.md     — implementatiechecklist
     Ready for implementation!

Als u het uitgebreide workflowprofiel heeft ingeschakeld, kunt u dit ook in twee stappen doen: /opsx:new en dan /opsx:ff (of /opsx:continue incrementeel).

2. Wat er wordt aangemaakt ​

proposal.md - Vangt de intentie op:

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - Delta met nieuwe vereisten:

markdown
# Delta voor UI

## TOEGEVOEGDE Vereisten

### Vereiste: Thema-selectie
Het systeem ZAL gebruikers toestaan tussen licht en donker thema te kiezen.

#### Scenario: Handmatige schakelaar
- GIVEN een gebruiker op een willekeurige pagina
- WHEN de gebruiker op de themaschakelaar klikt
- THEN schakelt het thema onmiddellijk over
- EN de voorkeur wordt behouden tussen sessies

#### Scenario: Systeemvoorkeur
- GIVEN een gebruiker zonder opgeslagen voorkeur
- WHEN de applicatie laadt
- THEN wordt de voorkeurkleurschema van het systeem gebruikt

tasks.md - Implementatiechecklist:

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. Implementeren ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

Tijdens de implementatie, als u ontdekt dat het ontwerp aanpassing nodig heeft, werkt u het artefact gewoon bij en gaat u verder.

4. Archiveren ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

Uw delta-specificaties zijn nu onderdeel van de hoofdspecificaties, die documenteren hoe uw systeem werkt.

Verifiëren en beoordelen ​

Gebruik de CLI om uw wijzigingen te controleren:

bash
# Actieve wijzigingen weergeven
openspec list

# Details van wijziging bekijken
openspec show add-dark-mode

# Specificatieformatering valideren
openspec validate add-dark-mode

# Interactief dashboard
openspec view

Volgende stappen ​