Michał Kopeć
0c06cb64ab
Commit all in-flight work — ckb-module and ckb-reset skills, the .agents/modules/ scaffold, OPENSPEC docs, decision records D-0001 and D-0002, graph edges and workload summaries — so the reset that follows is fully recoverable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
209 lines
8.9 KiB
Markdown
209 lines
8.9 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 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**.
|
|
|
|
```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 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](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](wiki/decisions/0001-opt-in-file-based-kb-modules.md),
|
|
[D-0002](wiki/decisions/0002-software-module-design.md)
|
|
|
|
---
|
|
|
|
*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](LICENSE).*
|