OpenSpec

Słownik pojęć ​

Każde pojęcie OpenSpec w jednym miejscu, zdefiniowane prostym językiem. Przeczytaj go raz, a reszta dokumentacji będzie czytać się szybciej.

Pojęcia są pogrupowane tematycznie, a wewnątrz każdej grupy ułożone alfabetycznie.

Główne rzeczowniki ​

Spec. Dokument opisujący, jak zachowuje się część Twojego systemu. Specyfikacje znajdują się w openspec/specs/, są organizowane według domen i składają się z wymagań oraz scenariuszy. Specyfikacja to uzgodniona odpowiedź na pytanie „co robi ten program?". Zobacz Pojęcia.

Źródło prawdy. Katalog openspec/specs/ jako całość. Zawiera aktualne, uzgodnione zachowanie Twojego systemu. Zmiany proponują edycje; archiwizacja je stosuje.

Zmiana. Jedna jednostka pracy, zapakowana jako folder pod openspec/changes/<name>/. Zmiana zawiera wszystko dotyczące danej pracy: jej propozycję, projekt, zadania oraz wprowadzane edycje specyfikacji. Jedna zmiana, jedna funkcja lub poprawka.

Artefakt. Dokument wewnątrz zmiany. Standardowe artefakty to propozycja, specyfikacje delta, projekt i zadania. Są tworzone w kolejności zależności i wpływają na siebie nawzajem.

Specyfikacja delta. Specyfikacja wewnątrz zmiany, która opisuje wyłącznie to, co się zmienia, używając sekcji ADDED, MODIFIED i REMOVED, zamiast ponownie opisywać całą specyfikację. Dzięki temu OpenSpec może czysto edytować istniejące systemy. Zobacz Pojęcia.

Domena. Logiczna grupa specyfikacji, np. auth/, payments/ lub ui/. Wybierasz domeny tak, aby odpowiadały sposobowi, w jaki myślisz o swoim systemie.

Wewnątrz specyfikacji ​

Wymaganie. Pojedyncze zachowanie, które system musi mieć, zwykle zapisane z użyciem słowa kluczowego z RFC 2119: „System SHALL wygasać sesje po 30 minutach." Wymagania określają co, nie jak.

Scenariusz. Konkretny, testowalny przykład działania wymagania, zwykle w formie Given/When/Then. Scenariusze czynią wymaganie weryfikowalnym: na jego podstawie można napisać test automatyczny.

Słowa kluczowe RFC 2119. Słowa MUST, SHALL, SHOULD i MAY, które mają ustandaryzowane znaczenie dotyczące rygoru wymagania. MUST i SHALL są bezwzględne. SHOULD jest zalecane z możliwością wyjątków. MAY jest opcjonalne. Nazwa pochodzi od dokumentu standardów internetowych, który je zdefiniował.

Artefakty ​

Propozycja (proposal.md). Dlaczego i co danej zmiany: jej intencja, zakres i ogólne podejście. Pierwszy artefakt, który tworzysz.

Projekt (design.md). Jak: podejście techniczne, decyzje architektoniczne i pliki, które zamierzasz zmienić. Opcjonalny dla prostych zmian.

Zadania (tasks.md). Lista kontrolna implementacji z polami wyboru. AI przechodzi przez nią podczas /opsx:apply i odhacza elementy w miarę postępów.

Cykl życia ​

Archiwizacja. Działanie kończące zmianę. Jej specyfikacje delta są scalane z głównymi specyfikacjami, a folder zmiany przenoszony jest do openspec/changes/archive/YYYY-MM-DD-<name>/. Po archiwizacji Twoje specyfikacje opisują nową rzeczywistość. Zobacz Pojęcia.

Synchronizacja. Scalanie specyfikacji delta zmiany z głównymi specyfikacjami bez archiwizacji zmiany. Zwykle automatyczna (archiwizacja oferuje to zrobić), ale dostępna samodzielnie jako /opsx:sync dla długotrwałych zmian. Zobacz Polecenia.

Praca i polecenia ​

OPSX. Aktualny standardowy przepływ pracy OpenSpec, oparty na płynnych działaniach zamiast sztywnych faz. Wszystkie jego polecenia z ukośnikiem zaczynają się od /opsx:. Zobacz Przepływ pracy OPSX.

Polecenie z ukośnikiem. Polecenie, które wpisujesz w czacie swojego asystenta AI, np. /opsx:propose. Polecenia z ukośnikiem napędzają przepływ pracy. Nie są to polecenia terminala. Zobacz Jak działają polecenia.

Eksploracja (/opsx:explore). Polecenie partnera do myślenia. Czyta Twoją bazę kodu, porównuje opcje i doprecyzowuje niejasny pomysł w konkretny plan, nie tworząc żadnych artefaktów ani nie pisząc kodu. Zalecany punkt startowy, gdy masz problem, ale jeszcze nie masz planu. Zobacz Najpierw eksploruj.

CLI. Program openspec, który uruchamiasz w terminalu. Konfiguruje projekty, wypisuje i waliduje zmiany, otwiera panel i archiwizuje. Terminalowa strona OpenSpec. Zobacz CLI.

Umiejętność. Folder instrukcji (.../skills/openspec-*/SKILL.md), który Twój asystent AI automatycznie wykrywa i stosuje. Umiejętności to rozwijający się standard między narzędziami dla dostarczania przepływu pracy OpenSpec do asystenta.

Plik poleceń. Plik poleceń z ukośnikiem dla danego narzędzia (.../commands/opsx-*). Starszy mechanizm dostarczania, wciąż wspierany obok umiejętności. Rzadko masz z nimi bezpośredni kontakt.

Profil. Zestaw poleceń z ukośnikiem zainstalowanych w Twoim projekcie. Core (domyślny) to propose, explore, apply, update, sync, archive. Rozszerzony zestaw dodaje new, continue, ff, verify, bulk-archive, onboard. Zmień go za pomocą openspec config profile.

Dostawa. Czy OpenSpec instaluje umiejętności, pliki poleceń, czy oba dla Twoich narzędzi. Konfigurowane globalnie i stosowane za pomocą openspec update.

Dostosowywanie ​

Schemat. Definicja, jakie artefakty ma dany przepływ pracy i jak zależą od siebie. Domyślny wbudowany schemat to spec-driven (propozycja → specyfikacje → projekt → zadania). Możesz go rozgałęzić lub napisać własny. Zobacz Dostosowywanie.

Szablon. Plik Markdown wewnątrz schematu, który kształtuje to, co AI generuje dla danego artefaktu. Edycja szablonu natychmiast zmienia wynik AI, bez ponownej kompilacji.

Konfiguracja projektu (openspec/config.yaml). Ustawienia na poziomie projektu: domyślny schemat, pole context: wstrzykiwane do każdego żądania planowania oraz reguły rules: dla poszczególnych artefaktów. Najłatwiejszy sposób, aby nauczyć OpenSpec o Twoim stacku i konwencjach. Zobacz Dostosowywanie.

Iniekcja kontekstu. Wstawienie tła projektu w pole context: pliku config.yaml, aby było automatycznie dodawane do każdego artefaktu generowanego przez AI. Bardziej niezawodne niż liczenie na to, że AI przeczyta osobny plik.

Graf zależności. Skierowany graf utworzony przez relacje requires: artefaktów. Jest to DAG (skierowany graf bezcykliczny: strzałki wskazują tylko do przodu, nigdy w pętlę), a OpenSpec używa go, aby wiedzieć, co możesz utworzyć jako następne.

Umożliwiacze, nie bramki. Zasada, że zależności artefaktów pokazują, co staje się możliwe jako następne, a nie co jest wymagane jako następne. Możesz wrócić i edytować dowolny artefakt w dowolnym momencie. Zobacz Pojęcia w pigułce.

Współpraca między repozytoriami (beta) ​

Te pojęcia dotyczą wyłącznie sytuacji, gdy Twoje planowanie obejmuje więcej niż jedno repozytorium. Są w wersji beta. Większość użytkowników może je zignorować. Zobacz Przewodnik po magazynach.

Magazyn. Samodzielne repozytorium, którego jedynym zadaniem jest planowanie. Ma ten sam kształt openspec/, który już znasz (specyfikacje i zmiany), plus mały plik tożsamości. Rejestrujesz go na swoim komputerze raz, według nazwy, a następnie dowolne polecenie OpenSpec może w nim działać z dowolnego miejsca.

Referencja. Deklaracja w pliku openspec/config.yaml repozytorium kodu, wskazująca na magazyn, z którego dane repozytorium korzysta. Referencje są tylko do odczytu: repozytorium zachowuje własny korzeń, a openspec instructions zyskuje indeks specyfikacji referencjonowanego magazynu, każdy z dokładnym poleceniem do pobrania.

Kontekst roboczy. To, co openspec context zbiera dla bieżącego repozytorium: jego korzeń OpenSpec plus każdy referencjonowany magazyn, każdy z instrukcją pobierania. Odpowiedź na pytanie „z czym pracuję?".

Zestaw roboczy. Osobisty, lokalny zestaw folderów, które otwierasz razem (magazyn obok repozytoriów kodu, z którymi pracujesz). Tworzony jawnie za pomocą openspec workset create; nic o tych lokalnych ścieżkach nie jest commitowane do wspólnego repozytorium planowania.

Zobacz także ​