FAQ

Szybkie odpowiedzi na najczęściej zadawane pytania. Jeśli twoje pytanie to w istocie pytanie „coś jest zepsute”, lepiej zajrzeć na stronę Rozwiązywanie problemów. Jeśli chcesz znaleźć definicję terminu, zobacz Słowniczek.

Podstawy

Czym jest OpenSpec, w jednym zdaniu?

Lekka warstwa, która pozwala Tobie i Twojemu asystentowi kodowania AI uzgodnić na piśmie, co zostanie zbudowane, zanim powstanie jakikolwiek kod.

Dlaczego miałbym tego chcieć?

Ponieważ asystenci AI są pewni siebie nawet wtedy, gdy się mylą. Gdy wymagania istnieją tylko w wątku czatu, AI wypełnia luki domysłami, a Ty odkrywasz to po napisaniu kodu. OpenSpec przesuwa uzgodnienia na wcześniejszy etap, kiedy błędy można naprawić tanio. Pełne uzasadnienie znajdziesz w Kluczowe pojęcia w skrócie.

Czy muszę go używać do wszystkiego?

Nie. Używaj go tam, gdzie porozumienie ma znaczenie, czyli przy większości nietrywialnych zadań. Przy poprawkach typu jeden znak literówki ta oprawa prawdopodobnie nie jest warta zachodu – i to jest w porządku.

Czy mogę go użyć na dużym istniejącym kodzie, czy tylko w nowych projektach?

Istniejące bazy kodu to główne pole działania. OpenSpec stawia na projekty legacy (brownfield): nie dokumentujesz całej aplikacji z góry. Piszesz specyfikacje tylko dla tego, czego dotyczy dana zmiana, a Twoje specyfikacje stopniowo się uzupełniają wokół faktycznie wykonanej pracy. Istnieje dedykowany przewodnik: Korzystanie z OpenSpec w istniejącym projekcie.

Czy jest powiązany z jednym narzędziem AI?

Nie. OpenSpec działa z ponad 30 asystentami, w tym Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex i innymi. Pełna lista i szczegóły dla poszczególnych narzędzi znajdują się w Obsługiwane narzędzia.

Uruchamianie poleceń

Gdzie wpisać /opsx:propose?

W czacie asystenta AI, a nie w terminalu. To najczęstsze źródło nieporozumień, dlatego ma własną stronę: Jak działają polecenia. W skrócie: openspec ... uruchamiasz w terminalu, /opsx:... – w czacie.

Jak „uruchomić tryb interaktywny”?

Nie ma osobnego trybu do uruchomienia. Otwierasz asystenta AI jak zwykle i wpisujesz polecenie z ukośnikiem w jego czacie. Polecenie z ukośnikiem to sposób na „wejście” do OpenSpec. (Jedyną prawdziwie interaktywną funkcją terminala jest openspec view – pulpit do przeglądania specyfikacji i zmian.) Pełne wyjaśnienie znajdziesz w Jak działają polecenia.

Wpisałem polecenie z ukośnikiem i nic się nie stało. Dlaczego?

Najprawdopodobniej wpisałeś je w terminalu zamiast w czacie AI, użyłeś pisowni, której Twoje narzędzie nie rejestruje, albo polecenia nie są jeszcze zainstalowane. Jeśli brakuje plików – lub nigdy nie skonfigurowałeś narzędzia – uruchom openspec init; openspec update odświeża tylko pliki, które już istnieją. Następnie uruchom ponownie asystenta i użyj formy wydrukowanej w sekcji „Getting started” – zobacz Jak wywoływać. Pełna lista kontrolna znajduje się w Rozwiązywanie problemów.

Dlaczego składnia to /opsx:propose w jednym narzędziu, a /opsx-propose w innym?

Każde narzędzie AI wyświetla niestandardowe polecenia nieco inaczej, a OpenSpec zapisuje je w sposób, w jaki Twoje narzędzie ładuje utworzony plik. Plik polecenia o nazwie opsx-propose.md wpisuje się jako /opsx-propose; plik umieszczony w commands/opsx/ – jako /opsx:propose. Narzędzia, które używają umiejętności (skills) zamiast poleceń, korzystają z nazwy umiejętności – Codex wymaga $openspec-propose, Kimi Code – /skill:openspec-propose. Linia „Getting started” wyświetlana po openspec init drukuje już właściwą formę dla wybranych narzędzi; pełna tabela znajduje się w Jak wywoływać.

Jaka jest różnica między umiejętnością a poleceniem?

Oba to pliki zapisywane przez OpenSpec, aby asystent mógł uruchomić przepływ pracy. Umiejętności (.../skills/openspec-*/SKILL.md) to nowszy standard międzynarzędziowy; polecenia (.../commands/opsx-*) to starsze pliki z ukośnikami specyficzne dla narzędzia. Nie musisz wybierać. Po prostu wpisujesz polecenie z ukośnikiem, a OpenSpec instaluje to, czego używa Twoje narzędzie.

Przebieg pracy

Od czego zacząć, jeśli nie jestem pewien, co zbudować?

Od /opsx:explore. To bez ryzyka partner do myślenia, który czyta Twoją bazę kodu, przedstawia opcje i zamienia mglisty problem w konkretny plan – zanim powstanie jakakolwiek zmiana czy kod. Znajduje się w domyślnym profilu, więc jest zawsze dostępny. Gdy plan jest jasny, przekazuje sterowanie do /opsx:propose. To najlepszy nawyk do wyrobienia, ponieważ powstrzymuje nadgorliwą AI przed pewnym zbudowaniem niewłaściwej rzeczy. Zobacz Najpierw eksploruj.

Jaki jest najprostszy możliwy przepływ?

/opsx:explore (opcjonalnie)   potem   /opsx:propose <co chcesz>   potem   /opsx:apply   potem   /opsx:archive

Eksploruj, aby przemyśleć pomysł, zaproponuj, aby naszkicować plan, zastosuj, aby zbudować, archiwizuj, aby odłożyć na później. Pomiń eksplorację, gdy już dokładnie wiesz, czego chcesz.

Jaka jest różnica między /opsx:propose a /opsx:new?

/opsx:propose to domyślne polecenie jednoetapowe: tworzy zmianę i od razu szkicuje wszystkie artefakty planowania. /opsx:new jest częścią rozszerzonego zestawu poleceń i tworzy jedynie szkielet pustej zmiany, pozostawiając tworzenie artefaktów pojedynczo za pomocą /opsx:continue (lub wszystkich naraz przez /opsx:ff). Używaj propose, chyba że chcesz kontroli krok po kroku. Zobacz Polecenia.

Czym są profile core i rozszerzony?

Profil decyduje o tym, które polecenia z ukośnikiem są instalowane. Core (domyślny) daje propose, explore, apply, update, sync, archive. Zestaw rozszerzony dodaje new, continue, ff, verify, bulk-archive i onboard, zapewniając większą kontrolę. Przełącz za pomocą openspec config profile, a następnie zastosuj przez openspec update.

Czy muszę uruchomić /opsx:sync?

Zwykle nie. Sync scala specyfikacje delta zmiany z głównymi specyfikacjami, a /opsx:archive zaproponuje wykonanie tego za Ciebie. Uruchom sync ręcznie tylko wtedy, gdy chcesz scalić specyfikacje przed archiwizacją, na przykład przy długotrwałej zmianie. Zobacz Polecenia.

Jak edytować propozycję, specyfikację lub zadanie po rozpoczęciu?

Po prostu edytuj plik. Każdy artefakt to zwykły Markdown w openspec/changes/<name>/ i nie ma zablokowanej fazy ani specjalnego trybu edycji. Zmień go ręcznie lub poproś AI, aby go poprawiła („zaktualizuj projekt, żeby używał kolejki”), a potem kontynuuj. AI zawsze pracuje na bieżącej zawartości plików. Pełny przewodnik: Edycja i iterowanie zmian.

Czy mogę wrócić i zmienić plan po wdrożeniu jego części?

Tak, w każdej chwili. Przepływ pracy jest płynny, więc przegląd i edycja nie są fazami, z których można zostać wykluczonym. Edytuj artefakt, a potem kontynuuj. Jeśli chcesz sprawdzić strukturalnie, czy kod nadal jest zgodny z planem, uruchom /opsx:verify. Zobacz Edycja i iterowanie zmian.

Ręcznie edytowałem kod. Jak go pogodzić ze specyfikacją?

Przywróć ich synchronizację przed archiwizacją, ponieważ archiwizacja czyni specyfikacje zapisem prawdy. Jeśli kod jest teraz poprawny, zaktualizuj specyfikację delta, aby odpowiadała temu, co dostarczyłeś; jeśli specyfikacja jest poprawna, kontynuuj budowanie, aż kod będzie z nią zgodny. /opsx:verify ujawnia niezgodności. Zobacz Edycja i iterowanie zmian.

Kiedy zaktualizować istniejącą zmianę, a kiedy zacząć nową?

Zaktualizuj, gdy to ta sama praca, tylko dopracowana. Zacznij od nowa, gdy cel zasadniczo się zmienił lub zakres rozrósł się w inną pracę. Schemat decyzyjny i przykłady znajdziesz w Przepływy pracy.

Co jeśli sesja straci kontekst lub wymagania zmienią się w trakcie implementacji?

Właśnie tutaj specyfikacje pokazują swoją wartość. Ponieważ plan istnieje w plikach (nie tylko w historii czatu), możesz wyczyścić kontekst, rozpocząć nową sesję AI i wznowić pracę za pomocą /opsx:apply – odczytuje ono artefakty i wznawia od pierwszego niezaznaczonego zadania. Jeśli wymagania się zmienią, edytuj artefakty, by odzwierciedlały nową rzeczywistość, i kontynuuj. Utrzymywanie czystego okna kontekstowego daje też lepsze rezultaty – wyczyść je przed implementacją.

Czy powinienem commitować folder openspec/ do git?

Tak. Twoje specyfikacje, aktywne zmiany i archiwum są częścią historii projektu. Commituj je jak każdy inny kod źródłowy. Archiwum szczególnie staje się trwałym zapisem tego, dlaczego Twój system działa tak, a nie inaczej.

Specyfikacje i zmiany

Co trafia do specyfikacji, a co do projektu?

Specyfikacja opisuje obserwowalne zachowanie: co robi system, jego dane wejściowe, wyjściowe i warunki błędów. Projekt opisuje, jak to zbudujesz: podejście techniczne, decyzje architektoniczne, zmiany w plikach. Jeśli implementacja może się zmienić bez zmiany widocznego na zewnątrz zachowania, należy to do projektu, nie do specyfikacji. Koncepcje omawiają to głębiej.

Czym jest specyfikacja delta?

Specyfikacja, która opisuje tylko to, co się zmienia, używając sekcji ADDED, MODIFIED i REMOVED, zamiast powtarzać całą specyfikację. To sposób, w jaki OpenSpec czysto obsługuje edycje istniejących systemów. Zobacz Koncepcje.

Gdzie trafiają zarchiwizowane zmiany?

Do openspec/changes/archive/YYYY-MM-DD-<name>/, gdzie zachowane są wszystkie artefakty zmiany. Zmiana znika z listy aktywnych. Zmiana, która jawnie deklaruje retire_capabilities: true, może również usunąć główną specyfikację zdolności, gdy pozbawia tę zdolność ostatniego wymagania.

Konfiguracja i dostosowywanie

Jak przekazać AI informacje o moim stosie technologicznym?

Umieść je w openspec/config.yaml pod kluczem context:. Ten tekst jest wstrzykiwany do każdego żądania planowania, więc AI zawsze zna Twój stos i konwencje. Zobacz Dostosowywanie.

Czy mogę generować specyfikacje w języku innym niż angielski?

Tak. Dodaj instrukcję językową do pola context: w konfiguracji. Wielojęzyczność zawiera gotowe fragmenty do skopiowania dla kilku języków.

Czy mogę zmienić sam przepływ pracy?

Tak, za pomocą niestandardowych schematów. Schemat definiuje, jakie artefakty istnieją i jak od siebie zależą. Skopiuj domyślny za pomocą openspec schema fork spec-driven my-workflow, a następnie edytuj go. Zobacz Dostosowywanie.

Modele, prywatność i aktualizacje

Którego modelu AI powinienem używać?

OpenSpec najlepiej działa z modelami o silnym rozumowaniu. README zaleca modele takie jak Codex 5.5 i Opus 4.7 zarówno do planowania, jak i implementacji. Dbaj też o czyste okno kontekstowe – wyczyść je przed implementacją, aby uzyskać najlepsze rezultaty.

Czy OpenSpec zbiera dane?

Zbiera anonimowe statystyki użytkowania: tylko nazwy poleceń i wersję. Bez argumentów, ścieżek, treści ani danych osobowych, a w CI jest automatycznie wyłączone. Możesz zrezygnować, ustawiając export OPENSPEC_TELEMETRY=0 lub export DO_NOT_TRACK=1.

Jak zaktualizować?

Dwa kroki. Zaktualizuj pakiet (npm install -g @fission-ai/openspec@latest), a następnie uruchom openspec update w każdym projekcie, aby odświeżyć wygenerowane umiejętności i polecenia.

Jak odinstalować OpenSpec?

Nie ma polecenia odinstalowania, ponieważ to tylko globalny pakiet plus pliki w Twoim projekcie. Usuń pakiet (npm uninstall -g @fission-ai/openspec) i opcjonalnie usuń katalog openspec/ oraz wygenerowane pliki narzędzi. Instrukcje krok po kroku, w tym co bezpiecznie zachować, znajdziesz w Instalacja: Odinstalowywanie.

Uzyskiwanie pomocy

Gdzie zadawać pytania lub zgłaszać błędy?

• Discord: discord.gg/YctCnvvshC
• Zgłoszenia GitHub: github.com/Fission-AI/OpenSpec/issues
• Z terminala: openspec feedback "twoja wiadomość" otwiera zgłoszenie na GitHubie.

Ta dokumentacja jest błędna lub myląca. Co robić?

Daj nam znać albo popraw. Pull requesty do dokumentacji są mile widziane i doceniane. Otwórz zgłoszenie lub wyślij pull request.