OpenSpec – szybki start: instalacja, przepływ pracy i typowe pułapki

Specyfikacje jako delty, nie 40-stronicowy PRD.

Page content

OpenSpec to darmowe, otwartoźródłowe narzędzie CLI od Fission AI, które pozwala Tobie i Twojemu agentowi programistycznemu uzgodnić zmiany w prostym Markdownie, zanim napisany zostanie jakikolwiek kod, bez fazy ceremonii charakterystycznej dla ciężkich, spec-driven frameworków.

Większość zespołów, które próbują Spec-Driven Development, utyka na tym samym kompromisie: dość procesu, aby powstrzymać agenta przed zgadywaniem, ale bez tyle szkieletu, że naprawa błędu o pięćdziesięciu liniach wymagałaby dokumentu propozycji. Odpowiedzią OpenSpec jest całkowite pominięcie instynktu „zadokumentuj najpierw cały system” i pisanie specyfikacji wyłącznie dla tych elementów, które zmiana faktycznie dotyka, używając delt ADDED, MODIFIED i REMOVED zamiast pełnego przepisania za każdym razem.

Przepływ pracy spec-driven development w OpenSpec z asystentem AI

Ta centrowana na zmianie architektura 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 specyfikacji podlegających rewizji, bez fazy planowania na 800 linii. Ten przewodnik obejmuje instalację CLI, czteroetapowy workflow używany na co dzień, to, jak zmiana wygląda na dysku, oraz pytania i zastrzeżenia, które najczęściej pojawiają się na Reddit i we własnym trackerze problemów OpenSpec.

Czym jest OpenSpec?

OpenSpec opisuje własną filozofię w czterech zdaniach: płynny, nie sztywny; iteracyjny, nie kaskadowy; prosty, nie złożony; stworzony dla brownfield, nie tylko dla 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 etapy specify-plan-implement w ścisłej kolejności, tak jak opisuje to neutralne wobec narzędzi podejście SDD.

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

Artefakt Cel
proposal.md Dlaczego zmiana istnieje i co zmienia, w prostym języku
specs/ Deltowe wymagania i scenariusze – testowalna specyfikacja dla tej zmiany
design.md Opcjonalne podejście techniczne, dla zmian, które go potrzebują
tasks.md Lista kontrolna implementacji, którą agent odhacza

Gdy zmiana zostanie zaimplementowana i zarchiwizowana, jej specyfikacje delt scalają się z openspec/specs/, co staje się trwałą, aktualną deskrypcją Twojego systemu – to samo podejście „specyfikacja jako źródło prawdy” omówione w Czym jest Spec-Driven Development?, tylko zakresowane do jednej zmiany naraz, zamiast pisać wszystko od razu.

Instalacja OpenSpec

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

node --version

Zainstaluj CLI globalnie za pomocą npm, a następnie zweryfikuj, czy znajduje się w Twoim PATH:

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

Deno, pnpm, yarn, bun i nix to również wspierane ścieżki instalacji, jeśli pasują do Twojej konfiguracji lepiej niż npm. Po zainstalowaniu zainicjalizuj go wewnątrz projektu:

cd twoj-projekt
openspec init

openspec init pyta, których narzędzi AI używasz i zapisuje odpowiadające pliki umiejętności i poleceń – OpenSpec wspiera ponad 30 asystentów, w tym Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro i OpenCode. Dla CI lub skryptowej konfiguracji, pomiń wybierzarkę 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

Uruchom ponownie IDE, aby rozpoznało nowo zapisane umiejętności i polecenia. Jeśli wolisz, aby to Twój asystent wykonał całą instalację za Ciebie, OpenSpec dostarcza prompt ustawieniowy, który możesz wkleić do Claude Code lub innego agenta, który wykona instalację, uruchomi openspec init i odnotuje, co skonfigurował.

Główny Workflow: Explore, Propose, Apply, Archive

To jest ta jedna rzecz, która niemal zawsze zastawia pułapkę w pierwszym dniu: polecenia openspec działają w Twoim terminalu, ale polecenia /opsx: działają w oknie czatu Twojego asystenta AI. Nie ma osobnego „trybu interaktywnego”, do którego trzeba wejść – wpisywanie polecenia ze slashem w czacie to sposób na rozpoczęcie.

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 stawki. Czyta istotną część Twojej bazy kodu, wyprowadza opcje i kształtuje plan, zanim cokolwiek zostanie zapisane na dysku – warto to uczynić nawykiem, ponieważ powstrzymuje żądznego agenta przed pewnym budowaniem niewłaściwej rzeczy.
  • /opsx:propose <nazwa> tworzy openspec/changes/<nazwa>/ i szkicuje propozycję, specyfikacje delt, opcjonalny projekt i listę zadań w jednym kroku. Przeglądasz plan tutaj, zanim rozpocznie się implementacja.
  • /opsx:apply przechodzi przez listę zadań, odhaczając elementy w miarę postępu. Ponieważ postęp istnieje w plikach, a nie tylko w historii czatu, możesz wyczyścić okno kontekstu lub zacząć nową sesję i podjąć dokładnie tam, gdzie skończył /opsx:apply.
  • /opsx:archive archiwizuje ukończoną zmianę w openspec/changes/archive/YYYY-MM-DD-<nazwa>/ i scala jej specyfikacje delt z kanonicznym drzewem openspec/specs/.

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

Każde narzędzie pisze to samo polecenie 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 wypisuje dokładną formę dla wybranych narzędzi, więc najszybsza naprawa dla „nic się nie stało, kiedy wpisałem polecenie” to zwykle ponowne odczytanie tej podpowiedzi, a nie zgadywanie.

Jak zmiana wygląda na dysku

Folder zmiany pod openspec/changes/add-dark-mode/ zawiera typowo propozycję, specyfikację deltę i listę zadań w następującej 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 delta ADDED/MODIFIED/REMOVED to mechanizm, który pozwala OpenSpec uniknąć przepisania całego pliku specyfikacji dla zmiany jednego pola. To też powód, dla którego OpenSpec jest wyraźnie brownfield-first, a nie greenfield-first: nigdy nie dokumentujesz całej aplikacji przed uzyskaniem wartości, tylko dokumentujesz fragment, który dotyka każda realna zmiana, a openspec/specs/ wypełnia się naturalnie w miesiące normalnej pracy.

Przydatne polecenia CLI do sprawdzania tego stanu bez opuszczania terminala:

openspec list                 # aktywne zmiany
openspec show add-dark-mode   # podgląd artefaktów zmiany
openspec validate --all       # sprawdzenie formatowania specyfikacji w całym projekcie
openspec view                 # interaktywny dashboard

Zacommituj cały folder openspec/ do git. Aktywne zmiany i archiwum mają stać się trwałą, wersjonowaną rejestracją tego, co robi Twój system i dlaczego się zmienił – a nie notatnikiem, którego kasujesz po scaleniu.

Wdrożenie OpenSpec w istniejącej bazie kodu

Najczęstszą obawą zespołów oceniających OpenSpec w realnym projekcie jest wersja pytania: „moja aplikacja ma 80 000 linii, czy muszę najpierw zaspecyfikować całość?”. Nie musisz. Własne wytyczne OpenSpec są tu dosadne: wybierz coś małego i realnego, co i tak zamierzałeś zbudować w tym tygodniu, uruchom /opsx:explore na obszarze, którego zamierzasz dotknąć, aby agent najpierw zmapował, jak rzeczy faktycznie działają, a następnie /opsx:propose zmiana zakresowana do tylko tego fragmentu.

Jeśli masz już PRD, dokumenty SRS lub dokumenty projektowe leżące w Notion lub Confluence, traktuj je jako materiał źródłowy do eksploracji, a nie coś, co trzeba masowo konwertować na specyfikacje. Wklej odpowiednią sekcję do sesji /opsx:explore i pozwól agentowi ukształtować z tego skupioną deltę; jednorazowa mechaniczna konwersja czterdziestostronicowego PRD tenduje do wytworzenia specyfikacji, której nikt nie będzie ufał pół roku później. Dla zespołów, które chcą prowadzonego, opowiedzianego pierwszego przebiegu zamiast skoków prosto na realną zmianę, rozszerzone polecenie /opsx:onboard skanuje Twoją bazę kodu pod kątem małej, bezpiecznej poprawki i przechodzi przez pełną pętlę na niej.

Częste pytania i problemy

Są to problemy, które powtarzają się w Discord OpenSpec, issue’ach GitHub i wątkach na Reddit w subredditach takich jak r/cursor, r/RooCode i r/opencodeCLI.

„Wpisałem polecenie ze slashem i nic się nie stało.” Prawie zawsze jest to jedna z tych rzeczy: wpisałeś to w terminalu, a nie w czacie asystenta, Twoje IDE nie zostało uruchomione ponownie od czasu, gdy działalo openspec init, albo wersja CLI jest na tyle stara, że openspec update raportuje wszystko jako aktualne, bez kiedykolwiek zapisania nowych plików workflow. Uruchom openspec update, zrestartuj IDE i potwierdź, ż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 jest najczęstsza skarga w dłuższych opisach: agent może zamienić funkcjonalność trzydziestu minut na specyfikację 800 linii. OpenSpec ogranicza pole context: wstrzykiwane do każdego żądania do 50KB, aby wymusić dyscyplinę, ale same specyfikacje delt nie mają twardego limitu, więc przycinanie wygenerowanych specyfikacji do tego, co jest faktycznie nośne, to nawyk, który musisz podtrzymywać sam, a nie coś, co narzędzie egzekwuje za Ciebie.

„Dwie zmiany dotknęły tego samego wymagania i jedna cicho usunęła scenariusz drugiej.” To jest realny, udokumentowany przypadek brzegowy: archiwizacja stosuje deltę MODIFIED jako całościową zamianę bloku kluczoną nazwą wymagania, więc jeśli dwie aktywne zmiany zmieniają to samo wymaganie, archiwizacja drugiej używała do nadpisywania scenariuszy pierwszej bez ostrzeżenia. Bieżące wersje dodają sprawdzenie dryfu, które przerywa archiwizację i mówi Ci, abyś najpierw odświeżył specyfikację zmiany – ale wciąż warto wiedzieć o tym trybie awarii, jeśli uruchamiasz kilka zmian na tym samym obszarze równolegle.

„Jakiego modelu AI powinnem faktycznie z tym używać?” Własne dokumenty OpenSpec zalecają modele o wysokim rozumowaniu zarówno do planowania, jak i implementacji – modele klasy Opus i klasy Codex są wymienione konkretnie – oraz czyszczenie okna kontekstu przed implementacją, ponieważ czysty kontekst daje mierzalnie lepsze wyniki niż długa, akumulowana sesja.

„Czym to różni się od Spec Kit, Kiro, Superpowers lub BMAD?” To jest najczęstsze pytanie na Reddit, i uczciwą odpowiedzią jest „ciężar procesu”. Własny README OpenSpec przedstawia porównanie bezpośrednio: Spec Kit jest wnikliwy, ale cięższy, z większą ilością Markdownu i sztywnymi bramkami faz; Kiro jest potężne, ale blokuje Cię w IDE AWS i modelach Claude; OpenSpec wymienia część tej wstępnej struktury na możliwość swobodnego iterowania i pracy z dowolnym asystentem, który już masz otwarty. Pełne rozbicie w stosunku do Spec Kit, Kiro, umiejętności Claude Code, BMAD-METHOD i Superpowers, zobacz dedykowane porównanie narzędzi SDD.

„Czy AI faktycznie przestrzega specyfikacji, którą właśnie napisało?” Nie zawsze, i to jest udokumentowany problem w narzędziach SDD ogólnie, a nie unikalny dla OpenSpec – duże okno kontekstu nie oznacza, że agent równomiernie zwraca uwagę na każdą jego część. Polecenie /opsx:verify istnieje konkretnie po to, aby wyłapywać wygenerowany kod, który sprzeciwia się własnej specyfikacji, i warto go uruchamiać przy wszystkim, co nie jest trywialne, zamiast ślepo ufać implementacji.

„Czy potrzebuję tego do poprawki jednej linii?” Nie. Własne FAQ OpenSpec mówi to wprost: używaj tam, gdzie zgoda ma znaczenie, co jest większość nietrywialnej, wieloplikowej pracy, i pomijaj to dla poprawki literówki lub wyrzucalnego prototypu, który usuniesz za tydzień.

„Jak powstrzymać agenta przed ponownym proponowaniem czegoś, co już odrzuciliśmy?” /opsx:archive nie ma dedykowanego statusu dla odrzuconej zmiany, więc nic nie informuje przyszłej propozycji, że pomysł został już zbadany i odrzucony. Zobacz Odrzucone propozycje OpenSpec: Konwencja pamięci decyzyjnej dla wzorca decision.md i reguły konfiguracji, która sprawia, że agent przeszukuje archiwum przed ponownym proponowaniem.

Kiedy OpenSpec pasuje, a kiedy nie

Dobre dopasowanie:

  • Bazy kodu brownfield, gdzie chcesz specyfikacji podlegających rewizji bez dokumentowania całego systemu z góry.
  • Samodzielni deweloperzy i małe zespoły, które chcą lżejszej ceremonii niż Spec Kit, ale nadal otrzymują pisemny plan przed kodem.
  • Praca obejmująca kilka plików, zmianę schematu lub cokolwiek, czego junior inżynier racjonalnie chciałby mieć krótki dokument projektowy.
  • Zespoły już zaangażowane w recenzowanie planów w pull requestach – specyfikacje delt diffują się czysto, ponieważ opisują tylko to, co się zmieniło.

Słabsze dopasowanie:

  • Jedno- liniowe poprawki błędów i wyrzucalne prototypy, gdzie krok propozycja-recenzja kosztuje więcej, niż oszczędza.
  • Zespoły, które potrzebują cięższej, bardziej preskryptywnej struktury Spec Kit lub doświadczenia natywnego dla AWS, zintegrowanego z IDE, jak Kiro – zobacz ramę decyzyjną w porównaniu narzędzi o tym, gdzie każde narzędzie wygrywa.
  • Funkcje między repozytoriami dzisiaj, chyba że jesteś gotów wypróbować beta funkcję stores w OpenSpec, która przenosi planowanie do własnego współdzielonego repozytorium, aby wiele baz kodu i agentów mogło czytać ten sam plan.
  • Każdy, kto wciąż decyduje, czy dana funkcjonalność w ogóle zasługuje na specyfikację – przeczytaj [Spec-Driven Development vs Vibe Coding](https://www.glukhov.org/pl/ai-devtools/vibe-coding/spec-driven-development-vs-vibe-coding/ “Spec-Driven Development vs Vibe Coding – Kaskada?”) najpierw, ponieważ OpenSpec pomaga tylko wtedy, gdy już zdecydowałeś, że struktura jest warta overheadu.

Wniosek

Zakład OpenSpec polega na tym, że większość bólu Spec-Driven Development pochodzi z ceremonii, a nie z podstawowego pomysłu uzgadniania planu przed istnieniem kodu. Delty zamiast pełnych przepisań, brak zablokowanych faz i workflow brownfield-first czynią go zauważalnie lżejszym niż Spec Kit lub Kiro wdrożenie na bazie kodu, której nie zbudowałeś od zera. Kompromisy są też realne – rozrost specyfikacji to prawdziwe ryzyko bez dyscypliny, obsługa konfliktów wokół jednoczesnych zmian jednego wymagania wciąż dojrzałości się, a ekosystem jest młodszy niż własne narzędzia GitHub. Zainstaluj go na jednym realnym projekcie, uruchom małą zmianę przez explore-propose-apply-archive od początku do końca i zadecyduj na tej podstawie, czy lżejsza ceremonia uzasadnia jej koszt wobec Twojego rzeczywistego obciążenia.

Przydatne linki

Subskrybuj

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