ckb/OPENSPEC.pl.md

OpenSpec w tej bazie wiedzy

Read this in: English | Polski

Jak dodać OpenSpec do Cascade KB, które dokumentuje tworzone przez Ciebie oprogramowanie, i jak to współgra z wiki.

To przewodnik dla człowieka. Zasady dla samego agenta są w module software — .agents/modules/software/ — który musi być zainstalowany, zanim cokolwiek z poniższych zacznie obowiązywać. Powiedz: „zainstaluj moduł software”.

---

Spis treści

1. Po co tu OpenSpec
2. Przeczytaj to, zanim uruchomisz openspec init
3. Instalacja
4. Dwa poziomy specyfikacji
5. Codzienna praca
6. Jak specyfikacje trafiają do wiki
7. Pilnowanie spójności poziomów
8. Szybki przegląd

---

1. Po co tu OpenSpec

Wiki zapisuje o oprogramowaniu trzy różne rzeczy i warto trzymać je osobno:

Pytanie	Gdzie mieszka	Kto zapisuje
Czym jest kod?	wiki/entities/ — strony repository i component	ckb-code-map
Co powinien robić?	openspec/specs/	ckb-spec + OpenSpec
Co wybraliśmy i dlaczego?	wiki/decisions/	ckb-decide

OpenSpec odpowiada za środkowy wiersz: specyfikacja opisuje obowiązujący kontrakt, a propozycja zmiany — co ma stać się prawdą w następnej kolejności. Piszesz specyfikację przed kodem, agent implementuje pod nią, a zarchiwizowana zmiana staje się częścią trwałego zapisu.

Jeśli coś nie ogranicza przyszłego zachowania, to nie jest specyfikacja, tylko decyzja. Powiedz wtedy „zapisz decyzję”.

2. Przeczytaj to, zanim uruchomisz openspec init

Nigdy nie uruchamiaj openspec init w katalogu głównym bazy wiedzy. Uruchamiaj go w src/<repo>/.

To nie jest ostrożność na wszelki wypadek. openspec init zapisuje pliki integracji z narzędziami w .claude/skills/ oraz dodaje bloki znacznikowe do AGENTS.md / CLAUDE.md. W tym repozytorium oba te miejsca są nośne:

• .claude/skills to dowiązanie symboliczne do .agents/skills. Cokolwiek OpenSpec tam zapisze, ląduje w zestawie skilli Twojej bazy wiedzy.
• CLAUDE.md to dowiązanie symboliczne do AGENTS.md — systemowego prompta bazy. To jeden i ten sam plik, więc blok zapisany „do obu” zapisuje się dwukrotnie w to samo miejsce.

Uruchomienie w katalogu głównym wmiesza instrukcje OpenSpec dla pojedynczego repozytorium w reguły rządzące całą bazą wiedzy. Uruchomienie w src/<repo>/ zostawia wszystko na swoim miejscu: repozytorium dostaje własne .claude/, własny AGENTS.md, a jego specyfikacje podróżują razem z kodem.

Katalog openspec/ w korzeniu bazy nie jest instalacją OpenSpec (§4), więc nigdy nie wymaga init.

3. Instalacja

Wymaga Node.js 20.19.0 lub nowszego.

npm install -g @fission-ai/openspec@latest   # albo pnpm / yarn / bun
openspec --version

Następnie, dla każdego repozytorium:

cd src/<repo>
openspec init

Po późniejszej aktualizacji CLI uruchom w każdym repozytorium openspec update, żeby odświeżyć wygenerowane pliki instrukcji.

Odinstalowanie z repozytorium oznacza ręczne usunięcie katalogu openspec/, wygenerowanych plików narzędziowych oraz bloków znacznikowych OpenSpec z AGENTS.md / CLAUDE.md tego repozytorium — CLI tego za Ciebie nie cofa.

4. Dwa poziomy specyfikacji

Specyfikacje mieszkają w dwóch miejscach i jest to zamierzone.

Korzeń bazy — openspec/ — przekrojowe zdolności obejmujące kilka repozytoriów w src/. To co i dlaczego, którego nie posiada żadne pojedyncze repozytorium.

Tą warstwą zarządza skill ckb-spec, a nie CLI OpenSpec. Nie ma pod nią kodu ani repozytorium, którym miałaby rządzić, więc workflow OpenSpec — skrojony pod repozytorium — tu nie pasuje. Warstwa ta jest śledzona w historii gita bazy, tak jak każda inna wiedza.

Per repozytorium — src/<repo>/openspec/ — jak to repozytorium realizuje te zdolności. To jak. Rodzimy przypadek OpenSpec: zarządzany przez CLI i jego własne instrukcje, podróżujący z kodem i biorący udział w pull requestach tego repozytorium.

Agent oddaje tu pole OpenSpec i nie podstawia własnego workflow. Jeśli CLI nie jest zainstalowane, powie to wprost, zamiast improwizować.

5. Codzienna praca

W zainicjalizowanym repozytorium pętla wygląda tak: propose → apply → archive.

Krok	Powiedz / uruchom	Co się dzieje
Propozycja	/opsx:propose <co chcesz zbudować>	Propozycja, delta specyfikacji, projekt i zadania zapisane jako Markdown w openspec/changes/<id>/
Przegląd	openspec show <id>, openspec validate <id>	Czytasz deltę; walidacja sprawdza strukturę oraz zmodyfikowane wymagania wobec specyfikacji, które mają zastąpić
Wdrożenie	/opsx:apply	Agent implementuje pod specyfikację
Archiwizacja	/opsx:archive lub openspec archive <id>	Zmiana scala się z główną specyfikacją i trafia do changes/archive/

Przydatne obok: openspec list, openspec status, openspec view (interaktywny pulpit).

Dla warstwy w korzeniu bazy nie ma CLI — po prostu powiedz „napisz przekrojową specyfikację dla X”, a zajmie się tym ckb-spec.

6. Jak specyfikacje trafiają do wiki

Trzy mostki, wszystkie obsługiwane przez ckb-spec. To one sprawiają, że OpenSpec nie staje się równoległym światem obok bazy wiedzy.

Zarchiwizowana zmiana → rekord decyzji. Wdrożona i zarchiwizowana zmiana to decyzja, którą podjęto i wykonano. Agent proponuje zapisanie jej w wiki/decisions/ — uzasadnienie z propozycji staje się Kontekstem i Uzasadnieniem, delta staje się Decyzją, a odrzucone opcje — Rozważanymi alternatywami.

Proponuje, a nie robi tego automatycznie, i jest to celowe. Nie każda rutynowa zmiana zasługuje na trwały, numerowany rekord, a dziennik decyzji zapchany nimi przestaje być wart czytania.

Specyfikacja → strona encji. Aktualne specyfikacje z korzenia bazy pojawiają się w wiki/entities/ jako cienkie strony type: spec, dzięki czemu pytania w rodzaju „co to ma robić?” da się odpowiedzieć z indeksu, bez otwierania drzewa specyfikacji. Źródłem prawdy pozostaje plik specyfikacji — strona wiki jest wskaźnikiem, nie kopią.

Poziom → poziom. Specyfikacje z korzenia i z repozytoriów linkują się nawzajem (§7).

7. Pilnowanie spójności poziomów

Dwa poziomy specyfikacji to dwa miejsca, w których może mieszkać to samo stwierdzenie — a więc i dwa, w których może się po cichu rozjechać. Zapobiega temu jedna zasada:

Specyfikacja z korzenia wymienia każdą implementującą ją specyfikację repozytorium w implemented_by:. Specyfikacja repozytorium wskazuje rodzica w implements:. Zawsze ustawiaj obie strony.

Te odnośniki stają się krawędziami grafu, co zamienia rozjazd w widoczne znalezisko, zamiast w cichy drugi ośrodek prawdy.

Powiedz „zsynchronizuj specyfikacje” (albo uruchom lint), a dostaniesz cztery kontrole:

1. Specyfikacje z korzenia bez implementacji — opisane, ale nikt tego nie buduje.
2. Specyfikacje repozytorium, których rodzic zniknął lub trafił do archiwum — budujesz pod coś, co przestało obowiązywać.
3. Jednostronne odnośniki, w dowolnym kierunku.
4. Specyfikacje z korzenia starsze niż zmapowany commit każdego repozytorium, które je implementuje — możliwy rozjazd, wart sprawdzenia.

Żadna z tych rzeczy nie jest naprawiana automatycznie. Każda jest stwierdzeniem o intencji, a tylko Ty wiesz, która strona ma rację.

8. Szybki przegląd

Chcesz	Powiedz / uruchom
Włączyć to wszystko	„zainstaluj moduł software”
Dodać OpenSpec do repozytorium	cd src/<repo> && openspec init
Zmapować repozytorium do wiki	„zmapuj src/<repo>”
Napisać przekrojową specyfikację	„napisz przekrojową specyfikację dla X”
Zaproponować zmianę w repozytorium	/opsx:propose <co>
Sprawdzić stan specyfikacji	„zsynchronizuj specyfikacje”
Zamienić zarchiwizowaną zmianę w decyzję	„zapisz tę zmianę jako decyzję”

Nigdy: nie uruchamiaj openspec init w korzeniu bazy · nie rób git add niczego w src/ · nie przerabiaj plików OpenSpec repozytorium pod konwencje tej bazy.

---

Źródła

• Dokumentacja OpenSpec · Fission-AI/OpenSpec · @fission-ai/openspec na npm
• Rekordy projektowe: D-0001, D-0002

---

Udostępniane na licencji Apache License 2.0 — zobacz LICENSE.