Molekularny harness dla Claude Code: jak prowadzę rozbudowane projekty AI

Dlaczego w ogóle harness

Claude Code z "pudełka" jest szybki i nieostrożny. W małym projekcie to cecha — w tydzień zbudujesz rzecz, która działa. W projekcie, który ma żyć miesiącami, dotykać produkcji, mieć fazy i ADR-ki, ta sama szybkość staje się wadą: agent pisze 400 linii kodu zamiast 40, deklaruje "should work" zamiast zweryfikować, zaczyna fazę drugą, gdy pierwsza jeszcze się wali.

Mój harness to próba ujarzmienia tej szybkości bez jej zabijania.

Testuję go na GroqeSTT — aplikacji Electron do transkrypcji głosu z routingiem do wątków tematycznych. Kodowa baza to kilkadziesiąt tysięcy linii, stack to TypeScript + Electron + PostgreSQL + Railway + Supabase + Groq/Gemini API. Projekt ma 5 faz roadmapy (Phase 0 → Phase 5: Knowledge Mesh + Second Brain), ADR-ki, dedicated views, UI impact maps — dokumentacja jest porządna, a mimo to pojedyncza sesja Claude'a bez harness'u potrafiłaby ją "znormalizować" w ciągu godziny, jeśli tylko jej pozwolić.

Harness nie pozwala.

Trzy obserwacje, na których stoi harness

1. Agent nie ma pamięci

Każda sesja Claude'a startuje od zera. To, co "zapadło w pamięć" w ostatniej rozmowie, jest iluzją — nowa sesja nie wie nic poza CLAUDE.md i tym, co sam przeczyta.

Bez świadomości tego faktu agent udaje, że pamięta: "wydaje mi się, że ten plik ma funkcję X", "w poprzedniej iteracji ustaliliśmy Y". Nie ustaliliśmy. To jest konfabulacja.

2. Agent jest optymistą

Agent powie "should work", gdy kod się skompiluje. Nie uruchomi testów. Nie zbuduje DMG. Nie sprawdzi, czy migracja na Supabase rzeczywiście się zaaplikowała. Powie, że "jest gotowe", a dopiero ręczna weryfikacja pokaże, że coś nie działa.

Weryfikacja przed zamknięciem musi być regułą, nie sugestią.

3. Agent jest szybki

W dwie minuty zrobi migrację, zmieni routing, przepisze 4 komponenty i zacommituje wszystko jednym commitem "feat: improvements". Potem nie jesteś w stanie prześledzić, co poszło nie tak. Molekularność — jedna sprawa na commit — jest podstawą audit trail.

Ale Claude Code ma przecież Plan Mode — po co to wszystko?

Słuszne pytanie, bo sam zadaję je sobie raz na miesiąc. Plan Mode rozwiązuje jeden konkretny problem: wymusza plan przed pierwszym edytem w sesji. To wartościowe i ten harness używa tego samego instynktu.

Ale Plan Mode to pojedyncza bramka na starcie sesji. Nie robi wielu rzeczy, których wymagam od pracy na długim projekcie:

Plan Mode jest świetny na pierwsze 10 minut sesji. Molekularny harness jest tym, co chroni następne 5 miesięcy projektu przed wpadnięciem w entropię.

Można — i należy — używać obu. Plan Mode do wstępnego framingu, harness do wszystkiego po.

Architektura harness'u

Cały harness to siedem plików i jedna taksonomia. Wszystkie są w repo (plus .env.*.local gitignored dla creds):

repo/
├── CLAUDE.md                                 # auto-loaded, manifest
├── .claude/
│   ├── rules.md                              # project-specific gotchas (dev ≠ prod, clean build)
│   └── settings.local.json                   # hardened permissions allowlist
├── docs/
│   ├── session-briefs/
│   │   ├── next-session-phase2-brief.md      # ciągłość — wklejasz na start sesji
│   │   └── scope-per-phase.md                # mapa faz
│   └── architecture/
│       ├── 00-CURRENT-STATE.md
│       ├── 01-VISION.md
│       ├── 02-DATA-MODEL.md
│       └── 05-OPERATING-MODES.md
└── .env.test.local / .env.prod.local          # gitignored — creds fallback

Plus zewnętrzne źródło prawdy (u mnie ClickUp Knowledge Mesh doc) dla: koncepcji, ADR-ów, phase speców, status notes, dedicated views. To nie jest do pobrania — to część kontraktu, że CLAUDE.md odsyła do czegoś, co Ty (nie agent) pielęgnujesz.

Siedem zasad nienegocjowalnych

Te trafiły do CLAUDE.md po kolejnych sesjach, w których coś poszło źle. Każda ma za sobą konkretny incydent.

1. Plan przed kodem. 3–5 bullet plan → czekam na GO → piszę kod. Bez GO = brak edytów.
2. Weryfikacja przed zamknięciem. "Gotowe" dopiero po build/test/działającej funkcji, nie po "kompiluje się".
3. Jedna sprawa na commit. Schemat / logika / UI → osobne commity. Monolityczny commit = brak audit trail.
4. Dyscyplina faz. Nie wchodzę w Fazę N+1 bez zaakceptowanego DoD Fazy N. Nawet jeśli kusi.
5. Read before edit. Każdy edytowany plik czytany w tej samej sesji. Nie w pamięci.
6. Tool failed → STOP i diagnoza. Nie retry, nie workaround. Tool fail to sygnał, nie przeszkoda.
7. Pytaj tylko o realne decyzje. Nie mnóż sztucznych opcji, gdy jest jedna sensowna ścieżka.

Siódma zasada jest najmłodsza — dodana dzisiaj po rozmowie, którą zaraz opiszę.

Trzy ścieżki decyzyjne (najciekawsza część)

Jak agent ma pytać o decyzję? Najpierw instynkt: mnożyć opcje, żeby pokazać przemyślenie. A/B/C dla każdego kroku, trade-offy rozpisane, dbałość o "demokrację wyboru". Efekt: użytkownik traci czas, bo B i C są oczywiście gorsze od A, a agent i tak by zrekomendował A.

Poprawka z dzisiejszej sesji: diagnozuj ile jest realnych opcji, zanim zapytasz.

Ścieżka 1 — jedna sensowna opcja

Jeśli pipeline pokazuje oczywisty następny krok (np. kolejna migracja w numerowanej serii), agent wystawia propozycję:

Propozycja: dodam config.ts z ROUTING_V2_ENABLED — z.string().default('false').transform(v => v==='true'||v==='1') (edge-case safe boolean parsing). Wpływ: test env + prod env przyjmie nową env var; domyślnie off. Ryzyko: żadne (default off, zero touch v1 routing).

Widzisz luki? Jeśli nie — GO.

Trzy linie, nie trzy akapity. Domyślnie czekam na NO-GO — brak odpowiedzi ≠ GO. Odpowiadam: GO, luka: ..., albo inaczej: ....

Dla większości kroków w molekularnym harness to jest właściwy format. Sztuczne A/B/C gdzie B i C są oczywiście gorsze marnuje mi 30 sekund na każdą decyzję. Przez 3 godziny pracy to 10 minut zmarnowane na rytuał.

Ścieżka 2 — 2–3 realne opcje

Gdy są realne opcje z różnymi implikacjami (różny blast radius, różna odwracalność, różny koszt), agent używa klasycznego formatu 3-liniowego:

A hotfix — zmieniam Railway env var i redeploy backend. Wpływ: tylko test env, bez ruszenia prod. Trade-off: ~3 min, odwracalne.

B merge — merge feature/knowledge-mesh do main, prod auto-deploy. Wpływ: PROD live, migracja 031_edges uruchomi się na prod Supabase. Trade-off: rollback przez git revert + redeploy, additive migracja więc safe.

C pauza — nic nie robię. Wpływ: zero. Trade-off: wracasz kiedy chcesz.

Rekomenduję A — B jest reversible ale chcę mieć test verify pierwsze.

Trzy linie per opcja + jedna TL;DR. Użytkownik w 10 sekund wie, co klika.

Ścieżka 3 — > 3 opcje, żadna nie dominuje

Decyzja zbyt gruba. Zawęź najpierw do kryterium ("które ważniejsze: bundle size czy API ergonomics?"), potem dopiero pełne A/B.

Co się dzięki temu zmienia w praktyce

• Agent ma przestrzeń decyzyjną. Nie pyta o kosmetykę (commit message, kolor badge, format JSON).
• Agent pyta zawsze o irreversible, high-cost, prod-impact, scope expansion — niezależnie od ścieżki.
• Ja mam mniej przerywników. Single-path propozycja kosztuje mnie GO — 2 znaki, decyzja w 3 sekundy.

Ciągłość między sesjami

Największa luka w pracy z Claude Code to handoff. Sesja A kończy się, sesja B startuje nazajutrz, i pierwsze 20 minut to "gdzie skończyliśmy".

Rozwiązanie: session brief. Plik docs/session-briefs/next-session-phase{N}-brief.md, committed w repo. Sesja zamykająca fazę musi go wygenerować przed końcem. Sesja startująca dostaje go na pierwszej wiadomości:

Jestem nową sesją Claude dla <project>. Przeczytaj docs/session-briefs/next-session-phase2-brief.md i działaj zgodnie z nim.

Brief ma sztywną strukturę: kolejność czytania (5 min), gdzie jesteśmy (TL;DR), insights/gotchas, pierwsze zadanie, phase rough refs, infra quick-check, harness reminder, źródła prawdy.

Cała dziesiąta strona, ale startuję w 2 minuty zamiast w 20.

Trade-offy, których się nie boję

Powiem wprost: harness zamienia szybkość na kontrolę. Są trzy rzeczy, które stają się wolniejsze.

1. Więcej odpowiadania na prompty

Agent częściej pyta. Mniej sam decyduje. Pierwsze 2 dni są frustrujące — czuje się jak mikromenedżment. Po 3 dniach jednak zaczynasz rozpoznawać, że każde pytanie jest zawsze w punkcie: irreversible, prod-impact, scope expansion, realna alternatywa.

Dzisiejsza poprawka (single-option path) jeszcze zmniejsza ten koszt — agent pyta tylko, gdy faktycznie jest wybór.

2. Plan dodaje frykcję na początku

Zamiast "rzuć kod i zobacz", jest "wystaw plan, czekaj na GO". Pierwszy plan w danej fazie trwa 2 minuty zamiast 0. Ale każdy następny krok idzie szybciej, bo plan rozmawia z agentem w tym samym języku (mapa plików + DoD + commit strategy).

3. Molekularność wymaga więcej commitów

Zamiast feat: improvements, dostaję feat(db): migration 032_pgvector, feat(router): candidates.ts stub, feat(router): rerank.ts stub, feat(api): /suggest-v2 endpoint gated. Cztery commity zamiast jednego. Audit trail nie pozostawia wątpliwości, który commit coś zepsuł — to warto.

Co w zamian

Co zyskuję:

• Molekularne ADR-ki. Każda decyzja (Phase 2 routing, Phase 5 reshape Palace → Second Brain, ADR-007 canvas lib, ADR-008 polski reranker) jest osobnym dokumentem z datą, alternatywami, konsekwencjami. Żadna nie znika w commit history.
• Nic się nie dzieje bez mojej wiedzy. Plan przed kodem + single-path propozycja = każdy edyt jest świadomą decyzją. Agent nie "improwizuje" pod pretekstem "mały krok, zaraz pokażę".
• Mam szansę wyłapać zmiany po drodze. Gdy agent wystawia propozycję, widzę ją przed tym jak się stanie. Mogę powiedzieć luka: nie uwzględniłeś X i wracamy do planu.
• Ciągłość sesji. Następna sesja Claude'a nie powtarza moich pomyłek — brief je pokazuje jako "gotchas".

Co się jeszcze zmieni

Harness ewoluuje. Rzeczy, które testuję / planuję:

• Auto-generowanie briefów z git log --since="last session" + TODO. Dzisiaj wypełniam brief ręcznie. Prostszy skrypt powinien to wstępnie wygenerować, ja tylko sprawdzam.
• Agent harness-validator. Subagent, który sprawdza compliance z regułami na końcu sesji: czy był Read przed każdym Edit? Czy commits są atomowe? Czy brief na następną sesję powstał?
• Telemetria sesji. Ile razy tool_failed → retry vs tool_failed → STOP. Ile pytań było Ścieżką 1 (propozycja) vs Ścieżką 2 (A/B/C). Czy agent łamie regułę 7 (sztuczne opcje)? Bez pomiaru trudno poprawiać.
• Single-option path w skillach. Dziś dodaliśmy regułę do CLAUDE.md i do promptu decision-prompt-three-lines. Kolejne 2 tygodnie pokażą, czy agent rzeczywiście rzadziej mnoży sztuczne warianty.
• Hooks PreToolUse dla Edit/Write, które sprawdzają readFiles set w sesji. Hak blokujący Edit bez Read. Ryzyko — agresywny hook blokuje legit flows, więc dziś polegam na dyscyplinie.

Jak to wziąć i odpalić u siebie

Cały harness żyje teraz jako publiczne repo na GitHubie — 6 artefaktów (3 prompty + 3 skille) plus 3 gotowe przykłady plików (CLAUDE.md.example, next-session-phase1-brief.md.example, settings.local.json.example) plus README, CHANGELOG, CONTRIBUTING. Licencja MIT.

→ github.com/yx-aesthete/madesky-claude-harness

Minimalna ścieżka adopcji:

git clone https://github.com/yx-aesthete/madesky-claude-harness.git
cd madesky-claude-harness
cp prompts/molecular-harness-working-mode.md /path/to/your/repo/CLAUDE.md
mkdir -p /path/to/your/repo/docs/session-briefs
cp examples/next-session-phase1-brief.md.example \
   /path/to/your/repo/docs/session-briefs/next-session-phase1-brief.md
# wypełnij brief — 5-10 min, to jedyna ręczna praca
cp examples/settings.local.json.example /path/to/your/repo/.claude/settings.local.json

Potem otwierasz Claude Code w swoim repo i pierwszą wiadomością wklejasz:

Jestem nową sesją Claude. Przeczytaj docs/session-briefs/next-session-phase1-brief.md i działaj zgodnie z nim.

Forkuj, adaptuj, opublikuj swoje zmiany. Każdy prompt i skill masz też jako osobną stronę tu na madejski.ai, z "copy raw" i podglądem markdown — linki w sekcji "Powiązane prompty i skille" na dole tego wpisu.

Projekty, na których harness działa

Harness testuję na kilku aktywnych projektach z różnymi profilami ryzyka:

• GroqeSTT — Electron + PostgreSQL + Railway + Supabase + Groq/Gemini. Knowledge Mesh Phase 2 in progress. Harness tu się narodził.
• Pryzmat — pipeline medialny Next.js + Supabase. Phase-driven development.
• AvoidSCT — aplikacja kliniczna, najwyższe wymagania co do audit trail. Harness jest tu kluczowy.
• BasePlate — platforma SaaS, która sama hostuje kilka mniejszych produktów. Harness replikowany per-workspace.
• AI Possibilities Lab — projekt edukacyjny, gdzie harness służy też jako materiał dydaktyczny "jak prowadzić sesję z Claude'em".

W każdym projekcie CLAUDE.md zaczyna się od tego samego szkieletu. Różni się tylko taksonomia dokumentów i entry point phase brief.

Zaproszenie

Jeśli prowadzisz projekt z Claude Code dłużej niż 2 tygodnie — fork repo, dopasuj do siebie i opublikuj swoje zmiany. Jeszcze lepiej: otwórz issue z konkretnym incydentem, którego istniejące reguły nie złapały. Wiele z tego, co tu jest, wynikło z realnych pomyłek — Twoje pomyłki mogą nauczyć mnie tyle, ile moje nauczyły mnie.

• Repo: github.com/yx-aesthete/madesky-claude-harness
• Feedback: LinkedIn albo komentarz pod postem