OpenSpec

Przepływy pracy ​

Ten przewodnik obejmuje powszechne wzorce przepływów pracy dla OpenSpec oraz sytuacje, w których należy stosować każdy z nich. Aby poznać podstawową konfigurację, zobacz Szybki start. Aby sprawdzić referencję poleceń, zobacz Polecenia.

Filozofia: Akcje, nie fazy ​

Tradycyjne przepływy pracy zmuszają Cię do przejścia przez kolejne fazy: planowanie, następnie implementacja, a potem zakończenie. Jednak prawdziwa praca nie mieści się w sztywnych ramach.

OPSX podejmuje inne podejście:

text
Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

Kluczowe zasady:

  • Akcje, nie fazy – polecenia to czynności, które możesz wykonać, a nie etapy, w których jesteś uwięziony
  • Zależności to ułatwienia – pokazują, co jest możliwe, a nie co jest wymagane jako następny krok

Dostosowywanie: Przepływy pracy OPSX są sterowane schematami, które definiują sekwencje artefaktów. Zobacz Dostosowywanie, aby uzyskać szczegółowe informacje na temat tworzenia niestandardowych schematów.

Workflow w skrócie ​

Domyślny workflow pozostaje płynny: eksploracja i weryfikacja są opcjonalne, a artefakty planowania można aktualizować zawsze, gdy implementacja ujawni coś nowego.

mermaid
flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

Asystent AI prowadzi workflow, podczas gdy CLI zapewnia deterministyczne szkielety, status i instrukcje dotyczące artefaktów:

mermaid
sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

Dwa tryby ​

Domyślna szybka ścieżka (profil core) ​

Nowe instalacje domyślnie korzystają z profilu core, który zapewnia:

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:update
  • /opsx:sync
  • /opsx:archive

Typowy przepływ:

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

Zacznij od eksploracji (zwyczaj, który warto wyrobić) ​

/opsx:explore jest częścią domyślnego profilu, a nie zaawansowanym dodatkiem. To ruch, którego należy dokonać zawsze, gdy masz problem, ale jeszcze nie masz planu — co przy asystencie AI zdarza się najczęściej.

text
You: /opsx:explore

AI:  What would you like to explore?

You: Our search results feel stale. I'm not sure if it's caching,
     indexing, or the query itself.

AI:  Let me look... [reads the search service and cache layer]
     It's the index: it only rebuilds nightly, so edits don't show
     up until the next day. Two options: rebuild on write (simple,
     more load) or a short-TTL cache invalidation (more moving parts,
     less load). Given your write volume is low, rebuild-on-write is
     the cleaner fix. Want to scope it?

You: Yes.

You: /opsx:propose rebuild-search-index-on-write

Eksploracja nie tworzy żadnych artefaktów i nie zapisuje kodu. To swobodna rozmowa bez stawki, która zamienia mgliste obawy w precyzyjną zmianę, dzięki czemu następująca propozycja jest ostra. Już wiesz dokładnie, czego chcesz? Pomiń i przejdź od razu do /opsx:propose. Pełny przewodnik: Explore First.

Rozszerzony/pełny workflow (wybór niestandardowy) ​

Jeśli chcesz jawnie używać poleceń szkieletowych i budowania (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), włącz je za pomocą:

bash
openspec config profile
openspec update

Wzorce workflow (tryb rozszerzony) ​

Szybka funkcja ​

Gdy wiesz, co chcesz zbudować, i potrzebujesz tylko wykonać:

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

Przykładowa rozmowa:

text
You: /opsx:new add-logout-button

AI:  Created openspec/changes/add-logout-button/
     Ready to create: proposal

You: /opsx:ff

AI:  Creating all planning artifacts...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

You: /opsx:apply

AI:  Working through tasks...
     ✓ Added logout button to header
     ✓ Implemented session clearing
     ✓ Added confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  ✓ Merged specs
     ✓ Archived change

Najlepsze do: Małych i średnich funkcji, poprawek błędów, prostych zmian.

Eksploracyjny ​

Gdy wymagania są niejasne lub najpierw musisz przeprowadzić dochodzenie:

text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Przykładowa rozmowa:

text
You: /opsx:explore

AI:  What would you like to explore?

You: I want to improve page load performance but I'm not sure
     where the bottlenecks are.

AI:  Let me help investigate...
     [Analyzes bundle sizes, identifies slow queries, reviews
     component render patterns]

     I found three main bottlenecks:
     1. Large unoptimized images
     2. Synchronous data fetching in ProductList
     3. Re-renders from context changes

     Which would you like to address first?

You: Let's tackle the data fetching issue.

You: /opsx:new optimize-product-list-fetching

AI:  Created change. Ready to create: proposal

You: /opsx:continue

AI:  Creating proposal based on our exploration...
     [Writes proposal incorporating investigation insights]

     Ready to create: specs, design
     Which would you like next?

You: /opsx:continue

AI:  Creating specs...

Najlepsze do: Optymalizacji wydajności, debugowania, decyzji architektonicznych, niejasnych wymagań.

Równoległe zmiany ​

Pracuj nad wieloma zmianami jednocześnie:

text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Przykładowa rozmowa:

text
You: I'm working on add-dark-mode but got pulled into a bug fix

You: /opsx:new fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ Created planning artifacts

You: /opsx:apply

AI:  Working on fix-login-redirect...
     [Implements the fix]
     All tasks complete!

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect

You: Let's get back to dark mode

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode...
     Picking up at task 2.3: Update Header...

Najlepsze do: Równoległych strumieni pracy, pilnych przerw, współpracy zespołowej.

Gdy masz wiele ukończonych zmian, użyj /opsx:bulk-archive:

text
You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (all tasks done)
     - fix-login-redirect (all tasks done)
     - update-footer (all tasks done)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will apply in chronological order.

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-redirect
     ✓ Archived update-footer
     Specs merged in order: add-dark-mode → update-footer

Bulk archive wykrywa, gdy wiele zmian dotyka tych samych specyfikacji i rozwiązuje konflikty, sprawdzając, co faktycznie zostało zaimplementowane.

Zakończenie zmiany ​

Zalecany przepływ zakończenia:

text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              validates          prompts to sync
              implementation     if needed

Verify: Sprawdź swoją pracę ​

/opsx:verify waliduje implementację względem Twoich artefaktów w trzech wymiarach:

text
You: /opsx:verify

AI:  Verifying add-auth...

     COMPLETENESS
     ✓ All 12 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Session timeout after inactivity" not tested

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "event-driven" but implementation uses polling

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for session timeout scenario
     2. Consider refactoring to event-driven as designed, or update design.md

Co verify sprawdza:

WymiarCo waliduje
KompletnośćWszystkie zadania wykonane, wszystkie wymagania zaimplementowane, scenariusze pokryte
PoprawnośćImplementacja zgodna z intencją specyfikacji, przypadki brzegowe obsłużone
SpójnośćDecyzje projektowe odzwierciedlone w kodzie, wzorce spójne

Verify nie blokuje archiwizacji, ale ujawnia problemy, które możesz chcieć najpierw rozwiązać.

Archive: Sfinalizuj zmianę ​

/opsx:archive kończy zmianę i przenosi ją do archiwum:

text
You: /opsx:archive

AI:  Archiving add-auth...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (12/12 tasks complete)

     Delta specs: Not yet synced to main
     → Would you like to sync now?

You: Yes

AI:  ✓ Synced specs to openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/

     Change archived successfully.

Archive zapyta, jeśli specyfikacje nie zostały zsynchronizowane. Nie zablokuje przy niedokończonych zadaniach, ale ostrzeże Cię.

Kiedy używać czego ​

/opsx:ff vs /opsx:continue ​

SytuacjaUżyj
Jasne wymagania, gotowość do budowania/opsx:ff
Eksploracja, chęć przeglądu każdego kroku/opsx:continue
Chęć iterowania nad propozycją przed specyfikacjami/opsx:continue
Presja czasu, potrzeba szybkiego działania/opsx:ff
Złożona zmiana, chęć kontroli/opsx:continue

Zasada ogólna: Jeśli możesz opisać pełny zakres z góry, użyj /opsx:ff. Jeśli dopracowujesz to w trakcie, użyj /opsx:continue.

Kiedy aktualizować, a kiedy zaczynać od nowa ​

Częste pytanie: kiedy aktualizacja istniejącej zmiany jest w porządku, a kiedy należy zacząć nową?

Aktualizuj istniejącą zmianę, gdy:

  • Ten sam zamiar, udoskonalone wykonanie
  • Zakres się zawęża (najpierw MVP, reszta później)
  • Korekty wynikające z nauki (koda nie jest tym, czego się spodziewałeś)
  • Drobne zmiany projektowe na podstawie odkryć implementacyjnych

Zacznij nową zmianę, gdy:

  • Zamiar fundamentalnie się zmienił
  • Zakres rozszerzył się do zupełnie innej pracy
  • Oryginalna zmiana może zostać oznaczona jako "ukończona" samodzielnie
  • Łatki wprowadzą więcej zamieszania niż jasności
text
                     ┌─────────────────────────────────────┐
                     │     Is this the same work?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Same intent?      >50% overlap?      Can original
          Same problem?     Same scope?        be "done" without
                 │                  │          these changes?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YES               NO YES           NO  NO              YES
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW

Przykład: "Dodaj tryb ciemny"

  • "Muszę też obsłużyć niestandardowe motywy" → Nowa zmiana (zakres się rozszerzył)
  • "Wykrywanie preferencji systemowych jest trudniejsze niż się spodziewałem" → Aktualizacja (ten sam zamiar)
  • "Najpierw wypuść przełącznik, dodaj preferencji później" → Aktualizacja, potem archiwizacja, potem nowa zmiana

Najlepsze Praktyki ​

Zachowaj skupienie zmian ​

Jedna logiczna jednostka pracy na zmianę. Jeśli robisz „dodaj funkcję X i jednocześnie refaktoryzuj Y”, rozważ rozdzielenie na dwie zmiany.

Dlaczego to ważne:

  • Łatwiejszy przegląd i zrozumienie
  • Czystsza historia archiwum
  • Można wdrażać niezależnie
  • Prostsze wycofanie, jeśli zajdzie taka potrzeba

Używaj /opsx:explore w przypadku niejasnych wymagań ​

Zanim zaangażujesz się w zmianę, zbadaj przestrzeń problemu:

text
Ty: /opsx:explore

AI:  Co chciałbyś zbadać?

Ty: Jak powinniśmy obsłużyć rate limiting dla naszego API?

AI:  Pozwól, że zbadam twoją obecną konfigurację i opcje...
     [Bada bazę kodu, rozważa wzorce]

     Widzę trzy podejścia, które możemy zastosować:
     1. Oparte na oprogramowaniu pośredniczącym (middleware) (proste, na punkt końcowy)
     2. Oparte na Redis (skalowalne, współdzielony stan)
     3. Token bucket na użytkownika (sprawiedliwe, złożone)

     Twój obecny stos technologiczny sugeruje #1 lub #2. Jaka jest twoja skala?

Eksploracja wyjaśnia myślenie przed utworzeniem artefaktów.

Weryfikuj przed archiwizacją ​

Użyj /opsx:verify, aby sprawdzić, czy implementacja jest zgodna z artefaktami:

text
Ty: /opsx:verify

AI:  Weryfikacja add-dark-mode...

     ✓ Wszystkie zadania w tasks.md są zaznaczone
     ✓ Wymagania w specyfikacjach mają odpowiadający kod
     ✓ Decyzje projektowe są odzwierciedlone w implementacji

     Gotowe do archiwizacji!

Wyłapuje niezgodności, zanim zamkniesz zmianę.

Nazywaj zmiany jasno ​

Dobre nazwy sprawiają, że openspec list jest użyteczne:

Dobre:                         Unikaj:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Szybki przegląd poleceń ​

Pełne szczegóły poleceń i opcje znajdują się w Commands.

PolecenieCelKiedy używać
/opsx:proposeTworzenie zmiany + artefaktów planowaniaSzybka ścieżka domyślna (profil core)
/opsx:explorePrzemyślenie pomysłów z AIZacznij tutaj, gdy nie masz pewności: niejasne wymagania, dochodzenie, porównywanie opcji
/opsx:newRozpoczęcie szkieletu zmianyTryb rozszerzony, jawna kontrola artefaktów
/opsx:continueTworzenie następnego artefaktuTryb rozszerzony, tworzenie artefaktów krok po kroku
/opsx:ffTworzenie wszystkich artefaktów planowaniaTryb rozszerzony, jasny zakres
/opsx:applyImplementacja zadańGotowy do pisania kodu
/opsx:verifyWalidacja implementacjiTryb rozszerzony, przed archiwizacją
/opsx:syncScalenie specyfikacji deltaTryb rozszerzony, opcjonalnie
/opsx:archiveZakończenie zmianyCała praca zakończona
/opsx:bulk-archiveArchiwizacja wielu zmianTryb rozszerzony, praca równoległa

Następne kroki ​