Inżynieria procentu składanego: jak moja baza kodu przyspiesza zamiast się degradować

Większość baz kodu zwalnia wraz ze wzrostem. Moja przyspiesza. Po zbudowaniu 95 hooków, 44 umiejętności i 14 plików konfiguracyjnych w mojej infrastrukturze .claude/, każda nowa funkcja kosztuje mniej niż poprzednia, ponieważ infrastruktura przejmuje coraz większą część pracy.¹

TL;DR

Inżynieria procentu składanego opisuje bazy kodu, w których dodanie każdej funkcji sprawia, że kolejne funkcje są tańsze w realizacji. Doświadczyłem tego na własnej skórze: mój system hooków Claude Code zaczynał się od 3 hooków i rozrósł się do 95. Budowa pierwszego hooka zajęła godzinę. Najnowsze hooki powstają w 10 minut, ponieważ infrastruktura (zdarzenia cyklu życia, ładowanie konfiguracji, zarządzanie stanem, środowisko testowe) już istnieje. Przeciwny wzorzec — inżynieria entropii — opisuje bazy kodu, w których każda nowa funkcja zwiększa koszt kolejnych. Różnica między zespołem, który w trzecim roku dostarcza szybciej niż w pierwszym, a zespołem, który utknął w martwym punkcie, polega na tym, czy decyzje inżynieryjne akumulują się pozytywnie, czy negatywnie.

Procentowanie w praktyce: moja infrastruktura .claude/

Krzywa wzrostu

Pierwszy hook (git-safety-guardian.sh) wymagał zbudowania całego cyklu życia hooków: zrozumienia zdarzeń PreToolUse, pisania basha parsującego dane wejściowe JSON, obsługi przypadków błędów, ręcznego testowania. Dziewięćdziesiąty piąty hook odziedziczył całą tę infrastrukturę. Czas na jeden hook spadł 6-krotnie nie dlatego, że hooki stały się prostsze, lecz dlatego, że infrastruktura przejęła większą część pracy.

Co się akumuluje

Spójność wzorców. Każdy hook ma tę samą strukturę: odczytaj dane wejściowe JSON, sparsuj za pomocą jq, sprawdź warunki, zwróć decyzję w formacie JSON. Programista (lub agent AI) czytający dowolny hook natychmiast rozpoznaje wzorzec. Mój 12-modułowy linter blogów stosuje tę samą zasadę spójności: każdy moduł eksportuje ten sam interfejs (check(content, meta) -> findings), co sprawia, że dodawanie nowych modułów jest trywialne.

Zachowanie sterowane konfiguracją. Wszystkie 14 plików konfiguracyjnych JSON koduje progi i reguły, które wcześniej były zakodowane na stałe. Kiedy przeniosłem próg konsensusu deliberacji z zakodowanej na stałe wartości 0.70 w Python do pliku deliberation-config.json, zyskałem możliwość dostosowywania go do typu zadania (bezpieczeństwo=85%, dokumentacja=50%) bez zmian w kodzie.²

Infrastruktura testowa. Pierwszych 20 hooków nie miało testów. Dodanie środowiska testowego (48 testów integracyjnych w bashu, 81 testów jednostkowych w Python) kosztowało dwa tygodnie. Od tamtej pory każdy hook jest dostarczany z testami w mniej niż 5 minut, ponieważ fixtury, helpery asercji i runnery testów już istnieją.

System pamięci. Mój plik MEMORY.md rejestruje błędy, decyzje i wzorce pomiędzy sesjami. Przy 54 wpisach zapobiega powtarzaniu tych samych pomyłek. Problem z ((VAR++)) w bashu z hooka #23 zapobiegł temu samemu błędowi w hookach od #24 do #95. Każdy wpis akumuluje się w każdej przyszłej sesji.³

Model procentu składanego

Pozytywna akumulacja

Produktywność inżynierska podlega formule procentu składanego:

Productivity(n) = Base × (1 + r)^n

Gdzie r to wskaźnik zmiany produktywności na funkcję, a n to liczba dostarczonych funkcji.

Dodatnie r (akumulacja): Każda funkcja sprawia, że następna jest o 2–5% tańsza. Po 50 funkcjach: 1,03^50 = 4,38-krotna poprawa produktywności.

Ujemne r (entropia): Każda funkcja sprawia, że następna jest o 2–5% droższa. Po 50 funkcjach: 0,97^50 = 0,22-krotna produktywność — degradacja o 78%.

Różnica między tymi trajektoriami to 20-krotna przepaść w prędkości inżynieryjnej po 50 funkcjach.⁴

Moje rzeczywiste liczby

Moja strona blakecrosley.com zaczynała się jako pojedyncza trasa FastAPI z szablonem HTML. Dziewięć miesięcy później:

Ostatni wpis to wypłata z akumulacji: dodanie nowego modułu lintera zajmuje 15 minut, ponieważ interfejs modułu, integracja CLI, środowisko testowe i pipeline CI już istnieją. Pierwszy moduł zajął 3 godziny, ponieważ żadna z tych elementów infrastruktury jeszcze nie istniała.⁵

Przykłady entropii z mojej własnej bazy kodu

Akumulacja nie zachodzi automatycznie. Sam również doświadczyłem entropii:

Skrót ze schematem ContentMeta

Zdefiniowałem dataclass ContentMeta posta blogowego w jednej sesji: title, slug, date, description, tags, author, published. Nie uwzględniłem category, series, hero_image, scripts ani styles. Każde późniejsze dodanie wymagało modyfikacji parsera, aktualizacji każdego szablonu korzystającego z metadanych i ponownego przetestowania całego pipeline’u. Pięć dodatków w ciągu trzech miesięcy kosztowało łącznie więcej czasu, niż kosztowałoby staranne zaprojektowanie schematu na początku. To problem doboru momentu decyzji: nieodwracalne decyzje zasługują na analizę z wyprzedzeniem.

Kolizja kluczy cache i18n

Szybka implementacja cachowania tłumaczeń używała slugów blogów jako kluczy cache. Gdy dwa tłumaczenia tego samego sluga istniały w różnych lokalizacjach językowych, cache zwracał nieprawidłowy język. Debugowanie zajęło 3 godziny. Naprawa zajęła 15 minut (dodanie prefiksu lokalizacji do klucza cache). Skrót, który zaoszczędził 5 minut podczas implementacji, kosztował 3 godziny debugowania i przegląd architektoniczny każdego klucza cache w systemie.⁶

Katalog debugowania o rozmiarze 3,2 GB

Dane wyjściowe debugowania hooków gromadziły się w ~/.claude/debug/ bez czyszczenia. W ciągu trzech miesięcy katalog urósł do 3,2 GB. Umiejętność audytu kontekstu, którą zbudowałem później, wykryła to i wyczyściła pliki starsze niż 7 dni, ale infrastruktura czyszczenia powinna była powstać wraz z pierwszym zapisem danych debugowania.

Praktyki, które się akumulują

Spójne wzorce ponad optymalne wzorce

Zespół, który stosuje ten sam „wystarczająco dobry” wzorzec w 50 funkcjach, działa szybciej niż zespół, który stosuje „optymalny” wzorzec dla każdej poszczególnej funkcji. Spójność redukuje obciążenie poznawcze, umożliwia automatyzację narzędzi i przyspiesza przeglądy kodu.⁷

Mój system hooków używa tego samego wzorca bashowego we wszystkich 95 hookach, mimo że niektóre hooki byłyby naturalniej wyrażone w Python. Spójność oznacza, że każdy hook jest czytelny dla każdego (lub każdego agenta AI), kto przeczytał jeden hook. Nieoptymalny wybór języka jest więcej niż rekompensowany zerową krzywą uczenia się dla nowych hooków.

Infrastruktura jako pierwsza funkcja

Zbudowałem swój pipeline CI/CD, środowisko testowe i workflow wdrożeniowy, zanim stworzyłem jakiekolwiek funkcje produktowe na blakecrosley.com. Inwestycja wydawała się wtedy powolna. Każda funkcja od tamtej pory jest wdrażana w mniej niż 2 minuty z automatycznym testowaniem.⁸

Wzorzec pałacu pamięci

Mój katalog .claude/ funkcjonuje jako „pałac pamięci” — uporządkowany zbiór dokumentów zoptymalizowany zarówno do konsumpcji przez ludzi, jak i przez AI:

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

Pałac pamięci akumuluje się, ponieważ każdy nowy wpis wzbogaca kontekst dostępny dla przyszłych sesji rozwojowych. Po 54 wpisach w MEMORY.md agent AI unika błędów, które już rozwiązałem. Po 95 hookach nowe hooki piszą się same, naśladując ustalone wzorce. Bogatszy kontekst generuje lepiej dopasowany kod tworzony przez AI, co sprawia, że następna funkcja jest tańsza.⁹

Akumulacja w erze AI

AI wzmacnia oba kierunki

Asystenci kodowania AI przyspieszają dowolny wzorzec, który baza kodu już stosuje. Moje 95 hooków ze spójnymi wzorcami generuje doskonałe hooki tworzone przez AI, ponieważ AI dopasowuje się do ustalonej struktury. Baza kodu z 5 różnymi stylami hooków generowałaby gorszy kod AI, ponieważ AI nie miałoby spójnego wzorca do naśladowania.¹⁰

Efekt akumulacji podwaja się: spójne wzorce przyspieszają rozwój prowadzony przez ludzi (redukcja obciążenia poznawczego) ORAZ rozwój wspomagany przez AI (dopasowywanie wzorców). Niespójne wzorce spowalniają jedno i drugie.

Bazy kodu czytelne dla agentów

Zaprojektowałem swoją infrastrukturę .claude/ z myślą o konsumpcji przez agentów AI:

• Ustrukturyzowane konfiguracje (JSON, nie wartości zakodowane na stałe), które agenci parsują programowo
• Spójne konwencje nazewnictwa (verb-noun.sh dla hooków, SKILL.md dla definicji umiejętności)
• Sprawdzanie jakości weryfikowalne maszynowo (141 testów, które agenci uruchamiają autonomicznie)
• Jawna dokumentacja (MEMORY.md, handoffy, docs/), którą agenci czytają na początku sesji

Każda inwestycja w czytelność dla agentów akumuluje się w miarę jak narzędzia AI stają się coraz bardziej zaawansowane.¹¹

Kluczowe wnioski

Dla inżynierów: - Śledź swój „czas na funkcję” w miarę wzrostu bazy kodu; jeśli rośnie — masz entropię, jeśli maleje — masz akumulację - Stosuj zasadę trzech przed wydzielaniem abstrakcji: zbuduj konkretne rozwiązanie dwukrotnie, a następnie wyodrębnij reużywalny wzorzec przy trzecim wystąpieniu - Inwestuj 15–20% każdego sprintu w ulepszanie infrastruktury i narzędzi; złożone zwroty przewyższają krótkoterminowy koszt prędkości dostarczania funkcji w ciągu 3–5 sprintów

Dla menedżerów inżynierii: - Mierz kondycję inżynieryjną czasem realizacji funkcji w czasie; rosnący czas realizacji sygnalizuje entropię - Traktuj dokumentację i infrastrukturę testową jako funkcje, nie jako narzut; moja inwestycja w infrastrukturę testową (2 tygodnie) zaoszczędziła ponad 50 godzin w ciągu 95 hooków

Źródła