Skip to content

Koncepcje ​

Ten przewodnik wyjaśnia podstawowe idee stojące za OpenSpec i jak się one ze sobą łączą. Aby zapoznać się z praktycznym użyciem, zobacz Getting Started i Workflows.

Filozofia ​

OpenSpec jest zbudowany wokół czterech zasad:

elastyczne, nie sztywne   — bez bramek fazowych, pracuj nad tym, co ma sens
iteracyjne, nie kaskadowe — ucz się podczas budowania, udoskonalaj w miarę postępu
łatwe, nie złożone        — lekka konfiguracja, minimalna formalność
brownfield-first          — działa z istniejącymi bazami kodu, nie tylko z nowymi projektami

Dlaczego te zasady mają znaczenie ​

Elastyczne, nie sztywne. Tradycyjne systemy specyfikacji zamykają cię w fazach: najpierw planujesz, potem implementujesz, a potem koniec. OpenSpec jest bardziej elastyczny — możesz tworzyć artefakty w dowolnej kolejności, która ma sens dla twojej pracy.

Iteracyjne, nie kaskadowe. Wymagania się zmieniają. Zrozumienie się pogłębia. To, co na początku wydawało się dobrym podejściem, może nie przetrwać po zobaczeniu bazy kodu. OpenSpec akceptuje tę rzeczywistość.

Łatwe, nie złożone. Niektóre frameworki specyfikacji wymagają rozbudowanej konfiguracji, sztywnych formatów lub ciężkich procesów. OpenSpec nie przeszkadza ci. Zainicjalizuj w kilka sekund, zacznij pracę natychmiast, dostosuj tylko w razie potrzeby.

Brownfield-first. Większość pracy nad oprogramowaniem to nie budowanie od zera — to modyfikowanie istniejących systemów. Oparte na deltach podejście OpenSpec ułatwia specyfikowanie zmian w istniejącym zachowaniu, a nie tylko opisywanie nowych systemów.

Ogólny obraz ​

OpenSpec organizuje Twoją pracę w dwóch głównych obszarach:

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  Źródło prawdy      │◄─────│  Proponowane modyfikacje      │   │
│   │  Jak system obecnie │scalanie│  Każda zmiana = jeden folder   │   │
│   │  działa             │      │  Zawiera artefakty + delty    │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Specyfikacje są źródłem prawdy — opisują, jak system zachowuje się obecnie.

Zmiany to proponowane modyfikacje — żyją w osobnych folderach do momentu, gdy jesteś gotów je scalić.

To rozdzielenie jest kluczowe. Możesz pracować nad wieloma zmianami równolegle, bez konfliktów. Możesz przejrzeć zmianę, zanim wpłynie ona na główne specyfikacje. A kiedy archiwizujesz zmianę, jej delty są czysto scalane ze źródłem prawdy.

Specyfikacje ​

Specyfikacje opisują zachowanie systemu za pomocą ustrukturyzowanych wymagań i scenariuszy.

Struktura ​

openspec/specs/
├── auth/
│   └── spec.md           # Zachowanie uwierzytelniania
├── payments/
│   └── spec.md           # Przetwarzanie płatności
├── notifications/
│   └── spec.md           # System powiadomień
└── ui/
    └── spec.md           # Zachowanie UI i motywy

Organizuj specyfikacje według domen — logicznych grup, które mają sens dla Twojego systemu. Typowe wzorce:

  • Według obszaru funkcjonalnego: auth/, payments/, search/
  • Według komponentu: api/, frontend/, workers/
  • Według ograniczonego kontekstu: ordering/, fulfillment/, inventory/

Format specyfikacji ​

Specyfikacja zawiera wymagania, a każde wymaganie ma scenariusze:

markdown
# Specyfikacja Auth

## Cel
Uwierzytelnianie i zarządzanie sesjami dla aplikacji.

## Wymagania

### Wymaganie: Uwierzytelnianie użytkownika
System SHALL wydać token JWT po pomyślnym zalogowaniu.

#### Scenariusz: Prawidłowe dane logowania
- ZAKŁADAJĄC użytkownika z prawidłowymi danymi logowania
- KIEDY użytkownik wysyła formularz logowania
- WTEDY zwracany jest token JWT
- ORAZ użytkownik jest przekierowywany do dashboardu

#### Scenariusz: Nieprawidłowe dane logowania
- ZAKŁADAJĄC nieprawidłowe dane logowania
- KIEDY użytkownik wysyła formularz logowania
- WTEDY wyświetlany jest komunikat błędu
- ORAZ token nie jest wydawany

### Wymaganie: Wygaśnięcie sesji
System MUST wygasać sesje po 30 minutach bezczynności.

#### Scenariusz: Limit czasu bezczynności
- ZAKŁADAJĄC uwierzytelnioną sesję
- KIEDY minie 30 minut bez aktywności
- WTEDY sesja jest unieważniana
- ORAZ użytkownik musi ponownie się uwierzytelnić

Kluczowe elementy:

ElementCel
## CelOgólny opis domeny tej specyfikacji
### Wymaganie:Konkretne zachowanie, które system musi posiadać
#### Scenariusz:Konkretny przykład działania wymagania
SHALL/MUST/SHOULDSłowa kluczowe RFC 2119 określające siłę wymagania

Dlaczego specyfikacje są tak zorganizowane ​

Wymagania to „co” — określają, co system powinien robić, nie definiując implementacji.

Scenariusze to „kiedy” — dostarczają konkretne przykłady, które można zweryfikować. Dobre scenariusze:

  • Są testowalne (można dla nich napisać automatyczny test)
  • Obejmują zarówno ścieżkę szczęśliwą, jak i przypadki brzegowe
  • Używają formatu Zakładając/Kiedy/Wtedy lub podobnego

Słowa kluczowe RFC 2119 (SHALL, MUST, SHOULD, MAY) komunikują intencję:

  • MUST/SHALL — wymaganie bezwzględne
  • SHOULD — zalecane, ale istnieją wyjątki
  • MAY — opcjonalne

Czym specyfikacja jest (a czym nie jest) ​

Specyfikacja to kontrakt zachowania, a nie plan implementacji.

Dobra zawartość specyfikacji:

  • Obserwowalne zachowania, na których polegają użytkownicy lub systemy downstream
  • Dane wejściowe, wyjściowe i warunki błędów
  • Zewnętrzne ograniczenia (bezpieczeństwo, prywatność, niezawodność, kompatybilność)
  • Scenariusze, które można przetestować lub jawnie zweryfikować

Unikaj w specyfikacjach:

  • Wewnętrznych nazw klas/funkcji
  • Wyboru bibliotek lub frameworków
  • Krok po kroku szczegółów implementacji
  • Szczegółowych planów wykonawczych (te należą do design.md lub tasks.md)

Szybki test:

  • Jeśli implementacja może się zmienić bez zmiany zewnętrznie widocznego zachowania, prawdopodobnie nie należy do specyfikacji.

Zachowaj lekkość: Stopniowa rygorystyczność ​

OpenSpec dąży do unikania biurokracji. Używaj najlżejszego poziomu, który wciąż czyni zmianę weryfikowalną.

Lekka specyfikacja (domyślna):

  • Krótkie wymagania skoncentrowane na zachowaniu
  • Wyraźny zakres i cele nieobjęte
  • Kilka konkretnych testów akceptacyjnych

Pełna specyfikacja (dla wyższego ryzyka):

  • Zmiany międzyzespołowe lub międzyrepozytoryjne
  • Zmiany API/kontraktów, migracje, kwestie bezpieczeństwa/prywatności
  • Zmiany, gdzie niejednoznaczność może spowodować kosztowne przeróbki

Większość zmian powinna pozostać w trybie lekkim.

Współpraca człowieka i agenta ​

W wielu zespołach ludzie eksplorują, a agenci tworzą szkice artefaktów. Docelowy obieg wygląda tak:

  1. Człowiek dostarcza intencję, kontekst i ograniczenia.
  2. Agent przekształca to w wymagania i scenariusze zorientowane na zachowanie.
  3. Agent trzyma szczegóły implementacji w design.md i tasks.md, a nie w spec.md.
  4. Walidacja potwierdza strukturę i jasność przed implementacją.

Dzięki temu specyfikacje pozostają czytelne dla ludzi i spójne dla agentów.

Zmiany ​

Zmiana to proponowana modyfikacja systemu, spakowana jako folder zawierający wszystko, co potrzebne do jej zrozumienia i implementacji.

Struktura zmiany ​

openspec/changes/add-dark-mode/
├── proposal.md           # Dlaczego i co
├── design.md             # Jak (podejście techniczne)
├── tasks.md              # Lista kontrolna implementacji
├── .openspec.yaml        # Metadane zmiany (opcjonalne): schema, created, skip_specs, retire_capabilities
└── specs/                # Specyfikacje delta
    └── ui/
        └── spec.md       # Co się zmienia w ui/spec.md

Każda zmiana jest samodzielna. Zawiera:

  • Artefakty — dokumenty ujmujące intencję, projekt i zadania
  • Specyfikacje delta — specyfikacje tego, co jest dodawane, modyfikowane lub usuwane
  • Metadane — opcjonalna konfiguracja dla tej konkretnej zmiany

Dlaczego zmiany są folderami ​

Pakowanie zmiany jako folderu ma kilka zalet:

  1. Wszystko razem. Propozycja, projekt, zadania i specyfikacje znajdują się w jednym miejscu. Nie trzeba szukać po różnych lokalizacjach.

  2. Praca równoległa. Wiele zmian może istnieć jednocześnie bez konfliktów. Pracuj nad add-dark-mode, podczas gdy fix-auth-bug jest również w toku.

  3. Czysta historia. Po zarchiwizowaniu zmiany przenoszone są do changes/archive/ z zachowaniem pełnego kontekstu. Możesz spojrzeć wstecz i zrozumieć nie tylko co się zmieniło, ale także dlaczego.

  4. Przyjazne dla recenzji. Folder zmiany jest łatwy do przejrzenia — otwórz go, przeczytaj propozycję, sprawdź projekt, zobacz specyfikacje delta.

Artefakty ​

Artefakty to dokumenty wewnątrz zmiany, które kierują pracą.

Przepływ artefaktów ​

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
  dlaczego       co się       jak           kroki
 + zakres       zmienia     podejście      do podjęcia

Artefakty budują na sobie. Każdy artefakt dostarcza kontekst dla następnego.

Typy artefaktów ​

Propozycja (proposal.md) ​

Propozycja ujmuje intencję, zakres i podejście na wysokim poziomie.

markdown
# Propozycja: Dodanie trybu ciemnego

## Cel
Użytkownicy zażądali opcji trybu ciemnego, aby zmniejszyć zmęczenie oczu
podczas użytkowania w nocy i dopasować do preferencji systemowych.

## Zakres
W zakresie:
– Przełącznik motywu w ustawieniach
– Wykrywanie preferencji systemowych
– Utrwalanie preferencji w localStorage

Poza zakresem:
– Niestandardowe motywy kolorystyczne (prace przyszłe)
– Nadpisywanie motywu na stronie

## Podejście
Wykorzystanie niestandardowych właściwości CSS do stylizacji z kontekstem React
do zarządzania stanem. Wykrywanie preferencji systemowych przy pierwszym ładowaniu,
umożliwienie ręcznego nadpisania.

Kiedy zaktualizować propozycję:

  • Zmiany zakresu (zawężanie lub rozszerzanie)
  • Cel się wyjaśnia (lepsze zrozumienie problemu)
  • Podejście fundamentalnie się zmienia

Specyfikacje (specyfikacje delta w specs/) ​

Specyfikacje delta opisują co się zmienia względem obecnych specyfikacji. Zobacz Specyfikacje delta poniżej.

Projekt (design.md) ​

Projekt ujmuje podejście techniczne i decyzje architektoniczne.

markdown
# Projekt: Dodanie trybu ciemnego

## Podejście techniczne
Stan motywu zarządzany przez React Context, aby uniknąć przekazywania propsów.
Niestandardowe właściwości CSS umożliwiają przełączanie w czasie wykonywania bez przełączania klas.

## Decyzje architektoniczne

### Decyzja: Context zamiast Redux
Użycie React Context dla stanu motywu, ponieważ:
– Prosty stan binarny (jasny/ciemny)
– Brak złożonych przejść stanu
– Unika dodawania zależności Redux

### Decyzja: Niestandardowe właściwości CSS
Użycie zmiennych CSS zamiast CSS-in-JS, ponieważ:
– Działa z istniejącym arkuszem stylów
– Brak narzutu w czasie wykonywania
– Natywna dla przeglądarki

## Przepływ danych
```
ThemeProvider (kontekst)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
Zmienne CSS (zastosowane do :root)
```

## Zmiany plików
- `src/contexts/ThemeContext.tsx` (nowy)
- `src/components/ThemeToggle.tsx` (nowy)
- `src/styles/globals.css` (zmodyfikowany)

Kiedy zaktualizować projekt:

  • Implementacja ujawnia, że podejście nie zadziała
  • Odkryto lepsze rozwiązanie
  • Zmieniają się zależności lub ograniczenia

Zadania (tasks.md) ​

Zadania to lista kontrolna implementacji — konkretne kroki z polami wyboru.

markdown
# Zadania

## 1. Infrastruktura motywu
- [ ] 1.1 Utwórz ThemeContext ze stanem jasny/ciemny
- [ ] 1.2 Dodaj niestandardowe właściwości CSS dla kolorów
- [ ] 1.3 Zaimplementuj utrwalanie w localStorage
- [ ] 1.4 Dodaj wykrywanie preferencji systemowych

## 2. Komponenty UI
- [ ] 2.1 Utwórz komponent ThemeToggle
- [ ] 2.2 Dodaj przełącznik na stronę ustawień
- [ ] 2.3 Zaktualizuj nagłówek o szybki przełącznik

## 3. Stylizacja
- [ ] 3.1 Zdefiniuj paletę kolorów ciemnego motywu
- [ ] 3.2 Zaktualizuj komponenty, aby używały zmiennych CSS
- [ ] 3.3 Przetestuj współczynniki kontrastu pod kątem dostępności

Dobre praktyki dotyczące zadań:

  • Grupuj powiązane zadania pod nagłówkami
  • Używaj numeracji hierarchicznej (1.1, 1.2, itd.)
  • Utrzymuj zadania na tyle małe, aby można je było ukończyć w jednej sesji
  • Zaznaczaj zadania jako ukończone w miarę ich realizacji

Specyfikacje delta ​

Specyfikacje delta są kluczową koncepcją, która sprawia, że OpenSpec działa w rozwoju systemów istniejących (brownfield). Opisują one co się zmienia, zamiast ponownie opisywać całą specyfikację.

Format ​

markdown
# Delta dla Auth

## DODANE Wymagania

### Wymaganie: Uwierzytelnianie dwuskładnikowe
System MUST obsługiwać uwierzytelnianie dwuskładnikowe oparte na TOTP.

#### Scenariusz: Rejestracja 2FA
- ZAKŁADAJĄC użytkownika bez włączonego 2FA
- KIEDY użytkownik włącza 2FA w ustawieniach
- WTEDY wyświetlany jest kod QR do konfiguracji aplikacji autoryzującej
- ORAZ użytkownik musi zweryfikować kodem przed aktywacją

#### Scenariusz: Logowanie z 2FA
- ZAKŁADAJĄC użytkownika z włączonym 2FA
- KIEDY użytkownik przesyła prawidłowe dane logowania
- WTEDY prezentowane jest wyzwanie OTP
- ORAZ logowanie kończy się dopiero po podaniu prawidłowego OTP

## ZMODYFIKOWANE Wymagania

### Wymaganie: Wygaśnięcie sesji
System MUST wygasać sesje po 15 minutach bezczynności.
(Poprzednio: 30 minut)

#### Scenariusz: Limit czasu bezczynności
- ZAKŁADAJĄC uwierzytelnioną sesję
- KIEDY minie 15 minut bez aktywności
- WTEDY sesja jest unieważniana

## USUNIĘTE Wymagania

### Wymaganie: Zapamiętaj mnie
(Zdeprecjonowane na rzecz 2FA. Użytkownicy powinni ponownie się uwierzytelniać przy każdej sesji.)

Sekcje delty ​

SekcjaZnaczenieCo się dzieje podczas archiwizacji
## DODANE WymaganiaNowe zachowanieDodawane do głównej specyfikacji
## ZMODYFIKOWANE WymaganiaZmienione zachowanieZastępuje istniejące wymaganie
## USUNIĘTE WymaganiaZdeprecjonowane zachowanieUsuwane z głównej specyfikacji; usunięcie ostatniego wymagania wyłącza zdolność i usuwa jej plik specyfikacji, gdy zmiana deklaruje retire_capabilities: true
## CelDo czego służy zupełnie nowa zdolnośćInicjuje Cel głównej specyfikacji, która jest tworzona; ignorowane, gdy specyfikacja już istnieje

Dlaczego używać delt zamiast pełnych specyfikacji ​

Jasność. Delta pokazuje dokładnie, co się zmienia. Czytając pełną specyfikację, musiałbyś mentalnie porównać ją z aktualną wersją.

Unikanie konfliktów. Dwie zmiany mogą dotyczyć tego samego pliku specyfikacji bez konfliktu, o ile modyfikują różne wymagania.

Efektywność przeglądu. Recenzenci widzą zmianę, a nie niezmieniony kontekst. Skup się na tym, co istotne.

Dopasowanie do brownfield. Większość pracy modyfikuje istniejące zachowanie. Deltas czynią modyfikacje pierwszorzędnymi, a nie dodatkiem.

Schematy ​

Schematy definiują typy artefaktów i ich zależności dla przepływu pracy.

Jak działają schematy ​

yaml
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # No dependencies, can create first

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # Needs proposal before creating

  - id: design
    generates: design.md
    requires: [proposal]      # Can create in parallel with specs

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # Needs both specs and design first

Artefakty tworzą graf zależności:

                    proposal
                   (root node)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (requires:                  (requires:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (requires:
                specs, design)

Zależności to umożliwienia, nie bramki. Pokazują, co można stworzyć, a nie co musisz stworzyć jako następne. Możesz pominąć projekt, jeśli go nie potrzebujesz. Możesz tworzyć specyfikacje przed projektem lub po nim — obie zależą tylko od propozycji.

Wbudowane schematy ​

spec-driven (domyślny)

Standardowy przepływ pracy dla rozwoju sterowanego specyfikacjami:

proposal → specs → design → tasks → implement

Najlepszy dla: Większości prac nad funkcjami, gdzie chcesz uzgodnić specyfikacje przed implementacją.

Własne schematy ​

Twórz własne schematy dla przepływu pracy swojego zespołu:

bash
# Create from scratch
openspec schema init research-first

# Or fork an existing one
openspec schema fork spec-driven research-first

Przykładowy własny schemat:

yaml
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # Do research first

  - id: proposal
    generates: proposal.md
    requires: [research]   # Proposal informed by research

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # Skip specs/design, go straight to tasks

Zobacz Dostosowywanie aby uzyskać pełne szczegóły dotyczące tworzenia i używania własnych schematów.

Archiwizacja ​

Archiwizacja kończy zmiany, scalając ich specyfikacje delta ze specyfikacjami głównymi i zachowując zmianę dla historii.

Co się dzieje, gdy archiwizujesz ​

Before archive:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ merge
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


After archive:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # Now includes 2FA requirements
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # Preserved for history
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

Proces archiwizacji ​

  1. Scalenie delt. Każda sekcja specyfikacji delta (DODANE/ZMODYFIKOWANE/USUNIĘTE) jest stosowana do odpowiedniej specyfikacji głównej.

  2. Przeniesienie do archiwum. Folder zmiany przenosi się do changes/archive/ z prefiksem daty dla chronologicznego porządkowania.

  3. Zachowanie kontekstu. Wszystkie artefakty pozostają nienaruszone w archiwum. Zawsze możesz spojrzeć wstecz, aby zrozumieć, dlaczego dokonano zmiany.

Dlaczego archiwizacja jest ważna ​

Czysty stan. Aktywne zmiany (changes/) pokazują tylko pracę w toku. Ukończona praca znika z drogi.

Ślad audytowy. Archiwum zachowuje pełny kontekst każdej zmiany — nie tylko to, co się zmieniło, ale także propozycję wyjaśniającą dlaczego, projekt wyjaśniający jak oraz zadania pokazujące wykonaną pracę.

Ewolucja specyfikacji. Specyfikacje rozwijają się organicznie wraz z archiwizacją zmian. Każda archiwizacja scala swoje delty, budując z czasem kompletną specyfikację.

Jak to wszystko się składa ​

┌──────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC FLOW                                   │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
│   │     CHANGE     │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
│   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
│   │                │  (based on schema dependencies)                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. IMPLEMENT  │  /opsx:apply                                            │
│   │     TASKS      │  Work through tasks, checking them off                  │
│   │                │◄──── Update artifacts as you learn                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. VERIFY     │  /opsx:verify (optional)                                │
│   │     WORK       │  Check implementation matches specs                     │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │    │
│   │     CHANGE     │     │  Change folder moves to archive/             │    │
│   └────────────────┘     │  Specs are now the updated source of truth   │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Cnotliwy cykl:

  1. Specyfikacje opisują obecne zachowanie
  2. Zmiany proponują modyfikacje (jako delty)
  3. Implementacja czyni zmiany rzeczywistymi
  4. Archiwizacja scala delty ze specyfikacjami
  5. Specyfikacje opisują teraz nowe zachowanie
  6. Następna zmiana opiera się na zaktualizowanych specyfikacjach

Słowniczek ​

TerminDefinicja
ArtefaktDokument w ramach zmiany (propozycja, projekt, zadania lub specyfikacje delta)
ArchiwizacjaProces kończenia zmiany i scalania jej delt ze specyfikacjami głównymi
ZmianaProponowana modyfikacja systemu, zapakowana jako folder z artefaktami
Specyfikacja deltaSpecyfikacja opisująca zmiany (DODANE/ZMODYFIKOWANE/USUNIĘTE) względem aktualnych specyfikacji
DomenaLogiczne grupowanie specyfikacji (np. auth/, payments/)
WymaganieKonkretne zachowanie, które system musi mieć
ScenariuszKonkretny przykład wymagania, zazwyczaj w formacie Given/When/Then
SchematDefinicja typów artefaktów i ich zależności
SpecyfikacjaSpecyfikacja opisująca zachowanie systemu, zawierająca wymagania i scenariusze
Źródło prawdyKatalog openspec/specs/, zawierający aktualne uzgodnione zachowanie

Następne kroki ​