Dostosowywanie

OpenSpec oferuje trzy poziomy dostosowywania:

Poziom	Funkcja	Najlepszy dla
Konfiguracja projektu	Ustawianie wartości domyślnych, wstrzykiwanie kontekstu/zasad	Większość zespołów
Niestandardowe schematy	Definiowanie własnych artefaktów przepływu pracy	Zespoły z unikalnymi procesami
Globalne nadpisanie	Udostępnianie schematów między wszystkimi projektami	Zaawansowani użytkownicy

---

Konfiguracja projektu

Plik openspec/config.yaml to najprostszy sposób dostosowania OpenSpec do potrzeb zespołu. Pozwala na:

• Ustawienie schematu domyślnego – Pomijanie --schema przy każdym poleceniu
• Wstrzyknięcie kontekstu projektu – AI widzi Twój stos technologiczny, konwencje itp.
• Dodanie zasad dla poszczególnych artefaktów – Niestandardowe zasady dla konkretnych artefaktów
• Dodanie wytycznych dla poszczególnych operacji – Doradcze preferencje dla operacji apply i archive
• Zapamiętanie wyborów integracyjnych – np. opt-in do GitHub Copilot cloud coding agent

Szybkie uruchomienie

openspec init

Polecenie to przeprowadza Cię krok po kroku przez interaktywne tworzenie konfiguracji. Możesz też utworzyć ją ręcznie:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

Jak to działa

Schemat domyślny:

# Bez konfiguracji
openspec new change my-feature --schema spec-driven

# Z konfiguracją – schemat jest automatyczny
openspec new change my-feature

Wstrzykiwanie kontekstu i zasad:

Podczas generowania dowolnego artefaktu Twój kontekst i zasady są wstrzykiwane do promptu AI:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• Kontekst pojawia się we WSZYSTKICH artefaktach
• Zasady pojawiają się TYLKO dla odpowiadającego artefaktu

Wytyczne operacyjne:

operations.apply.guidance i operations.archive.guidance to opcjonalne tablice instrukcji doradczych dotyczących sposobu przeprowadzania tych operacji przez agenta. Są one odrębne od rules: wytyczne operacyjne nie ograniczają treści artefaktów, a zasady artefaktów nigdy nie są przeklasyfikowane jako wytyczne operacyjne.

Operacje apply i archive pobierają te dane wejściowe w czasie wykonania:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Oba interfejsy zwracają bieżący kontekst projektu oraz odpowiadające operationGuidance jako osobne opcjonalne pola. Każde wywołanie odczytuje świeży snapshot z rozwiązanej ścieżki korzeniowej. Gdy wybrano --store <id>, zmiana, kontekst i wytyczne pochodzą z tego magazynu, a nie z bieżącego repozytorium. Polecenie instrukcji archive jest tylko do odczytu: nie inspekcjonuje ani nie scalają specyfikacji delta, nie zapisuje głównych specyfikacji, nie przenosi zmiany ani nie uruchamia statycznego przepływu archiwizacji.

Kontekst projektu to wymagane dane wejściowe na poziomie promptu. Generowane przepływy pracy odczytują go i stosują odpowiednie fakty, konwencje i ograniczenia projektu. Wytyczne operacyjne to opcjonalna dodatkowa rada: przepływy pracy rozważają każdy wpis i stosują wpisy, które są stosowne i zgodne z wbudowanym przepływem pracy.

Oba pola pozostają odrębne od stanu kontrolowanego przez CLI, rozwiązanych ścieżek, wbudowanych kroków, jawnych wyborów użytkownika i zasad artefaktów. Przepływ pracy zgłasza konflikty kontekstu, zachowując kontrolowaną wartość. Nie stosuje nieistotnych ani konfliktujących wytycznych i wyjaśnia dlaczego. Żadne z pól nie jest wymagalnym sprawdzeniem, a przepływy pracy nie kopiują ich treści do plików implementacji, specyfikacji, artefaktów zmian ani podsumowań, chyba że użytkownik osobno o to poprosi.

Bezpieczeństwo danych wejściowych archiwizacji i synchronizacji specyfikacji:

Archiwizacja, masowa archiwizacja i samodzielna synchronizacja używają artifactPaths.specs.existingOutputPaths z openspec status --json jako jedynej źródła specyfikacji delta. Schemat bez artefaktu specs lub zmiana, której konkretna lista wyjściowa jest pusta, nie ma niczego do zsynchronizowania; inne artefakty nie są używane do wnioskowania o specyfikacjach delta.

Przed semantycznym scaleniem zapisującym główną specyfikację, przepływ pracy zużywa bieżące dane wyjściowe openspec instructions specs --change <name> --json. Zwrócone zasady specs ograniczają wyłącznie główne specyfikacje wytworzone przez to scalenie. Pojedyncza archiwizacja przekazuje ten snapshot do synchronizacji inline, samodzielna synchronizacja pobiera go bezpośrednio, a masowa archiwizacja uzyskuje wszystkie wymagane snapshoty przed pierwszym zapisem specyfikacji. Niezerowy lub nieprawidłowy odpowiedź JSON instrukcji archiwizacji/specyfikacji to błąd wyszukiwania, a nie puste dane wejściowe: przepływ pracy zatrzymuje się przed dotkniętym zapisem specyfikacji lub przeniesieniem zmiany (w przypadku masowej archiwizacji, przed jakimkolwiek zapisem lub przeniesieniem partii).

Ta konfiguracja nie zmienia faz wykonania archiwizacji, promptów użytkownika, operacji na systemie plików, własności semantycznego scalenia, bezpośredniego polecenia openspec archive ani struktury i danych wyjściowych zasad rules artefaktów.

Kolejność rozwiązywania schematu

Gdy OpenSpec potrzebuje schematu, sprawdza go w tej kolejności:

1. Flaga CLI: --schema <name>
2. Metadane zmiany (.openspec.yaml w folderze zmiany)
3. Konfiguracja projektu (openspec/config.yaml)
4. Domyślny (spec-driven)

---

Niestandardowe schematy

Gdy konfiguracja projektu nie wystarcza, możesz utworzyć własny schemat z całkowicie niestandardowym przepływem pracy. Niestandardowe schematy znajdują się w katalogu openspec/schemas/ projektu i są wersjonowane razem z kodem.

your-project/
├── openspec/
│   ├── config.yaml        # Konfiguracja projektu
│   ├── schemas/           # Niestandardowe schematy znajdują się tutaj
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Twoje zmiany
└── src/

Forkowanie istniejącego schematu

Najszybszy sposób na dostosowanie schematu to forkowanie wbudowanego schematu:

openspec schema fork spec-driven my-workflow

Polecenie to kopiuje cały schemat spec-driven do openspec/schemas/my-workflow/, gdzie możesz go swobodnie edytować.

Co otrzymujesz:

openspec/schemas/my-workflow/
├── schema.yaml           # Definicja przepływu pracy
└── templates/
    ├── proposal.md       # Szablon dla artefaktu proposal
    ├── spec.md           # Szablon dla specyfikacji
    ├── design.md         # Szablon dla projektu
    └── tasks.md          # Szablon dla zadań

Teraz edytuj schema.yaml, aby zmienić przepływ pracy, lub edytuj szablony, aby zmienić to, co generuje AI.

Tworzenie schematu od zera

Dla całkowicie nowego przepływu pracy:

# Interaktywnie
openspec schema init research-first

# Nieinteraktywnie
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Struktura schematu

Schemat definiuje artefakty w przepływie pracy oraz zależności między nimi:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Kluczowe pola:

Pole	Cel
id	Unikalny identyfikator, używany w poleceniach i regułach
generates	Nazwa pliku wyjściowego (obsługuje globy, np. specs/**/*.md)
template	Plik szablonu w katalogu templates/
instruction	Instrukcje dla AI dotyczące tworzenia tego artefaktu
requires	Zależności — które artefakty muszą istnieć wcześniej

Wypisz artefakty w kolejności, w jakiej chcesz je tworzyć. Pole requires decyduje, co jest możliwe; kolejność w liście artifacts: decyduje, co powstaje pierwsze, gdy kilka artefaktów jest jednocześnie gotowych.

Szablony

Szablony to pliki markdown, które kierują działaniem AI. Są wstrzykiwane do promptu podczas tworzenia danego artefaktu.

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Szablony mogą zawierać:

• Nagłówki sekcji, które AI powinno uzupełnić
• Komentarze HTML z wytycznymi dla AI
• Przykładowe formaty pokazujące oczekiwaną strukturę

Walidacja schematu

Przed użyciem niestandardowego schematu zwaliduj go:

openspec schema validate my-workflow

Sprawdza to:

• poprawność składni schema.yaml
• istnienie wszystkich referowanych szablonów
• brak cyklicznych zależności
• poprawność identyfikatorów artefaktów

Używanie niestandardowego schematu

Po utworzeniu użyj schematu za pomocą:

# Określ w poleceniu
openspec new change feature --schema my-workflow

# Lub ustaw jako domyślny w config.yaml
schema: my-workflow

Debugowanie rozwiązywania schematu

Nie jesteś pewien, który schemat jest używany? Sprawdź za pomocą:

# Zobacz, skąd pochodzi dany schemat
openspec schema which my-workflow

# Wylistuj wszystkie dostępne schematy
openspec schema which --all

Wyjście pokazuje, czy schemat pochodzi z projektu, katalogu użytkownika, czy z pakietu:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Uwaga: OpenSpec obsługuje również schematy na poziomie użytkownika w ~/.local/share/openspec/schemas/ do współdzielenia między projektami, ale zalecane są schematy na poziomie projektu w openspec/schemas/, ponieważ są wersjonowane razem z kodem.

---

Przykłady

Przepływ pracy szybkiej iteracji

Minimalny przepływ pracy do szybkich iteracji:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Dodawanie artefaktu przeglądu

Zforkuj domyślny schemat i dodaj krok przeglądu:

openspec schema fork spec-driven with-review

Następnie edytuj schema.yaml, aby dodać:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... istniejąca konfiguracja zadań ...
    requires:
      - specs
      - design
      - review    # Teraz zadania wymagają również przeglądu

---

Schematy społecznościowe

OpenSpec obsługuje również schematy utrzymywane przez społeczność, dystrybuowane przez niezależne repozytoria. Zapewniają one zdyscyplinowane przepływy pracy integrujące OpenSpec z innymi narzędziami lub systemami, podobnie jak katalog rozszerzeń społecznościowych github/spec-kit działa dla spec-kit.

Schematy społecznościowe nie są włączane do rdzenia OpenSpec — znajdują się w własnych repozytoriach z własnym harmonogramem wydań. Aby z nich skorzystać, skopiuj pakiet schematu do katalogu openspec/schemas/<schema-name>/ projektu (README każdego repozytorium zawiera instrukcje instalacji).

Schemat	Utrzymujący	Repozytorium	Opis
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Zbiera intencję zmiany, obserwowalne zachowanie, projekt techniczny i trwałe decyzje architektoniczne przed implementacją. Dodaje manifest przeglądu ADR lokalny dla zmiany i zapisuje kwalifikujące się długoterminowe decyzje jako niezmienniczne, nadpisywalne ADR-y.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Integruje zarządzanie artefaktami OpenSpec z umiejętnościami wykonawczymi obra/superpowers (burza mózgów, tworzenie planów, TDD przez subagentów, przegląd kodu, finalizacja). Dodaje artefakt retrospective oparty na dowodach, wypełniający lukę, której Superpowers nie pokrywa natywnie.
nanopm	@nmrtn	nmrtn/nanopm	Przepływ pracy z priorytetem PM. Uruchamia potok planowania nanopm (audyt → strategia → roadmapa → PRD) przed implementacją. Łączy planowanie produktowe z przepływem pracy inżynieryjnym opartym na specyfikacji w OpenSpec. Artefakty są odczytywane z .nanopm/, jeśli istnieje — proposal czerpie z audytu, design czerpie ze strategii, a tasks czerpie z rozbicia PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Runbooki testów end-to-end na poziomie funkcjonalności. Każda funkcjonalność otrzymuje niezmienną specyfikację, niezmienny szablon zadań i jeden zapisany z datą raport wykonania na każde uruchomienie. Asercje obejmują wyłącznie obserwowalne zachowanie (status HTTP, treść odpowiedzi, stan trwały — nigdy podciągi logów); każde uruchomienie rejestruje czas rozpoczęcia/zakończenia UTC, czas trwania i szacunkowe zużycie tokenów LLM.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Przepływ pracy oparty na specyfikacji z dyscypliną TDD i krokiem przeglądu adwersaryjnego. Przebieg: proposal → specs → design → review → test-plan → tasks → apply → verify. review jest tworzony przez przeglądarka z nowym kontekstem i tylko do odczytu (drugi model, jeśli jest dostępny) i emituje linię VERDICT:, informując agenta o zablokowaniu test-plan, tasks i apply; OpenSpec sprawdza jedynie istnienie artefaktów, więc wymuś bramkę za pomocą własnego CI lub hooka. test-plan mapuje każdy scenariusz specyfikacji na nazwany test i służy jako rejestr czerwony/zielony, który verify audytuje.

Chcesz przyczynić się do schematu społecznościowego? Otwórz issue z linkiem do swojego repozytorium lub złóż PR dodający wiersz do tej tabeli.

---

Zobacz też

• Referencja CLI: Polecenia schematów - Pełna dokumentacja poleceń