Dzielenie się wiedzą — wersjonuj dowody, nie triki

Dzielenie się wiedzą w inżynierii wspomaganej AI, tak jak ocenia je CTO Scorecard Q20, polega na zamienianiu lekcji z przyjętych zmian, nieudanych przebiegów agenta, ustaleń z review i incydentów w wersjonowane artefakty z właścicielem i źródłem. Maksimum wymaga aktualizacji z realnych dowodów i ćwiczenia na regularnych sesjach.

Ta strona jest dla tech leada, który dba o to, żeby konfiguracja agentów w zespole działała, i dla CTO, który odpowiada na Q20. Sytuacja: w czerwcu ktoś spędził popołudnie na ustaleniu, dlaczego agent generuje migracje ze złym formatem znacznika czasu, i wrzucił rozwiązanie do wątku na czacie. We wrześniu nowa osoba trafia na ten sam błąd, wątku już nie ma, a zespołowe wiki wciąż poleca dwa polecenia, które narzędzia w międzyczasie przemianowały.

Co daje ci wersjonowana pętla wiedzy

Tabelę punktacji Q20 i jej związek z pytaniem o dzielenie się wiedzą w Tech Lead Scorecard.
Tabelę routingu, która kieruje każdą lekcję do jednego miejsca: pliku instrukcji, skilla, hooka, testu, runbooka albo zapisu decyzji.
Szablon rekordu lekcji z właścicielem, pochodzeniem, dowodem i warunkiem wycofania, gotowy do commitu.
Pułapki poszczególnych narzędzi, przez które lekcje zostają w pamięci jednej osoby, oraz test w trybie headless, który dowodzi, że świeża sesja agenta znajduje wspólną wersję.
Agendę 30-minutowej cyklicznej sesji, trzy prompty do skopiowania, miary, które pokazują, że pętla działa, i typowe awarie.

Jak CTO Scorecard Q20 ocenia dzielenie się wiedzą?

Scorecard pyta: „Jak zespół dzieli się wiedzą o AI tooling (skills, prompty, MCP, sztuczki)?” i punktuje cztery odpowiedzi.

Punkty	Odpowiedź	Dowód, który ją uzasadnia
0	Nie ma — Slack ad hoc	Brak.
1	Kanał Slack/Discord, brak archiwum	Kanał, który ludzie przewijają wstecz w poszukiwaniu odpowiedzi.
2	Wewnętrzny doc / wiki z wzorcami	Strona z promptami i konfiguracjami, zwykle bez właścicieli i dat.
3	Wersjonowane wzorce z ownerami i dowodami, aktualizowane po review oraz incydentach i ćwiczone na regularnych sesjach zespołu	Indeks wiedzy, rekordy lekcji powiązane z awariami, z których powstały, wyniki testów wykrywalności i notatki z dwóch ostatnich sesji.

Liczy się przejście z 2 na 3. Wiki zapisuje to, w co ktoś kiedyś wierzył. Wersjonowany artefakt z właścicielem, źródłem i testem da się sprawdzić, zmienić przez review i usunąć, gdy nowe wydanie narzędzia czyni go nieaktualnym.

Tech Lead Scorecard zadaje to samo pytanie z perspektywy zespołu („Czy prowadzicie wewnętrzny knowledge-sharing o workflow AI?”) i najwyżej ocenia odpowiedź „Regularny rytm + zapisane artefakty”. Pętla opisana na tej stronie spełnia oba warunki.

Skieruj każdą lekcję do jednego kanonicznego miejsca

Wiedza zespołu zwykle zaczyna się psuć od lekcji zapisanej w złym miejscu: twardej reguły spisanej jako rada w pliku Markdown albo osobistej preferencji skopiowanej do pliku instrukcji każdego narzędzia. Kieruj lekcję według tego, co musi się stać, żeby zaczęła działać.

Gdy lekcja to…	Jej miejsce to…	Strona kanoniczna	Dowód, że działa
Fakt o repozytorium potrzebny w każdej sesji (polecenia, chronione ścieżki, konwencje)	Wspólny rdzeń instrukcji, `AGENTS.md` albo `CLAUDE.md`	Wspólne reguły agentów	Świeża sesja poprawnie ją cytuje
Procedura dla powtarzalnego zadania	Skill (pakiet `SKILL.md`)	Wspólne skills	Przypadki testowe (fixtures) pozytywne i negatywne dla wyzwalacza
Coś, co nigdy nie może się zdarzyć	Hook, reguła uprawnień albo bramka CI	Zarządzanie wspólnymi hookami	Test zablokowanej akcji
Klasa defektu, która prześlizgnęła się przez review	Test, sprawdzenie właściwości albo reguła lintera	Taksonomia awarii	Kontrola kończy się błędem na wadliwym commicie
Reakcja operacyjna (rollback, rotacja poświadczeń)	Runbook	Pętla utrzymania	Próba na sucho przez kogoś, kto go nie pisał
Wybór między opcjami (narzędzie, model, workflow)	Zapis decyzji	Decyzje architektoniczne	Punkt odniesienia, wynik i data przeglądu
Nowy, nieprzetestowany pomysł	Do sprawdzenia: demo albo temat sesji	Ta strona, „Prowadź cykliczną sesję dzielenia się wiedzą o AI”	Staje się jednym z wierszy powyżej albo odpada

Dwie zasady utrzymują tabelę w ryzach. Po pierwsze, wybieraj najwcześniejszą kontrolę, która łapie problem: lekcja, która może być testem, nie powinna być zdaniem w AGENTS.md, bo model może zignorować zdanie, a CI nie zignoruje testu. Po drugie, każda lekcja ma dokładnie jedno miejsce; inne pliki linkują do niego zamiast je kopiować.

Napisz rekord lekcji, który zespół może sprawdzić

Rekord lekcji to metadane, dzięki którym każdy w minutę oceni, czy dana wiedza wciąż jest aktualna. Trzymaj jeden rekord na lekcję w docs/agent-knowledge/, a listę w docs/agent-knowledge/INDEX.md, żeby było jedno miejsce do szukania.

---
id: KN-014
title: Migrations must use UTC timestamps in the file name
owner: "@payments-lead"
status: active            # draft | active | superseded | retired
home: AGENTS.md#migrations   # the one canonical artifact this lesson lives in
source: incident INC-2291 (2026-06-12), PR #4410 review finding
evidence: tests/migrations/test_filename_format.py fails on commit 3f9c2e1
tools_checked: Claude Code 2.1.283, Codex CLI 0.157.1
last_verified: 2026-09-26
review_by: 2026-12-26
retire_when: the migration generator enforces UTC itself
---

## What happened
The agent generated migrations named with local time; two ran out of order in staging.

## What changed
Added the rule to AGENTS.md#migrations and a filename test that fails on local-time names.

## How we know it holds
The test runs in CI on every PR. The discovery probe asks a fresh session
for the migration naming rule and checks the answer quotes AGENTS.md.

Najważniejsze są cztery pola. source wiąże lekcję z prawdziwą awarią, więc nikt nie utrzymuje reguły, której powód zaginął. home wymusza jedno kanoniczne miejsce. evidence wskazuje test albo kontrolę, która kończy się błędem, gdy lekcja zostanie złamana. retire_when z góry mówi, co uczyni lekcję zbędną — dzięki temu zespół może ją usunąć bez dyskusji.

Dodaj wpis w CODEOWNERS dla docs/agent-knowledge/ oraz dla każdej ścieżki z instrukcjami i skillami, żeby każda zmiana wspólnej wiedzy przechodziła review jej właściciela. Dla datowanych faktów o narzędziach, od których zależą lekcje (wersje, flagi, ustawienia domyślne), i dla sprawdzenia w CI, które wyłapuje wycofane terminy, użyj konfiguracji z utrzymywania zespołu na bieżąco, zamiast budować drugą.

Uruchom pętlę dzielenia się wiedzą o AI w pięciu krokach

Łap sygnał tam, gdzie się pojawia. Daj zespołowi jedno wejście: etykietę knowledge na zgłoszeniach albo krótki formularz, który je tworzy. Warto łapać powtarzające się pytanie, nieudany lub porzucony przebieg agenta, ustalenie z review, które agent powtarza, defekt, który uciekł na produkcję, blokadę w onboardingu i wynik eksperymentu. Sygnał to jedna linijka plus link do przebiegu, PR-a albo incydentu.
Skieruj go do jednego miejsca w ciągu tygodnia. Właściciel wejścia stosuje tabelę routingu powyżej albo zamyka sygnał jako „nietrwały” z uzasadnieniem. Nieskierowane sygnały starsze niż dwa tygodnie są pierwszym punktem następnej sesji.
Zmieniaj artefakt przez pull request z dowodem. PR aktualizuje artefakt docelowy i dodaje lub aktualizuje rekord lekcji. Zawiera przypadek odtwarzający błąd (reprodukcję) albo kontrolę kończącą się błędem, a CI uruchamia fixtures skilli i testy hooków, których zmiana dotyczy. Zatwierdza właściciel z CODEOWNERS.
Udowodnij wykrywalność w świeżej sesji. Uruchom test wykrywalności (następna sekcja) w każdym zatwierdzonym narzędziu. Lekcja, której świeża sesja agenta nie potrafi znaleźć, nie istnieje dla następnej osoby, niezależnie od tego, co mówi wiki.
Przeglądaj i wycofuj zgodnie z harmonogramem. Najpóźniej w dniu review_by właściciel ponownie sprawdza dowód i albo przedłuża datę, albo ustawia status: retired i usuwa tekst z miejsca docelowego. Zastąpione lekcje przez jedno wydanie wskazują swojego następcę, potem znikają.

Nie pozwól, żeby osobista pamięć stała się źródłem zespołu

Claude Code i Codex przechowują część wiedzy per osoba i to tam lekcje zespołu po cichu utykają. Zasada jest ta sama we wszystkich trzech narzędziach: osobista pamięć to szkic, a wszystko, czego potrzebuje zespół, trafia do repozytorium przez review.

Sprawdzone na Claude Code 2.1.283.

Claude Code czyta pliki CLAUDE.md i potrafi „accumulate learnings automatically with auto memory” (dokumentacja pamięci). Auto memory jest lokalna dla maszyny: leży w ~/.claude/projects/<project>/memory/ i nie jest współdzielona między maszynami ani przez repozytorium, więc zapisana tam lekcja pomaga tylko osobie, która trafiła na błąd. /memory pokazuje pliki CLAUDE.md, włącza i wyłącza auto memory oraz otwiera jej folder; przejrzyj, czego nauczyła się auto memory, i przenieś części ważne dla zespołu do pliku instrukcji repozytorium albo do skilla przez PR.

Claude Code czyta AGENTS.md tylko wtedy, gdy projekt nie ma CLAUDE.md, i dopiero od v2.1.277 na kanale latest; kanał stable był 2026-09-26 na wersji 2.1.274. Jeśli wspólnym rdzeniem jest AGENTS.md, trzymaj cienki CLAUDE.md, który do niego odsyła, jak opisują wspólne reguły agentów.

Sprawdzone na Codex CLI 0.157.1.

Funkcja memories w Codeksie jest stabilna, ale domyślnie wyłączona (codex features list), a /memories konfiguruje jej użycie i generowanie. Jeśli zespół ją włączy, traktuj ją jak auto memory w Claude Code: osobisty szkic, który zasila pull requesty, a nie wspólne źródło.

Większą pułapką jest zaufanie. Od Codeksa 0.150.0 niezaufany projekt nie dostarcza swojego projektowego AGENTS.md, więc osoba, która odrzuci pytanie o zaufanie, pracuje bez żadnej ze wspólnych lekcji, a nic głośno nie zawodzi. Uruchamiaj test wykrywalności w zaufanym checkoucie.

Sprawdź, czy świeża sesja agenta znajduje lekcję

Przeczytanie rekordu lekcji nie dowodzi, że agent ją zastosuje. Test wykrywalności zadaje świeżej sesji w trybie tylko do odczytu pytanie, na które lekcja odpowiada, i porównuje odpowiedź z rekordem. Uruchom go w terminalu z katalogu głównego repozytorium i zachowaj wynik jako dowód do kroku 4.

# Claude Code 2.1.283: plan mode does not edit files; the session is not saved to disk
# needs CLAUDE.md, or AGENTS.md on the latest channel (v2.1.277+)
claude -p --permission-mode plan --no-session-persistence \
  "How must new database migration files be named in this repository? Quote the file and line that says so. If no instruction covers it, answer NOT FOUND." \
  > probe-KN-014-claude.txt

# Codex CLI 0.157.1: read-only sandbox, no session files, final answer to a file
# run in a trusted checkout: untrusted projects don't load AGENTS.md (0.150.0+)
codex exec --sandbox read-only --ephemeral -o probe-KN-014-codex.txt \
  "How must new database migration files be named in this repository? Quote the file and line that says so. If no instruction covers it, answer NOT FOUND."

Test jest zaliczony, gdy odpowiedź podaje regułę i cytuje miejsce wskazane w polu home albo plik, z którego jest ono importowane (liczy się CLAUDE.md, który wskazuje na AGENTS.md). NOT FOUND, parafraza wyczytana z kodu albo cytat z nieaktualnej strony wiki oznaczają porażkę, a poprawka należy do właściciela. Uruchamiaj testy dla każdej lekcji zmienionej w danym wydaniu, a dla całego indeksu raz na kwartał.

Prompty do skopiowania: utrzymanie bazy wiedzy

Uruchamiaj je w zatwierdzonym narzędziu z katalogu głównego repozytorium. Działają tak samo w Claude Code, Codeksie i Cursorze.

Read the failed run, review comment, or incident I paste below, then read AGENTS.md (or CLAUDE.md), .agents/skills/, docs/agent-knowledge/INDEX.md, and the CI configuration.
1. State the lesson in one sentence.
2. Say whether existing guidance already covers it; if so, quote it and explain why it did not prevent the failure.
3. Choose the single home for the lesson: instruction file, skill, hook or permission rule, test or lint rule, runbook, or decision record. Prefer the earliest automated control. Explain the choice in two sentences.
4. Draft the change to that home and a lesson record with id, owner, source, evidence, tools_checked, review_by, and retire_when.
Do not copy the lesson into more than one file. Do not edit anything until I accept the plan.

Read docs/agent-knowledge/INDEX.md and every lesson record it lists. For each record, report in a table:
- review_by in the past, or last_verified older than 90 days
- a home that no longer exists or no longer contains the lesson
- the same rule stated in more than one file (quote both locations)
- an evidence check that no longer exists in the test suite or CI
- a tool command, flag, or model name, with the tool version the record says it was checked against
- no source, or a source that is only a chat message
Do not change any file. End with the five records most likely to mislead a new engineer, and why.

Act as an engineer who joined today and has only this repository. Without reading docs/agent-knowledge/, work out how to add a database migration that backfills a new column.
List every file you read, in order, and the rule you took from each. Then compare your answer with docs/agent-knowledge/KN-014.md and report: whether you found the rule, how many files it took, any instruction that contradicted it, and the link or sentence that would have led you there sooner.
Do not edit anything.

Zamień KN-014 i zadanie z migracją na lekcję z własnego indeksu. Trzeci prompt sprawdza ścieżkę, którą przechodzi człowiek, czego test w trybie headless nie robi.

Prowadź cykliczną sesję dzielenia się wiedzą o AI

Najwyższa odpowiedź w scorecardzie wymaga, żeby wzorce były „ćwiczone na regularnych sesjach zespołu”. Co dwa tygodnie prowadź 30-minutową sesję wiedzy z rotującym prowadzącym, oddzielną od slotu na demo.

Minuty	Punkt	Wynik
5	Otwarte sygnały starsze niż tydzień	Każdy skierowany albo zamknięty z uzasadnieniem
10	Jedna lekcja z ostatnich dwóch tygodni pokazana na prawdziwej awarii: przebieg, poprawka, sprawdzenie	Zespół potwierdza miejsce docelowe albo je zmienia
10	Jedna lekcja do przeglądu: jej test wykrywalności i sprawdzenie dowodu uruchomione na żywo	Przedłużona, przepisana albo wycofana
5	Jedno nowe zachowanie narzędzia, które ktoś zauważył w tym okresie	Zgłoszony sygnał albo zapisane „nic”

Zapisuj notatki w docs/agent-knowledge/sessions/ z datą i listą zmienionych artefaktów. Sesja bez zmiany artefaktu i bez jawnie zapisanego „nic” się nie liczy. Trening umiejętności należy do sesji review-to-learn; ta sesja dotyczy samej bazy wiedzy.

Jak sprawdzić, że dzielenie się wiedzą działa, bez czytania każdej strony?

Tech lead nie powinien co miesiąc czytać całej bazy wiedzy od nowa. Pętlę weryfikuje się po tym, co produkuje.

Powtarzalne awarie maleją. Taguj awarie agentów według klas z taksonomii awarii. Klasa awarii, która ma rekord lekcji i nadal wraca, oznacza, że lekcja jest w złym miejscu albo nikt jej nie znajduje.
Testy wykrywalności przechodzą. Wyniki testów dla każdej lekcji zmienionej w wydaniu są dołączone do PR-a wydania. Kwartalny pełny przebieg trafia do notatek z sesji.
Sprawdzenia dowodów działają w CI. Każde pole evidence wskazuje test, fixture albo test hooka uruchamiany przez CI; rekord, którego sprawdzenie usunięto, zostaje oflagowany przez prompt audytowy.
Nic nie jest przeterminowane. Zaplanowane zadanie wypisuje rekordy po terminie review_by. Zespół na każdej sesji widzi tę liczbę i to, czy spada.
Wycofania się zdarzają. Baza wiedzy, z której przez kwartał nic nie wycofano, rośnie bez utrzymania.
Odbiór podpisuje wskazany właściciel. Tech lead jest właścicielem indeksu i akceptuje kwartalny audyt; dowodem CTO dla Q20 są indeks, notatki z dwóch ostatnich sesji i najnowsze wyniki testów wykrywalności.

Co się psuje, gdy zespół dzieli się wiedzą o AI?

Archiwum porad. Strona wiki z 60 promptami i skopiowanymi konfiguracjami, której nikt nie jest właścicielem, w połowie napisana dla wersji narzędzi, których już nie ma. Naprawa: przenieś do rekordów lekcji tylko pozycje, które mają źródło i obecnego właściciela, a resztę zarchiwizuj z datą. Pozycje, których nikt nie przejmie w ciągu dwóch tygodni, zostają w archiwum.

Ta sama reguła w pięciu plikach. Lekcja skopiowana do CLAUDE.md, AGENTS.md, reguły Cursora, skilla i README rozjeżdża się w ciągu miesiąca, a agent słucha tej wersji, którą przeczytał ostatnio. Naprawa: wybierz jedno miejsce, zastąp kopie linkami i dodaj kontrolę „więcej niż jeden plik” z promptu audytowego do kwartalnego przebiegu. Jeśli musisz utrzymywać osobne pliki dla każdego narzędzia, generuj je z jednego źródła (synchronizacja reguł) zamiast edytować każdą kopię.

Rada tam, gdzie powinna być kontrola. Zdanie „Nigdy nie edytuj wygenerowanego klienta” zawodzi, gdy model pierwszy raz je zignoruje. Naprawa: przenieś je do reguły uprawnień, hooka albo sprawdzenia w CI, a zdanie zostaw tylko jako wyjaśnienie.

Lekcje żyją w osobistej pamięci. Auto memory albo prywatny plik reguł rozwiązały problem jednej osobie, a wszyscy pozostali wciąż na niego trafiają. Naprawa: zrób z „przenieś osobistą pamięć do repozytorium” stałe pytanie na sesji i dodaj test wykrywalności do onboardingu developerów, żeby nowa osoba ujawniła lukę.

Nieaktualne fakty o narzędziach. Lekcja podaje flagę albo ustawienie domyślne, które zmieniło się w nowym wydaniu, a agent się do niej stosuje. Naprawa: zapisuj tools_checked w każdej lekcji, datuj fakty o narzędziach w jednym pliku i blokuj w CI wycofane terminy, jak opisuje utrzymywanie zespołu na bieżąco.

Sesje zamieniają się w demo. Co dwa tygodnie spotkanie pokazuje nowe funkcje, a żaden artefakt się nie zmienia. Naprawa: trzymaj się agendy powyżej i jawnie zapisuj „nic”, gdy nic się nie zmieniło, żeby wzorzec był widoczny.

Dokąd dalej po wdrożeniu dzielenia się wiedzą

Warunkiem wstępnym tej pętli są działający wspólny rdzeń instrukcji i działająca konfiguracja skilli; kolejnym krokiem jest automatyczne zasilanie jej dowodami z produkcji.

Q5 · Wspólne reguły agentów Rdzeń instrukcji, do którego trafia większość lekcji.

Wspólne skills Pakuj procedury z fixtures i przypiętą dystrybucją.

Utrzymanie Automatycznie zamieniaj ustalenia z produkcji w nowe intencje.

Rozwój kompetencji zespołu Katy i sesje review-to-learn po stronie ludzi.

Dla pozostałych pytań ze scorecardu zacznij od klucza odpowiedzi CTO Scorecard. Wersję tego pytania dla tech leada znajdziesz w kluczu odpowiedzi Tech Lead Scorecard.