OpenSpec

Eksploruj najpierw ​

/opsx:explore to twój partner do myślenia. Sięgaj po niego, gdy masz problem, ale jeszcze nie masz planu. Bada twoją bazę kodu, rozważa razem z tobą opcje i wyjaśnia, czego właściwie potrzebujesz – wszystko to, zanim powstanie jakikolwiek artefakt lub linia kodu. Kiedy obraz jest jasny, przekazuje sterowanie do /opsx:propose.

Jeśli masz wynieść z tej dokumentacji jeden nawyk, to właśnie ten: gdy nie jesteś pewien, najpierw eksploruj, zanim zaproponujesz.

Oto dlaczego to ważne. Asystenci kodowania AI są zbyt chętni. Gdy zadasz nieprecyzyjne pytanie, z pewnością zbudują coś, co być może nie jest tym, czego potrzebowałeś. Eksploracja to lekarstwo. To rozmowa bez ryzyka, w której Ty i AI wspólnie ustalacie właściwy kierunek, dzięki czemu, gdy już zaproponujesz, proponujesz to, co właściwe.

Kiedy eksplorować ​

Eksploracja jest właściwym pierwszym krokiem częściej, niż się ludziom wydaje. Użyj jej, gdy którekolwiek z poniższych jest prawdą:

  • Znasz problem, ale nie znasz rozwiązania („Strony są wolne”, „Autoryzacja to bałagan”, „Ciągle dostajemy duplikaty zamówień”).
  • Wybierasz pomiędzy różnymi podejściami i chcesz poznać kompromisy na podstawie rzeczywistego kodu.
  • Jesteś nowy w bazie kodu i potrzebujesz zrozumieć, jak coś działa, zanim to zmienisz.
  • Wymagania są niejasne i chcesz je doprecyzować, zanim się zaangażujesz.
  • Podejrzewasz, że praca jest większa lub mniejsza, niż się wydaje, i chcesz ją uczciwie oszacować.

Pomiń eksplorację tylko wtedy, gdy dokładnie wiesz, czego chcesz i jak to zrobić. W takim przypadku od razu przejdź do /opsx:propose.

Co robi (a czego nie) ​

Eksploracja to rozmowa, nie generator.

Robione jest:

  • Czyta i przeszukuje bazę kodu, aby odpowiedzieć na prawdziwe pytania.
  • Porównuje opcje i nazywa kompromisy każdej z nich.
  • Rysuje diagramy, aby projekt stał się czytelny.
  • Pomaga zamienić niejasny pomysł w konkretny, możliwy do zbudowania zakres.
  • Przechodzi do /opsx:propose, gdy jesteś gotów.

Nie jest robione:

  • Tworzenie folderu zmiany.
  • Zapisanie jakichkolwiek artefaktów (bez propozycji, specyfikacji, projektu ani zadań).
  • Pisanie lub modyfikowanie kodu.

W tym właśnie rzecz. Eksplorowanie nic cię nie kosztuje i do niczego nie zobowiązuje. Możesz zbadać trzy ślepe zaułki, z każdego czegoś się nauczyć i dopiero wtedy zaproponować ścieżkę, która przetrwała.

Jest już zainstalowane ​

Dobra wiadomość: /opsx:explore jest dołączony do domyślnego profilu core, razem z propose, apply, update, sync i archive. Nie musisz niczego włączać. Jeśli OpenSpec jest skonfigurowany w Twoim projekcie, eksploracja jest gotowa w czacie AI. (Tak jak w przypadku wszystkich komend /opsx:*, wpisujesz ją w czacie asystenta, nie w terminalu. Zobacz Jak działają komendy.)

Pełny przykład ​

Zobacz, jak niejasne zmartwienie zamienia się w precyzyjną, możliwą do zbudowania zmianę.

text
Ty: /opsx:explore

AI:  Co chciałbyś zbadać?

Ty: Nasz proces finalizacji zamówienia czasami tworzy duplikaty zamówień. Nie wiem dlaczego i nie wiem, jak to bezpiecznie naprawić.

AI:  Pozwól, że zagłębię się w ścieżkę realizacji...
     [czyta serwis zamówień, handler webhooka płatności i logikę wysyłania po stronie klienta]

     Oto co znalazłem. Istnieją dwa sposoby, w jakie duplikat może powstać:

     1. Klient może wysłać dwukrotnie (podwójne kliknięcie, ponowna próba przy wolnym połączeniu). Nic tego nie eliminuje.
     2. Webhook płatności może wywołać się więcej niż raz, a handler tworzy zamówienie za każdym razem. Brak klucza idempotentności.

     Przyczyna nr 2 jest niebezpieczna: może obciążyć i zrealizować zamówienie dwukrotnie.

     Trzy sposoby naprawienia tego, z grubsza w kolejności solidności:
     - Klucz idempotentności na punkcie końcowym tworzenia zamówienia (obsługuje obie przyczyny)
     - Deduplikacja webhooka według identyfikatora payment-intent (obsługuje tylko przyczynę 2)
     - Eliminacja drgań po stronie klienta (obsługuje tylko przyczynę 1, maskuje prawdziwy błąd)

     Biorąc pod uwagę, że Twój kod już przechowuje identyfikator payment-intent, podejście z kluczem idempotentności to niewielka zmiana o największych korzyściach. Chcesz, żebym to oszacował?

Ty: Tak, zróbmy z kluczem idempotentności.

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

AI:  Utworzono openspec/changes/add-order-idempotency-key/, z propozycją i specyfikacją delta opartą na tym, co właśnie znaleźliśmy. Gotowe do implementacji.

Zauważ, co się stało. Punktem wyjścia było „coś jest nie tak i boję się tego dotknąć”. Dwadzieścia sekund eksploracji zmieniło to w nazwaną przyczynę źródłową, trzy uszeregowane opcje, rekomendację opartą na istniejącym kodzie i precyzyjną zmianę. Propozycja, która po tym następuje, jest ostra, ponieważ myślenie odbyło się wcześniej.

Przekazywanie do propose ​

Eksploracja nie zapisuje niczego. Kiedy jesteś gotów, po prostu rozpoczynasz zmianę, a AI przenosi kontekst z Twojej rozmowy do artefaktów.

explore  ──►  propose  ──►  apply  ──►  archive
 (myślenie)   (uzgadnianie)  (budowanie)  (zapisywanie)

Możesz powiedzieć to zwykłym językiem („zamieńmy to w zmianę”) lub bezpośrednio uruchomić /opsx:propose <nazwa>. Tak czy inaczej, właśnie wykonana eksploracja staje się podstawą propozycji, a nie bezużyteczną rozmową.

Jeśli używasz rozszerzonego zestawu komend, eksploracja może przekazać sterowanie do /opsx:new, aby tworzyć artefakty krok po kroku. Zobacz Workflows.

Wskazówki dotyczące dobrej eksploracji ​

  • Przynieś problem, a nie rozwiązanie. „Logowanie jest wolne” daje AI pole do zbadania. „Dodaj cache Redis” zobowiązuje cię z góry do odpowiedzi, której jeszcze nie przetestowałeś.
  • Pytaj na głos o kompromisy. „Jakie są wady każdej z opcji?” przynosi bardziej uczciwe porównanie.
  • Pozwól mu najpierw przeczytać. Najlepsze eksploracje zaczynają się od tego, że AI faktycznie patrzy na Twój kod, a nie zgaduje. Wskaż odpowiedni obszar, jeśli to pomoże.
  • W porządku jest się wycofać. Jeśli eksploracja ujawni, że pomysł nie jest tego wart, to zwycięstwo. Nauczyłeś się tego tanio.
  • Eksploruj ponownie w trakcie zmian. Utknąłeś podczas /opsx:apply? Możesz się cofnąć i zbadać podproblem, a potem wrócić.

Szczerze o kompromisach ​

Co zyskujesz: eksploracja wyłapuje błędne ścieżki w najtańszym możliwym momencie, zanim powstanie jakikolwiek artefakt. Jest szczególnie potężna w nieznanym kodzie, gdzie zdolność AI do czytania i podsumowywania systemu oszczędza ci popołudnia przekopywania się.

Co kosztuje: trochę cierpliwości. Eksploracja to rozmowa, więc jest wolniejsza niż wystrzelenie /opsx:propose i nadzieja, że trafi. W przypadku prac, które naprawdę rozumiesz, ten dodatkowy krok to czysty narzut i powinieneś go pominąć.

Zasada kciuka: im bardziej mgliste zadanie, tym bardziej opłaca się eksploracja. Im bardziej klarowne, tym bardziej możesz pominąć i przejść od razu do proponowania.

Co dalej ​