Jak przestać pisać kod ręcznie i zacząć projektować uprzęże dla sieci neuronowych

Ostatnio złapałem się na dziwnym uczuciu. Siedzę w edytorze, uruchamiam agenta takiego jak Claude Code czy Cursor, zlecam mu zadanie, a dziesięć minut później przeglądam stos wymyślonych funkcji i popsutych typów. Próba dyktowania pięciostronicowego prompta systemowego zwykle pogarsza sytuację: model zapomina początek instrukcji już przy trzecim kroku.

Okazuje się, że w społeczności inżynieryjnej wokół OpenAI, Anthropic i Cursor problem ten został już sformalizowany jako osobna dyscyplina. Nazywa się Harness Engineering, co można przetłumaczyć jako projektowanie uprzęży lub wędzideł dla agentów.

Repozytorium deusyu/harness-engineering zebrało w jednym miejscu obszerną bazę wiedzy na ten temat: analizy koncepcji, tłumaczenia dziesiątek artykułów w języku angielskim od inżynierów takich jak Martin Fowler, LangChain i twórcy Bun, a także gotowe szablony do wdrożenia tego podejścia we własnych projektach.

Skąd wzięła się ta idea

Jeśli w klasycznym tworzeniu oprogramowania człowiek pisze kod, a maszyna go wykonuje, to wraz z pojawieniem się autonomicznych agentów łańcuch się zmienia. Człowiek formułuje ograniczenia i reguły gry, sieć neuronowa pisze kod, a środowisko uruchamia sprawdzenia i zwraca informacje zwrotne do agenta.

Chodzi o to, że inżynier przestaje być autorem każdej linijki. Głównym produktem pracy inżyniera staje się system ograniczeń: pliki konfiguracyjne AGENTS.md, niestandardowe lintery, testy strukturalne i ścisłe bramki w CI.

W repozytorium cytowane są dane z prawdziwego eksperymentu jednego z zespołów: w ciągu 5 miesięcy zespół liczący 3-7 osób zmergowal około 15 000 pull requestów obejmujących prawie milion linii kodu, zamykając średnio 3,5 PR-ów na osobę dziennie. Większość generacji odbywała się nocą w sześciogodzinnych sesjach.

Główne zasady Harness Engineering

Autor repozytorium dekonstruuje to podejście na kilka zastosowanych koncepcji.

Repozytorium jako jedyne źródło prawdy

Wszystko, co nie znajduje się w repozytorium git, nie istnieje dla agenta. Twoje rozmowy na Zoomie, dyskusje o architekturze na Slacku czy szkice w Google Docs nie trafiają do kontekstu modelu.

Jeśli postanowiłeś zmienić sygnaturę API lub uzgodniłeś strukturę folderów, powinno to żyć w repozytorium jako versioned pliki. Wszelkie specyfikacje i plany zadań są natychmiast commitowane do branchy.

Mapa zamiast encyklopedii

Typowym błędem przy konfigurowaniu agentic development jest tworzenie masywnego pliku systemowego z wszystkimi instrukcjami projektu. Modele toną w długich promptach.

Zamiast tego używa się pliku AGENTS.md o długości około 100 linii. Działa on jak spis treści lub mapa terenu, wskazując agentowi, które podkatalogi przeglądać po szczegóły w zależności od zadania. Każdy podkatalog zawiera własny lokalny plik AGENTS.md. Ta zasada nazywa się progresywnym ujawnianiem kontekstu.

Kontrola mechaniczna zamiast werbalnych ustaleń

Reguły tekstowe w dokumentacji szybko stają się nieaktualne, a agenci mają tendencję do ich ignorowania lub błędnej interpretacji. Lintery i testy jednostkowe nie stają się nieaktualne.

Zamiast rozbudowanych opisów stylu architektonicznego pisze się niestandardowe lintery. Najciekawsza część: komunikaty o błędach w takich linterach natychmiast zawierają jasne instrukcje naprawy problemu. Agent uruchamia sprawdzenie, łapie błąd lintera, czyta podpowiedź i sam przepisuje problematyczną sekcję kodu.

Czytelność kodu dla agentów i zarządzanie entropią

Przy wyborze bibliotek priorytet mają stabilne, dobrze udokumentowane technologie o przewidywalnym zachowaniu. Jeśli biblioteka jest zbyt złożona lub używa ciemnej magii metaprogramowania, agent będzie się ciągle potykać. Czasami łatwiej jest zaimplementować prosty wewnętrzny moduł od zera, niż zmusić sieć neuronową do zgadywania zachowania nieprzejrzystego zewnętrznego pakietu.

Ponadto agenci uwielbiają kopiować złe wzorce, jeśli znajdą je w istniejącym kodzie. Aby zapobiec gniciu repozytorium, w tle działają specjalne agenty refaktoryzacyjne, których zadanie sprowadza się do znajdowania odchyleń od standardów i tworzenia korekcyjnych PR-ów.

Samoreferencyjne repozytorium

To, co wyróżnia projekt deusyu/harness-engineering, to fakt, że jest zbudowany na tych samych zasadach, które opisuje.

Wewnątrz repozytorium działa ścisły skrypt scripts/check-consistency.sh, wyzwalany przez pre-commit hooki i GitHub Actions. Skrypt sprawdza trzynaście poziomów integralności:

• Weryfikuje dokładną liczbę artykułów wspomnianych w badge'ach i dokumentacji
• Monitoruje, czy struktura katalogów odpowiada zadeklarowanemu drzewu plików
• Waliduje wszystkie linki i tabele
• Kontroluje audyt obrazów w tłumaczeniach artykułów, aby żadne diagramy z oryginałów nie zostały utracone

Proces dodawania nowych materiałów jest zautomatyzowany poprzez wyspecjalizowany skill Claude, gdzie agenci wykonują wstępne parsowanie i formatowanie artykułów, podczas gdy człowiek działa tylko jako ostateczny cenzor.

Dla kogo jest ten projekt

Jeśli piszesz pet projects samodzielnie lub chcesz skonfigurować efektywną pracę z Cursor, Claude Code, Aider czy lokalnymi modelami w swoim zespole, to repozytorium warto dodać do zakładek.

Nie ma tutaj magicznych przycisków ani gotowych binarek. To podręcznik i zbiór doświadczeń inżynieryjnych, wyjaśniający, dlaczego Twoje prompty przestają działać na dystansie i jak skonfigurować repozytorium tak, aby sieci neuronowe przynosiły korzyści zamiast zamieniać bazę kodu w wysypisko.

Najłatwiejszy sposób na rozpoczęcie nauki to pliki w katalogu concepts/, następnie przyjrzyj się implementacji AGENTS.md w korzeniu projektu i przymierz się do podobnej struktury dla własnych roboczych repozytoriów.