Anthropic kończy swój tekst o code review regułą: gdy reviewer coś przeoczy, zapytaj, czego model nie miał przed oczami, i umieść poprawkę w CLAUDE.md, w skillu albo w nowym checku (artykuł (si apre in una nuova scheda)). Theo, czytając to, nazwał to złym domyślnym wyborem, i tu jestem z nim. Pracuję tak od miesięcy: zmieniam kod tak, żeby błąd był trudny do popełnienia, dodaję check, który go złapie, i dopiero potem piszę instrukcje. Zanim zaczniesz grzebać w CLAUDE.md i REVIEW.md, zapytaj, czy architektura albo kod nie powinny się zmienić tak, żeby błąd był niemożliwy by design. Spoiler: często tak jest.
Instrukcje to najbardziej kruche miejsce na regułę
Za instrukcję płacisz kontekstem w każdej sesji, można ją odczytać w najdroższy możliwy sposób i starzeje się, gdy kod się zmienia. Nauczyłem się tego na własnym setupie. Moje instrukcje mówiły, żeby najmocniejszego modelu używać do decyzji, a orkiestrator uruchamiał go jako subagenta także do zwykłej pracy. Dziś ta reguła jest napisana wielkimi literami (historia). Wielkie litery to nadal słowa. Następny krok to check w harnessie, który odrzuca takie uruchomienie, tak jak linter odrzuca import.
Brakujące tłumaczenie psuje build
Ta strona jest pisana po włosku, angielsku i polsku. Mogłem kazać agentom pamiętać o tłumaczeniu każdego eseju. Zamiast tego build się wywraca, jeśli esej istnieje w jednym języku, a w innym go brakuje, więc ani ja, ani agent nie możemy opublikować połowy zmiany. Ten esej istnieje w trzech językach, bo inaczej strona się nie kompiluje.
W kolofonie jest zdanie, pod którym nadal się podpisuję: minimalny wystarczający kontekst to właściwość repo, nie promptu.
Usuń złą opcję i postaw fence
W Intarget, na platformie agentowej, dwie biblioteki robiły to samo, czyli pobierały dane z serwera, i ludziom oraz agentom łatwo było wybrać złą. Jedną usunęliśmy, a lint rule wywraca się za każdym razem, gdy ktoś ją znowu importuje. Instrukcja „używaj tej drugiej biblioteki” byłaby przestrzegana, prawie zawsze. Lint rule nie da się obejść słowami.
Ta sama idea w mniejszej skali: w agencie WhatsApp dla CVing przeniosłem checki bezpieczeństwa z promptu do kodu, który wykonuje każdą akcję (szczegóły). To, co musi obowiązywać zawsze, należy umieścić tam, gdzie model nie może tego interpretować.
Jeśli agent robi review gorzej niż ty, najpierw spójrz na codebase
Hot take Theo, i moja: większość agentów robi dziś code review lepiej niż większość ludzi, a jeśli twój nie radzi sobie na twoim repo, zacznij od repo. Boris Cherny mówi to od drugiej strony: kod trudny do sprawdzenia tworzy codebase, w której trudno się pracuje.
Test, którego używam, pochodzi od Theo. Wyobraź sobie bardzo bystrego new hire'a, który pracował w tysiącach codebase'ów, nigdy w twojej, i który cały dzień robi nudną pracę bez narzekania. To, o co on się potknie, potknie też agenta, a poprawka jest dla obu ta sama: jaśniejsze granice, nazwy mówiące, co rzeczy robią, jeden oczywisty sposób na każdą rzecz.
Dotyczy to modeli frontier z prawdziwym budżetem tokenów. Jeśli masz mały model albo plan z wyliczonymi tokenami, ograniczeniem naprawdę jest model, i to każdemu się wybacza. Napisałem to, kiedy poprawiłem jeden z moich wcześniejszych tekstów.
To samo rozumowanie dotyczy pisania kodu. Jeśli myślisz, że twoją wartością jest pisanie lepszego kodu niż Opus, mierzysz niewłaściwą pracę. Moja to architektura, ograniczenia i kryteria akceptacji, oraz decyzja, czego w ogóle nie budować.
Instrukcje zmieniają się, gdy zmienia się projekt
Theo pokazał liczbę, która mi się spodobała: instrukcje dla agentów w jego repo zmieniają się mniej więcej raz dziennie, a komponent czatu od trzydziestu do pięćdziesięciu razy dziennie. Ostatnia zmiana instrukcji przyszła, bo repo przeszło na nowy setup. To zdrowy rytm: instrukcje opisują projekt, a kod zapobiega błędom.
Kiedy code-os, framework open source, którego używamy w Yempik, przeszedł na drugą wersję, usunęliśmy własne zduplikowane reguły. Każdy duplikat to kolejna dwuznaczność, za którą płaci się kontekstem w każdej sesji.
Zarzut: czyli pliki z instrukcjami są bezużyteczne
Są użyteczne i powinny być krótkie. Rada Anthropic dotycząca REVIEW.md jest dobra i stosuję ją: właściciele danej części kodu piszą, jak wygląda tam błąd (dla dokumentacji, że kłamie; dla konfiguracji, że źle kieruje), ograniczają nity, wymieniają ścieżki do pominięcia i proszą o plik i linię jako dowód. To wiedza, której kod sam nie wyrazi. Błędem jest używanie ich do łatania kodu, który zaprasza do błędu.
Od poniedziałku
- Po każdym powtórzonym błędzie agenta najpierw zapytaj, co w kodzie go zaprosiło.
- Tam, gdzie się da, spraw, żeby błąd był niemożliwy: typy, build, który się wywraca, usunięta zależność z fence.
- Potem check: lint rule, test, hook w harnessie.
- Dopiero potem linijka w instrukcjach, a plik niech będzie krótki.
- Używaj bystrego new hire'a jako testu dla swojej codebase.
- Aktualizuj instrukcje, gdy zmienia się projekt.
// reguła wielkimi literami nadal jest w moich instrukcjach. hook, który ją zastąpi, jest następny na liście.