Kodowanie wspierane przez AI zawodzi, gdy kontrakt behawioralny między człowiekiem a LLM jest niedookreślony. Zespoły, które zapisują te kontrakty w swoim toolchainie, zyskują narastającą przewagę. Zespoły, które pomijają tę pracę, wracają z kolejnymi zgłoszeniami dotyczącymi halucynowanych wyników.
Dowodem jest forrestchang/andrej-karpathy-skills na GitHub. Jeden plik CLAUDE.md, który przekształca obserwacje Andreja Karpathy'ego na temat pułapek LLM w programowaniu w praktyczne zasady dla Claude Code. 22 700 gwiazdek. 1 800 forków. Za jeden plik.
Ta liczba gwiazdek pokazuje, że 22 000 deweloperów zmaga się z tym samym problemem: asystenci AI do kodowania są potężni, ale nieprzewidywalni, a dobrze napisany kontrakt behawioralny to zmienia (liczba gwiazdek mierzy widoczność, nie zweryfikowane wyniki).
Cztery zasady stojące za 22 000 gwiazdek
Repozytorium koduje cztery zasady, z których każda celuje w konkretny tryb awarii w kodowaniu wspomaganym przez LLM:
- Myśl przed kodowaniem. Ujawniaj założenia, przedstawiaj kompromisy, pytaj zamiast zgadywać. Celuje w tryb awarii, w którym LLM przechodzi do implementacji, zanim zrozumie problem.
- Prostota przede wszystkim. Minimalny działający kod, bez spekulatywnych funkcji ani abstrakcji. Celuje w tryb awarii, w którym LLM nadmiernie komplikuje rozwiązania przez zbędną złożoność.
- Wykonanie zorientowane na cel. Określaj kryteria sukcesu, nie instrukcje krok po kroku. Pozwól LLM iterować, aż kryteria zostaną spełnione. Celuje w tryb awarii, w którym imperatywne instrukcje prowadzą do kruchego, dosłownego kodu.
- Jawna komunikacja. Żadnych milczących założeń. Każda decyzja udokumentowana. Celuje w tryb awarii, w którym LLM podejmuje wybory wyglądające sensownie, ale naruszające niewypowiedziane ograniczenia.
Żadna z tych zasad nie jest zaskakująca sama w sobie. Zaskakuje to, że zakodowanie ich w jednym pliku robi różnicę między "AI zmarnowało mi popołudnie" a "AI dostarczyło funkcję, gdy ja robiłem przegląd."
CLAUDE.md to nie przewodnik po stylu kodu
Większość zespołów traktuje plik CLAUDE.md (lub równoważny plik systemowego promptu) jak przewodnik po stylu kodu: preferencje formatowania, konwencje nazewnictwa, może kilka notatek specyficznych dla projektu. To całkowicie mija się z celem.
CLAUDE.md to kontrakt behawioralny. Definiuje, jak agent AI rozumuje o problemach, kiedy prosi o wyjaśnienie, a kiedy przyjmuje założenia, jak określa zakres pracy i co weryfikuje przed ogłoszeniem ukończenia. Przewodniki po stylu mówią AI, jak powinien wyglądać kod. Kontrakty behawioralne mówią AI, jak ma myśleć.
Własny przepływ pracy Karpathy'ego przy kodowaniu z AI potwierdza to podejście. Jego pętla (wypełnianie kontekstu, opisywanie zmiany, wybór podejścia, przegląd, testy, commit, powtórzenie) traktuje AI jak to, co sam nazywa "nadgorliwym stażystą-sawantem": encyklopedyczna wiedza, zerowy osąd. Kontrakt behawioralny dostarcza osądu, którego modelowi brakuje.
Ta zmiana perspektywy ma konkretny skutek. Gdy agent AI produkuje złe wyniki, pytanie przesuwa się z "czy model jest wystarczająco dobry?" na "czy kontrakt jest wystarczająco precyzyjny?" Pierwsze pytanie prowadzi do oczekiwania na GPT-5. Drugie prowadzi do pull requesta, który można wysłać dzisiaj.
Skalowanie kontraktów behawioralnych do systemów wieloagentowych
Zasady Karpathy'ego zostały zaprojektowane dla indywidualnego dewelopera pracującego z jednym asystentem AI. Jednak ten sam wzorzec skaluje się do wieloagentowej orkiestracji, gdzie wyspecjalizowane agenty koordynują złożone zadania.
Do koordynacji 19 wyspecjalizowanych subagentów służy oh-my-claudecode (OMC), open-source'owa wieloagentowa warstwa orkiestracji dla Claude Code, obejmująca architekta, executora, recenzenta, audytora bezpieczeństwa, inżyniera testów i innych. Każdy agent ma własny kontrakt behawioralny definiujący wzorce rozumowania, granice zakresu i wymagania weryfikacyjne.
| Wymiar | Kontrakt jednoagentowy | Kontrakt wieloagentowy |
|---|---|---|
| Zakres | Jeden deweloper, jeden asystent | 19 wyspecjalizowanych agentów z odrębnymi rolami |
| Weryfikacja | Człowiek przegląda wyniki AI | Agent recenzent sprawdza executora; człowiek przegląda wynik końcowy |
| Kontekst | Pełna baza kodu w jednym oknie | Każdy agent otrzymuje tylko kontekst istotny dla swojego zadania |
| Tryb awarii | AI nadmiernie komplikuje jeden plik | Agenty powielają pracę lub są ze sobą sprzeczne |
| Fokus kontraktu | Jak myśleć o tym kodzie | Kto odpowiada za które decyzje i jak działają przekazania |
Dowodem koncepcji jest pełna integracja produktu wygenerowana ze specyfikacji produktu przez potok agentów OMC. Ważnym wnioskiem była kontrola jakości, nie liczba linii kodu. Kontrakty behawioralne zdefiniowane w systemowym prompcie każdego agenta stanowiły główny wkład autorski człowieka poza samą specyfikacją.
Claude był już wystarczająco inteligentny. Kontrakty były wystarczająco precyzyjne, by około 19 agentów mogło koordynować pracę bez nadpisywania wyników pozostałych.
Gdzie naprawdę leży przewaga konkurencyjna
Jeśli infrastruktura AI ulega komodyzacji (a tak jest, przy zarządzanych środowiskach uruchomieniowych dla agentów dostępnych już za 0,08 USD za godzinę sesji), pojawia się pytanie: gdzie leży trwała przewaga konkurencyjna?
Warto spojrzeć na to przez pryzmat pięciowarstwowego stosu:
| Warstwa | Funkcja | Obronność |
|---|---|---|
| Infrastruktura | Hosting modeli, sandboxing, persystencja | Niska. Skomodyzowana. Wielu dostawców. |
| Orkiestracja | Koordynacja wieloagentowa, kontrakty behawioralne | Średnia. Wymaga skumulowanej wiedzy praktycznej. |
| Zasady projektowania | Inżynieria produktu zorientowana na agenty | Średnio-wysoka. Wymaga doświadczenia domenowego. |
| Teza produktowa | Co budować i dla kogo | Wysoka. Wymaga wglądu rynkowego. |
| Model biznesowy | Jak praca generuje przychody | Najwyższa. Wymaga relacji z klientami. |
Kontrakty behawioralne mieszczą się w warstwie orkiestracji. To warstwa, w której większość zespołów obecnie zawodzi. Prawidłowe opanowanie orkiestracji oddziela "eksperymentowaliśmy z AI w kodowaniu" od "AI jest naszym sposobem na dostarczanie kodu."
Zasady inżynierii produktu zorientowanej na agenty od PostHog potwierdzają to od strony produktowej. Ich piąta zasada ("traktuj agenty jak prawdziwych użytkowników") to w istocie ten sam wniosek: AI potrzebuje jawnych, przetestowanych i zweryfikowanych ograniczeń, nie domysłów.
Trzy wzorce warte wdrożenia
Z repozytorium karpathy-skills warto wynieść przede wszystkim te trzy wzorce:
- Definiuj kryteria sukcesu, nie instrukcje. Zasada Wykonania Zorientowanego na Cel Karpathy'ego działa, ponieważ LLM lepiej iteruje ku mierzalnemu celowi niż podąża za krokami proceduralnymi. Zdefiniuj, jak wygląda "ukończone". Agent sam znajdzie drogę do tego punktu.
- Rozdziel tworzenie od przeglądu. W systemach wieloagentowych agent piszący kod nie powinien być tym samym, który go zatwierdza. W przepływach jednoagentowych ta sama zasada obowiązuje: wyniki AI należy przeglądać z taką samą rzetelnością, jaką stosuje się do pull requesta młodszego dewelopera.
- Wersjonuj kontrakty jak kod. Pliki CLAUDE.md, systemowe prompty i definicje agentów to artefakty produkcyjne. Należą do kontroli wersji, zasługują na code review i powinny ewoluować na podstawie zaobserwowanych awarii. Samo repozytorium karpathy-skills jest dowodem: to wersjonowany, recenzowany przez społeczność kontrakt behawioralny.
Te 22 000 gwiazdek wskazuje na ideę, że różnica między narzędziami AI produkującymi szum a narzędziami AI dostarczającymi gotowe do wdrożenia funkcje często sprowadza się do dobrze napisanego pliku kontraktów. webvise buduje na tej idei każdego dnia. Aby zbadać, co kontrakty behawioralne i wieloagentowa orkiestracja mogłyby oznaczać dla danego przepływu pracy deweloperskiej, wystarczy napisać.
Praktyki webvise są zgodne z normami ISO 27001 i ISO 42001.