ckb/docs/OPENSPEC.pl.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

209 lines
8.8 KiB
Markdown

# OpenSpec w tej bazie wiedzy
*Read this in: [English](OPENSPEC.md) | **Polski***
Jak dodać [OpenSpec](https://openspec.dev) 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/](../.agents/modules/software/README.md) — 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](#1-po-co-tu-openspec)
2. [Przeczytaj to, zanim uruchomisz `openspec init`](#2-przeczytaj-to-zanim-uruchomisz-openspec-init)
3. [Instalacja](#3-instalacja)
4. [Dwa poziomy specyfikacji](#4-dwa-poziomy-specyfikacji)
5. [Codzienna praca](#5-codzienna-praca)
6. [Jak specyfikacje trafiają do wiki](#6-jak-specyfikacje-trafiają-do-wiki)
7. [Pilnowanie spójności poziomów](#7-pilnowanie-spójności-poziomów)
8. [Szybki przegląd](#8-szybki-przegląd)
---
## 1. Po co tu OpenSpec
Wiki zapisuje o oprogramowaniu trzy różne rzeczy. Trzymaj 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ępnym kroku.
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**.
```bash
npm install -g @fission-ai/openspec@latest # albo pnpm / yarn / bun
openspec --version
```
Następnie, dla każdego repozytorium:
```bash
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 celowo mieszkają w dwóch miejscach.
**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. Historię tej warstwy, jak każdej innej wiedzy,
śledzi git bazy.
**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.
Celowo tylko proponuje. 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 na 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.*
Agent nie naprawia żadnej z nich 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](https://openspec.dev/docs/installation) ·
[Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) ·
[@fission-ai/openspec na npm](https://www.npmjs.com/package/@fission-ai/openspec)
- Rekordy projektowe: [D-0001](decisions/0001-opt-in-file-based-kb-modules.md),
[D-0002](decisions/0002-software-module-design.md)
---
*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../LICENSE).*