83 lines
4.2 KiB
Markdown
83 lines
4.2 KiB
Markdown
# Moduł `software`
|
|
|
|
*Read this in: [English](README.md) | **Polski***
|
|
|
|
Opcjonalny. Instalacja: „install the software module”; usunięcie: „uninstall
|
|
the software module”. Dopóki moduł nie jest zainstalowany, nic tutaj nie
|
|
działa. Poniższe skille leżą w tym folderze, a nie w `.agents/skills/`,
|
|
po to, żeby ich opisy nie zajmowały kontekstu w bazach, które nie
|
|
dokumentują oprogramowania.
|
|
|
|
## Co zakłada
|
|
|
|
Tworzysz oprogramowanie, a ta baza przechowuje wiedzę *o* nim. Sam kod leży w
|
|
`src/<repo>/` jako zwykłe klony: **ignorowane przez git**, każdy z własnym
|
|
zdalnym repozytorium i własną historią. Jedna baza może ich mieć kilka.
|
|
|
|
Kod nie jest częścią historii bazy i może go w ogóle nie być w świeżym klonie.
|
|
To celowe i dlatego moduł zapisuje dla każdego repozytorium stronę encji
|
|
`type: repository`: adres zdalnego repozytorium, domyślna gałąź, język,
|
|
polecenie budowania, ścieżka, właściciel. **Trwałym zapisem jest ta strona;
|
|
klon to tylko wygoda.**
|
|
|
|
## Co dodaje
|
|
|
|
| Skill | Co robi |
|
|
|---|---|
|
|
| `ckb-code-map` | Czyta klon `src/<repo>` i zapisuje go w `wiki/entities/` jako stronę repozytorium oraz strony komponentów, oznaczone commitem, z którego powstały, żeby dało się wykryć ich nieaktualność. |
|
|
| `ckb-spec` | Zarządza specyfikacjami na poziomie bazy, specyfikacje poszczególnych repozytoriów zostawia OpenSpec i łączy oba poziomy z `wiki/`: zarchiwizowane zmiany stają się rekordami decyzji, bieżące specyfikacje stronami `type: spec`. |
|
|
|
|
Do tego: szkielet `src/` i `openspec/`, blok routingu w `AGENTS.md`, reguły
|
|
`.gitignore` dla `src/*` oraz typy `repository`/`component`/`spec`.
|
|
|
|
Te skille zapisują czasowniki grafu z bazowego słownika w
|
|
`wiki/graph/index.md`: `ckb-code-map` zapisuje `part_of`, `depends_on` i `owns`,
|
|
a `ckb-spec` — `implements`. Moduł nie wprowadza nowych czasowników.
|
|
|
|
## Dwa poziomy specyfikacji
|
|
|
|
Specyfikacje istnieją na **obu** poziomach i właśnie o ten podział chodzi:
|
|
|
|
- **`openspec/` w katalogu głównym bazy**: co i dlaczego, ponad
|
|
repozytoriami. Kontrakty przekrojowe, których nie posiada żadne pojedyncze
|
|
repozytorium. Obsługuje je bezpośrednio `ckb-spec`, bo `openspec/` w
|
|
katalogu głównym nie jest zwykłą instalacją OpenSpec: nie ma pod nim kodu.
|
|
- **`src/<repo>/openspec/`**: jak to repozytorium to realizuje. Naturalny
|
|
przypadek OpenSpec: podróżuje razem z kodem i trafia do PR-ów samego
|
|
repozytorium. Obsługują go instrukcje samego OpenSpec; `ckb-spec` się im
|
|
podporządkowuje i mówi wprost, gdy CLI nie jest zainstalowane, zamiast
|
|
improwizować zastępstwo.
|
|
|
|
Poziomy łączą pola frontmatter `implements:` / `implemented_by:`, które stają
|
|
się krawędziami grafu. Dzięki temu dwa poziomy specyfikacji, które się rozjadą,
|
|
dają **sygnał w lincie** zamiast dwóch po cichu rozbieżnych prawd. Specyfikacja na poziomie bazy bez implementacji albo specyfikacja
|
|
repozytorium, której rodzic został zarchiwizowany, to znalezisko.
|
|
|
|
## Czego nie robi
|
|
|
|
- **`src/` nie jest warstwą kaskady.** To materiał dowodowy, jak
|
|
`raw/archive/`. `ckb-retrieve` może otworzyć kod i zacytować go, żeby
|
|
zweryfikować twierdzenie; nigdy nie odpowiada nim na pytanie „czym jest
|
|
encja X”, a `ckb-ingest` nie traktuje kodu jako materiału do skrzynki. Bez
|
|
tej reguły każdy ingest zamieniałby twój kod w strony wiki.
|
|
- **Nie commituje ani nie wypycha repozytoriów z `src/`.** To osobne
|
|
repozytoria z osobnymi zdalnymi. `ckb-sync-changes` nigdy nie wykonuje
|
|
`git add` w `src/`.
|
|
|
|
## Konfiguracja OpenSpec
|
|
|
|
Zobacz [docs/OPENSPEC.pl.md](../../../docs/OPENSPEC.pl.md)
|
|
([English](../../../docs/OPENSPEC.md)): instalacja, codzienna pętla
|
|
propose → apply → archive i powód, dla którego `openspec init` nigdy nie może
|
|
być uruchomione w katalogu głównym bazy.
|
|
|
|
## Zapis decyzji projektowych
|
|
|
|
- [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md): dlaczego moduły są plikami w repozytorium.
|
|
- [D-0002](../../../docs/decisions/0002-software-module-design.md): dlaczego ignorowane klony, oba poziomy specyfikacji i hybrydowe vendorowanie.
|
|
|
|
Rekordy decyzji są po angielsku.
|
|
|
|
---
|
|
|
|
*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../../../LICENSE).*
|