Przygotowanie repozytorium na agentów kodujących, ze sprawdzeniami, które to potwierdzają

Czego agent nie ma, a twoi inżynierowie mają

Każda sesja Claude Code zaczyna się od pustego okna kontekstu i inni agenci kodujący działają podobnie. Poza instrukcjami organizacji lub osobistymi i pamięcią wczytywanymi na starcie agent wie o twoim repozytorium tyle, ile repozytorium mu powie, plus to, co znajdzie, przeszukując kod. Resztę twoi inżynierowie noszą w głowie, na przykład zmienną środowiskową, którą trzeba ustawić, usługę, która musi działać przed testami integracyjnymi, i test, który pada w poniedziałki.

Bez tej wiedzy agent zgaduje. Dokumentacja GitHuba dla jego agenta chmurowego mówi, że Copilot potrafi znaleźć i zainstalować zależności metodą prób i błędów, ale jest to wolne i zawodne, a przy prywatnych zależnościach może się w ogóle nie udać. Zgadywanie, które się kompiluje, i tak trafia do review, gdzie wygląda jak zwykły kod.

Sześć pytań, na które musi odpowiedzieć świeży checkout

Zadajemy je czystemu klonowi, w kontenerze albo na maszynie, która nigdy nie widziała tego repozytorium. Odpowiedź tak wymaga dowodu: komenda faktycznie się wykonała.

• Czy jedna udokumentowana komenda instaluje zależności z lockfile'a, bez pytań i bez narzędzi, które istnieją tylko na laptopach?
• Czy jedna komenda uruchamia szybki zestaw testów, który za każdym razem daje ten sam wynik, a wolne lub niestabilne zestawy są oznaczone i wyłączone z niego?
• Czy bazy danych, kolejki i inne usługi startują ze skryptu albo definicji kontenera, z danymi testowymi, których oczekują testy?
• Czy zapisano, jakich poświadczeń potrzebuje konfiguracja, a których sesja agenta nie może nigdy dostać?
• Czy plik instrukcji wymienia komendy, ścieżki, których agent nie może edytować, i konwencje, których pilnują recenzenci?
• Czy ten plik i otaczająca go konfiguracja agenta mają wskazanego właściciela?

Zamień udokumentowane komendy w job CI

Instrukcje starzeją się po cichu. Ktoś zmienia nazwę skryptu, a plik instrukcji nadal podaje starą. Rozwiązaniem jest jeden punkt wejścia, który wskazuje plik instrukcji i który job CI uruchamia z czystego checkoutu, dzięki czemu nieaktualna instrukcja psuje build, a nie przebieg agenta.

#!/usr/bin/env bash
# The one command agents and CI both run from a clean checkout.
# Named in AGENTS.md; CI runs it on every change to setup files.
set -euo pipefail
pnpm install --frozen-lockfile
pnpm build
pnpm lint
pnpm test:unit

Agenci hostowani dokładają własną warstwę konfiguracji, która wymaga tego samego podejścia. GitHub przed startem swojego agenta chmurowego uruchamia workflow copilot-setup-steps.yml, i to tylko z domyślnego brancha. Jeśli krok konfiguracji się nie powiedzie, agent pomija pozostałe kroki i zaczyna pracę w takim stanie środowiska, jaki akurat jest, więc zepsuta konfiguracja objawia się dziwnym zachowaniem agenta, a nie czerwonym buildem. Workflow uruchamia się też jako zwykły check przy każdej zmianie i można go odpalić ręcznie, więc da się go testować.

W Codex Cloud od OpenAI Codex przygotowuje i testuje środowisko razem z tobą, a publikacja utrwala przygotowany system plików, od którego startują nowe zadania. Zmiany w tej przygotowanej konfiguracji docierają do nowych zadań po ponownej publikacji, a istniejące zadania zachowują własne pliki. Część zapisanej konfiguracji działa od razu w aktywnym środowisku, więc przed testem sprawdź, jaki rodzaj zmiany wprowadziłeś.

Co powinien zawierać plik instrukcji, a czego nie

Dokumentacja Claude Code wymaga instrukcji na tyle konkretnych, żeby dało się je sprawdzić, na przykład dokładnej komendy testów, i zaleca, by każdy CLAUDE.md miał poniżej 200 linii, bo dłuższe pliki zużywają kontekst i gorzej są przestrzegane. Dokumentacja reguł Cursora odradza kopiowanie przewodników stylu, które może egzekwować linter. To, czego plik potrzebuje, jest krótkie:

• Komendy instalacji, budowania, lintowania i szybkich testów, dokładnie takie, jakie uruchamia CI
• Ścieżki, których agent nie może edytować, na przykład kod generowany, dołączone zależności i zmergowane migracje
• Konwencje pilnowane przez recenzentów, które odbiegają od typowych domyślnych
• Co znaczy gotowe: które checki muszą przejść i co zawiera opis pull requesta

Kilka narzędzi czyta już AGENTS.md. Claude Code czyta go, gdy nie ma pliku CLAUDE.md, Cursor obsługuje go w katalogu głównym i w podkatalogach, a agent chmurowy GitHuba czyta pliki AGENTS.md obok własnych plików instrukcji. Jeden wspólny plik z cienkimi dodatkami dla konkretnych narzędzi zapobiega rozjeżdżaniu się trzech kopii. Żaden z tych plików niczego nie egzekwuje: dokumentacja Claude Code mówi, że narzędzie traktuje je jako kontekst, więc reguła, która musi obowiązywać, należy do uprawnień, hooków albo CI.

Od odpowiedzi do reguły pracy

Odpowiedzi decydują, jak agenci mogą pracować w danym repozytorium. Stosujemy taką regułę:

• Wszystkie sześć na tak: kandydaci do zadań delegowanych, które recenzent może zweryfikować, przy niezmienionym review i wymaganych checkach.
• Konfiguracja działa, ale testy są niestabilne lub wolne: tylko praca interaktywna, w której inżynier czyta wyniki testów, dopóki szybki zestaw testów się nie ustabilizuje.
• Czysty checkout się nie buduje: najpierw to napraw, bo agent zużyje tam budżet na ponowne odkrywanie konfiguracji.

W hipotetycznym repozytorium usługi checkout wymaga lokalnego Postgresa, którego inżynierowie uruchomili miesiące temu, i tokenu do prywatnego rejestru pakietów. Naprawa to definicja kontenera dla bazy, poświadczenie do rejestru dostępne tylko dla konfiguracji i powyższy skrypt agent-check, każde jako jedna zmiana do review.

Czego gotowość nie naprawi

Przygotowane repozytorium kończy zgadywanie co do środowiska. Nie sprawi jednak, że niejasne zadania staną się jasne, nie doda mocy przerobowej w review i nie uczyni agentów odpowiednimi do pracy wymagającej głębokiej wiedzy domenowej. Repozytoria zależne od licencjonowanych narzędzi, specjalnego sprzętu albo systemów wewnętrznych mogą nie pasować do współdzielonego hostowanego sandboxa, ale to nie wyklucza delegowania. Agent chmurowy GitHuba może działać na self-hosted runnerach z dostępem do zasobów wewnętrznych, zalecanych jako jednorazowe runnery na jeden job, a konfiguracja self-hosted lub lokalna sprawdza się, jeśli jest powtarzalna i ma te same uprawnienia, checki i review. Dopiero gdy nic z tego nie jest możliwe, pozostaje lokalna praca interaktywna.

Gdy zmiany agenta przechodzą lokalnie, a padają w CIHarness engineering