ckb/docs/MANUAL.pl.md
Michał Kopeć 7dd73bb6e4 Sync: local changes as of 2026-10-30T12:12:54Z
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-30 13:12:54 +01:00

59 KiB

Podręcznik użytkownika

Read this in: English | Polski

To jest podręcznik dla człowieka korzystającego z Cascade Knowledge Base (tego repozytorium) — nie dla agenta. Zasady działania samego agenta znajdziesz w AGENTS.md / CLAUDE.md. Techniczny, funkcja-po-funkcji przegląd znajdziesz w README.md (lub README.pl.md). Pełny schemat strony wraz z historią obu numerów wersji znajdziesz w CHANGELOG.pl.md. Ten dokument jest zorientowany na zadania: „chcę zrobić X — co mam powiedzieć i co się wtedy stanie?”

Wszędzie poniżej „powiedz” oznacza napisanie tego do dowolnego agenta AI, z którego korzystasz w tym repozytorium (Claude Code lub inny agent, który czyta AGENTS.md). Nie musisz używać dokładnych sformułowań — pokazane frazy wyzwalające to przykłady, nie magiczne słowa; agent dopasowuje się do intencji.


Spis treści

  1. Tworzenie lub inicjalizacja wiki
  2. Dodawanie wiedzy
  3. Utrzymanie porządku
  4. Synchronizacja — z samym sobą i z innymi ludźmi
  5. Aktualizacja szablonu
  6. Przykłady użycia
  7. Co jest generowane przez agenta, a co możesz edytować
  8. Szybki przegląd

1. Tworzenie lub inicjalizacja wiki

Wymagania wstępne

Agent robi prawie wszystko, czytając i pisząc Markdown. Cztery skille dodatkowo uruchamiają mały skrypt w Pythonie 3.8+ (tylko biblioteka standardowa, nic do pip install): lint (w tym kontrola uruchamiana na początku każdej sesji), ranking przy wyszukiwaniu oraz dwa eksporty. Python jest zalecany, nie bezwzględnie wymagany:

Bez Pythona Co się dzieje
Kontrola na starcie sesji Zamiast niej działa zapasowy skrypt bash/PowerShell. Wykrywa strony uszkodzone, przeterminowane i zmienione źródła; zaznacza, że cytaty Crux nie zostały sprawdzone.
„Lint” Agent przechodzi ręczną listę kontrolną z grep — wolniej, w ograniczonym zakresie, i mówi, co pominął.
Pytania Agent szereguje kandydatów ręcznie z indeksów i grep zamiast skryptu fuzji.
Eksport OKF / Starlight Niedostępny do czasu zainstalowania Pythona.

Agent raz na sesję mówi, że nie znalazł interpretera, i dalej pracuje ścieżkami zapasowymi. Jak zainstalować Pythona:

  • Windows — winget install Python.Python.3.12 w terminalu, albo aplikacja „Python 3.12” z Microsoft Store, albo instalator z python.org (zaznacz Add python.exe to PATH). Potem python --version lub py -3 --version powinno wypisać Python 3.x. Jeśli python otwiera Store, wyłącz Aliasy wykonywania aplikacji dla python.exe w Ustawieniach Windows albo używaj py -3.
  • macOS — brew install python przez Homebrew albo xcode-select --install dla python3 dostarczanego przez Apple.
  • Linux — sudo apt install python3 (Debian/Ubuntu), sudo dnf install python3 (Fedora), sudo pacman -S python (Arch). Większość dystrybucji już go ma.

Dowolne z python3, python lub py -3 wystarczy; agent próbuje ich w tej kolejności.

Jeśli czytasz to wewnątrz istniejącej Cascade KB

Nie musisz nic robić — struktura już istnieje (wiki/, raw/, outputs/ itd.). Przejdź do §2.

Zakładanie zupełnie nowej wiki gdzie indziej

Powiedz:

„Set up a new wiki like this one in ~/projects/my-notes.”

To sklonuje wyłącznie schemat — strukturę katalogów, plik zachowań AGENTS.md/CLAUDE.md oraz pusty szkielet wiki/ — do docelowego folderu. Nigdy nie kopiuje rzeczywistej zawartości tego projektu (żadnych encji, danych grafu, notatek). Otrzymujesz świeżą, pustą KB, gotową na pierwszy zrzut do raw/inbox/. Zobacz .agents/skills/ckb-init/SKILL.md.

Szablon może pochodzić z dwóch miejsc: z plików tego repozytorium albo ze świeżego, płytkiego klona kanonicznego repozytorium szablonu (lub dowolnego forka/mirrora, którego URL podasz), pobranego do folderu roboczego. Powiedz „pull the latest template and set up a KB in <folder>” — albo uruchom skilla spoza jakiejkolwiek KB — a agent najpierw sklonuje repozytorium, a dopiero potem zbuduje szkielet. Klon jest wyłącznie roboczy: nowa KB dostaje własną historię gita (agent pyta przed git init), a nie historię szablonu.

Jeśli docelowy folder wygląda już jak baza wiedzy (ma wiki/ lub AGENTS.md), agent zatrzyma się i zapyta, zanim czegokolwiek dotknie — nie nadpisze po cichu istniejącej bazy wiedzy.

Budowanie na bazie cudzej wiki

Cascade KB może opierać się na jednej lub wielu nadrzędnych bazach wiedzy, które pozostają tylko do odczytu. Są trzy sposoby ich podpięcia:

  • Dowiązanie symboliczne (inna KB na twojej maszynie, lub taka, którą utrzymujesz gdzie indziej i chcesz mieć „na żywo”):

    ln -s /path/to/other-kb ./linked/other-team
    
  • Kopia git (zewnętrzna KB, której chcesz mieć zamrożoną, wersjonowaną kopię):

    git clone https://github.com/org/external-kb ./libs/external-kb
    

    Nie chcesz używać gita? Większość hostingów git oferuje też opcję „Download ZIP” na stronie repozytorium — pobierz i rozpakuj zawartość bezpośrednio do ./libs/external-kb. Tak czy inaczej otrzymujesz tę samą zamrożoną, tylko-do-odczytu kopię. Różnica polega tylko na tym, że nie odświeżysz jej później przez git pull; żeby ją zaktualizować, pobierz ZIP ponownie i rozpakuj go na starą zawartość.

  • Konektor (żywe zewnętrzne źródło, którego nie chcesz mieć w pełnej lokalnej kopii — folder SharePoint, folder Google Drive albo inne podłączone źródło): sam utwórz libs/<name>/source.yaml:

    connector: sharepoint
    location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
    description: "Wspólny folder raportów zespołu finansowego"
    

    a potem powiedz „index external sources". Agent czyta konfigurację, łączy się z tym, co jest dostępne w danej sesji (podłączonym narzędziem Microsoft 365/Google Drive albo zwykłym pobraniem URL), i buduje krótki indeks tego, co znajdzie — po jednym wpisie na dokument — wewnątrz tego samego folderu libs/<name>/. Zobacz §6 po omówiony przykład i to, jak wygląda wynik.

    Zanim oprzesz się na źródle typu konektor:

    • Nie musisz sam budować indeksu. source.yaml może dodać blok index: wskazujący na już zbudowany indeks — repozytorium git albo zasób współdzielony — dzięki czemu pobierasz to, co ktoś inny już zaindeksował, zamiast samodzielnie skanować żywe źródło. Każde uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już tam jest, dostajesz go. Jeśli go tam jeszcze nie ma (normalny stan, zanim ktokolwiek z dostępem do zapisu to uruchomił), to nie błąd: najbliższe uruchomienie osoby z dostępem do zapisu po raz pierwszy go tam utworzy i opublikuje.
    • Budowanie i odświeżanie są opcjonalne, per osoba, per źródło. Domyślnie każdy ma do źródła typu konektor dostęp tylko do odczytu — niczyj agent nie przeskanuje żywego konektora w imieniu osoby, która wyraźnie o to nie poprosiła. Powiedz „make me the admin for <source>", żeby się na to zapisać (tworzy to lokalny, osobisty plik libs/<name>/source.local.yaml — nigdy niecommitowany, nigdy niewidoczny dla współpracowników). Jedna lub dwie osoby utrzymują źródło dla całego zespołu; nikt inny go ponownie nie skanuje.
    • Możesz ustawić, jak często ma być odświeżane. Dodaj opcjonalne refresh_interval_days: 7 do source.yaml (domyślnie 30). Folder zmieniający się codziennie potrzebuje krótszego okna niż kwartalne archiwum, którego nikt nie tyka. Wtedy zarówno „index external sources", jak i „Lint" powiedzą ci, kiedy źródło jest zaległe i o ile. Ma to największe znaczenie, jeśli masz do niego dostęp tylko do odczytu: gdy wiesz, które źródło się przedawniło, możesz zapytać osobę, która je utrzymuje.

Niezależnie od sposobu, po podpięciu wystarczy normalnie zadawać pytania. Agent sprawdza najpierw twoją lokalną wiki/, potem przechodzi przez linked/, potem libs/, i korzysta z tego, co ma odpowiedź. Nigdy nie edytujesz plików wewnątrz linked/ ani kopii git w libs/<name>/ bezpośrednio; jeśli coś tam jest błędne lub nieaktualne, poprawiasz to, zapisując poprawioną wersję we własnej lokalnej wiki/, która zawsze wygrywa. (libs/<name>/ oparty na konektorze to jedyne miejsce, gdzie agent sam zapisuje w twoim imieniu — zobacz §6 — ale tylko swój generowany indeks, i tylko część budowania/odświeżania, jeśli jesteś administratorem tego źródła; source.yaml zawsze pozostaje twój do edycji, nigdy agenta.)


2. Dodawanie wiedzy

To główny sposób, w jaki rośnie wiki. Jest pięć dróg:

A. Wrzuć materiał, potem powiedz „Ingest”

Umieść cokolwiek nieprzetworzonego w raw/inbox/ — wklejone notatki, plik .txt z transkrypcją, links.txt z adresami URL, PDF, chaotyczny plik roboczy. Nie musisz go najpierw porządkować. Następnie powiedz:

„Ingest.” (lub „Update the wiki” — to samo; nigdy fraza zawierająca „sync”, to jest git)

Przykład:

Wrzucasz meeting-2026-07-10.txt (surowe notatki z rozmowy z klientem) do raw/inbox/, potem mówisz „Ingest.”

Agent czyta plik, wydobywa wymienione osoby, decyzje i otwarte pytania, tworzy lub aktualizuje strony encji w wiki/entities/, zapisuje relacje w wiki/graph/edges.json, dodaje nowe strony do wiki/index.md, loguje zmianę w wiki/log.md i przenosi oryginalny plik do raw/archive/2026-07-10/. Na koniec przypomina o przejrzeniu wyniku i powiedzeniu „sync changes”, gdy wynik będzie ci odpowiadał.

Przy długim transkrypcie agent nie poprzestaje na jednej stronie podsumowania. Wyciąga wyszukiwalne pytanie, podsumowanie, rozwiązanie oraz zaangażowane systemy i osoby — a pojedyncze fragmenty awansuje do własnych znajdowalnych sekcji, jeśli inaczej przepadłyby wewnątrz podsumowania. Ta ostatnia część ma celowy próg: fragment musi zawierać konkretny termin (flagę, komunikat błędu, klauzulę, numer wersji), mieć co najmniej kilka zdań i być potwierdzony przez coś dalej w materiale. W przeciwnym razie zostaje wtopiony w podsumowanie. Bez tego progu każdy akapit wygląda na wart zacytowania, a strona wiki znów staje się transkryptem — co przekreśla sens jego zingestowania.

Jeśli raw/inbox/ jest puste, agent skanuje bezpośrednio raw/ (nadal pomijając raw/archive/, które zawiera już przetworzoną historię).

Skill: .agents/skills/ckb-ingest/SKILL.md.

B. Po prostu powiedz agentowi coś w rozmowie

Nie zawsze potrzebujesz pliku. Jeśli powiesz agentowi fakt o trwałej wartości, np. „właściwie to termin przesunął się na wrzesień”, agent może zapisać go bezpośrednio do wiki/ jako nową stronę lub aktualizację istniejącej, tak samo jak z zaingestowanego pliku.

C. Pozwól agentowi powiedzieć, czego brakuje (Demand-Driven Context)

Jeśli zapytasz o coś, na co wiki nie potrafi odpowiedzieć, agent nie zawiedzie po cichu. Wskaże lukę i zaproponuje minimalną stronę, która ją wypełni.

Przykład:

Ty: „Jaka jest nasza polityka w sprawie X?” Agent: „Wiki jeszcze tego nie pokrywa. Chcesz, żebym dodał zalążek strony, czy możesz wkleić/opisać tę politykę, a ja ją spiszę?”

Zatwierdzasz, wklejasz źródło albo wrzucasz je do raw/inbox/ — kolejny ingest to wchłonie. Dzięki temu wiki pozostaje napędzana zapotrzebowaniem: rośnie wokół tego, o co faktycznie pytasz, a nie wokół wszystkiego, co teoretycznie dałoby się spisać.

Trwałe braki można też śledzić w wiki/query-gaps.md. Dobry wpis o luce jest maleńki: pytanie, gdzie agent szukał i jakie najmniejsze źródło lub strona sprawiłaby, że odpowiedź będzie dostępna następnym razem.

D. Zapisz decyzję

Gdy zapada jakaś decyzja — wybór technologii, zmiana procesu, polityka — powiedz:

„Zapisz decyzję: przenosimy billing na Postgresa. Alice i Bob zdecydowali dzisiaj, bo zapytania raportowe zabijały MySQL-a."

Agent zapisze numerowany rekord pod wiki/decisions/ z decyzją, autorami, datą, uzasadnieniem, alternatywami i tym, czego dotyczy. Jeśli zastępuje wcześniejszą decyzję, połączy obie w obu kierunkach i oznaczy starą jako zastąpioną — nie ruszając jej uzasadnienia. O to, czego nie podasz, dopyta w jednej turze; jeśli jesteś w środku pracy, powiedz to, a zapisze, co ma, i wskaże, które pola zostawił otwarte.

Potem pytaj, jak chcesz:

„Co zdecydowaliśmy w sprawie bazy danych billingu?" „Dlaczego używamy Postgresa?" „Kto to zdecydował i kiedy?" „Które decyzje są wciąż tylko propozycjami?" „Co zastąpiło decyzję 3?"

Odpowiedź zawsze przychodzi z informacją kto i kiedy, i wprost mówi, gdy decyzja jest propozycją, a nie decyzją obowiązującą, albo została już zastąpiona — żeby nie opierać się na czymś, co nie obowiązuje. Skill: ckb-decide.

Dwie zasady:

  • Decyzje są tylko do dopisywania. „Właściwie zmieniliśmy zdanie" tworzy nową decyzję zastępującą starą; nigdy nie edytuje uzasadnienia starej. Historia jest tu sednem. Zwykłe błędy zapisu („tam miała być Anna, nie Alice") agent poprawia w miejscu.
  • Propozycja to nie decyzja. Jeśli sprawa nie została rozstrzygnięta, zapisywana jest jako proposed bez daty decyzji i pojawia się, gdy pytasz, co jest jeszcze otwarte.

E. Utwórz lokalny zakres projektu

Gdy jakiś temat, klient, system lub inicjatywa wraca często, poproś:

„Utwórz zakres projektu dla integracji płatności."

Agent utworzy lub zaktualizuje zwykłą stronę Markdown pod wiki/projects/, wymieniającą strony, encje, pliki z raw/archive/, indeksy konektorów i obszary grafu, które należy przeszukać najpierw dla tego zakresu. Nadal masz jedną lokalną wiki; to tylko daje powracającym pytaniom lepszy punkt startowy.


3. Utrzymanie porządku

Powiedz, kiedy chcesz — po dużym ingest lub po prostu okresowo (albo niech robi to za ciebie rutyna):

„Lint.”

To uruchamia przegląd kondycji całej wiki:

  • strony bez wymaganego frontmatteru (type) są oflagowywane
  • strony nietykane od dłuższego czasu są oflagowywane jako nieaktualne
  • wyniki pewności (confidence) zanikają, jeśli nic ostatnio ich nie wzmocniło
  • stare, niskopriorytetowe strony są archiwizowane do wiki/archived/ (nigdy usuwane)
  • sprzeczne strony są łączone stare→nowe (supersesja)
  • osierocone strony (nic do nich nie linkuje) dostają odnośniki zwrotne albo są archiwizowane
  • uszkodzone krawędzie grafu są naprawiane lub usuwane
  • brakujące/podwójne wpisy w indeksie i dzienniku są poprawiane
  • konektorowe źródła, których indeks jest zaległy do odświeżenia, zostają oflagowane wraz z informacją o ile — przydatne nawet jeśli masz do tego źródła dostęp tylko do odczytu, bo mówi ci, kogo dopytać
  • strony, których źródło faktycznie się zmieniło, zostają oflagowane — patrz niżej
  • cytaty, których nie ma już w źródle, na które się powołują, zostają oflagowane
  • powtarzające się problemy systemowe trafiają do wiki/error-book.md

Dwa ostatnie punkty to różnica między „ta strona jest stara" a „ta strona jest błędna".

Każda strona zapisuje skrót materiału, z którego powstała. Nieaktualność liczona datą to przypuszczenie: strona napisana rok temu może być wciąż całkowicie poprawna. Skrót nie jest przypuszczeniem — agent przelicza go i albo źródło jest co do bajtu tym, przeciwko czemu stronę napisano, albo ktoś je zmienił. Gdy źródło się zmienia, strona na nim zbudowana trafia na szczyt listy, przed wszystko, co się jedynie zestarzało.

Strony cytują też swoje źródła wprost, w sekcji ## Crux — kilka dosłownych linijek niosących właściwe twierdzenie, pod streszczeniem agenta. Wynikają z tego dwie rzeczy. Gdy zadajesz pytanie, agent często może odpowiedzieć z cytatu zamiast ponownie czytać całe źródło i pokazać ci słowa, a nie swoją parafrazę. A gdy cytat przestaje zgadzać się ze źródłem, to strona twierdzi — w cudzysłowie — coś, czego jej dowód już nie mówi. To najmocniejsze znalezisko lintu i agent nigdy nie „naprawi" go, po cichu dopasowując cytat do źródła.

Połowa wykrywająca działa jako skrypt Python tylko-do-odczytu (scripts/lint_report.py; bez Pythona zob. Wymagania wstępne, co nadal działa), więc ta sama wiki zawsze daje tę samą listę znalezisk. Agent czyta ten raport, a potem wykonuje części wymagające osądu (supersesja, niejednoznaczne sieroty, wpisy do księgi błędów oraz decyzja, co naprawić, a co oddać tobie). Naprawia samodzielnie to, co może zrobić bezpiecznie, a resztę zgłasza do twojej decyzji. Podobnie jak Ingest, na koniec przypomina o przejrzeniu i synchronizacji. Skill: .agents/skills/ckb-lint/SKILL.md.

Rutyny: rób to za mnie co N dni

Wszystko, co można powiedzieć agentowi, można zamienić w rutynę:

„Lint co tydzień.” „Indeksuj zewnętrzne źródła co 30 dni, ale najpierw mnie zapytaj.”

Agent zapisuje ją w ckb.yaml w bloku routines: (nazwa, fraza do wykonania, okres, czy pytać najpierw i data ostatniego uruchomienia). Rutyna liczy czas od ostatniego uruchomienia, nie według kalendarza: na starcie każdej sesji agent sprawdza, którym rutynom minął okres, najpierw odpowiada na to, o co prosisz, a potem w tej samej turze wykonuje zaległe, raportując każdą jedną linijką. Rutyna oznaczona „najpierw zapytaj” jest zamiast tego proponowana na końcu odpowiedzi i uruchamia się tylko po twojej zgodzie. Rutyna, która się nie powiodła albo została odrzucona, nie jest oznaczana jako wykonana, więc wraca w następnej sesji. Ręczne wykonanie też się liczy — gdy sam powiesz „Lint”, licznik tygodniowego lintu startuje od nowa.

Ponieważ data ostatniego uruchomienia jest commitowana z repozytorium, rutyna odpala się raz na okres dla wszystkich pracujących w tej KB, a nie raz na maszynę. Dwóch akcji nie da się zrobić rutyną: resetu wiki i synchronizacji z gitem. „List routines”, „which routines are due”, „run the routines now” i „remove the weekly lint” robią to, co mówią. To nie jest chmurowy harmonogram Claude Code: nic się nie dzieje, gdy nikt nie ma KB otwartej. Skill: .agents/skills/ckb-routine/SKILL.md.

Zaczynanie od zera: reset do czystego szablonu

Czasem chcesz zachować kształt bazy wiedzy bez jej zawartości — zwykle dlatego, że to repozytorium pełni też rolę szablonu przekazywanego innym, a zdążyło zebrać decyzje, podsumowania sesji i strony encji, które nie powinny z nim wędrować.

„Zresetuj wiki.” / „Zrób z tego czysty szablon.”

To jedyne polecenie w tym repozytorium, które celowo usuwa wiedzę, więc jest zbudowane tak, żeby trudno było je uruchomić przez przypadek:

  1. Najpierw szuka punktu przywracania. Jeśli drzewo robocze jest „brudne”, zatrzymuje się i proponuje commit — po resecie wszystko, co zacommitowane, jest o jedno git checkout stąd, a wszystko niezacommitowane po prostu znika. Może też otagować commit (pre-reset-<data>), żeby nie trzeba było pamiętać hasha.
  2. Pyta, jak daleko sięgnąć. Sześć poziomów wybieranych osobno: wiedza w wiki, historia workload/, materiał źródłowy w raw/, outputs/, źródła zewnętrzne i zainstalowane moduły. Domyślnie włączony jest tylko pierwszy. libs/, linked/ i moduły domyślnie na nie — linked/ zawiera dowiązania do cudzych baz wiedzy, więc usuwa dowiązanie, ale nigdy nie podąża za nim.
  3. Liczy, zanim zapyta. Dostajesz inwentarz — ile stron, ile rekordów decyzji (wymienionych z numerem i tytułem), ile krawędzi grafu, plus wszystko oznaczone retention: high — i jedną linijkę o tym, co przetrwa.
  4. Wymaga wpisania frazy, nie „tak”. A jeśli w odpowiedzi zmienisz zakres, przeliczy wszystko i zapyta ponownie, bo zgoda dotyczyła konkretnej liczby, a liczba się zmieniła.
  5. Weryfikuje po wszystkim, uruchamiając lint, zanim powie, że się udało.

Odtwarza dokładnie to, co utworzyłby ckb-init: te same katalogi, te same pliki szkieletu, ten sam kb_schema_version. Opróżnienie treści nie cofa wersji schematu.

Czego nie rusza nigdy, z potwierdzeniem czy bez: warstwy szablonu (AGENTS.md, .agents/, LICENSE, VERSION, dokumentacja) oraz src/, gdzie leżą niezależne repozytoria kodu, do których usuwania to polecenie nie ma żadnego tytułu.

Jedna celowa osobliwość: w odróżnieniu od każdego innego skilla ten nie zapisuje notatki sesji w workload/ — byłby to pierwszy wpis w katalogu, który właśnie opróżnił. Informuje o tym w raporcie.

Skill: .agents/skills/ckb-reset/SKILL.md.


4. Synchronizacja — z samym sobą i z innymi ludźmi

Są tu dwa różne rodzaje „synchronizacji”. Nie myl ich:

Ingest / Lint Sync changes
Warstwa Treść (co wiki wie) Git (czyj dysk ma jakie pliki)
Czego dotyczy wiki/, raw/ Historia commitów repo i zdalne repozytorium origin
Powiedz „Ingest” / „Lint” „Sync changes”

Uzgadnianie z origin (synchronizacja na poziomie gita)

Powiedz:

„Sync changes.”

To commituje wszelkie lokalne zmiany (np. z ostatniego Ingest lub Lint), pobiera wszystko nowe z origin, scala oba, a jeśli pojawi się konflikt — przeprowadza cię przez niego plik po pliku, pytając, czy zachować twoją wersję, wersję zdalną, czy podać scaloną treść dla każdego konfliktowego fragmentu. Gdy wszystko jest rozwiązane, wypycha zmiany (push).

Jeśli to repozytorium nigdy nie było połączone ze zdalnym, agent najpierw poprosi cię o wklejenie adresu URL:

Agent: „To repozytorium nie ma skonfigurowanego zdalnego origin. Wklej adres URL zdalnego repozytorium, a dodam je jako origin.”

Ty: https://git.wierzbowa.cloud/michal/ckb

Dla tej Cascade KB kanoniczną, zawsze aktualną kopią jest repozytorium źródłowe git.wierzbowa.cloud/michal/ckb. Jeśli nie masz pewności, czy twoja lokalna kopia jest aktualna, porównaj ją właśnie z nim.

Nie musisz go też klonować przez git clone, żeby mieć działającą kopię. Jeśli wolisz w ogóle nie używać gita, pobierz go jako ZIP z tej strony i rozpakuj lokalnie: dostajesz dokładnie te same pliki i możesz od razu skierować swojego agenta na rozpakowany folder. Zabraknie tylko skonfigurowanego origin, więc „sync changes” i „upgrade the wiki” nie będą miały z czym porównywać ani dokąd wypychać zmian. Gdy zechcesz z nich korzystać, uruchom git init w rozpakowanym folderze i dodaj powyższy adres jako origin (git remote add origin https://git.wierzbowa.cloud/michal/ckb).

Od tej pory „sync changes” uzgadnia stan właśnie z tym zdalnym repozytorium. Tak dzieli się jedną wiki między wieloma osobami: każdy robi ingest/edycje lokalnie, a „sync changes” to sposób, w jaki zmiany każdej osoby docierają do reszty — i jak zmiany innych docierają do ciebie. Skill: .agents/skills/ckb-sync-changes/SKILL.md.

Agent przypomina o tym też sam: na początku i na końcu sesji pracy wykonuje szybkie, tylko-do-odczytu sprawdzenie, czy jest coś niezacommitowanego lub niewypchniętego, i informuje, czy warto uruchomić „sync changes”. Nigdy nie wypycha zmian bez twojej prośby. Na końcu sesji, w której wykonano realną pracę, pyta też raz, czy zapisać rozmowę (zob. „Zapisywanie rozmowy” w Przykładach użycia) — i zapisuje tylko wtedy, gdy się zgodzisz.

Budowanie współdzielonej kaskady (synchronizacja na poziomie KB)

Jeśli zamiast jednej współdzielonej wiki chcesz mieć własną wiki, która buduje na cudzej — np. wiki twojego zespołu nadbudowana na ogólnofirmowej KB — to w ogóle nie jest synchronizacja gita; to podpięcie linked//libs/ opisane w §1. Każda osoba/zespół utrzymuje własną lokalną wiki/ (która zawsze wygrywa), a nadrzędne bazy wiedzy aktualizują się według własnego harmonogramu, niezależnie.


5. Aktualizacja szablonu

To inny rodzaj „bycia na bieżąco” niż wszystko w §4: tamta sekcja dotyczy zdalnego repozytorium twojej własnej KB — dzielenia się twoją zawartością ze współpracownikami. Ta sekcja dotyczy nadganiania narzędzi twojej KB względem ulepszeń wprowadzonych w samym kanonicznym szablonie Cascade KB, niezależnie skąd twoja KB pierwotnie pochodzi (ckb-init, klon, fork, albo KB, która istnieje wystarczająco długo, by poprzedzać niektóre z tych konwencji).

Powiedz:

„Upgrade the wiki.” / „Check for a newer template version.”

Z jakiego kanału pobierasz

Repozytorium szablonu utrzymuje trzy gałęzie i domyślnie dostajesz tę stabilną:

Gałąź Czym jest Kto powinien na niej być
main Stabilna — wydany szablon Ty, o ile nie masz powodu, żeby być gdzie indziej
test Kandydat do wydania — walidowany, zanim trafi do main Pomagasz walidować wydanie albo potrzebujesz poprawki, która weszła, ale nie została wydana
experimental Rozwojowa — bieżąca praca, może być zepsuta albo wycofana Rozwijasz sam szablon

Żeby użyć innej, powiedz której:

„Upgrade from the test branch.” / „Check experimental for updates.” / „Switch this KB back to the stable channel.”

To, co wybierzesz, zostaje — jest zapisane w ckb.yaml, więc kolejny upgrade zostanie na tym samym kanale, zamiast po cichu ściągnąć cię z powrotem na main. Tak samo przy tworzeniu: „zainicjuj z gałęzi experimental”.

Na jedno warto uważać. Jeśli śledzisz test albo experimental, twoja KB może mieć wersję, której main jeszcze nie wydało. Sprawdzenie względem main nie znajdzie wtedy nic nowszego — agent powie ci, że wyprzedzasz, a nie że jesteś aktualny, bo to dwie różne sytuacje. Powrót stamtąd na main to downgrade: może usunąć skille i cofnąć schemat poniżej tego, pod co napisano twoje strony. Agent poprosi o wyraźne potwierdzenie, a gdy treść przestałaby być zgodna z własnym zadeklarowanym schematem, odmówi wprost.

Co jest sprawdzane

Sprawdzane są dwie odrębne rzeczy, i każda, obie albo żadna może coś wykazać:

  • Warstwa szablonu/narzędzi — AGENTS.md/CLAUDE.md, każdy skill pod .agents/skills/, LICENSE, VERSION oraz dokumenty README/MANUAL. Porównywana z plikiem VERSION samego kanonicznego repozytorium.
  • Własna wersja schematu twojej treści wiki — pole kb_schema_version w wiki/index.md, porównywane z tym, czego obecnie oczekuje szablon. KB może być w pełni aktualna pod względem narzędzi, ale nadal nosić treść wiki/ zbudowaną lata temu pod starszym (albo w ogóle brakującym) kb_schema_version — albo odwrotnie.

Jeśli nic nie jest opóźnione na żadnym froncie, dostaniesz „już aktualne — szablon vX, schemat wiki vY” i nic się nie zmieni.

Jeśli warstwa szablonu jest opóźniona, zobaczysz podział na to, co nowe (nic lokalnego do stracenia) i to, co zmienione (plik szablonu, którego lokalna kopia różni się — to może być ulepszenie szablonu albo twoja celowa zmiana, np. w AGENTS.md). Agent zapyta, plik po pliku albo wszystko naraz, czy wziąć wersję szablonu, zachować swoją, czy najpierw zobaczyć pełną różnicę — nic nie zostanie po cichu nadpisane.

Jeśli schemat twojej treści wiki jest opóźniony (w tym częsty przypadek starszej KB bez żadnego kb_schema_version — „niewersjonowanej” wiki), dostaniesz odrębne, wyraźne pytanie:

Agent: „Twoja treść wiki/ została zbudowana bez kb_schema_version (lub ze starszą wersją). Czy mam też zaktualizować wszystkie foldery i dane związane z wiki do nowego standardu?”

Jeśli powiesz tak, agent:

  • dodaje wszelkie brakujące elementy szkieletu (np. wiki/graph/index.md, który nigdy nie istniał, jeśli twoja KB poprzedza funkcję grafu),
  • uzupełnia brakujący frontmatter na istniejących stronach — tldr, confidence, quality, retention i tak dalej — bez przepisywania czegokolwiek z twojego tekstu; dodawana jest tylko struktura i metadane, nigdy treść merytoryczna strony,
  • potwierdza z tobą, zanim przypisze type do jakiejkolwiek strony, gdzie nie jest to oczywiste,
  • loguje każdą dotkniętą stronę w wiki/log.md jako wpis migracyjny, żeby było jasne, że zmiana była strukturalna, a nie nową wiedzą,
  • i podnosi kb_schema_version, gdy skończy.

Jeśli powiesz nie, agent nie dotknie niczego pod wiki/ — nawet kb_schema_version — więc następnym razem, gdy to uruchomisz, nadal zostanie to poprawnie oflagowane jako opóźnione, zamiast po cichu uznane za załatwione. Te dwie decyzje (warstwa szablonu, treść wiki) są niezależne: możesz zaakceptować jedną i odrzucić drugą.

Podobnie jak Ingest i Lint, na koniec pojawia się przypomnienie o przejrzeniu wyniku i uruchomieniu „sync changes” względem twojego własnego origin — repozytorium szablonu, z którym właśnie porównano, jest zwykle osobnym zdalnym repozytorium dla każdej KB innej niż własna kopia robocza projektu szablonu. Skill: .agents/skills/ckb-upgrade/SKILL.md.


6. Przykłady użycia

Zadawanie pytań

Zapytaj zwykłym językiem:

„Co wiemy o ryzyku migracji w Q3?”

Agent najpierw czyta wiki/index.md, żeby znaleźć odpowiednie strony. Jeśli istnieje pasujący zakres projektu pod wiki/projects/, przeszukuje najpierw ten zakres. Potem uruchamia retrieve_candidates.py, który zbiera sygnały dokładnych dopasowań, tldr, zakresu projektu, grafu i zaufania w jeden połączony ranking, rozszerza kontekst wokół dopasowanych sekcji, przechodzi po grafie wiedzy w poszukiwaniu powiązanych faktów i sięga do linked//libs/, jeśli lokalna wiki nic nie ma. Dostajesz odpowiedź opartą na tym, co faktycznie zostało spisane, a nie na domysłach.

Dwa szczegóły mają znaczenie dla użytkownika:

  • Przeszukuje też raw/inbox/. Materiał wrzucony dziś rano i jeszcze niezingestowany nadal może odpowiedzieć na twoje pytanie. Agent powie ci, kiedy odpowiedź pochodzi z niezingestowanego materiału, co jednocześnie sygnalizuje, że „Ingest" jest zaległy.
  • Odpowiedzi noszą własne zastrzeżenia. Jeśli strona stojąca za odpowiedzią przekroczyła okno świeżości, ma niską pewność albo została przeczytana z zapisanego indeksu konektora zamiast z żywego źródła, odpowiedź mówi o tym obok danego twierdzenia. Jeśli dwie strony są ze sobą sprzeczne, a żadna nie została jeszcze oznaczona jako zastąpiona, też o tym usłyszysz. Nie trzeba samodzielnie czytać frontmatteru, żeby wiedzieć, na ile ufać otrzymanej odpowiedzi.

Gdy nadal nie ma odpowiedzi, agent powinien powiedzieć, czego brakuje, i albo dodać/zaproponować krótki wpis w wiki/query-gaps.md, albo zasugerować najmniejsze źródło do wrzucenia do raw/inbox/.

Pytanie, kto się na czymś zna

„Kto zna się na ścieżce przywracania checkpointów?" / „Kto jest właścicielem usługi billingowej?"

Na te pytania odpowiada bezpośrednio graf wiedzy, a nie wyszukiwanie nazwisk po słowach kluczowych. Ingest zapisuje krawędź eksperctwa lub własności, gdy materiał źródłowy faktycznie pokazuje, że ktoś odpowiada na pytania w danym temacie albo ma zadeklarowaną odpowiedzialność za niego — a nie na podstawie obecności na spotkaniu czy nazwy stanowiska. Jeśli nikt nie ma jeszcze zapisanej krawędzi, agent wraca do tego, kogo zarchiwizowane źródła pokazują jako odpowiadającego na tego rodzaju pytania, i mówi ci, że wnioskuje, a nie raportuje.

Nauka z wiki

Szybki test tego, co wiesz — powiedz:

„Quiz me on the onboarding process.”

Agent zapyta o liczbę pytań i format (otwarte / jednokrotnego wyboru), a następnie przeprowadzi cię przez nie jedno po drugim, z natychmiastową informacją zwrotną i bieżącym wynikiem. Potem nic nie zostaje zapisane — to jednorazowy sprawdzian. .agents/skills/ckb-quiz/SKILL.md.

Prawdziwy kurs, rozłożony w czasie — powiedz:

„Teach me the wiki.” / „Teach me about the supplier onboarding process.”

Pierwsze wywołanie planuje program nauczania: pyta, czy chcesz jedną sesję czy serię, jak długa ma być każda sesja i jak często, oraz czy potrzebny jest plik kalendarza .ics z przypomnieniami. Następnie dzieli materiał na porcje wielkości sesji (raczej jedna krótka sesja więcej niż upychanie materiału) i pokazuje ci plan, zanim cokolwiek zapisze. Później powiedzenie „next lesson” (lub podobnie) wznawia naukę od miejsca, w którym się zatrzymała, ucząc za każdym razem inną techniką — pytania sokratejskie, analogie, przykłady rozwiązane krok po kroku, „naucz mnie z powrotem”, mnemotechniki — i krótko sprawdzając, co zostało w pamięci, zanim przejdzie dalej, powtarzając to, co niepewne. Plany i postępy żyją w outputs/teaching/<topic>/. .agents/skills/ckb-teach-me/SKILL.md.

Prowadzona kolejność czytania bez pełnego kursu — powiedz:

„Onboard me on the payments integration.” / „Where do I start with X?”

Dostajesz krótki przegląd plus uporządkowaną listę do przeczytania — najpierw podstawy, potem sam temat, potem to, co się na nim opiera — zbudowaną przez przejście po grafie wiedzy na zewnątrz. Tylko do odczytu; nic nie jest zapisywane. .agents/skills/ckb-onboard-me/SKILL.md.

Generowanie dokumentów / dzielenie się wiedzą poza wiki

Szybki skrót najwyższego poziomu — powiedz:

„Give me a project summary.” / „Where do things stand?”

Regeneruje PROJECT-OVERVIEW.md w katalogu głównym repozytorium: jedno- lub dwustronicowy przegląd, bieżący stan, otwarte działania ze statusem, ryzyka i założenia — w całości zsyntetyzowane z aktualnej wiki. Jest za każdym razem nadpisywany w całości, więc zawsze odzwierciedla to, co wiki mówi teraz. .agents/skills/ckb-project-summary/SKILL.md.

Eksport maszynowy dla innych narzędzi — powiedz:

„Export the wiki as OKF.”

Tworzy pakiet Open Knowledge Format w outputs/okf/, możliwy do skonsumowania przez ogólne narzędzia OKF (np. wizualizator grafu), bez potrzeby rozumienia bogatszego, własnego schematu tej wiki. .agents/skills/ckb-export-okf/SKILL.md.

Czytelna dla człowieka strona dokumentacji — powiedz:

„Export the wiki to Starlight.” / „Build a docs site from the wiki.”

Tworzy gotową do uruchomienia stronę Astro + Starlight w outputs/starlight/ — prawdziwe strony, prawdziwą nawigację, coś, co możesz hostować i dać komuś, kto nigdy nie widział wiki. .agents/skills/ckb-export-starlight/SKILL.md.

Dokument, który piszesz regularnie, z szablonu — powiedz:

„Prepare a new document using template status-report.” / „New status report from the template, for Atlas, last two weeks.”

Szablony leżą w templates/, każdy w jednym pliku Markdown. Nagłówki nadają dokumentowi kształt, a komentarz HTML pod każdym nagłówkiem mówi agentowi, co ma tam trafić: „zapytaj użytkownika”, „weź to ze strony projektu w wiki”, „trzy zdania, bez punktów”. Agent czyta szablon, zadaje ci wszystkie pytania naraz, resztę bierze z wiki i zapisuje gotowy dokument w outputs/documents/. Czego nie znalazł, zostawia w pliku jako linię TODO:, nigdy nie zmyśla. W zestawie jest jeden przykład, templates/status-report.md, a templates/README.md opisuje format na jednej stronie. Powiedz „make a template for a handover note”, a agent przygotuje szkic szablonu do twojej edycji. .agents/skills/ckb-document/SKILL.md.

Dokument Word, prezentacja lub PDF z zawartości wiki — nie ma dedykowanego skilla do tego, ale to normalna prośba:

„Turn the wiki page on our pricing model into a one-page Word doc I can send to legal.”

Agent czyta odpowiednie strony wiki i używa swoich ogólnych umiejętności tworzenia dokumentów (docx, pptx, pdf), aby wytworzyć plik — wiki pozostaje źródłem prawdy, dokument jest jednorazowym, pochodnym artefaktem.

Dodawanie informacji

W pełni opisane w §2 — w skrócie: wrzuć materiał do raw/inbox/ i powiedz „Ingest”, albo powiedz agentowi w rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.

Zapisywanie rozmowy

Każda nowa sesja dostaje tytuł, który agent sam wybiera na podstawie twojej pierwszej wiadomości (albo ten, który w niej podasz: „title: …”). Nikt cię nie pyta; pierwsza odpowiedź zaczyna się od jednej linijki z tytułem i przypomnieniem, że „rename this conversation to X” go zmienia. Tytuł nadaje nazwę zapisanemu transkryptowi i blokowi sesji w workload/. Jeśli ta linijka ci przeszkadza, powiedz „stop telling me the title” — agent przestawi announce_title: false w bloku conversations: w ckb.yaml; tytuł nadal jest ustawiany, tylko nie jest ogłaszany.

Powiedz „save this conversation”, a agent skopiuje transkrypt sesji do raw/saved-conversations/<RRRR-MM-DD>/ — oryginalny plik JSONL, który przechowuje Claude Code, bajt w bajt, plus czytelną wersję .md tej samej wymiany zdań (twoje wiadomości i odpowiedzi agenta dosłownie, wywołania narzędzi jako jednolinijkowe notatki, wyniki narzędzi skrócone, prywatne rozumowanie agenta pominięte). raw/saved-conversations/index.md wymienia wszystko, co zapisano. Wcześniejsze sesje tego samego projektu też można zapisać: poproś, a agent wyświetli listę do wyboru.

Zapisane rozmowy są celowo poza wiki. Na pytania agent nadal odpowiada wyłącznie z wiki/, linked/ i libs/ — transkrypt sam z siebie nigdy nie staje się dowodem. Możesz natomiast pytać o same rozmowy: „czy rozmawialiśmy o przełączeniu rozliczeń”, „co mówiliśmy o nazewnictwie w zeszłym tygodniu”, „jaka była moja prośba w sprawie eksportu”. Agent przeszukuje zapisane pliki .md i cytuje dokładną wymianę zdań wraz z datą.

Jeśli wolisz, żeby agent nie pytał, powiedz „save conversations automatically”: agent przestawi autosave: true w bloku conversations: w ckb.yaml i od tej pory każda sesja jest zapisywana na końcu bez pytania. „Turn off autosave” przestawia z powrotem. Przełącznik jest commitowany z repozytorium, więc dotyczy wszystkich pracujących w tej KB. Ponieważ jest to reguła, którą agent wykonuje na końcu sesji, sesja przerwana w połowie tury zostałaby pominięta — dlatego funkcja ma też połowę per maszyna: hook Stop Claude Code w .claude/settings.local.json (ignorowanym przez gita), który ponownie zapisuje transkrypt po każdej turze. Agent nigdy nie instaluje go samodzielnie. Przy włączonym autozapisie kontrola na starcie sesji zauważa maszynę, na której hooka brakuje (albo taką, na której autozapis wyłączono, a hook wciąż jest), i pyta raz, czy zmienić konfigurację tej maszyny; zmianę wprowadza tylko po twojej zgodzie. Każda maszyna otwierająca repozytorium zostaje zapytana raz.

Jeśli rozmowa zawiera wiedzę, która należy do wiki, skopiuj jej .md do raw/inbox/ i powiedz „Ingest” — kopię robisz ty, więc nic nie trafia do wiki bez twojego wyboru. Pamiętaj, że transkrypt jest dosłowny: zawiera wszystko, co agent wypisał w trakcie sesji (zawartość plików, wyniki poleceń), i staje się śledzonym plikiem w repozytorium. Skill: .agents/skills/ckb-add-conversation/SKILL.md.

Indeksowanie zewnętrznego źródła

Powiedz:

„Index external sources.” (lub „index libs”, „refresh the external index”)

To przeszukuje każdy libs/<name>/, który ma source.yaml (zobacz §1), i buduje krótki indeks tego, co znajdzie — po jednym wpisie na dokument, plus stronę przeglądową — w całości wewnątrz tego samego folderu libs/<name>/. Niczego pod wiki/ nie dotyka.

Przykład:

Tworzysz libs/finance-reports/source.yaml:

connector: sharepoint
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
description: "Wspólny folder raportów zespołu finansowego"
refresh_interval_days: 7

potem mówisz „Index external sources.”

Agent łączy się, korzystając z tego, co jest dostępne w danej sesji (w tym przypadku podłączonego narzędzia Microsoft 365), listuje dokumenty w tym folderze, czyta wystarczająco dużo z każdego, aby napisać krótkie podsumowanie, i tworzy libs/finance-reports/index.md (przegląd źródła) plus jedną stronę na dokument w libs/finance-reports/entities/, połączone krzyżowo przez libs/finance-reports/graph/edges.json. Loguje wszystko w libs/finance-reports/log.md, dzienniku odrębnym od wiki/log.md, ponieważ ten indeks jest ograniczony do jednego konektora, a nie wmieszany w twoją główną wiki. Na koniec przypomina o przejrzeniu wyniku i powiedzeniu „sync changes”, gdy wynik będzie ci odpowiadał.

Jeśli konektor wymaga autoryzacji (np. połączenie z SharePoint lub Google Drive, które nie jest jeszcze skonfigurowane), agent mówi, który to i gdzie go autoryzować, a potem kontynuuje z innymi skonfigurowanymi źródłami, zamiast zatrzymywać cały przebieg. Uruchom „index external sources” ponownie w każdej chwili, gdy źródło się zmieni — odświeża istniejące wpisy w miejscu, zamiast je duplikować, i nigdy nie usuwa strony dla dokumentu, który zniknął ze źródła (zamiast tego oflagowuje ją, żeby kolejny przebieg „Lint” zarchiwizował ją naturalnie). Skill: .agents/skills/ckb-index-external/SKILL.md.

Kto może go budować i gdzie jest współdzielony. Domyślnie nikt nie ma dostępu do zapisu w źródle typu konektor, dopóki tego nie zadeklaruje — to chroni zespół dziesięciu osób przed redundantnym skanowaniem tego samego folderu SharePoint. Powiedz:

„Make me the admin for finance-reports.”

To zapisuje osobisty libs/finance-reports/source.local.yaml z access: write — nigdy niecommitowany, nigdy niewidoczny dla współpracowników. Każdy bez tego pliku jest tylko-do-odczytu dla tego źródła: jeśli powie „index external sources”, agent w jego imieniu w ogóle nie dotknie żywego konektora. Zgłosi, co już zaindeksowano (albo powie wprost, że nic jeszcze nie zaindeksowano i kogo o to zapytać).

Jeśli zespół finansowy chce, żeby wszyscy czytali ten sam indeks, a nie każdy utrzymywał własną lokalną kopię w swojej własnej KB, administrator dodaje blok index: do współdzielonego source.yaml:

index:
  store: git
  location: "https://github.com/finance-team/index-cache.git"
  # ref: main   — opcjonalnie: przypina branch, tag albo podścieżkę w tym miejscu

Za pierwszym razem, gdy ktokolwiek uruchomi „index external sources” po dodaniu tego bloku, https://github.com/finance-team/index-cache.git jest puste. To oczekiwane, nie błąd. Każde uruchomienie sprawdza je najpierw: użytkownicy tylko-do-odczytu zobaczą „nic jeszcze nie opublikowano, zapytaj administratora”, a uruchomienie administratora je tworzy, bo uruchomienie z dostępem do zapisu zawsze przebudowuje indeks z żywego konektora i wypycha wynik do tej lokalizacji, niezależnie od tego, czy coś tam wcześniej było. Od tego momentu, kiedy ktokolwiek powie „index external sources”, agent najpierw pobiera to, co już zostało opublikowane. Użytkownicy tylko-do-odczytu na tym kończą; administrator dodatkowo przebudowuje indeks z żywego konektora i wypycha odświeżoną wersję do tej samej lokalizacji, żeby kolejne pobranie innej osoby ją uwzględniło. Pomiń blok index: (najprostsza konfiguracja, właściwy domyślny wybór dla jednego małego zespołu), a indeks leży bezpośrednio wewnątrz libs/finance-reports/ we własnym repozytorium tej KB, współdzielony w normalny sposób przez „sync changes”, dokładnie jak w prostym przykładzie powyżej.

Dodawanie opcjonalnego modułu

Niektóre możliwości mają sens tylko w części baz wiedzy, dlatego są dostarczane jako moduły w .agents/modules/: obecne w każdej kopii, nieaktywne, dopóki ich nie zainstalujesz. Powiedz:

  • „What modules are available”: lista modułów z informacją, czy są zainstalowane.
  • „Install the <name> module”: sprawdza, czego moduł potrzebuje, mówi ci o tym przed jakimkolwiek zapisem, a potem dodaje jego skille, foldery i ustawienia. Instalacja jest zapisana w ckb.yaml.
  • „Uninstall the <name> module”: usuwa jego skille i ustawienia. Twoja treść zostaje: strony wiki, które utworzył, klony w src/, specyfikacje.
Moduł Do czego służy Przewodnik
software Baza dokumentuje tworzone oprogramowanie: repozytoria jako ignorowane klony w src/, kod mapowany na encje wiki, specyfikacje z OpenSpec OPENSPEC.pl.md · README modułu
mcp Korzystanie z bazy w aplikacjach Claude (web/desktop/mobile), Claude Code lub innym agencie przez serwer MCP: wyszukiwanie, odczyt, dodawanie materiału, cofanie źle skierowanego zgłoszenia. Można podłączyć kilka baz naraz MCP.pl.md · README modułu

Skill: .agents/skills/ckb-module/SKILL.md.


7. Co jest generowane przez agenta, a co możesz edytować

Krótka wersja: lokalna wiki/ zawsze wygrywa w kaskadzie, co oznacza, że to twoja wiki — nic nie blokuje ci jej bezpośredniej edycji. „Zarządzane przez agenta” poniżej oznacza, że agent traktuje się jako odpowiedzialnego za utrzymanie tej treści strukturalnie poprawną (frontmatter, indeks, dziennik, graf) — a nie że nie wolno ci jej dotykać. Jeśli ręcznie edytujesz stronę wiki, dobrą praktyką jest uruchomienie potem „Lint”, żeby indeks/dziennik/graf pozostały spójne z wprowadzonymi zmianami.

Jest jeden wyjątek działający w drugą stronę. Na każdej stronie, którą agent regeneruje — indeks konektora, mapa kodu — wszystko, co napiszesz, zwykle ginie przy następnej przebudowie. Dlatego każda taka strona kończy się sekcją ## Notes, której żaden skill nigdy nie tknie:

## Notes

<!-- Twoje. Żaden skill tego nie nadpisuje. -->

Pisz tam, co chcesz — że ten dokument jest nieaktualny, że osoba w nim wymieniona już nie pracuje, kogo naprawdę zapytać. Treść jest przenoszona przez przebudowy co do bajtu. Wszystko, co napiszesz powyżej tego nagłówka na stronie generowanej, zostanie nadpisane.

Lokalizacja Kto zwykle to zapisuje Uwagi
raw/inbox/, luźne pliki w raw/ Tylko ty Agent tylko czyta, archiwizuje i przenosi rzeczy tutaj — nigdy nie tworzy treści w raw/ sam.
raw/archive/<data>/ Agent Automatycznie zarchiwizowana kopia tego, co trafiło do raw/inbox/, uporządkowana według daty ingestu. Nie umieszczaj tu plików ręcznie — pozwól, żeby zrobił to Ingest, tak by data i powiązanie z wpisem w dzienniku były poprawne.
linked/<name>/ Ty (tworzysz dowiązanie symboliczne) Wskazuje na rzeczywiste pliki innej KB, które żyją i są edytowane w tamtym repozytorium — nigdy tutaj. Agent nigdy nie może zapisywać wewnątrz linked/.
libs/<name>/ (kopia git, bez source.yaml) Ty (robisz git clone) Zamrożona kopia zewnętrznej KB. Aktualizujesz ją, ponownie pobierając to repozytorium samodzielnie, a nie ręcznie edytując pliki tutaj. Agent nigdy nie może zapisywać wewnątrz niej.
libs/<name>/source.yaml (konektor) Tylko ty Deklaruje konektor, lokalizację, opcjonalnie jak często ma być odświeżany (refresh_interval_days:) i opcjonalnie gdzie znajduje się współdzielony/wcześniej zbudowany indeks (index:). Agent go czyta, ale nigdy nie zapisuje — tak jak wszystko inne nadrzędne.
libs/<name>/source.local.yaml (konektor) Ty (albo agent, tylko gdy wyraźnie poprosisz o zostanie/przestanie bycia administratorem tego źródła) Osobiste, per-komputer ustawienie access: write/read — nigdy niecommitowane, nigdy niewidoczne dla innych. Brak = tylko do odczytu, domyślnie.
libs/<name>/{index.md,entities/,graph/,log.md} (konektor) Generowane przez agenta, możesz swobodnie edytować Własny indeks agenta dla tego jednego źródła konektora, budowany/odświeżany przez „Index external sources” — ale tylko jeśli masz lokalnie access: write; użytkownicy tylko-do-odczytu dostają pobraną kopię. Strukturalnie ta sama zasada jak przy wierszu wiki/ poniżej — śmiało popraw wpis ręcznie, a potem uruchom „Lint” (teraz sprawdza też indeksy oparte na konektorach, respektując ten sam podział odczyt/zapis). Ograniczone wyłącznie do tego konektora; nigdy nie wmieszane w wiki/. Przebudowę przetrwa tylko ## Notes — trzymaj tam wszystko, co chcesz zachować.
wiki/decisions/ Generowane przez agenta, edytuj ostrożnie Mechanicznie tak samo jak reszta wiki/, ale te strony są z założenia tylko do dopisywania: popraw swobodnie literówkę czy źle przypisane nazwisko, ale nie przepisuj kontekstu ani uzasadnienia decyzji pod późniejszy pogląd — zapisz zamiast tego decyzję zastępującą, żeby historia przetrwała.
wiki/ (strony, index.md, overview.md, log.md, error-book.md, entities/, graph/) Generowane przez agenta, możesz swobodnie edytować To jedyne miejsce, w którym zarówno agent zapisuje, jak i spodziewa się, że ty też możesz. Śmiało popraw stronę ręcznie — zachowaj tylko pola frontmatteru (lub zaktualizuj last_updated) i uruchom potem Lint, jeśli zmiana dotyczy czegoś, do czego odwołuje się indeks/graf/dziennik.
outputs/okf/, outputs/starlight/ Agent, w pełni regenerowane Nie edytuj ręcznie — to zignorowane przez git artefakty budowania, cicho nadpisywane przy każdym kolejnym eksporcie. Jeśli coś jest nie tak, popraw stronę wiki, z której to pochodzi, i wyeksportuj ponownie.
outputs/teaching/<topic>/ Agent, stan półtrwały plan.md/progress.md, które skill do nauczania czyta i zapisuje między sesjami. Możesz je oglądać kiedy chcesz; ręczna edycja jest możliwa, ale może pomieszać śledzenie „co dalej” — bezpieczniej powiedzieć agentowi, co chcesz zmienić, i pozwolić mu zaktualizować pliki.
PROJECT-OVERVIEW.md (katalog główny) Agent, w pełni regenerowany Nadpisywany w całości za każdym razem, gdy poprosisz o podsumowanie projektu. Nie edytuj go ręcznie — edytuj strony wiki, z których jest syntetyzowany, a potem zregeneruj.
templates/ Ty Szablony dokumentów: nagłówki plus komentarz pod każdą sekcją mówiący, co ma tam trafić i skąd. Agent je czyta, a nowy zapisuje tylko na twoją prośbę. Nic nie regeneruje ani nie resetuje tego katalogu. Zacznij od templates/status-report.md.
outputs/documents/ Agent (jeden plik na prośbę), możesz edytować Dokumenty przygotowane z szablonu. Śledzone w gicie i nigdy nie nadpisywane przez kolejne uruchomienie (powtórzona nazwa dostaje -2, -3). Edytuj je swobodnie; frontmatter zapisuje, z jakiego szablonu i z jakich stron wiki powstały.
workload/YYYY-MM-DD_<autor>_summary.md Agent (dopisywane co sesję) Bieżący dziennik tego, co działo się każdego dnia, jeden plik na osobę, więc współdzielone repozytorium zapisuje, kto co zrobił, i nigdy nie konfliktuje w tym miejscu. Autor to tożsamość gita sesji. Możesz go swobodnie czytać, edytować lub skracać — to dziennik dla ciągłości, a nie plik krytyczny dla działania systemu.
workload/ingest-reports/ Agent (jeden plik na ingest) Co zmienił każdy ingest: przyjęte pliki z raw/ i miejsce ich archiwizacji, zapisane decyzje, utworzone lub zaktualizowane encje i inne strony, krawędzie grafu oraz to, co nowy materiał potwierdził, rozszerzył lub z czym był sprzeczny. Zapisywany raz i nigdy nie przepisywany — przeczytaj go, aby przejrzeć ingest bez odtwarzania go z logu i diffa.
AGENTS.md / CLAUDE.md Ty (rzadko) To prompt systemowy, który definiuje zachowanie agenta w tym repozytorium. Edytuj go, jeśli chcesz zmienić globalną zasadę — np. schemat frontmatteru, format logowania czy kontrakt katalogów. Zmiany obowiązują od kolejnej sesji.
.agents/skills/*/SKILL.md Ty (zaawansowane/opcjonalne) Każdy plik definiuje jedną możliwość na żądanie. Możesz tworzyć nowe albo edytować istniejące, wzorując się na tych, które już tu są — to nie jest wymagane do normalnego użytku, ale nic ci w tym nie przeszkadza.
LICENSE, VERSION, README*, docs/, ckb.yaml Agent, możesz edytować Część tej samej warstwy szablonu co AGENTS.md — utrzymywane w synchronizacji przez ckb-upgrade, gdy zaakceptujesz aktualizację szablonu. ckb-upgrade zawsze zapyta, zanim dotknie linii praw autorskich w LICENSE albo któregokolwiek z tych plików, jeśli twoja lokalna kopia różni się od szablonu — dostosowanie tutaj (np. własna nazwa projektu czy posiadacz licencji) jest oczekiwana, nie jest błędem.

Gdzie leżą własne decyzje szablonu

docs/decisions/ przechowuje zapisy projektowe szablonu (D-0001, D-0002…) w tym samym formacie co wiki/decisions/, ale jako część warstwy szablonu: skille i dokumentacja się na nie powołują, więc muszą przetrwać ckb-reset i podróżować z ckb-upgrade. Decyzje twojej KB nadal trafiają do wiki/decisions/ przez „record a decision” — nigdy tutaj.

Sprawdzanie wydania szablonu

tests/smoke.sh uruchamia deterministyczne skrypty (lint_report.py, retrieve_candidates.py, save_conversation.py) na fixture'ach w tests/fixtures/ i porównuje wynik z tests/expected/. Uruchom go przed scaleniem czegokolwiek do test lub main; z --update po zamierzonej zmianie wyjścia skryptów. Folder tests/ istnieje tylko w repo szablonu: ckb-init go nie kopiuje, a ckb-upgrade go nie dostarcza, więc baza wiedzy nigdy go nie zawiera.

8. Szybki przegląd

Powiedz... Co się dzieje Skill
„Set up a new wiki like this one in <folder>” Zakłada świeżą, pustą KB z tym schematem ckb-init
„Pull the ckb repo into <folder> and set up the wiki” Klonuje repozytorium szablonu do katalogu roboczego, a potem zakłada z niego pustą KB ckb-init
„Ingest” / „Update the wiki” Przetwarza raw/inbox/ na ustrukturyzowane strony wiki/ ckb-ingest
„Zapisz decyzję: ...” / „zdecydowaliśmy ...” Zapisuje numerowany rekord decyzji pod wiki/decisions/ ckb-decide
„Co zdecydowaliśmy w sprawie X” / „kto zdecydował X” / „co jest otwarte” Odpowiada z zapisów decyzji, z autorem, datą i statusem ckb-decide
„Lint” Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może ckb-lint
„Zresetuj wiki” / „Zrób z tego czysty szablon” Destrukcyjne. Usuwa zgromadzoną wiedzę i odtwarza pusty szkielet, po inwentarzu i potwierdzeniu wpisaną frazą ckb-reset
„Sync changes” / „Sync with git” Commituje, pobiera, rozwiązuje konflikty, wypycha do origin ckb-sync-changes
„Save this conversation” Kopiuje transkrypt sesji (JSONL + czytelne .md) do raw/saved-conversations/<data>/; poza wyszukiwaniem ckb-add-conversation
„Did we discuss X” / „What did I tell you about X” Przeszukuje zapisane rozmowy i cytuje wymianę zdań ckb-add-conversation
„Save conversations automatically” / „Turn off autosave” Przestawia conversations.autosave w ckb.yaml; po włączeniu każda sesja jest zapisywana na końcu bez pytania ckb-add-conversation
„Rename this conversation to X” / „Stop telling me the title” Ustawia tytuł sesji (używany przez zapisany transkrypt i notatkę workload) / przestawia conversations.announce_title ckb-add-conversation
„Retract X” / „Undo the ingest of X” / „This went to the wrong KB” Pokazuje, co zbudowało źródło (strony, twierdzenia, krawędzie), a po twojej zgodzie usuwa dokładnie to; obsługuje prośby z raw/retractions/ ckb-retract
„Lint every week” / „Index external sources every 30 days, ask me first” Dodaje rutynę do ckb.yaml; zaległe rutyny wykonują się na starcie sesji, po twojej prośbie ckb-routine
„List routines” / „Which routines are due” / „Remove the weekly lint” Pokazuje, sprawdza lub usuwa rutyny ckb-routine
„What modules are available” / „Install the mcp module” Pokazuje lub instaluje opcjonalny moduł; nic w nim nie działa przed instalacją ckb-module
„Deploy the MCP server” / „Connect the KB to Claude web” Prowadzi przez udostępnienie bazy przez serwer MCP i dodanie jej jako konektora (moduł mcp) ckb-mcp
„Quiz me on X” Jednorazowy, punktowany sprawdzian wiedzy ckb-quiz
„Teach me the wiki” / „Teach me about X” Planuje i prowadzi rozłożony w czasie kurs ze śledzeniem postępu ckb-teach-me
„Onboard me on X” / „Where do I start with X” Krótka, prowadzona kolejność czytania po grafie ckb-onboard-me
„Give me a project summary” Regeneruje PROJECT-OVERVIEW.md ckb-project-summary
„Prepare a new document using template X” / „List templates” / „Make a template for X” Wypełnia szablon z templates/ twoimi odpowiedziami i treścią wiki, zapisuje go w outputs/documents/; wypisuje lub przygotowuje szablony ckb-document
„Export the wiki as OKF” Eksport maszynowy w outputs/okf/ ckb-export-okf
„Export the wiki to Starlight” Czytelna dla człowieka strona dokumentacji w outputs/starlight/ ckb-export-starlight
„Upgrade the wiki” / „Check for a newer template version” Sprawdza wersje szablonu i schematu wiki względem kanonicznego repozytorium, aktualizuje to, co zaakceptujesz ckb-upgrade
„Index external sources” / „Index libs” Buduje/odświeża samodzielny indeks dla każdego libs/<name>/ opartego na konektorze ckb-index-external
Po prostu zadaj pytanie Odpowiedź z wiki, przy użyciu kaskady indeks/TLDR/graf, z zastrzeżeniami gdy źródło jest nieaktualne lub sprzeczne ckb-retrieve
„Kto wie o X" / „Kto jest właścicielem X" Odpowiedź z krawędzi eksperctwa/własności w grafie ckb-retrieve