OpenSpec

Eerst Verkennen ​

/opsx:explore is je denkpartner. Gebruik het wanneer je een probleem hebt maar nog geen plan. Het onderzoekt je codebase, weegt samen met jou opties af en verduidelijkt wat je eigenlijk wilt, allemaal voordat er een enkel artefact of regel code is aangemaakt. Wanneer het beeld helder is, draagt het over aan /opsx:propose.

Als je één gewoonte uit deze documentatie overneemt, dan deze: wanneer je het niet zeker weet, verken eerst voordat je voorstelt.

En hier is waarom dat telt. AI-codeerassistenten zijn enthousiast. Stel een vage vraag en ze bouwen met veel vertrouwen iets, alleen misschien niet wat je nodig had. Verkennen is de remedie. Het is een gesprek zonder verplichtingen waarin jij en de AI samen de juiste aanpak bepalen, zodat tegen de tijd dat je een voorstel doet, je het juiste voorstelt.

Wanneer verkennen ​

Verkennen is vaker de juiste eerste stap dan mensen verwachten. Gebruik het wanneer één van de volgende zaken waar is:

  • Je kent het probleem, maar niet de oplossing. ("Pagina's voelen traag." "De authenticatie is een puinhoop." "We krijgen steeds dubbele bestellingen.")
  • Je kiest tussen aanpakken en wilt de afwegingen afgezet tegen je eigen code.
  • Je bent nieuw in een codebase en moet begrijpen hoe iets werkt voordat je het verandert.
  • De vereisten zijn vaag en je wilt ze aanscherpen voordat je je vastlegt.
  • Je vermoedt dat het werk groter of kleiner is dan het lijkt en wilt de omvang eerlijk inschatten.

Sla verkennen alleen over als je al precies weet wat je wilt en hoe. Ga in dat geval direct naar /opsx:propose.

Wat het doet (en niet doet) ​

Verkennen is een gesprek, geen generator.

Het doet:

  • Je codebase lezen en doorzoeken om echte vragen te beantwoorden.
  • Opties vergelijken en de afwegingen van elk benoemen.
  • Diagrammen tekenen om een ontwerp inzichtelijk te maken.
  • Je helpen een vaag idee in te perken tot een concrete, bouwbare scope.
  • Overgaan naar /opsx:propose wanneer je klaar bent.

Het doet niet:

  • Een wijzigingsmap aanmaken.
  • Artefacten schrijven (geen voorstel, specificaties, ontwerp of taken).
  • Code schrijven of wijzigen.

Dat is het punt. Verkennen kost je niets en verplicht je tot niets. Je kunt drie doodlopende wegen verkennen, van elk iets leren, en pas dan het pad voorstellen dat overbleef.

Het is al geïnstalleerd ​

Goed nieuws: /opsx:explore is standaard inbegrepen in het core-profiel, samen met propose, apply, update, sync en archive. Je hoeft niets in te schakelen. Als OpenSpec in je project is ingesteld, is verkennen klaar in je AI-chat. (Zoals bij alle /opsx:*-opdrachten typ je het in de chat van je assistent, niet in de terminal. Zie Hoe opdrachten werken.)

Een volledig voorbeeld ​

Let op hoe een vage zorg een scherpe, bouwbare wijziging wordt.

text
Jij: /opsx:explore

AI:  Wat wil je verkennen?

Jij: Onze checkout maakt soms dubbele bestellingen aan. Ik weet niet waarom
     en ik weet niet hoe ik het veilig kan oplossen.

AI:  Laat me in het afrekenpad duiken...
     [leest de bestelservice, de handler voor de betalingswebhook en
      de verzendlogica van de client]

     Dit is wat ik vond: er zijn twee manieren waarop een duplicaat kan
     ontstaan:

     1. De client kan twee keer verzenden (dubbelklik, opnieuw proberen bij
        een trage netwerkverbinding). Er is geen debounce.
     2. De betalingswebhook kan meer dan één keer vuren, en de handler maakt
        elke keer een bestelling aan. Er is geen idempotentiesleutel.

     Oorzaak #2 is de gevaarlijke: die kan twee keer in rekening brengen en
     twee keer uitvoeren.

     Drie manieren om het op te lossen, ruwweg in volgorde van robuustheid:
     - Idempotentiesleutel op het bestellingsaanmaak‑endpoint (pakt beide
       oorzaken aan)
     - Dedup op de webhook op basis van payment-intent-id (pakt alleen #2
       aan)
     - Client-side debounce (pakt alleen #1 aan, maskeert de echte bug)

     Aangezien je code al de payment-intent-id opslaat, is de
     idempotentiesleutel‑aanpak een kleine wijziging met de grootste
     opbrengst. Wil je dat ik dat uitwerk?

Jij: Ja, laten we de idempotentiesleutel doen.

Jij: /opsx:propose add-order-idempotency-key

AI:  openspec/changes/add-order-idempotency-key/ aangemaakt, met een voorstel
     en delta-spec gebaseerd op wat we net hebben gevonden. Klaar voor
     implementatie.

Merk op wat er gebeurde. Het startpunt was “er is iets mis en ik durf er niet aan te komen.” Twintig seconden verkennen veranderde dat in een benoemde hoofdoorzaak, drie gerangschikte opties, een aanbeveling gekoppeld aan de bestaande code, en een precieze wijziging. Het voorstel dat volgt is scherp omdat het denken eerst plaatsvond.

Overdragen aan propose ​

Verkennen archiveert niets. Wanneer je klaar bent, start je gewoon een wijziging en de AI neemt de context van je gesprek mee in de artefacten.

explore  ──►  propose  ──►  apply  ──►  archive
 (denk)     (overeenstem)     (bouw)     (leg vast)

Je kunt het in gewone taal zeggen (“laten we dit omzetten in een wijziging”) of direct /opsx:propose <naam> uitvoeren. Hoe dan ook, de verkenning die je net hebt gedaan wordt de basis van het voorstel, geen wegwerpchat.

Als je de uitgebreide opdrachtenset gebruikt, kan verkennen overdragen aan /opsx:new in plaats daarvan, voor stapsgewijze artefactcreatie. Zie Workflows.

Tips voor een goede verkenning ​

  • Breng het probleem, niet de oplossing. “Inloggen voelt traag” geeft de AI ruimte om te onderzoeken. “Voeg een Redis‑cache toe” legt je van tevoren vast aan een antwoord dat je nog niet hebt getest.
  • Vraag hardop naar de afwegingen. “Wat zijn de nadelen van elke optie?” levert een eerlijkere vergelijking op.
  • Laat het eerst lezen. De beste verkenningen beginnen met de AI die daadwerkelijk naar je code kijkt, niet met gissen. Wijs het naar het relevante gebied als dat helpt.
  • Het is oké om af te haken. Als de verkenning uitwijst dat het idee de moeite niet waard is, is dat winst. Je hebt het goedkoop geleerd.
  • Verken opnieuw halverwege de wijziging. Vastgelopen tijdens /opsx:apply? Je kunt een stap terug doen en een deelprobleem verkennen, om daarna terug te keren.

De eerlijke afwegingen ​

Wat je wint: verkennen vangt verkeerde afslagen op het goedkoopst mogelijke moment, voordat er een artefact bestaat. Het is vooral krachtig in onbekende code, waar het vermogen van de AI om het systeem te lezen en samen te vatten je een middag speurwerk bespaart.

Wat het kost: een beetje geduld. Verkennen is een gesprek, dus het is langzamer dan /opsx:propose afvuren en hopen. Voor werk dat je al echt begrijpt, is die extra stap pure overhead en moet je hem overslaan.

De vuistregel: hoe vager de taak, hoe meer verkennen oplevert. Hoe duidelijker de taak, hoe meer je direct kunt overslaan naar voorstellen.

Waarheen nu? ​