Przykłady i przepisy

Prawdziwe zmiany, od początku do końca. Każdy przepis pokazuje, jakie polecenia wpisujesz i co widzisz w odpowiedzi, abyś mógł dopasować swoją sytuację do wzorca i go skopiować. Używają one domyślnych, podstawowych poleceń (propose, explore, apply, update, sync, archive); w przypadkach, gdy rozszerzony zestaw pomaga, jest to zaznaczone.

Przypomnienie przed rozpoczęciem: polecenia z ukośnikiem, takie jak /opsx:propose, wpisujesz na czacie swojego asystenta AI, a polecenia openspec – w terminalu. Jeśli to dla Ciebie nowość, najpierw przeczytaj Jak działają polecenia. W poniższych zapisach Ty: i AI: oznaczają czat, a linie zaczynające się od $ to terminal.

Nie jesteś pewien, co chcesz zbudować? Większość tych przepisów jest skuteczniejsza, jeśli najpierw zaczniesz od /opsx:explore, aby to przemyśleć. Przepis 3 pokazuje to w działaniu, a przewodnik Najpierw eksploruj opisuje pełne uzasadnienie.

Przepis 1: Mała funkcja, szybka ścieżka

Kiedy użyć: wiesz, czego chcesz, i jest to zamknięty fragment pracy. To najczęstszy przepis.

Całość to trzy polecenia. Zaproponuj, zbuduj, zarchiwizuj.

Ty: /opsx:propose add-logout-button

AI:  Utworzono openspec/changes/add-logout-button/
     ✓ proposal.md — dlaczego i co
     ✓ specs/      — nowe wymaganie i jego scenariusze
     ✓ design.md   — podejście techniczne
     ✓ tasks.md    — lista kontrolna implementacji
     Gotowy do implementacji. Uruchom /opsx:apply.

Teraz przeczytaj plan. Otwórz propozycję i specyfikację delta. To jest moment, dla którego stworzono OpenSpec: wyłapanie błędnego założenia, gdy to jeszcze jeden akapit, a nie 400 linii kodu. Jeśli coś jest nie tak, edytuj bezpośrednio dowolny artefakt i kontynuuj.

Ty: /opsx:apply

AI:  Praca nad zadaniami...
     ✓ 1.1 Dodanie przycisku wylogowania do nagłówka
     ✓ 1.2 Wyczyszczenie sesji po kliknięciu
     ✓ 1.3 Dodanie okna dialogowego potwierdzenia
     Wszystkie zadania ukończone!

Ty: /opsx:archive

AI:  Archiwizacja add-logout-button...
     ✓ Scalono specyfikacje do openspec/specs/auth/spec.md
     ✓ Przeniesiono do openspec/changes/archive/2026-06-22-add-logout-button/
     Gotowe. Gotowy na następną zmianę.

To wszystko. Zachowanie wylogowania jest teraz częścią Twoich specyfikacji, a zmiana jest zarchiwizowana z pełnym kontekstem.

Przepis 2: Poprawka błędu

Kiedy użyć: coś jest zepsute i chcesz, aby poprawka została zarejestrowana jako celowa zmiana zachowania, a nie tajemniczy commit.

Poprawki błędów działają dokładnie tak samo jak funkcje. Różnica polega na sposobie sformułowania propozycji: opisz poprawne zachowanie, a nie tylko „napraw błąd”.

Ty: /opsx:propose fix-login-redirect-loop

AI:  Utworzono openspec/changes/fix-login-redirect-loop/
     Propozycja opisuje obecne nieprawidłowe zachowanie i zamierzone
     zachowanie. Specyfikacja delta MODYFIKUJE wymaganie dotyczące
     przekierowania, dzięki czemu jest teraz precyzyjne i testowalne.
     Gotowy do implementacji.

Ponieważ poprawka trafia jako wymaganie MODIFIED z nowym scenariuszem, następna osoba (lub kolejna sesja AI) widzi nie tylko, że to naprawiłeś, ale też co oznacza „poprawnie”. Następnie /opsx:apply i /opsx:archive jak zwykle.

Wskazówka: w przypadku poprawki, dobrym scenariuszem jest test regresyjny w formie prozy. „GIVEN wylogowany użytkownik, WHEN przesyła poprawne poświadczenia, THEN ląduje na pulpicie i nie jest ponownie przekierowywany.” Napisz to, a implementacja zyska jasny cel.

Przepis 3: Eksploracja przed podjęciem decyzji

Kiedy użyć: masz problem, ale jeszcze nie masz planu. Nie jesteś pewien, co zbudować lub które podejście jest właściwe.

Zacznij od /opsx:explore. To partner do myślenia bez narzuconej struktury i tworzenia artefaktów. Czyta Twój kod i pomaga Ci podjąć decyzję.

Ty: /opsx:explore

AI:  Co chciałbyś zbadać?

Ty: Ładowanie stron wydaje się powolne, ale nie wiem, gdzie traci się czas.

AI:  Sprawdźmy... Znalazłem trzy prawdopodobne przyczyny:
     1. Duże, niezoptymalizowane obrazy na liście produktów
     2. Synchroniczne pobieranie danych blokujące renderowanie
     3. Ponowne renderowanie wywołane zmianami kontekstu
     Którym powinniśmy się zająć najpierw?

Ty: Tym z pobieraniem danych.

Ty: /opsx:propose optimize-product-list-fetching

AI:  Utworzono zmianę z propozycją opartą na tym, co właśnie
     odkryliśmy. Gotowy do implementacji.

Eksploracja wyjaśnia Twoje myślenie zanim przeznaczysz na to zmianę. Kiedy wgląd skrystalizuje się, zaproponuj, a AI przeniesie kontekst dalej.

Przepis 4: Żonglowanie dwiema zmianami jednocześnie

Kiedy użyć: jesteś w trakcie funkcji i pilna poprawka wskakuje przed kolejkę.

Zmiany to niezależne foldery, więc równoległa praca nie koliduje. Rozpocznij poprawkę, dostarcz ją, a następnie wróć do funkcji dokładnie tam, gdzie przerwałeś.

Ty: Jestem w trakcie add-dark-mode, ale teraz muszę naprawić błąd logowania.

Ty: /opsx:propose fix-login-redirect

AI:  Utworzono openspec/changes/fix-login-redirect/. Gotowy do implementacji.

Ty: /opsx:apply

AI:  Zaimplementowano poprawkę. Wszystkie zadania ukończone.

Ty: /opsx:archive

AI:  ✓ Zarchiwizowano fix-login-redirect.

Ty: Wracam do ciemnego motywu.

Ty: /opsx:apply add-dark-mode

AI:  Wznawianie add-dark-mode. Kontynuacja od zadania 2.3: Aktualizacja nagłówka...

Podanie nazwy zmiany w /opsx:apply add-dark-mode wskazuje AI konkretną zmianę, gdy aktywnych jest więcej niż jedna. Ponieważ zadania śledzą ukończenie w tasks.md, AI dokładnie wie, gdzie przerwałeś.

Gdy kilka zmian jest gotowych jednocześnie, rozszerzone /opsx:bulk-archive archiwizuje je razem i rozwiązuje konflikty specyfikacji, sprawdzając, co faktycznie zostało zaimplementowane. Zobacz Przepływy pracy.

Przepis 5: Refaktoryzacja bez zmiany zachowania

Kiedy użyć: restrukturyzujesz kod, a zewnętrznie widoczne zachowanie powinno pozostać identyczne.

To interesujący przypadek, ponieważ czysta refaktoryzacja nie ma nic do dodania do specyfikacji. Kontrakt zachowania nie ulega zmianie; zmienia się tylko implementacja. Dlatego praca dotyczy projektu i zadań, a specyfikacja delta jest pusta lub nieobecna.

Ty: /opsx:propose refactor-payment-module

AI:  Utworzono zmianę. Propozycja określa cel (podział modułu
     płatności, bez zmiany zachowania), a projekt opisuje nową
     strukturę. Brak zmian w specyfikacjach, ponieważ zachowanie
     jest identyczne. Gotowy do implementacji.

Zadeklaruj jawnie pustą deltę, ustawiając skip_specs: true w pliku .openspec.yaml zmiany:

schema: spec-driven
skip_specs: true

Bez tego oznacznika, openspec validate odrzuca zmianę z zerowymi deltami (więc pominięta faza specyfikacji nadal zostaje wyłapana); z nim walidacja przechodzi, a openspec status pokazuje etap specyfikacji jako jawnie pominięty, a nie oczekujący. Jeśli refaktoryzacja ostatecznie zmienia zachowanie, usuń skip_specs z .openspec.yaml i napisz specyfikacje delta — walidacja traktuje znacznik w połączeniu z plikami specyfikacji jako konflikt, więc nieaktualny znacznik nie może pozostać niezauważony.

Archiwizacja oznaczonej zmiany nie wymaga dodatkowych flag (nie ma delt do scalenia). Niezależnie, flaga --skip-specs nakazuje poleceniu terminala jawne pominięcie kroku specyfikacji:

$ openspec archive refactor-payment-module --skip-specs

Ta sama flaga jest przydatna dla narzędzi, CI i zmian dotyczących tylko dokumentacji. Zasada: specyfikacje opisują zachowanie, więc jeśli zachowanie się nie zmieniło, specyfikacja również nie powinna. Zobacz Koncepcje.

Przepis 6: Kontrola krok po kroku (polecenia rozszerzone)

Kiedy użyć: złożona lub ryzykowna zmiana, gdy chcesz przejrzeć każdy artefakt przed kontynuowaniem.

Podstawowe /opsx:propose tworzy szkic wszystkiego od razu. Gdy wolisz przechodzić krok po kroku, włącz rozszerzone polecenia:

$ openspec config profile      # wybierz rozszerzone przepływy pracy
$ openspec update              # zastosuj je w tym projekcie

Teraz możesz tworzyć szkielet i budować stopniowo:

Ty: /opsx:new add-2fa

AI:  Utworzono openspec/changes/add-2fa/. Gotowy do utworzenia: propozycja.

Ty: /opsx:continue

AI:  Utworzono proposal.md. Teraz dostępne: specyfikacje, projekt.

Ty: /opsx:continue

AI:  Utworzono specs/auth/spec.md. Teraz dostępne: projekt.

Przejrzyj każdy artefakt w miarę jego powstawania, edytuj dowolnie i kontynuuj, gdy jesteś zadowolony. Gdy chcesz, aby reszta została utworzona za jednym razem, /opsx:ff przewija do przodu przez pozostałe artefakty planowania. Przed archiwizacją, /opsx:verify sprawdza, czy implementacja faktycznie odpowiada specyfikacjom. Zobacz Przepływy pracy.

Przepis 7: Nauka całej pętli w praktyce

Kiedy użyć: zainstalowałeś OpenSpec i chcesz poczuć przepływ pracy na własnym kodzie, a nie na zabawkowym przykładzie.

Włącz rozszerzone polecenia (zobacz Przepis 6), a następnie:

Ty: /opsx:onboard

AI:  Witamy w OpenSpec! Przeprowadzę Cię przez kompletną zmianę
     na Twoim rzeczywistym kodzie. Pozwól, że przeskanuję w poszukiwaniu
     małego, bezpiecznego ulepszenia, które możemy zrobić razem...

/opsx:onboard znajduje prawdziwe (małe) ulepszenie, tworzy dla niego zmianę, implementuje ją i archiwizuje, opisując każdy krok. Zajmuje to od 15 do 30 minut i pozostawia Cię z prawdziwą zmianą, którą możesz zachować lub odrzucić. To najłagodniejszy sposób nauki. Zobacz Polecenia.

Sprawdzanie swojej pracy z terminala

W dowolnym momencie, z poziomu terminala, możesz sprawdzić stan rzeczy:

$ openspec list                      # aktywne zmiany
$ openspec show add-dark-mode        # szczegóły jednej zmiany
$ openspec validate add-dark-mode    # sprawdzenie struktury
$ openspec view                      # interaktywny pulpit

To narzędzia do odczytu i inspekcji. Proponowanie i budowanie nadal odbywa się za pomocą poleceń z ukośnikiem na czacie. Pełne szczegóły w referencji CLI.

Dokąd dalej

• Najpierw eksploruj: zalecany sposób rozpoczęcia, gdy nie jesteś pewien
• Przepływy pracy: powyższe wzorce, z wskazówkami decyzyjnymi, kiedy użyć każdego z nich
• Polecenia: każde polecenie z ukośnikiem w szczegółach
• Pierwsze kroki: kanoniczny przewodnik po pierwszej zmianie
• Koncepcje: dlaczego elementy do siebie pasują w ten sposób