Fixes F1-F5 from the 2.0.0 script review: - removeprefix/removesuffix (3.9+) replaced; lint, retrieve and consolidate crashed on Python 3.8 with any graph edges - routines.py --mark wrote `last_run:DATE` (invalid YAML) and swallowed trailing comments into the value - export_okf.py --out must be inside outputs/ (it is rmtree'd); export_starlight.py image copies confined to wiki/assets/ - script counts in AGENTS.md, READMEs and manuals New tests/unit/ (stdlib unittest, run from smoke.sh): 3.8 API guard, routines round-trips, exporter containment, AGENTS.md consistency. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
46 KiB
Cascade Knowledge Base
Read this in: English | Polski
Repozytorium źródłowe (zawsze najbardziej aktualna wersja): git.wierzbowa.cloud/michal/ckb
Co zawiera ta baza wiedzy: zobacz ABOUT.pl.md (lub ABOUT.md) - jej cel, odbiorców, zakres, właścicieli i poziom poufności, opisane przez osobę, która ją prowadzi. Reszta tego README opisuje narzędzia Cascade KB, takie same w każdej bazie.
Warstwowa wiki zarządzana przez agenta, w której lokalna zawartość nadpisuje źródła nadrzędne (upstream) dostępne tylko do odczytu. Zbudowana na wzorcu LLM Wiki Karpathy'ego, rozszerzonym o skalowanie, zarządzanie cyklem życia i wsparcie dla wielu agentów.
Ten dokument to techniczny przegląd funkcji. Przewodnik zorientowany na zadania (jak stworzyć wiki, dodawać wiedzę, utrzymywać porządek, synchronizować się z innymi, z przykładami dla każdego przypadku użycia) znajdziesz w docs/MANUAL.pl.md (English). Zaczynasz? Przeczytaj jednostronicowy docs/QUICKSTART.pl.md (English).
Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny moduł
software dodaje repozytoria w src/ i pracę sterowaną specyfikacją — zobacz
docs/OPENSPEC.pl.md (English).
Aby korzystać z bazy w aplikacji webowej Claude lub innym kliencie MCP, opcjonalny
moduł mcp udostępnia ją przez MCP: wyszukiwanie i odczyt, zgłoszenia do
raw/inbox/ i cofanie źle skierowanego zgłoszenia, także przy kilku bazach
podłączonych naraz — zobacz docs/MCP.pl.md
(English). Aby zapisywać strony WWW, PDF-y i transkrypcje filmów
w raw/inbox/, opcjonalny moduł capture zapisuje każdą jako datowany zrzut
oznaczony jako niezaufany. Aby wysłać dokument do innej bazy, opcjonalny moduł
share korzysta ze wspólnego repozytorium git z jedną skrzynką na bazę;
odbiorca bierze dokument do raw/inbox/ i przetwarza go zwykłym ingestem.
Każdy moduł ma własne README w obu językach w
.agents/modules/<nazwa>/.
Pełny schemat strony oraz historię obu numerów wersji znajdziesz w docs/CHANGELOG.pl.md (English). Własne decyzje projektowe szablonu, czyli dlaczego wygląda tak, a nie inaczej, opisuje docs/decisions/.
Kanały wydawnicze
Repozytorium szablonu utrzymuje cztery gałęzie. Nie są wymienne:
| Gałąź | Czym jest | Kto powinien ją śledzić |
|---|---|---|
main |
Stabilna — wydany szablon | Wszyscy, domyślnie |
test |
Kandydat do wydania — walidowany przed scaleniem do main |
Każdy, kto pomaga walidować wydanie albo potrzebuje poprawki, która weszła, ale jeszcze nie została wydana |
experimental |
Rozwojowa — bieżąca praca, może być zepsuta albo wycofana | Osoby rozwijające sam szablon |
1.x |
Utrzymaniowa — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | KB, które potrzebują PowerShella albo nie mogą jeszcze przejść na 2.0 |
Zarówno ckb-init, jak i ckb-upgrade domyślnie używają main. Żeby użyć
innego kanału, powiedz którego: „zainicjuj z gałęzi test",
„sprawdź experimental pod kątem aktualizacji", „przełącz tę KB z powrotem
na kanał stabilny". Śledzona gałąź jest zapisana w ckb.yaml:
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
KB bez ckb.yaml (albo bez bloku template:) jest traktowana jako śledząca
main; każda KB sprzed tej konwencji i tak go śledziła.
Struktura katalogów
├── ABOUT.md # Co zawiera ta KB: cel, odbiorcy, zakres, właściciele - piszesz go ty
├── ABOUT.pl.md # To samo po polsku - wypełnij plik w języku swojej bazy
├── ckb.yaml # Manifest repozytorium: śledzona gałąź szablonu, zainstalowane moduły, ustawienia rozmów, rutyny
├── docs/ # Podręcznik, changelog, przewodnik OpenSpec i decisions/ — własne ADR-y szablonu
├── tests/ # Tylko w repo szablonu: baza-fixture + test dymny (tests/smoke.sh); nie kopiowany do KB
├── libs/ # Zewnętrzne źródła tylko do odczytu — kopie git (w .gitignore) LUB
│ # konfiguracje konektora (source.yaml) z własnym generowanym indeksem
├── linked/ # Zewnętrzne bazy wiedzy tylko do odczytu, montowane jako dowiązania symboliczne
├── outputs/ # Wygenerowane artefakty, eksporty, skompilowane pliki
│ └── documents/ # Dokumenty przygotowane z templates/
├── raw/ # Materiał źródłowy dostarczony przez użytkownika
│ └── inbox/ # Strefa zrzutu: nieprzetworzony materiał
├── templates/ # Twoje szablony dokumentów: nagłówki plus komentarz z instrukcją pod każdą sekcją
├── tmp/ # Pliki tymczasowe, cache (w .gitignore)
├── wiki/ # Lokalna, ustrukturyzowana wiki w markdown (zarządzana przez agenta)
│ ├── index.md # Tabela routingu z wyzwalaczami „Use when" + kb_schema_version
│ ├── overview.md # Czego dotyczy ta KB — treść, nie schemat
│ ├── log.md # Główny dziennik zmian (rollup)
│ ├── error-book.md # Błędy kompilacji i wyprowadzone ograniczenia
│ ├── query-gaps.md # Pytania bez odpowiedzi, cele przyszłego ingestu
│ ├── projects/ # Opcjonalne lokalne zakresy zapytań
│ ├── decisions/ # Numerowane, tylko-dopisywane zapisy decyzji + własny index.md i log.md
│ ├── entities/ # Typowane strony encji (osoby, projekty, koncepcje) + własny index.md
│ └── graph/ # Listy krawędzi i dane relacji + własny index.md
└── workload/ # Podsumowania sesji i decyzje
└── YYYY-MM-DD_<autor>_summary.md
Priorytet kaskady
Podczas wyszukiwania warstwy są sprawdzane w kolejności — pierwsze trafienie wygrywa:
wiki/ (najwyższy) ← agent zapisuje tutaj, zawsze wygrywa
linked/A/ (średni) ← zamontowane przez symlink wiki nadrzędne
linked/B/ (niski) ← zamontowane przez symlink wiki nadrzędne
libs/A/ (najniższy) ← kopie zewnętrznych baz wiedzy zarządzane przez git, albo własny generowany indeks konektora
Agent nigdy nie zapisuje do linked/ ani do libs/<name>/ będącego kopią
git. Aby poprawić treść nadrzędną, zapisz właściwą wersję w wiki/, a ona
automatycznie zyska pierwszeństwo. Jedynym wyjątkiem jest libs/<name>/
oparty na konektorze (zobacz „Konektory zewnętrznych źródeł i indeksowanie”
poniżej): agent zarządza jego generowanym indeksem tak samo jak wiki/.
Funkcje
Każda funkcja poniżej to skill w .agents/skills/. Skill ładuje się do
kontekstu dopiero po wywołaniu; AGENTS.md zawiera routing i reguły
nienegocjowalne, nic więcej.
Przepływ oparty na skrzynce odbiorczej (Inbox)
Wrzuć dowolny surowy materiał (notatki, artykuły, linki) do raw/inbox/ bez
porządkowania. Po komendzie „Ingest" (lub „Update the wiki") agent
przetwarza skrzynkę odbiorczą: wydobywa wiedzę, zapisuje ją w wiki/
i archiwizuje przetworzone elementy do raw/. Potem przypomina o przejrzeniu
wyniku i uruchomieniu „sync changes", żeby wypchnąć zmiany do origin, kiedy
wynik będzie Ci odpowiadał. Skill:
.agents/skills/ckb-ingest/SKILL.md.
Zanim cokolwiek zapisze, skrypt (dedup_inbox.py) zgłasza pliki ze skrzynki,
które już zingestowano: identyczne co do bajtu lub co do tekstu kopie plików z
archiwum, pliki, których skrót strona już cytuje, linki do adresów URL, które
strona już cytuje, oraz duplikaty w samej skrzynce. Potem agent się
melduje: dla każdego źródła mówi, jak je rozumie, które strony zmieni i z
czym jest sprzeczne. Nic nie zostaje zapisane, dopóki nie odpowiesz. „Ingest
in batch” pomija meldunek. Tekst owinięty w <private>…</private> nigdy nie
jest ingestowany.
Dla długich rozmów, notatek ze spotkań, transkryptów lub eksportów czatu ingest używa strukturalnej destylacji, zamiast traktować cały plik jako jedną niezróżnicowaną bryłę: wyszukiwalne pytanie, krótkie podsumowanie, rozwiązanie lub decyzja, odniesienia do systemów/kodu, zaangażowane osoby oraz fragmenty o wysokiej wartości, które warto móc znaleźć osobno.
„Wysoka wartość" to jawny test, a nie ocena uznaniowa, bo inaczej każdy
fragment wygląda na wart zachowania, a strona staje się drugą kopią
transkryptu. Fragment zasługuje na własną wyszukiwalną sekcję tylko wtedy,
gdy zawiera termin rzadki w całej wiki (sprawdzane przez rg -c: ma to być
wyróżniający uchwyt wyszukiwania, a nie słowo obecne już na dwudziestu
stronach), ma około 200 znaków lub więcej i jest potwierdzony przez coś dalej
w materiale, co się z nim zgadza, działa na jego podstawie lub go koryguje.
Jeśli fragment nie spełnia choćby jednego warunku, treść nadal trafia na
stronę, tylko do podsumowania, a nie jako osobna jednostka. Wydzielone
fragmenty zabierają ze sobą nagłówek nadrzędny lub pytanie wątku, żeby dały się jednoznacznie
czytać samodzielnie.
Leniwie ładowany indeks z wyzwalaczami „Use When"
wiki/index.md to tabela routingu. Każdy wpis ma kolumnę Use when z
listą słów kluczowych wyzwalających. Agent najpierw czyta indeks (pozostaje
w kontekście), dopasowuje słowa kluczowe do zadania i ładuje tylko pasujące
strony. Indeks pozostaje mały; strony, na które wskazuje, nie muszą.
Warstwa zapytań oparta na TLDR
Każda strona zawiera jednozdaniowe podsumowanie tldr we frontmatterze.
Podczas zapytania agent najpierw czyta TLDR-y. Jeśli TLDR już odpowiada na
pytanie, agent w ogóle nie ładuje pełnej treści. Łańcuch odwoławczy: TLDR →
treść → surowe źródło.
Lokalne zakresy projektów
Dla powracających zespołów, klientów, systemów lub inicjatyw wiki może
trzymać zwykłe strony zakresów w formacie Markdown pod wiki/projects/.
Strona zakresu wymienia strony wiki, encje, źródła z raw/archive/,
konektorowe libs/, wyjścia i obszary grafu, które należy przeszukać
najpierw dla danego projektu. Daje to to samo, co przestrzeń robocza
projektu w większym systemie wyszukiwania, ale zakres pozostaje lokalny,
przejrzysty i edytowalny w dowolnym edytorze tekstu.
Zakresy zawężają tylko pierwsze przejście. Jeśli wyszukiwanie w zakresie nie odpowiada na pytanie, agent wraca do pełnej kaskady.
Lokalne wyszukiwanie hybrydowe
Gdy routing po indeksie/TLDR nie wystarcza, agent może połączyć kilka lokalnych sygnałów przed odpowiedzią:
- dokładne wyszukiwanie tekstu przez
rgdla komunikatów błędów, komend, flag, nazw plików, nazw hostów, identyfikatorów zgłoszeń i innych literalnych tokenów — również wraw/inbox/, więc materiał wrzucony godzinę temu i jeszcze nie zingestowany nadal może odpowiedzieć na pytanie (i sygnalizuje, że ingest jest zaległy) - dopasowania semantyczne/encyjne z tytułów stron, TLDR-ów, zakresów projektów i relacji w grafie
- metadane świeżości i pewności, dzięki którym nieaktualne lub słabe strony są traktowane ostrożnie
- rozszerzenie kontekstu wokół dopasowanej sekcji, aby odpowiedzi były osadzone w sąsiadujących nagłówkach i akapitach, a nie w samotnym urywku
- wyszukiwanie BM25 po sekcjach przez SQLite FTS5 (biblioteka standardowa),
każda sekcja indeksowana z tytułem strony, ścieżką nagłówków i
tldrjako kontekstem, więc kandydat wskazuje trafione sekcje i swój koszt w tokenach
Zebranie i połączenie tych sygnałów jest mechaniczne, więc wykonuje je
skrypt .agents/skills/ckb-retrieve/scripts/retrieve_candidates.py, tak
samo jak detekcję w lincie; agent czyta jego ranking i wykonuje osąd
(deduplikacja według twierdzenia, przerankowanie względem dosłownego pytania,
weryfikacja źródła). Każdy sygnał tworzy własną listę rankingową, a listy są
następnie łączone, a nie rozstrzygane wyborem ulubionego sygnału: każdy
kandydat zbiera weight / (k + rank) zsumowane po listach, na których
występuje, więc strona na trzecim miejscu w trzech listach wygrywa ze stroną
pierwszą w jednej. k wynosi 10, celowo mniej niż zwykle cytowane 60.
Wartość 60 jest dostrojona do wyszukiwarek zwracających setki kandydatów i spłaszcza wszystkie wyniki do
niemal identycznych wartości przy kilkunastu, które daje lokalna wiki.
Zapytania o literalne tokeny podnoszą wagę listy dokładnych dopasowań,
ponieważ żadne podobieństwo tytułu nie powinno wyprzedzić trafienia w dokładny
ciąg, który ktoś wklejił.
Połączeni kandydaci są następnie deduplikowani według twierdzenia — strona
wiki, plik z raw/archive/, który cytuje, i strona konektora wskazująca na
nią to trzy trafienia dla jednego faktu, nie trzy źródła — i przerankowani w
skali 0–10 według tego, jak dobrze odpowiadają na dosłownie zadane pytanie, a
nie jak dobrze pasują do jego sformułowania. Ten sam agent, świadome drugie
przejście, bez osobnego modelu.
Wynik jest wewnętrznie normalizowany jako pakiet dowodowy: ścieżka źródła, dopasowane twierdzenie, data/świeżość, pewność/jakość, wskazówki o relacjach lub zakresie oraz informacja, z których sygnałów każdy kandydat został połączony. Nie potrzeba serwera, bazy wektorowej ani osobnego klienta.
Zastrzeżenia w odpowiedziach
Metadane, które wiki już śledzi, są podawane w samej odpowiedzi, a nie tylko
sprawdzane przy jej budowaniu. Gdy strona stanowiąca podstawę odpowiedzi
przekroczyła freshness_window_days, ma niską confidence/quality, opiera
się na niezingestowanym materiale z raw/inbox/ lub została sprawdzona
względem zapisanego w pamięci indeksu konektora, a nie żywego źródła,
odpowiedź mówi o tym obok twierdzenia, którego to dotyczy. Konflikty między
dwiema aktywnymi stronami są ujawniane tak samo, nawet jeśli żadna nie ma
jeszcze superseded_by. Chodzi o to, żeby agent nie odpowiadał pewnie z
nieaktualnej strony, nie przekazując tej informacji dalej.
Konsolidacja i podsumowania tematów (na żądanie)
„Consolidate” zapisuje raport samych propozycji w outputs/reports/: grupy
tematów (i czy każda strona w wiki/topics/ istnieje i jest aktualna),
kandydatów do scalenia, brakujące linki, strony nieaktualne i stare wpisy
dziennika. Nic w wiki się nie zmienia, dopóki nie zaakceptujesz danej
pozycji. Zaakceptowane strony tematów podsumowują, co KB zawiera o jednym
temacie, i wymieniają strony członkowskie ze skrótami, więc lint oznacza temat,
gdy któryś członek się zmieni. Skill: .agents/skills/ckb-consolidate/SKILL.md.
Profile i lekcje
Każda osoba może mieć profil w workload/profiles/ (rola, jak z nią
pracować), wypisywany w podsumowaniu startu jej własnej sesji i niczyjej
innej. „Remember this” albo „lesson: …” zapisuje lekcję: osobistą w profilu,
dla całej KB w wiki/lessons.md, gdzie czeka na przegląd drugiej osoby.
Pierwszeństwo: AGENTS.md, potem ## Rules projektu, potem profil. Skill:
.agents/skills/ckb-profile/SKILL.md.
Zachowane odpowiedzi
Odpowiedź, która wymagała prawdziwej pracy, można na prośbę zachować w
outputs/answers/ ze skrótami w ## Sources i sekcją ## Gaps. Lint oznacza
zachowaną odpowiedź, której źródła się zmieniły, a to samo pytanie zadane
ponownie aktualizuje ją zamiast tworzyć duplikat. Wprowadzenie odpowiedzi do
wiki odbywa się zwykłym ingestem, nigdy bezpośrednim zapisem. Fragmenty
prywatne (<private>) nigdy nie są cytowane.
Wyszukiwanie ekspertów i właścicieli
„Kto wie o X" i „kto jest właścicielem X" to bezpośrednie zapytania do grafu,
a nie zgadywanie po pełnym tekście. Ingest zapisuje krawędzie
has_expertise_in, gdy ktoś wykazuje się odpowiadaniem na pytania lub
wyjaśnianiem decyzji w danym temacie, oraz krawędzie owns dla zadeklarowanej
odpowiedzialności za system, obszar lub decyzję — oba wyłącznie na podstawie
wykazanych dowodów, nigdy wnioskowane z obecności na spotkaniu czy ze
stanowiska. Gdy krawędzi jeszcze nie ma, wyszukiwanie wraca do dowodów
autorstwa i mówi, które z dwóch stanowiło podstawę odpowiedzi, bo domniemany
ekspert to słabsze twierdzenie niż zapisany.
Zapisy decyzji
wiki/decisions/ zawiera jedną numerowaną stronę na decyzję
(NNNN-slug.md): co postanowiono, przez kogo (decided_by), kiedy
(decided_on), dlaczego, jakie alternatywy odpadły i czego decyzja dotyczy
(affects). Pole status
(proposed/accepted/rejected/superseded/reversed) mówi, czy decyzja
faktycznie obowiązuje, a opcjonalna data review_on oznacza ją do przeglądu.
Strony decyzji są tylko do dopisywania. Gdy wybór się zmienia, nowa
decyzja zastępuje starą — supersedes/superseded_by ustawiane są po obu
stronach, status starej zmienia się na superseded lub reversed, a jej
pierwotny kontekst i uzasadnienie pozostają nietknięte. Dzięki temu na
pytanie „dlaczego jest tak, jak jest?" da się odpowiedzieć po latach, a
„używamy Postgresa" zamienia się w „używamy Postgresa, a wcześniej MySQL-a, zmienione we
wrześniu z powodu raportowania". decided_by i affects stają się też
krawędziami grafu, więc „kto zdecydował o X" i „jakie decyzje dotyczą Y" to
bezpośrednie wyszukania. Skill ckb-decide zapisuje decyzje i odpowiada na
pytania o nie; ckb-lint sprawdza ich strukturę (słownik statusów, wymagane
daty, dwustronne zastępowanie, unikalne numery, zaległe przeglądy).
Luki w zapytaniach
Jeśli kaskada nie potrafi odpowiedzieć na pytanie, agent zapisuje lub proponuje
krótki wpis w wiki/query-gaps.md: o co pytano, gdzie szukał i jakie
najmniejsze źródło lub strona zamknęłaby lukę. Nieudane wyszukiwania stają
się wtedy sygnałem zapotrzebowania dla następnego ingestu, zamiast przepadać
w historii czatu.
Schemat frontmatteru strony
Każda strona wiki używa frontmatteru YAML. Pole type jest wymagane; reszta
jest opcjonalna:
---
type: concept # WYMAGANE. Otwarty ciąg znaków: person, project, concept, library, decision, playbook, ...
resource: https://... # Kanoniczny URI do autorytatywnego zewnętrznego źródła, które opisuje ta strona
tldr: Jednozdaniowe podsumowanie zoptymalizowane pod odczyt przez LLM
confidence: 0.0–1.0 # Wynik potwierdzenia przez źródła
quality: 0.0–1.0 # Samoocena (poniżej 0.7 → oflagowane)
supersedes: path/to/old.md
superseded_by: path/to/new.md
last_updated: YYYY-MM-DD
freshness_window_days: 90 # Liczba dni, po których treść uznaje się za nieaktualną
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e # skrót źródła, z którego zbudowano tę stronę
source_checked: YYYY-MM-DD # kiedy ten skrót był ostatnio zweryfikowany
review: draft|reviewed|needs_update # z reviewed_by / reviewed_on (1.6)
tags: retries, billing # tylko tagi z wiki/tags.md (1.6)
---
- type — wymagane; niezarejestrowany ciąg znaków, nowe wartości są zawsze poprawne, czytelnicy tolerują nierozpoznane
- resource — opcjonalny wskaźnik do żywego/autorytatywnego źródła, oddzielony od własnego komentarza wiki
- confidence — ustawiane przy zapisie, zanika z czasem, wzmacniane przez nowe źródła
- quality — samoocena przy zapisie, strony poniżej 0.7 oznaczane do przeglądu
- supersedes / superseded_by — gdy nowa informacja zastępuje starą, połącz je
- freshness_window_days — strony starsze niż to okno są oznaczane podczas lintowania
- retention — strony o niskim priorytecie są archiwizowane po 2× oknie świeżości
- source_fingerprint / source_checked — skrót materiału, z którego zsyntetyzowano stronę, oraz data ostatniego potwierdzenia. Okno świeżości to przypuszczenie, że źródło mogło się zmienić; skrót to fakt, czy się zmieniło, a lint sprawdza go mechanicznie.
- review / reviewed_by / reviewed_on (1.6) — czy stronę sprawdził
człowiek: ingest zapisuje
draft, polecenie „mark X as reviewed” ustawiareviewed, a późniejsza zmiana tego, co strona twierdzi, ustawianeeds_update - tags (1.6) — płaska lista sprawdzana względem własnego słownika KB
w
wiki/tags.md; wyszukiwanie może po niej filtrować
Zastrzeżone sekcje treści
Trzy nagłówki ## mają w całej KB ściśle określone znaczenie:
| Sekcja | Co zawiera |
|---|---|
## Sources |
po jednym punkcie na źródło, każdy ze skrótem |
## Crux |
dosłowne cytaty z tych źródeł — dowód, nigdy parafraza |
## Notes |
pisane przez człowieka i chronione: żaden skill ich nie nadpisuje |
## Rules |
tylko na stronach zakresu projektu: zasady zespołu dla tego projektu, chronione jak ## Notes |
Gdy dwa źródła się nie zgadzają, a nikt nie zdecydował, które ma rację,
ingest wpisuje na stronę znacznik > CONTRADICTION: … zamiast wybierać
zwycięzcę; lint wypisuje go, dopóki człowiek go nie rozstrzygnie.
## Crux pozwala odpowiedzieć na pytanie ze strony zamiast z archiwum:
streszczenie może po cichu odpłynąć od źródła, cytat albo wciąż się z nim
zgadza, albo nie. ## Notes daje odwrotną gwarancję — na stronach
regenerowanych przez agenta (indeksy konektorów, mapy kodu) to jedyne miejsce,
w którym adnotacja przetrwa kolejną przebudowę.
Sam wiki/index.md dodatkowo zawiera kb_schema_version (obecnie "1.7"),
deklarujący, według której wersji tego schematu wiki została napisana —
zwiększaj wersję pomniejszą dla dodatkowych opcjonalnych pól, główną dla
zmian łamiących kompatybilność.
Ekstrakcja encji i graf wiedzy
Podczas ingestu agent wydobywa typowane encje (osoby, projekty, biblioteki,
koncepcje, systemy) i zapisuje je jako strony w wiki/entities/. Typowane
relacje są zapisywane w wiki/graph/edges.json przy użyciu zamkniętego
słownika, w którym każdy czasownik jest zdefiniowany przez pytanie, na jakie
odpowiada (patrz wiki/graph/index.md) — strukturalne (part_of, uses,
depends_on, produces, configures, validates, implements, caused,
contradicts, supersedes) oraz łączące osoby z tematami
(has_expertise_in, owns). Zapytania mogą przechodzić po grafie,
aby odkrywać powiązane strony (np. „co zależy od Redis?") albo bezpośrednio
odpowiadać na „kto wie o X".
Rekurencyjna konwencja indeksu i dziennika
Każdy podkatalog wiki/, który grupuje wiele stron (entities/, graph/,
przyszłe foldery tematyczne), utrzymuje własny index.md (zwykłą listę
linków bez frontmatteru), dzięki czemu nawigacja po podkatalogach pozostaje
leniwa, zamiast wymagać pełnego skanowania. Podkatalog może też utrzymywać
własny log.md, gdy ma już wystarczająco dużo niezależnej historii;
wiki/log.md pozostaje rollupem na poziomie głównym i nigdy nie powtarza
zmiany już zapisanej w dzienniku podkatalogu, tylko dostaje
jednolinijkowy wpis POINTER. wiki/decisions/log.md to jedyny dziennik
podkatalogu w bazowym szkielecie, a Reguła B w AGENTS.md wymienia go jako
wyjątek.
Konektory zewnętrznych źródeł i indeksowanie (na żądanie)
Folder libs/<name>/ obsługuje drugi sposób zasilania, obok istniejącej
kopii git: mały plik libs/<name>/source.yaml pisany przez użytkownika, który deklaruje
żywe zewnętrzne źródło — folder SharePoint, folder Google Drive, zwykły
URL albo inny konektor — którego nie chcesz w pełni kopiować lokalnie:
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 # opcjonalne, domyślnie 30
refresh_interval_days ustala częstotliwość osobno dla każdego źródła (folder zmieniający
się codziennie zasługuje na krótsze okno niż kwartalne archiwum, które prawie
nie drgnie) i ustawia freshness_window_days nadawane generowanym stronom
tego źródła. Zarówno „index external sources", jak i „Lint" raportują źródło
zaległe względem tej wartości i mówią o ile, żeby użytkownik z dostępem tylko
do odczytu wiedział, kogo zapytać, zamiast po cichu polegać na kopii zaległej
o trzy tygodnie.
Powiedz „index external sources", a agent go przeskanuje, dopasowując
connector do dowolnego żywego narzędzia dostępnego w danej sesji
(połączonego narzędzia MCP do Microsoft 365/Google Drive, albo WebFetch
dla zwykłego adresu URL), i zbuduje samodzielny, generowany indeks wewnątrz
tego samego libs/<name>/ — index.md/entities//graph//log.md,
odzwierciedlający strukturę wiki/ opisaną w Rekurencyjnej konwencji
indeksu i dziennika powyżej, ale ograniczony wyłącznie do tego jednego
konektora. Ten indeks nie jest wmieszany
w główne wiki/entities//wiki/graph/edges.json — pozostaje oddzielony na
warstwie kaskady libs/, tak samo jak pliki sklonowanej przez git KB. Sam
source.yaml pozostaje wyłącznie twój, agent nigdy go nie zapisuje.
Do tego dochodzą dwa rozszerzenia:
- Współdzielone, wcześniej zbudowane indeksy.
source.yamlmoże dodać opcjonalny blokindex:, który deklaruje, gdzie już zbudowany indeks się znajduje — repozytorium git albo zasób współdzielony, np. ścieżka sieciowa lub inna lokalizacja dostępna przez konektor:
Każde uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już tam jest, zostaje pobrany. Większość osób czyta to, co już jest, zamiast budować indeks samodzielnie. Jeśli go tam jeszcze nie ma, to normalny stan przy pierwszym uruchomieniu, a nie błąd: najbliższe uruchomienie przez użytkownika z dostępem do zapisu tworzy go tam i publikuje, bez osobnego kroku „inicjalizacji".index: store: git # git | shared location: "https://github.com/org/finance-index-cache.git" ref: main # opcjonalnie — branch, tag albo podpowiedź co do podścieżki w tym miejscu - Odczyt vs. zapis, per użytkownik, per źródło. Czy ten użytkownik
może przebudować indeks (a nie tylko czytać pobraną/
opublikowaną wersję) to odrębne, lokalne, ignorowane przez git
libs/<name>/source.local.yaml— domyślnie tylko do odczytu. Ustawienieaccess: writew tym pliku włącza dany komputer/użytkownika jako administratora tego źródła, dzięki czemu zespół może wyznaczyć jedną lub dwie osoby do utrzymywania źródła, podczas gdy reszta czyta tylko wynik — bez zbędnego, wielokrotnego przebudowywania i bez potrzeby, żeby każdy użytkownik miał własną autoryzację konektora.
Skill: .agents/skills/ckb-index-external/SKILL.md.
Podwójne linkowanie (Wikilinks + Markdown)
Każde odwołanie krzyżowe używa zarówno [[Wikilinks]] (kompatybilnych z
Obsidian), jak i standardowych linków [markdown](path.md). Działa w
widoku grafu Obsidian, renderowaniu GitHub i narzędziach CLI. Odwołania do
treści nadrzędnych używają pełnych ścieżek względnych: linked/<name>/...
lub libs/<name>/.... Odwołania wewnątrz wiki preferują ścieżki bezwzględne
względem katalogu głównego projektu (/wiki/entities/foo.md) zamiast
względnych, dzięki czemu linki przetrwają późniejsze przenoszenie plików.
Samonaprawiający się lint
Okresowo (lub na żądanie) agent sprawdza kondycję wiki:
- Zgodność (conformance) — oznacza każdą stronę bez poprawnego
frontmatteru lub pola
type - Świeżość — oznacza strony starsze niż ich
freshness_window_days - Zanik pewności (confidence decay) — zmniejsza
confidencedla stron niewzmacnianych nowymi źródłami - Przegląd retencji — archiwizuje strony
retention: lowstarsze niż 2× okno świeżości - Wykrywanie supersesji — znajduje sprzeczności, łączy stare→nowe
- Wykrywanie sierot — znajduje strony bez linków przychodzących
- Spójność grafu — weryfikuje, czy wszystkie krawędzie wskazują na istniejące encje
- Spójność indeksu/dziennika — weryfikuje, czy każdy podkatalog ma index.md i czy żadna zmiana nie jest podwójnie logowana
- Skróty źródeł — przelicza skrót każdego cytowanego źródła i oznacza strony, których dowód faktycznie się zmienił, a nie tylko się zestarzał
- Dosłowność sekcji Crux — oznacza cytat, którego nie ma już w źródle, na które się powołuje
- Częstotliwość konektorów — oznacza konektorowe źródło, którego
generowany indeks jest zaległy względem
refresh_interval_days, wraz z informacją o ile - Sekrety i fragmenty prywatne — oznacza postaci danych
uwierzytelniających w commitowanym tekście i fragmenty
<private>, które trafiły dowiki/, zamaskowane, nigdy nie naprawiane automatycznie; nieszkodliwe dopasowania trafiają do.secrets-allowopartego na skrócie linii - Zachowane odpowiedzi — oznacza odpowiedzi w
outputs/answers/, których źródła się zmieniły - Budżet kontekstu — szacuje warstwę ładowaną zawsze (
AGENTS.mdplus opisy skilli) i oznacza przekroczeniebudget.always_loaded_tokenswckb.yaml - Księga błędów (Error Book) — zapisuje systemowe problemy wraz z przyczyną i naprawą
Automatycznie naprawia to, co może (uszkodzone linki, brakujące odnośniki
zwrotne, nieaktualne flagi), i przypomina o przejrzeniu wyniku oraz
uruchomieniu „sync changes", aby wypchnąć zmiany do origin, gdy będziesz
z nich zadowolony. Skill: .agents/skills/ckb-lint/SKILL.md.
Rozwiązywanie konfliktów (Supersesja)
Gdy nowa informacja przeczy istniejącej stronie, agent dodaje linki
supersedes / superseded_by. Stara strona zostaje, oznaczona jako
nieaktualna. Kontrola wersji obejmuje więc wiedzę, a nie tylko pliki.
Ocena jakości
Każda strona przy zapisie otrzymuje wynik jakości (0.0–1.0), oparty na strukturze, cytowaniu źródeł i spójności z resztą wiki. Strony poniżej 0.7 są oznaczane do przeglądu lub przepisywane podczas kolejnego lintowania.
Księga błędów (Error Book)
Systematyczne błędy (uszkodzone linki, problemy z formatowaniem,
sprzeczności między stronami) są zapisywane w wiki/error-book.md wraz z
przyczyną, zastosowaną naprawą i ograniczeniem wielokrotnego użytku
zapobiegającym powtórce. Naprawa dwuwarstwowa:
- Warstwa 1 — deterministyczna automatyczna naprawa problemów strukturalnych
- Warstwa 2 — przebieg rozumowania agenta dla problemów semantycznych/między stronami
Konwencje sesji
To reguły, których agent przestrzega na podstawie AGENTS.md, a nie haki
wpięte w narzędzie: nic w .claude/ nie uruchamia się samo. Jeśli chcesz,
by któraś była wymuszana mechanicznie, musisz dodać ją jako hook Claude Code
albo zaplanowanego agenta.
- Start sesji → wybór tytułu rozmowy na podstawie pierwszej wiadomości
i podanie go w jednej linijce (chyba że
conversations.announce_title: false); jedno wywołaniesession_start.pyzapisuje tytuł i wypisujegit status, jednolinijkowy wyniklint_report.py --quick, zaległe rutyny i ostatni blok najnowszego podsumowania workload; sugestiackb-sync-changeslubckb-linttylko wtedy, gdy któreś coś zgłosi; zaległe rutyny wykonywane po pierwszej prośbie; przy włączonym autozapisie rozmów sprawdza też, czy ta maszyna ma hookStopw ignorowanym przez gita.claude/settings.local.json, i pyta przed jego zainstalowaniem. Podsumowanie wymienia też otwarte wątki: nieodhaczone pozycje- [ ]pod### Open threadsw notatkach workload - Hook startu sesji (opcjonalny, Claude Code) → przy
session.start_hook: truehookSessionStartna tej maszynie wstrzykuje to samo podsumowanie przed pierwszą wiadomością i ponownie po każdym kompaktowaniu; agent pyta przed jego zainstalowaniem - Koniec sesji → dopisanie do
workload/; powtórzenie sprawdzenia niezsynchronizowanych zmian; po sesji z realną pracą jednorazowe pytanie, czy zapisać rozmowę (ckb-add-conversation) — zapis tylko po „tak" albo bez pytania, gdy wckb.yamlustawionoconversations.autosave: true - Każda tura dotykająca KB → notatka w
workload/(Reguła D) - Błędne lub źle skierowane źródło →
ckb-retractusuwa je i dokładnie to, co wniosło (strony, twierdzenia, krawędzie), po pokazaniu planu; prośby zraw/retractions/(np. od serwera MCP) są zgłaszane przy ingestii - Pytanie bez odpowiedzi → wpis w
wiki/query-gaps.md, jedyny zapis, który należy dockb-retrieve; odpowiedzi nigdy nie są automatycznie zapisywane jako strony - Lint na żądanie lub przez rutynę → „Lint" uruchamia pełną kontrolę;
„lint every week" robi z tego rutynę w
ckb.yaml, która odpala się na pierwszym starcie sesji po upływie okresu (ckb-routine)
Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC)
Wiki rośnie dzięki rzeczywistym niepowodzeniom agenta, a nie dzięki doborowi treści z góry:
- Agent nie potrafi odpowiedzieć → identyfikuje brakującą wiedzę
- Proponuje minimalną encję/stronę wypełniającą lukę
- Użytkownik zatwierdza lub dostarcza materiał źródłowy
- Kolejny ingest ją uwzględnia
Podsumowania sesji
Po każdej akcji konwersacyjnej agent dopisuje do
workload/YYYY-MM-DD_<autor>_summary.md — jeden plik na osobę na dzień,
nazwany i opisany tożsamością gita, pod którą działa sesja. Daje to
ciągłość między sesjami, przeglądalną historię ewolucji bazy wiedzy, a we
współdzielonym repozytorium zapis, kto co zrobił, bez konfliktów scalania w
workload/. Ta sama tożsamość trafia do linii **Author:** każdego wpisu
w wiki/log.md. Agent czyta ostatnie podsumowanie na starcie sesji,
niezależnie od autora, aby kontynuować od miejsca, w którym skończono.
Dziennik zmian
Każda modyfikacja wiki jest natychmiast logowana w dokładnie jednym
dzienniku, w kolejności odwrotnie chronologicznej: wiki/decisions/log.md
dla wszystkiego pod wiki/decisions/, wiki/log.md dla reszty, z
jednolinijkowym POINTER w dzienniku głównym, gdy zmianę wchłania dziennik
decyzji. Lint zgłasza zmianę zapisaną w obu.
Eksport OKF (na żądanie)
Wiki można wyeksportować do outputs/okf/ jako pakiet zgodny z
Open Knowledge Format
v0.1, który odczyta dowolne ogólne narzędzie OKF (np. referencyjny
wizualizator grafu Google), bez naruszania bogatszego wewnętrznego schematu
(confidence/quality/retention/supersedes/podwójne linkowanie),
którego OKF natywnie nie rozumie. Całe przekształcenie (przemapowanie
frontmatteru, przepisanie linków, regenerację indeksów i dzienników oraz
sprawdzenie zgodności z OKF na własnym wyjściu) wykonuje deterministyczny
skrypt Python (scripts/export_okf.py), więc eksport jest odtwarzalny, a nie
wyprowadzany na nowo strona po stronie; agent uruchamia skrypt i przekazuje
raport. outputs/okf/ jest w .gitignore: to w pełni
regenerowalny artefakt budowania, więc każda maszyna/narzędzie regeneruje go
na żądanie zamiast przenosić go w historii gita. Skill:
.agents/skills/ckb-export-okf/SKILL.md.
Eksport Starlight (na żądanie)
Wiki można też wyeksportować do formatu dla Astro + Starlight
w outputs/starlight/, co daje czytelną dla człowieka stronę dokumentacji,
w odróżnieniu od eksportu OKF, przeznaczonego dla maszyn i narzędzi.
Deterministyczny skrypt Python (scripts/export_starlight.py) obsługuje
przemapowanie frontmatteru, zwijanie podwójnych linków, rozwiązywanie
wikilinków, kopiowanie zasobów i generowanie paska bocznego; agent zadaje
tylko dwa pytania konfiguracyjne (zakres eksportu: pełny uruchamialny
szkielet vs. tylko treść; czy dołączyć strony meta dziennika/księgi błędów)
i przekazuje raport skryptu. Skill: .agents/skills/ckb-export-starlight/SKILL.md.
Podobnie jak outputs/okf/, outputs/starlight/ jest w .gitignore jako
regenerowalny artefakt budowania.
Dziennik decyzji (na żądanie)
Powiedz „zapisz decyzję: ..." (albo po prostu „zdecydowaliśmy ..."), żeby
utworzyć numerowany rekord decyzji; zapytaj „co zdecydowaliśmy w sprawie X",
„kto to zdecydował", „które decyzje są wciąż propozycjami" albo „co zastąpiło
decyzję 3", żeby dostać ją z powrotem wraz z autorem, datą i statusem.
Zapisywanie zbiera brakujące pola w jednej turze zamiast wywiadu, ustawia
powiązania zastępowania w obu kierunkach, dodaje krawędzie grafu
decided_by/affects i zapisuje do wiki/decisions/log.md. Zobacz
.agents/skills/ckb-decide/SKILL.md.
Prowadzone wycieczki wprowadzające (na żądanie)
Poproś „oprowadź mnie po X" (lub „od czego zacząć z X", „krótka wycieczka
po X"), aby otrzymać krótką kolejność czytania w trybie tylko do odczytu:
akapit wprowadzający plus uporządkowaną listę stron wiki do przeczytania,
zbudowaną przez przejście po grafie wiedzy na zewnątrz od najlepiej
pasującej strony (najpierw podstawy, potem sam temat, potem to, co się na
nim opiera). Nigdy nie zapisuje do wiki/. Zobacz
.agents/skills/ckb-onboard-me/SKILL.md.
Podsumowanie projektu (na żądanie)
Poproś o „podsumowanie projektu" (lub „jak stoją sprawy", „wprowadź mnie
w bieżący stan projektu"), aby zregenerować PROJECT-OVERVIEW.md w
katalogu głównym repozytorium — jedno- lub dwustronicowy skrót (przegląd,
stan projektu, działania i ich status, ryzyka, założenia) zsyntetyzowany w
całości z bieżącej zawartości wiki/ i jej grafu wiedzy. Zawsze
nadpisywany w całości przy ponownym uruchomieniu, nigdy nie dopisywany
ręcznie. Zobacz .agents/skills/ckb-project-summary/SKILL.md.
Dokumenty z szablonów (na żądanie)
Dokumenty, które piszesz regularnie, trzymaj jako szablony w templates/:
plik Markdown, w którym nagłówki nadają kształt, a komentarze HTML mówią
agentowi, co ma trafić do każdej sekcji - zapytaj użytkownika, przeczytaj tę
stronę wiki, zmieść się w trzech zdaniach. „Prepare a new document using
template status-report" czyta szablon, zadaje wszystkie pytania naraz, resztę
bierze z wiki i zapisuje wynik w outputs/documents/, z frontmatterem
wskazującym szablon i użyte strony. Luki stają się liniami TODO:, nie
domysłami. W zestawie jest jeden przykład, templates/status-report.md;
format opisuje templates/README.md. Zobacz
.agents/skills/ckb-document/SKILL.md.
Synchronizacja gita (na żądanie)
Na żądanie agent uzgadnia historię gita tego repozytorium z jego zdalnym
repozytorium origin: commituje lokalne zmiany, pobiera i scala zdalne,
pokazuje Ci konflikty plik po pliku do rozwiązania, a na koniec
automatycznie wypycha wynik (push). Przed stagingiem sprawdza, czy to, co ma
zostać zacommitowane, nie zawiera sekretów, i zatrzymuje się, jeśli coś
znajdzie. Powiedz „sync changes", aby to uruchomić.
Nie ma to nic wspólnego z „Ingest", który zamienia raw/inbox/ na strony
wiki/ i nie dotyka gita. Samo „sync" zawsze oznacza gita. Skill:
.agents/skills/ckb-sync-changes/SKILL.md.
Zapisane rozmowy (na żądanie)
Powiedz „save this conversation", a transkrypt sesji zostanie skopiowany do
raw/saved-conversations/<RRRR-MM-DD>/ - oryginalny plik JSONL, który
przechowuje Claude Code, plus czytelna wersja .md - i wpisany do index.md
w tym folderze. Zapisane rozmowy pozostają poza wyszukiwaniem: na pytania
agent nadal odpowiada wyłącznie z wiki. Możesz natomiast pytać o same
rozmowy („czy rozmawialiśmy o X", „co ci mówiłem/mówiłam o Y") i dostać zacytowaną
dokładną wymianę zdań. Aby przenieść rozmowę do wiki, skopiuj jej .md do
raw/inbox/ i powiedz „Ingest". Powiedz „save conversations automatically",
aby przełączyć conversations.autosave w ckb.yaml - od tej pory każda
sesja jest zapisywana na końcu bez pytania. Każda sesja zaczyna się od
tytułu, który agent nadaje jej na podstawie pierwszej wiadomości i podaje
w pierwszej odpowiedzi; nazywa on zapisany transkrypt, a „stop telling me
the title" wycisza tę linijkę. Skill:
.agents/skills/ckb-add-conversation/SKILL.md.
Tryb quizu (na żądanie)
Poproś o odpytanie z wiki („quiz me on X", „sprawdź moją wiedzę"), aby
uzyskać jednorazowy, punktowany sprawdzian wiedzy: agent czyta odpowiednie
strony, generuje pytania otwarte lub jednokrotnego wyboru oparte na
konkretnych faktach z wiki, przeprowadza je jedno po drugim z natychmiastową
informacją zwrotną i bieżącym wynikiem, a na koniec podaje werdykt.
Bezstanowy: nic nie jest zapisywane między uruchomieniami. Zobacz
.agents/skills/ckb-quiz/SKILL.md.
Prowadzony program nauczania (na żądanie)
Poproś o naukę z wiki („teach me the wiki", „naucz mnie o X", „przeprowadź
sesję nauki"), aby otrzymać stanowy kurs zamiast jednorazowego quizu.
Pierwsze wywołanie go planuje: określa zakres materiału (opcjonalnie
uzupełniając cienkie miejsca z internetu, wyraźnie oznaczone jako
nieautorytatywne), pyta, czy ma to być jedna sesja, czy rozłożona w czasie
seria (czas trwania, częstotliwość, opcjonalne przypomnienia kalendarzowe
.ics), dzieli treść na porcje wielkości sesji (woli dodać sesję, niż
upychać materiał) i zapisuje zaakceptowany plan oraz tracker postępu w
outputs/teaching/<topic>/. Kolejne wywołania porównują plan z postępem,
uczą kolejnej porcji materiału inną techniką za każdym razem (pytania
sokratejskie, analogie, przykłady rozwiązane krok po kroku, „naucz mnie z
powrotem", mnemotechniki, ...), sprawdzają utrwalenie wiedzy i powtarzają
słabe punkty przed przejściem dalej. Nigdy nie zapisuje do wiki/. Zobacz
.agents/skills/ckb-teach-me/SKILL.md.
Wyjaśnienia metodą Feynmana (na żądanie)
Powiedz „Feynman me on X” (albo „wyjaśnij mi porządnie X”, „czego nie
rozumiem?”), a agent wyjaśni jedną stronę wiki słowami, które zna
dwunastolatek, pod każdym fragmentem podając link do sekcji, z której
pochodzi, a potem nazwie każde miejsce, w którym wyjaśnienie się rozrzedziło,
i przypisze je do jednej z trzech grup: luka na stronie, luka w jej
źródłach albo luka u wyjaśniającego. Agent nigdy nie łata luki własną
wiedzą. Następnie prosi cię, żebyś sam wyjaśnił jeden fragment, i schodzi
poziom głębiej. Gdy nie podasz pojęcia, proponuje strony robocze (draft),
oparte na jednym źródle albo nieaktualne. Sesja trafia do
outputs/teaching/feynman/; luka w źródłach trafia do wiki/query-gaps.md
tylko po twojej zgodzie. Zobacz .agents/skills/ckb-feynman/SKILL.md.
Szybki start
-
Opcjonalnie: zainstaluj Pythona 3.8+. Osiem skilli uruchamia skrypt w Pythonie (tylko biblioteka standardowa); bez niego kontrola na starcie sesji przechodzi na zapasowy skrypt bash (na Windows: Git Bash), lint i wyszukiwanie działają w wolniejszym trybie ręcznym, a eksporty są niedostępne. Kroki dla poszczególnych systemów: docs/MANUAL.pl.md → Wymagania wstępne.
-
Zamontuj nadrzędne bazy wiedzy:
ln -s /path/to/other-kb ./linked/my-upstream git clone https://github.com/org/external-kb ./libs/external-kbAlbo, dla żywego źródła, którego nie chcesz w pełni kopiować lokalnie, umieść zamiast tego
libs/<name>/source.yaml(zobacz „Konektory zewnętrznych źródeł i indeksowanie" powyżej) i powiedz „index external sources". -
Wrzuć surowy materiał do
raw/inbox/(notatki, linki, artykuły). -
Poleć agentowi „Ingest" — przetworzy skrzynkę odbiorczą, skonsultuje kaskadę, wydobędzie encje i zapisze ustrukturyzowany markdown w
wiki/. -
Zadawaj pytania — agent używa indeksu do routingu, TLDR-ów do szybkich odpowiedzi i grafu do odkrywania relacji.
-
Okresowo proś o „Lint" — agent sprawdzi kondycję wszystkiego, naprawi, co może, i zgłosi problemy.
Pliki instrukcji dla agenta
| Plik | Cel |
|---|---|
AGENTS.md |
Pełna instrukcja dla dowolnego agenta kodującego AI |
CLAUDE.md |
Dowiązanie symboliczne do AGENTS.md, automatycznie wykrywane przez Claude Code |
Skille znajdują się w jednej wspólnej lokalizacji, .agents/skills/, dzięki
czemu każde narzędzie agentowe respektujące tę konwencję je odnajduje.
.claude/skills to dowiązanie symboliczne do .agents/skills — Claude Code
widzi ten sam zestaw skilli bez drugiej kopii do utrzymywania w
synchronizacji.
Wskazówki
- Nadrzędne bazy wiedzy (
linked/i kopie git wlibs/) nigdy nie są modyfikowane przez agentów. Wyjątkiem jestlibs/<name>/oparty na konektorze (ten zsource.yaml) — agent zarządza jego generowanym indeksem, ale tylko dla użytkownika, który lokalnie ustawił sobieaccess: write(zobacz następny punkt); kopia każdego innego użytkownika pozostaje tylko do odczytu. - Aby poprawić treść nadrzędną, zapisz poprawną wersję w
wiki/— ona wygrywa. - Używaj
raw/inbox/dla wszystkiego, co nieprzetworzone; agent czyści ją podczas ingestu. - Tabela routingu
wiki/index.mdto najważniejszy plik — utrzymuj go na bieżąco. - Confidence, quality i freshness pozwalają ufać właściwej treści i oznaczać resztę do przeglądu.
tmp/jest w.gitignore. Podobnie większośćlibs/, z jednym podziałem: kopia git wlibs/<name>/pozostaje ignorowana, natomiast konektorowylibs/<name>/ma śledzonesource.yamloraz generowaneindex.md/entities//graph//log.md. Ten indeks to zsyntetyzowana wiedza warta udostępnienia przez „sync changes", a nie artefakt budowania.libs/<name>/source.local.yamlto wyjątek w wyjątku: osobisty stan maszyny, nigdy nie synchronizowany.outputs/jest śledzony, aleoutputs/okf/ioutputs/starlight/nie. Każdy z nich da się odtworzyć zwiki/na żądanie, więc nie ma czego uzgadniać w historii gita. Ręcznie utrzymywane artefakty woutputs/commituj normalnie.outputs/teaching/też jest ignorowany. Plany nauki, postęp sesji i sesje Feynmana są osobiste, nie są współdzieloną treścią KB.
Wersja i licencja
Aktualna wersja szablonu: VERSION. Licencja: Apache License 2.0.