ckb/.agents/modules/software/README.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

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ś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 (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.