Szybki start w OpenSpec: instalacja, przepływ pracy i typowe problemy

Specyfikacje jako różnice, a nie 40-stronicowy PRD.

Page content

OpenSpec to bezpłatne, open-source’owe narzędzie CLI od Fission AI, które pozwala Tobie i Twojemu agencji kodowania uzgodnić zmiany w prostym Markdownie, zanim napisany zostanie jakikolwiek kod, bez rygorystycznych fazy proceduralnych cięższych frameworków sterowanych specyfikacjami.

Większość zespołów, które próbują rozwijania sterowanego specyfikacją (Spec-Driven Development), napotyka ten sam dylemat: tyle procedury, aby zapobiec zgadywaniu przez agencję, ale nie tyle szkieletu, aby poprawka błędu z pięćdziesięcioma liniami kodu wymagała dokumentu propozycji. Odpowiedzią OpenSpec jest całkowite pominięcie instynktu „zadokumentuj najpierw cały system” i pisanie specyfikacji tylko dla tego, co dana zmiana faktycznie dotyka, używając delt ADDED (dodane), MODIFIED (zmodyfikowane) i REMOVED (usunięte) zamiast pełnego przepisania za każdym razem.

Przepływ pracy OpenSpec z rozwojem sterowanym specyfikacją z asystentem AI do kodowania

To projekt skupiony na zmianach jest również powodem, dla którego OpenSpec regularnie pojawia się obok GitHub Spec Kit, Kiro i Superpowers w porównaniu kategorii narzędzi SDD – zazwyczaj jest to wybór, gdy zespół chce mieć specyfikacje do recenzji bez fazy planowania liczącej 800 linii. Ten przewodnik obejmuje instalację CLI, czteroetapowy przepływ pracy, którego faktycznie używa się na co dzień, jak zmiana wygląda na dysku oraz najczęstsze pytania i skargi pojawiające się na Reddit oraz w własnym systemie śledzenia problemów OpenSpec.

Czym jest OpenSpec?

OpenSpec opisuje własną filozofię w czterech punktach: płynne, a nie sztywne; iteracyjne, a nie kaskadowe; proste, a nie złożone; stworzone dla istniejących projektów (brownfield), a nie tylko dla nowych (greenfield). W praktyce oznacza to, że nie ma zablokowanych faz – możesz edytować propozycję, specyfikację lub listę zadań w dowolnym momencie zmiany, zamiast być zmuszanym do przechodzenia przez ścieżkę „określ, a potem zaplanuj, a potem implementuj” w ścisłej kolejności, tak jak opisuje to niezależny od narzędzi przepływ pracy SDD.

Zmiana w OpenSpec generuje do czterech artefaktów Markdown w własnym folderze:

Artefakt Cel
proposal.md Dlaczego zmiana istnieje i co zmienia, w prostym języku
specs/ Wymagania deltowe i scenariusze – testowalna specyfikacja dla tej zmiany
design.md Opcjonalne podejście techniczne, dla zmian, które tego wymagają
tasks.md Lista kontrolna implementacji, z którą pracuje agencja

Gdy zmiana zostanie zaimplementowana i zarchiwizowana, jej specyfikacje deltowe są scalane z openspec/specs/, co staje się trwałym, obecnym opisem stanu Twojego systemu – to ta sama idea „specyfikacja jako źródło prawdy”, o której mowa w [Czym jest rozwój sterowany specyfikacją?](https://www.glukhov.org/pl/app-architecture/documentation/what-is-spec-driven-development/ “Czym jest rozwój sterowany specyfikacją? Specyfikacja jako źródło prawdy”), z tym że zakres obejmuje jedną zmianę naraz, zamiast być pisane wszystko naraz.

Instalacja OpenSpec

OpenSpec to CLI oparty na Node.js, więc potrzebujesz Node 20.19.0 lub nowszej wersji na swojej maszynie.

node --version

Zainstaluj CLI globalnie za pomocą npm, a następnie upewnij się, że znajduje się na Twoim PATH:

npm install -g @fission-ai/openspec@latest
openspec --version

Deno, pnpm, yarn, bun i nix to również wspierane metody instalacji, jeśli lepiej pasują do Twojego środowiska niż npm. Po zainstalowaniu zainicjuj go w projekcie:

cd your-project
openspec init

openspec init pyta, jakie narzędzia AI używasz i zapisuje odpowiadające im pliki umiejętności i komend – OpenSpec obsługuje ponad 30 asystentów, w tym Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro i OpenCode. W przypadku konfiguracji CI lub skryptowej pomiń wybór narzędzi całkowicie:

openspec init --tools claude,cursor   # skonfiguruj konkretne narzędzia
openspec init --tools all             # każde wspierane narzędzie
openspec init --tools none            # tylko struktura openspec/, bez plików narzędzi

Po zakończeniu zrestartuj IDE, aby wykryło nowo zapisane umiejętności i komendy. Jeśli wolisz, aby Twój asystent wykonał całą instalację za Ciebie, OpenSpec oferuje prompt ustawieniowy, który możesz wkleić w Claude Code lub innego agenta, który wykona instalację, uruchomi openspec init i zgłosi, co skonfigurował.

Główny przepływ pracy: Explore, Propose, Apply, Archive

To jest jedyna rzecz, która myli prawie każdego pierwszego dnia: komendy openspec są wykonywane w Twoim terminalu, ale komendy /opsx: są wykonywane w oknie czatu Twojego asystenta AI. Nie ma osobnego „trybu interaktywnego” do uruchomienia – wpisanie komendy ze slasza w czacie to sposób, w jaki się zaczyna.

flowchart LR A["/opsx:explore (opcjonalnie)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specyfikacje scalone| E["openspec/specs/"]
  • /opsx:explore to partner do myślenia bez ryzyka. Czyta odpowiednią część Twojej bazy kodu, przedstawia opcje i kształtuje plan, zanim cokolwiek zostanie zapisane na dysku – warto uczynić z tego nawyk, ponieważ zapobiega zapałliwej agencji w budowaniu nie tego, czego trzeba, z pewnością.
  • **``/opsx:propose ** tworzy openspec/changes//` i szkicuje propozycję, specyfikacje deltowe, opcjonalny projekt i listę zadań w jednym kroku. Przeglądasz tu plan, zanim rozpocznie się implementacja.
  • /opsx:apply pracuje przez listę zadań, odznaczając elementy w miarę postępu. Ponieważ postęp znajduje się w plikach, a nie tylko w historii czatu, możesz wyczyścić okno kontekstu lub zacząć nową sesję i wznowić dokładnie tam, gdzie /opsx:apply się zatrzymało.
  • /opsx:archive archiwizuje ukończoną zmianę do openspec/changes/archive/YYYY-MM-DD-<nazwa>/ i scal jej specyfikacje deltowe z kanonicznym drzewem openspec/specs/.

Domyślny profil core instaluje dokładnie te cztery komendy oraz update i sync. Rozszerzony profil dodaje new, continue, ff, verify, bulk-archive i onboard dla zespołów, które chcą tworzyć jeden artefakt na raz, zamiast wszystkiego naraz – przełącz się na niego za pomocą openspec config profile, a następnie openspec update.

Każde narzędzie zapisuje tę samą komendę inaczej w zależności od tego, jak ładuje niestandardowe instrukcje: /opsx:propose w Claude Code, /opsx-propose w Cursor i GitHub Copilot, @opsx-propose w Amazon Q lub $openspec-propose w Codex. openspec init wyświetla dokładną formę dla wybranych narzędzi, więc najszybsze naprawienie problemu „nic się nie stało, gdy wpisałem komendę” to zwykle ponowne przeczytanie wyświetlonej podpowiedzi zamiast zgadywania.

Jak zmiana wygląda na dysku

Folder zmiany pod openspec/changes/add-dark-mode/ zawiera typowo propozycję, specyfikację deltową i listę zadań w formie:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Ten format deltowy ADDED/MODIFIED/REMOVED to mechanizm, który pozwala OpenSpec unikać przepisywania całego pliku specyfikacji dla zmiany jednego pola. Jest to również powód, dla którego OpenSpec jest wyraźnie zorientowany na istniejące projekty (brownfield-first), a nie na nowe (greenfield-first): nigdy nie dokumentujesz całej aplikacji przed uzyskaniem wartości, tylko dokumentujesz fragment, którego dotyka każda rzeczywista zmiana, i openspec/specs/ wypełnia się naturalnie w ciągu miesięcy normalnej pracy.

Przydatne komendy CLI do sprawdzania tego stanu bez opuszczania terminala:

openspec list                 # aktywne zmiany
openspec show add-dark-mode   # wyświetl artefakty zmiany
openspec validate --all       # sprawdź formatowanie specyfikacji w całym projekcie
openspec view                 # interaktywna tablica zarządzania

Commituj cały folder openspec/ do git. Aktywne zmiany i archiwum mają stać się trwałym, wersjonowanym zapisem tego, co Twój system robi i dlaczego ulegał zmianom – a nie szkicem, który usuwasz po scaleniu.

Wdrożenie OpenSpec na istniejącej bazie kodu

Najczęstsza obawa zespołów oceniających OpenSpec na rzeczywistym projekcie to jakaś wersja pytania: „Moja aplikacja ma 80 000 linii, muszę najpierw sprecyzować całość?”. Nie. Własne wytyczne OpenSpec są tu bezlitosne: wybierz coś małego i rzeczywistego, które i tak planowałeś zbudować w tym tygodniu, uruchom /opsx:explore na obszarze, który zaraz dotkniesz, aby agencja najpierw zmapowała, jak rzeczy faktycznie działają, a następnie /opsx:propose zmianę ograniczoną do właśnie tego fragmentu.

Jeśli masz już PRD, dokumenty SRS lub dokumenty projektowe w Notion lub Confluence, traktuj je jako materiał źródłowy do eksploracji, a nie coś do masowej konwersji na specyfikacje. Wklej odpowiednią sekcję do sesji /opsx:explore i pozwól agencji ukształtować z tego skupioną deltę; jednorazowa mechaniczna konwersja czterdziestostronicowego PRD często produkuje specyfikację, której nikt nie ufa po sześciu miesiącach. Dla zespołów, które chcą przeprowadzonego, opowiadanie pierwszej próby zamiast wskakiwania od razu w rzeczywistą zmianę, rozszerzona komenda /opsx:onboard skanuje Twoją bazę kodu pod kątem małej, bezpiecznej poprawki i przeprowadza przez pełną pętlę na jej podstawie.

Częste pytania i problemy

Są to problemy, które regularnie pojawiają się na Discordzie OpenSpec, w problemach na GitHubie oraz na wątkach na Reddicie w subredditych takich jak r/cursor, r/RooCode i r/opencodeCLI.

„Wpisałem komendę ze slasza i nic się nie stało.” Prawie zawsze to jedna z przyczyn: wpisałeś ją w terminalu, a nie w czacie asystenta, Twoje IDE nie zostało zrestartowane od czasu uruchomienia openspec init, lub wersja CLI jest tak stara, że openspec update raportuje, że wszystko jest aktualne, nie zapisując nigdy nowszych plików przepływu pracy. Uruchom openspec update, zrestartuj IDE i upewnij się, że foldery umiejętności istnieją (.claude/skills/openspec-* dla Claude Code lub odpowiednik z listy wspieranych narzędzi dla Twojego narzędzia).

„AI generuje znacznie więcej specyfikacji, niż potrzebuję.” To najczęstsza skarga w dłuższych artykułach: agencja może zamienić funkcjonalność wymagającą trzydziestu minut na specyfikację o 800 liniach. OpenSpec ogranicza pole context: wstrzykiwane do każdego żądania do 50 KB, aby wymusić dyscyplinę, ale same specyfikacje deltowe nie mają twardego limitu, więc przycinanie wygenerowanych specyfikacji do tego, co naprawdę jest kluczowe, to nawyk, który musisz utrzymywać sam, a nie coś, co wymusza narzędzie.

„Dwie zmiany dotknęły tego samego wymagania, a jedna cicho usunęła scenariusz drugiej.” To rzeczywisty, udokumentowany przypadek brzegowy: archiwizowanie stosuje deltę MODIFIED jako zastąpienie całego bloku z kluczami według nazwy wymagania, więc jeśli dwie aktywne zmiany modyfikują to samo wymaganie, archiwizowanie drugiej używa nadpisywać scenariusze pierwszej bez ostrzeżenia. Aktualne wersje dodają kontrolę dryfu, która anuluje archiwizację i informuje, aby najpierw odświeżyć specyfikację zmiany – ale warto wiedzieć, że taki tryb awarii istnieje, jeśli prowadzisz kilka zmian na tym samym obszarze równolegle.

„Którego modelu AI powinienem faktycznie użyć?” Własne dokumenty OpenSpec zalecają modele o wysokiej zdolności rozumowania zarówno do planowania, jak i implementacji – konkretnie wymieniane są modele klasy Opus i klasy Codex – oraz czyszczenie okna kontekstu przed implementacją, ponieważ czysty kontekst daje mierzalnie lepsze wyniki niż długa, nagromadzona sesja.

„Jak to różni się od Spec Kit, Kiro, Superpowers lub BMAD?” To jest najczęściej zadawane pytanie na Reddit, a uczciwa odpowiedzią jest „waga procesu”. Własne README OpenSpec bezpośrednio ramuje to porównanie: Spec Kit jest staranny, ale cięższy, z większą ilością Markdowna i sztywnymi bramkami fazowymi; Kiro jest potężne, ale zamyka Cię w IDE od AWS i modelach Claude; OpenSpec zamienia część tej początkowej struktury na zdolność do swobodnego iterowania i pracy z jakimkolwiek asystentem, którego już masz otwartego. Pełne wyjaśnienie względem Spec Kit, Kiro, umiejętności Claude Code, BMAD-METHOD i [Superpowers](https://www.glukhov.org/pl/ai-devtools/superpowers/ “Superpowers Szybki start: instalacja, przepływ pracy i testy”) znajdziesz w dedykowanym [porównaniu narzędzi SDD](https://www.glukhov.org/pl/ai-devtools/ai-coding-assistants/spec-kit-vs-kiro-vs-claude-code/ “GitHub Spec Kit vs Kiro vs Claude Code: przepływy pracy SDD”).

„Czy AI faktycznie stosuje się do specyfikacji, którą właśnie napisało?” Nie zawsze, i jest to udokumentowany problem we wszystkich narzędziach SDD ogólnie, a nie wyjątkowo OpenSpec – duże okno kontekstu nie oznacza, że agencja poświęca równą uwagę każdej jego części. Komenda /opsx:verify istnieje właśnie po to, aby wykrywać wygenerowany kod, który sprzeczny jest z jego własną specyfikacją, i warto ją uruchamiać dla czegokolwiek niewymagającego dużego wysiłku, zamiast ślepo ufać implementacji.

„Czy potrzebuję tego do poprawy jednej linii?” Nie. Własne FAQ OpenSpec to mówi wprost: używaj go tam, gdzie zgoda ma znaczenie, czyli w większości niewymagających dużego wysiłku prac wieluplikowych, i pominij go dla poprawki literówki lub wyrzucalnego prototypu, który usuniesz za tydzień.

Kiedy OpenSpec pasuje, a kiedy nie

Dobre zastosowanie:

  • Bazy kodu brownfield, gdzie chcesz mieć specyfikacje do recenzji bez dokumentowania całego systemu z góry.
  • Programiści pracujący samodzielnie i małe zespoły, które chcą lżejszej ceremonialności niż Spec Kit, ale wciąż chcą mieć pisemny plan przed kodem.
  • Praca rozciągająca się na kilka plików, zmiana schematu lub cokolwiek, co młody inżynier rozsądnie chciałby mieć jako krótki dokument projektowy.
  • Zespoły już przyzwyczajone do recenzowania planów w pull requestach – specyfikacje deltowe dobrze się diffują, ponieważ opisują tylko to, co się zmieniło.

Słabsze zastosowanie:

  • Poprawki błędów jednej linii i wyrzucalne prototypy, gdzie krok recenzji propozycji kosztuje więcej, niż oszczędza.
  • Zespoły, które potrzebują cięższej, bardziej preskryptywnej struktury Spec Kit lub natywnego dla AWS doświadczenia zintegrowanego z IDE, jak Kiro – patrz [ramy decyzyjne w porównaniu narzędzi](https://www.glukhov.org/pl/ai-devtools/ai-coding-assistants/spec-kit-vs-kiro-vs-claude-code/ “GitHub Spec Kit vs Kiro vs Claude Code: przepływy pracy SDD”) dla miejsca, gdzie każde narzędzie wygrywa.
  • Funkcje między repozytoriami na dziś, chyba że jesteś gotów wypróbować funkcję stores OpenSpec w wersji beta, która przenosi planowanie do własnego wspólnego repozytorium, aby wiele baz kodu i agentów mogło czytać ten sam plan.
  • Ktokolwiek wciąż decyduje, czy dana funkcjonalność w ogóle zasługuje na specyfikację – przeczytaj [Rozwój sterowany specyfikacją vs Vibe Coding](https://www.glukhov.org/pl/ai-devtools/vibe-coding/spec-driven-development-vs-vibe-coding/ “Rozwój sterowany specyfikacją vs Vibe Coding – kaskada?”) najpierw, ponieważ OpenSpec pomaga dopiero, gdy już zdecydowałeś, że struktura warta jest nakładów.

Podsumowanie

Stawka OpenSpec polega na tym, że większość bólu związanego z rozwojem sterowanym specyfikacją wynika z ceremonialności, a nie z samej idei uzgadniania planu przed istnieniem kodu. Deltami zamiast pełnych przepisów, brak zablokowanych faz i przepływ pracy zorientowany na istniejące projekty sprawiają, że jest on zauważalnie lżejszy do wdrożenia na bazie kodu, której nie budowałeś od zera. Kompromisy są też realne – balonienie specyfikacji jest prawdziwym ryzykiem bez dyscypliny, obsługa konfliktów wokół jednoczesnych zmian jednego wymagania wciąż dojrzewa, a ekosystem jest młodszy niż własne narzędzia GitHuba. Zainstaluj to na jednym rzeczywistym projekcie, przeprowadź małą zmianę przez explore-propose-apply-archive od początku do końca i oceny wtedy, czy lżejsza ceremonialność zwraca się przy Twojej rzeczywistej obciążeniu.

Przydatne linki

Subskrybuj

Otrzymuj nowe wpisy o systemach, infrastrukturze i inżynierii AI.