Changelog — Rzemiosło (The Craft)

Wszystkie istotne zmiany doktryny Rzemiosło — The Craft (Kolada Build). Wersjonowanie semantyczne (MAJOR.MINOR.PATCH). Data wpisu = dzień publikacji — wtedy wersja została zdeployowana na thecraft.jakub.solutions i gotowa do pobrania.

Zasada: jedno źródło prawdy. version w craft.json zawsze odpowiada najwyższemu wpisowi poniżej. Każde wydanie tagujemy w gicie (vMAJOR.MINOR.PATCH) — Przykazanie VIII.

Wspólna oś wersji z witryną Rzemiosło Web. Rdzeń reguł i witryna dzielą numerację, więc numer pominięty tutaj oznacza wydanie po stronie witryny — 1.0.1 i 1.0.2 należały do Web, dlatego rdzeń idzie 1.0.0 → 1.0.3. Luki są zamierzone, nie brakiem.

MAJOR — przebudowa/usunięcie reguł lub rozdziału (zmiana niekompatybilna z dotychczasowym rozumieniem). MINOR — nowy rozdział lub istotna nowa reguła. PATCH — doprecyzowanie, przykład, literówka, drobna korekta.

1.0.3 — 2026-08-24

Lekcje z pracy w projekcie referencyjnym, wpisane do istniejących rozdziałów (bez zmiany listy rozdziałów — stąd PATCH), w obu językach (EN kanon + PL). Rdzeń: doktryna jest pisana pod jednego developera z AI, gdzie „solo” i tak znaczy kilka równoległych sesji Claude na jednym repo — i to one, nie ludzki zespół, wymuszają dyscyplinę koordynacji.

Dodane

• [intro] „Dla kogo to jest”. Pojedynczy developer + AI jako para; „solo” to i tak wielu piszących (równoległe sesje agenta) → reguły koordynacji istnieją już przy drugiej otwartej sesji.
• [05] Koordynacja pracy równoległej. Przeramowanie „pracy zespołowej” na równoległe sesje Claude; diff-przed-mergem do gałęzi deployu i pułapka cherry-pick 3-way merge; origin vs lokalne (deploy wypuszcza origin, sprawdź push przed deployem); boot-check na celu przed reloadem; pełna sekcja próby generalnej deployu: dev → preprod → prod (budowa preprodu z proda, anonimizacja PII, SITE_URL env-overridable, pułapki ACME/SSH/canonical). + nowe antywzorce.
• [14 § 7] Zadania cykliczne: patrz na skutek, nie na runnera. CzujkaWatchdog — Niezależny dozorca, który sam sprawdza, czy dane są świeże / aplikacja żyje, i alarmuje, gdy coś stoi. Przy zadaniach cyklicznych mierz skutek (wiek najświeższego rekordu), nie kod wyjścia joba — zielony raport potrafi kłamać. mierzy wiek najświeższego rekordu per źródło, nie kod wyjścia zadania; zielony raport pokrywa tylko to, o czym wie (druga ścieżka danych milczy); konfiguracja harmonogramu to produkcja i żyje poza repo (nadrabianie pominiętego uruchomienia, warunek bateryjny) → do runbooka. + 2 antywzorce.
• [16] Tryb planowaniaPlan mode — Tryb, w którym asystent najpierw czyta i przedstawia plan, ale nie zmienia plików — wykonanie dopiero po Twojej akceptacji. Do pracy szerokiej albo trudnej do cofnięcia: recenzujesz decyzję, nie diff. Dobry plan mówi też, jak sprawdzicie, że wyszło. jako osobna sekcja (kiedy sięgać, kiedy odpuścić, plan = artefakt przeglądu) oraz izolowany git worktree na równoległą sesję (wspólny checkout = wspólny index). + 3 antywzorce.
• [15] Serwis odpowiada dwa razy i te odpowiedzi mogą sobie przeczyć. robots.txt to POLITYKA właściciela, tarcza antybotowa to MASZYNA, która nie czyta intencji — przedstawiasz się prawdziwie i pytasz właściciela, nie szukasz obejścia; 403 z serwera + 200 z innej sieci = blokada ADRESU, 403 z KAŻDEJ sieci = tarcza.
• [03] Guard sprawdza się na incydencie, nie na fiksturze. Kontrolę pisaną po awarii odtwórz na prawdziwych danych tej awarii, zanim jej zaufasz — fiksturę pisze ta sama głowa, która napisała błąd.
• [04] Ścieżki absolutne na granicy narzędzi (/tmp znaczy co innego w Git Bash / Pythonie / PowerShell) oraz próba generalna masowej mutacji na kopii proda (nie tylko dry-runDry-run — Uruchomienie „na sucho” — skrypt pokazuje, co BY zrobił, ale niczego nie zmienia. Widzisz skutki przed wykonaniem; zmiana na danych idzie dopiero po świadomym potwierdzeniu.).
• [13] Mobile: viewport to ruchomy cel. 100dvh zamiast 100vh (kolejność deklaracji), elementy nad klawiaturą kotwiczone do visualViewport, flex-basis z wiersza staje się wysokością w kolumnie, emulator kłamie → mierz geometrię DOM / testuj na profilu urządzenia. + nowe antywzorce.
• [05] Cofanie: najprawdopodobniej tego nie straciłeś. Sekcja ratunkowa dla osób niebiegłych w gicie — sześć typowych panik i droga powrotna dla każdej (restore, reset --soft, reflog, ORIG_HEAD, przywrócenie pliku ze starego commita), reflog jako przycisk cofania repo oraz trzy jedyne komendy, które realnie niszczą pracę — i to wyłącznie niezacommitowaną. Reguła spinająca: commituj wcześnie, bo destrukcyjne komendy gita nie mają dry-run.
• [06] Mapa uprawnień — jedna tabela, trzy kolumny (wolno / zapytaj / nigdy). Granica całej doktryny w jednym miejscu, zamiast rozsypki po 00, 05, 06 i 16; lewa kolumna celowo szeroka (to ona czyni autopilota bezpiecznym), środkowa per-akcja, prawa nienegocjowalna.
• [06] Przekazanie stanu, gdy urywa się kontekst. Długa sesja nie kończy się — zostaje podsumowana, a podsumowanie gubi dlaczego i pół-gotowy stan w drzewie. Dowoź w commitach, nie w rozmowie; decyzję zapisz w chwili podjęcia; trwałe fakty do memory/; git status jest przekazaniem dla następcy; przy zbliżającym się suficie dowoź, nie zaczynaj. Test: czy następna sesja podniosłaby to z samego repo, bez tej rozmowy?
• [00] Odstępstwo od reguły — i podłoga, która się nie rusza. Doktryna to default, nie klatka: odstępuj na głos (nazwij regułę, uzasadnij, zaproponuj zamiennik), ciche pominięcie to grzech; precedencja CLAUDE.md gospodarza > docs/rules > defaulty agenta; reguła wciąż nadpisywana to bug doktryny do naprawienia w kanonie. Podłoga: III, V, VI, VII.

Zmienione

• [00] Reguła zerowa — „przeczytaj każdy plik” → „przeczytaj Dekalog, resztę grepuj po indeksie tematów” (spójność z ekonomią kontekstu z [01]); jawnie: wskaźnik, nie wklejka, a kopia wendorowana nie jest konstytucją projektu-gospodarza.
• [14 § 2] Runner dobierany do czasu życia zadania — tło sesji jest trwałe w sesji (i należy z niego korzystać), ginie z sesją; co ma przeżyć sesję → proces odpięty albo harmonogram systemu. Poprzednie brzmienie („nie uruchamiaj z tła sesji”) przeczyło rozdziałowi [16].
• [07] Notka [SYSTEM — READ FIRST] doprecyzowana (Dekalog → indeksIndeks (bazodanowy) — Skorowidz w bazie danych, dzięki któremu wyszukiwanie idzie błyskawicznie, zamiast przeglądać wszystko po kolei. Pierwszy ruch przy wolnych zapytaniach — jak indeks na końcu książki zamiast czytania 400 stron. tematów; wskaźnik, nie wklejka).
• [AI_README, CLAUDE.md] baner „kopia wendorowana ≠ konstytucja gospodarza”, indeks tematów i liczby zsynchronizowane ze stanem bieżącym.

1.0.0 — 2026-06-19

Pierwsze publiczne wydanie — kompletna doktryna The Craft, gotowa do wpięcia jako docs/rules/ w nowym projekcie. Od pierwszego commita po prod: jak budować z Claude tak, żeby projekt został zrozumiały, bezpieczny w zmianie i godny zaufania.

Dodane

• 17 rozdziałów w dwóch językach (EN kanon + PL — te same rozdziały, te same kotwice): Dekalog (00) + rdzeń (01–08) + pogłębienie (09–16) — od dokumentacji, testów, gita i wdrożeń, przez prawo, SEO i model danych, po wydajność, odporność operacyjną, scrapingScraping — Automatyczne zbieranie danych ze stron internetowych przez program zamiast ręcznego kopiowania. Potężne do pozyskiwania danych, ale wymaga kultury: szanuj cudze zasady (robots.txt), nie przeciążaj serwera./AI i prowadzenie Claude.
• Czytnik HTML paczki — render .md z dwukliku (file://), tryb jasny/ciemny, przełącznik EN/PL.
• Witryna thecraft.jakub.solutions — przyjazne opakowanie z pobieraniem.