FAQ

Snelle antwoorden op de meest gestelde vragen. Als je vraag eigenlijk een "iets is kapot"-vraag is, is Probleemoplossing een betere pagina. Als je een term gedefinieerd wilt hebben, zie de Verklarende woordenlijst.

De basis

Wat is OpenSpec, in één zin?

Een lichte laag die jou en je AI-coderingsassistent helpt om schriftelijk overeen te komen wat er gebouwd gaat worden, voordat er code wordt geschreven.

Waarom zou ik dat willen?

Omdat AI-assistenten zelfverzekerd zijn, zelfs als ze fout zitten. Wanneer de vereisten alleen in een chatthread bestaan, vult de AI hiaten met gissingen, en ontdek je dat pas nadat de code er is. OpenSpec verplaatst de overeenstemming naar een eerder moment, waar fouten nog goedkoop te herstellen zijn. Zie Kernconcepten in één oogopslag voor de volledige toelichting.

Moet ik het voor alles gebruiken?

Nee. Gebruik het waar overeenstemming belangrijk is, wat voor het meeste niet-triviale werk geldt. Voor een eenvoudige typefoutcorrectie is de ceremonie waarschijnlijk niet de moeite waard, en dat is prima.

Kan ik het op een grote bestaande codebase gebruiken, of alleen voor nieuwe projecten?

Bestaande codebases zijn het hoofdpodium. OpenSpec is brownfield-first: je documenteert niet je hele applicatie vooraf. Je schrijft alleen specificaties voor wat elke wijziging raakt, en je specificaties vullen zich in de loop van de tijd aan rondom het werk dat je daadwerkelijk doet. Er is een speciale handleiding: OpenSpec gebruiken in een bestaand project.

Is het gebonden aan één AI-tool?

Nee. OpenSpec werkt met meer dan 30 assistenten, waaronder Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex en meer. De volledige lijst en details per tool staan in Ondersteunde tools.

Opdrachten uitvoeren

Waar typ ik /opsx:propose?

In de chat van je AI-assistent, niet in je terminal. Dit is het meest voorkomende verwarringspunt, daarom heeft het een eigen pagina: Hoe opdrachten werken. Kort gezegd: openspec ... draait in de terminal, /opsx:... draait in de chat.

Hoe start ik de "interactieve modus"?

Er is geen aparte modus om te starten. Je opent je AI-assistent zoals gewoonlijk en typt een slashopdracht in de chat. De slashopdracht is hoe je OpenSpec "binnengaat". (De enige echt interactieve terminalfunctie is openspec view, een dashboard om specificaties en wijzigingen te bekijken.) Volledige uitleg in Hoe opdrachten werken.

Ik typte een slashopdracht en er gebeurde niets. Waarom?

Waarschijnlijk typte je het in de terminal in plaats van in je AI-chat, gebruikte je een spelling die je tool niet herkent, of zijn de opdrachten nog niet geïnstalleerd. Als de bestanden ontbreken – of je hebt de tool nog nooit ingesteld – voer dan openspec init uit; openspec update vernieuwt alleen bestanden die al bestaan. Start daarna je assistent opnieuw en gebruik de vorm die wordt weergegeven onder "Aan de slag" – zie Hoe aanroepen. Probleemoplossing bevat de volledige checklist.

Waarom is de syntax /opsx:propose in de ene tool en /opsx-propose in de andere?

Elke AI-tool toont aangepaste opdrachten net iets anders, en OpenSpec schrijft ze op de manier waarop jouw tool het bestand laadt dat het heeft geschreven. Een opdrachtbestand genaamd opsx-propose.md wordt getypt als /opsx-propose; een bestand onder commands/opsx/ wordt getypt als /opsx:propose. Tools die vaardigheden (skills) gebruiken in plaats van opdrachten, gebruiken de vaardigheidsnaam – Codex vereist $openspec-propose, Kimi Code /skill:openspec-propose. De "Aan de slag"-regel van openspec init toont al de juiste vorm voor de tools die je hebt gekozen; de volledige tabel staat in Hoe aanroepen.

Wat is het verschil tussen een vaardigheid (skill) en een opdracht?

Beide zijn bestanden die OpenSpec schrijft zodat jouw assistent de workflow kan uitvoeren. Vaardigheden (.../skills/openspec-*/SKILL.md) zijn de nieuwere, cross-tool standaard; opdrachten (.../commands/opsx-*) zijn de oudere, per-tool slash-bestanden. Je hoeft niet te kiezen. Je typt gewoon de slashopdracht, en OpenSpec installeert wat jouw tool gebruikt.

De workflow

Waar moet ik beginnen als ik niet zeker weet wat ik moet bouwen?

Met /opsx:explore. Het is een laagdrempelige denkpartner die je codebase leest, opties uiteenzet en een vaag probleem omzet in een concreet plan, allemaal voordat er een wijziging of code bestaat. Het zit in het standaardprofiel, dus het is altijd beschikbaar. Wanneer het plan duidelijk is, draagt het over aan /opsx:propose. Dit is de allerbeste gewoonte om aan te leren, want het voorkomt dat een enthousiaste AI vol vertrouwen het verkeerde bouwt. Zie Eerst verkennen.

Wat is de eenvoudigst mogelijke flow?

/opsx:explore (optioneel)   dan   /opsx:propose <wat je wilt>   dan   /opsx:apply   dan   /opsx:archive

Verkennen om het door te denken, voorstellen om het plan te schetsen, toepassen om het te bouwen, archiveren om het op te bergen. Sla verkennen over als je al precies weet wat je wilt.

Wat is het verschil tussen /opsx:propose en /opsx:new?

/opsx:propose is de standaard eenstapsopdracht: het creëert de wijziging en stelt alle planningsdocumenten in één keer op. /opsx:new maakt deel uit van de uitgebreide opdrachtenset en maakt alleen een lege wijziging (scaffold), waarna je stap voor stap documenten kunt aanmaken met /opsx:continue (of allemaal tegelijk met /opsx:ff). Gebruik propose tenzij je stapsgewijze controle wilt. Zie Opdrachten.

Wat zijn core en uitgebreide profielen?

Een profiel bepaalt welke slashopdrachten er worden geïnstalleerd. Core (de standaard) geeft je propose, explore, apply, update, sync, archive. De uitgebreide set voegt new, continue, ff, verify, bulk-archive en onboard toe voor fijnmazigere controle. Wissel met openspec config profile en pas toe met openspec update.

Moet ik /opsx:sync uitvoeren?

Meestal niet. Sync voegt de deltaspecificaties van een wijziging samen met je hoofdspecificaties, en /opsx:archive zal aanbieden dat voor je te doen. Voer sync alleen handmatig uit wanneer je de specificaties vóór archivering wilt laten samenvoegen, bijvoorbeeld bij een langlopende wijziging. Zie Opdrachten.

Hoe bewerk ik een voorstel, specificatie of taak nadat ik ben begonnen?

Bewerk gewoon het bestand. Elk document is platte Markdown in openspec/changes/<naam>/, en er is geen vergrendelde fase of speciale bewerkingsmodus. Wijzig het met de hand, of vraag je AI om het te herzien ("update het ontwerp om een wachtrij te gebruiken"), en ga dan verder. De AI werkt altijd met de huidige bestandsinhoud. Volledige handleiding: Wijzigen & Itereren op een verandering.

Kan ik teruggaan en het plan wijzigen nadat ik een deel ervan heb geïmplementeerd?

Ja, op elk moment. De workflow is vloeiend, dus beoordeling en bewerking zijn geen fasen waaruit je kunt worden buitengesloten. Bewerk het document en ga dan verder. Als je een gestructureerde controle wilt dat de code nog overeenkomt met het plan, voer dan /opsx:verify uit. Zie Wijzigen & Itereren op een verandering.

Ik heb de code met de hand bewerkt. Hoe verzoen ik dat met de specificatie?

Breng ze weer in sync voordat je archiveert, aangezien archivering jouw specificaties de waarheidsbron maakt. Als de code nu correct is, pas dan de deltaspecificatie aan om overeen te komen met wat je hebt opgeleverd; als de specificatie correct is, blijf dan bouwen tot de code ermee overeenkomt. /opsx:verify legt de mismatches bloot. Zie Wijzigen & Itereren op een verandering.

Wanneer moet ik een bestaande wijziging bijwerken versus een nieuwe starten?

Werk bij wanneer het hetzelfde werk is, verder verfijnd. Begin opnieuw wanneer de intentie fundamenteel is veranderd of de scope is geëxplodeerd tot ander werk. Er is een beslisstroomdiagram en voorbeelden in Workflows.

Wat als mijn sessie zonder context komt te zitten, of vereisten halverwege de implementatie veranderen?

Dit is waar specificaties hun waarde bewijzen. Omdat het plan in bestanden leeft (niet alleen in de chatgeschiedenis), kun je je context wissen, een frisse AI-sessie starten en verdergaan met /opsx:apply; het leest de documenten en hervat vanaf de eerste niet-aangevinkte taak. Als vereisten veranderen, bewerk dan de documenten om de nieuwe realiteit weer te geven en ga verder. Een schoon contextvenster levert ook betere resultaten op; maak het leeg vóór implementatie.

Moet ik de openspec/-map committen naar git?

Ja. Jouw specificaties, actieve wijzigingen en archief maken deel uit van de geschiedenis van je project. Commit ze zoals elke andere bron. Het archief wordt vooral een duurzaam verslag van waarom jouw systeem werkt zoals het werkt.

Specificaties en wijzigingen

Wat hoort in een specificatie versus een ontwerp?

Een specificatie beschrijft waarneembaar gedrag: wat het systeem doet, de inputs, outputs en foutcondities. Een ontwerp beschrijft hoe je het gaat bouwen: de technische aanpak, architectuurbeslissingen, bestandswijzigingen. Als de implementatie zou kunnen veranderen zonder het extern zichtbare gedrag te wijzigen, hoort het in het ontwerp, niet in de spec. Concepten gaat hier dieper op in.

Wat is een deltaspecificatie?

Een specificatie die alleen beschrijft wat er verandert, met TOEGEVOEGD, GEWIJZIGD en VERWIJDERD secties, in plaats van de hele spec te herhalen. Zo handelt OpenSpec bewerkingen van bestaande systemen netjes af. Zie Concepten.

Waar gaan gearchiveerde wijzigingen naartoe?

Naar openspec/changes/archive/JJJJ-MM-DD-<naam>/, waarbij alle wijzigingsdocumenten behouden blijven. De wijziging verdwijnt uit je actieve lijst. Een wijziging die expliciet retire_capabilities: true verklaart, kan ook een hoofd-capabiliteitsspecificatie verwijderen wanneer het de laatste vereiste van die capabiliteit verwijdert.

Configuratie en aanpassing

Hoe vertel ik de AI over mijn tech-stack?

Zet het in openspec/config.yaml onder context:. Die tekst wordt in elk planningsverzoek geïnjecteerd, zodat de AI altijd jouw stack en conventies kent. Zie Aanpassing.

Kan ik specificaties genereren in een andere taal dan Nederlands (of Engels)?

Ja. Voeg een taalinstructie toe aan de context: van je configuratie. Meertalig bevat knip-en-plak-snippets voor verschillende talen.

Kan ik de workflow zelf veranderen?

Ja, met aangepaste schema's. Een schema definieert welke documenten er bestaan en hoe ze van elkaar afhangen. Fork de standaard met openspec schema fork spec-driven mijn-workflow en bewerk het vervolgens. Zie Aanpassing.

Modellen, privacy en upgrades

Welk AI-model moet ik gebruiken?

OpenSpec werkt het beste met modellen die sterk zijn in redeneren. De README beveelt modellen aan zoals Codex 5.5 en Opus 4.7 voor zowel planning als implementatie. Houd ook je contextvenster schoon: maak het leeg vóór implementatie voor de beste resultaten.

Verzamelt OpenSpec gegevens?

Het verzamelt anonieme gebruiksstatistieken: alleen opdrachtnamen en versie. Geen argumenten, paden, inhoud of persoonlijke gegevens, en het staat automatisch uit in CI. Opt-out met export OPENSPEC_TELEMETRY=0 of export DO_NOT_TRACK=1.

Hoe upgrade ik?

In twee stappen. Upgrade het pakket (npm install -g @fission-ai/openspec@latest) en voer vervolgens openspec update uit in elk project om de gegenereerde vaardigheden en opdrachten te vernieuwen.

Hoe verwijder ik OpenSpec?

Er is geen verwijderopdracht, want het is slechts een globaal pakket plus bestanden in je project. Verwijder het pakket (npm uninstall -g @fission-ai/openspec) en verwijder optioneel de openspec/-directory en de gegenereerde toolbestanden. Stap voor stap, inclusief wat veilig bewaard kan blijven, staat in Installatie: Verwijderen.

Hulp krijgen

Waar kan ik vragen stellen of bugs melden?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Vanuit je terminal: openspec feedback "jouw bericht" opent een GitHub-issue voor je.

Deze documentatie is fout of verwarrend. Wat moet ik doen?

Vertel het ons, of herstel het. Documentatie-PR's zijn welkom en worden gewaardeerd. Open een issue of stuur een pull request.