4.2 KiB
Moduł software
Read this in: English | 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średniockb-spec, boopenspec/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-specsię 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, jakraw/archive/.ckb-retrievemoże otworzyć kod i zacytować go, żeby zweryfikować twierdzenie; nigdy nie odpowiada nim na pytanie „czym jest encja X”, ackb-ingestnie 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-changesnigdy nie wykonujegit addwsrc/.
Konfiguracja OpenSpec
Zobacz docs/OPENSPEC.pl.md
(English): 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: dlaczego moduły są plikami w repozytorium.
- D-0002: dlaczego ignorowane klony, oba poziomy specyfikacji i hybrydowe vendorowanie.
Rekordy decyzji są po angielsku.
Udostępniane na licencji Apache License 2.0 — zobacz LICENSE.