Strona główna / Artykuły

Twój plik AGENTS.md został napisany dla gorszego modelu: audyt zadłużenia związanych z promptami

Stare zasady AGENTS.md przetrwają błędy modelu, które naprawiono. Naucz się rozpoznawać problemy z promptami, sprowadzać umiejętności do niezbędnego minimum, ustawiać uprawnienia i określać cele przed rozpoczęciem pracy.

Wydawca: REACTAPP.TOP8 min czytania1854 słów

Źródła: Your AGENTS.md Was Written for a Worse Model

Każdy wiersz w pliku AGENTS.md był zazwyczaj dodawany w celu naprawy rzeczywistego błędu. Modele się udoskonalają, błąd zanika, a reguła pozostaje. To jest dług związany z promptami: rozwiązanie tymczasowe na słabość jednego modelu, które przerodziło się w stałą zasadę. Rozwiązaniem jest nadanie plikowi węższego zakresu obowiązków, obejmującego niezmienniki, ukryte ograniczenia i granice uprawnień, a także definicję ukończenia pracy.

Za każdym razem, gdy agent kodujący popełnia błąd, który ludzie pamiętają, ktoś dodaje regułę. Edytuje zbyt wiele, więc w pliku zaleca się modyfikowanie tylko tego, co konieczne. Pomija weryfikację, więc kolejny wiersz wymaga za każdym razem pełnego zestawu testów. Zmienia zależności bez prośby, więc zmiany w zależnościach wymagają już tylko zatwierdzenia. Błąka się po repozytorium, więc w pliku określono, które dokumenty należy przeczytać najpierw.

Każda reguła miała sens w momencie jej napisania. Potem zmienił się model.

OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done

Najnowsza generacja modeli, przykładem której jest GPT-6 Astra, znacznie lepiej wykonuje polecenia niż wcześniejsze modele do kodowania, co zmienia zasady funkcjonowania systemów opartych na promptach. Słaby model może zignorować zbyt ogólne zasady, natomiast silny może je ślepo przestrzegać. Dlatego polecenie opracowane w celu skorygowania wad starszego modelu może stać się przeszkodą w przypadku nowszego modelu. Jeśli zaktualizujesz model bez sprawdzenia jego poleceń, dawne słabości pozostaną w nowym systemie jako stała zasada. Model się poprawił, ale struktura promptów pozostała bez zmian.

Każda awaria pozostawia ślad

Kod gromadzi „dług techniczny”, gdy szybkie lokalne rozwiązanie staje się trwałą ograniczeniem strukturalnym. Polecenia skierowane do agentów w ten sam sposób powodują gromadzenie się takiego długu.

Załóżmy, że starszy model do kodowania ciągle zapominał sprawdzać swoje zmiany, więc ktoś dodał:

Always run the entire test suite after every change.

W tamtym czasie to mogło poprawić niezawodność. Rok później model już potrafi wyłapać dotknięte testy i sprawdzić własną pracę, a mimo to instrukcja wciąż istnieje. Teraz prosty poprawka jednym słowem może uruchomić dwadzieścia minut testów integracyjnych. Nic nie jest uszkodzone, a agent wiernie przestrzega zasad repozytorium. Problem polega na tym, że stary patch behawioralny stał się trwałą polityką inżynieryjną.

To jest dług szybkiego rozwiązania. Reguła rozwiązuje rzeczywisty problem, problem znika, a reguła pozostaje.

Umiejętności kosztują coś przed uruchomieniem

Umiejętności wydają się tanie, ponieważ ich pełna zawartość ładowana jest tylko w razie potrzeby. Format Agent Skills opisuje stopniowe ujawnianie informacji: najpierw ładowane są nazwa i opis umiejętności, a pełny plik dopiero wtedy, gdy zadanie się do niej odnosi.

Jednak zanim model będzie mógł wybrać umiejętność, musi najpierw rozpoznać dostępne opcje, więc nazwy i opisy już teraz konkurują o uwagę.

Wyobraź sobie repozytorium zawierające oddzielne umiejętności dotyczące migracji bazy danych, PostgreSQL, projektowania schematów, przechowywania danych w tle, optymalizacji zapytań oraz ich przywracania. Każda z nich ma ogólny opis, w którym wspomina się zarówno o SQL, migracjach, schematach, zapytaniach, modelach, jak i o przechowywaniu danych. Nawet niewielka modyfikacja zapytania wydaje się teraz istotna dla połowy dostępnych umiejętności, więc agent musi je sklasyfikować, zanim będzie mógł pisać kod.

Lepszym rozwiązaniem pozostaje stopniowe ujawnianie informacji, co również rekomenduje dokumentacja umiejętności OpenAI: szczegółowe wskazówki znajdują się w plikach pomocniczych, które są dostarczane dopiero wtedy, gdy zadanie ich wymaga.

database/
├── router.md
└── references/
    ├── migrations.md
    ├── performance.md
    └── recovery.md

Plik źródłowy wymaga tylko tyle informacji, ile jest potrzebne do przekierowania zadania. Zmiana schematu prowadzi do pliku migrations.md, wolna zapytanie do performance.md, a przy przywracaniu danych lub ich utracie do recovery.md. Te szczegóły nie są porzucane – pojawiają się wtedy, gdy zadanie daje agentowi powód, by je przeczytać, co pozwala lepiej wykorzystać kontekst niż poleganie na domysłach przy pozyskiwaniu wiedzy operacyjnej.

AGENTS.md powinien zawierać to, czego nie może wyjaśnić kod

Instrukcje na poziomie repozytorium zachowują się inaczej, ponieważ towarzyszą agentowi niemal przy każdym zadaniu. Pliki takie jak AGENTS.md są ładowane do sesji jako stały kontekst, tak jak to opisują dokumenty dotyczące pamięci w Claude Code, co sprawia, że ich błędy, przestarzałość lub niepotrzebna szerokość mają duży wpływ.

Praktyczny test: czy kompetentny inżynier, patrząc na ten repozytorium, mógłby to rozwiązać w sposób bezpieczny i tanio? Jeśli tak, to zasada może nie należeć do pliku AGENTS.md. Jeśli nie, to najprawdopodobniej należy.

Porównaj dwie instrukcje. Pierwsza to wiedza specyficzna dla repozytorium, której model nie może bezpiecznie wywnioskować, więc pozostaje taka, jaka jest:

KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.

Drugi opisuje proces pracy, który może być odpowiedni przy refaktoryzacji architektury, ale jest przesadą przy poprawianiu błędu pisowni jednego słowa, więc powinien zostać usunięty.

MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies

Trwałe instrukcje powinny obejmować przede wszystkim trzy elementy: niezmienne, które muszą pozostać prawdziwe, ukryte ograniczenia, których kod nie ujawnia jasno, oraz granice autonomii wskazujące, gdzie agent może działać, a gdzie decyzja musi zapadać u człowieka. To znacznie prostsze zadanie niż nauczenie modelu, jak zajmować się inżynierią oprogramowania.

Lepsze modele sprawiają, że uprawnienia stają się ważniejsze

Silniejsze przestrzeganie instrukcji prowadzi do subtelniejszych problemów. Agent może tak starannie przestrzegać ustalonych granic, że zatrzymuje się w momencie, w którym chcieliśmy, aby kontynuował działanie.

Załóżmy, że zaimplementuje jakąś zmianę, a lokalny test wpływany tą zmianą zawiedzie. Agent zgłosi, że auth_spec.ts nie działa poprawnie, i zapyta, czy powinien to naprawić. Model wie, jak naprawić ten test, ale nie wie, czy ta naprawa mieści się w zakresie uprawnień, które mu przyznano. W takim przypadku przyznanie uprawnień jest bardziej pomocne niż jakakolwiek inna procedura:

Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.

Te linijki informują agenta o trzech rzeczach, których nie zawsze może wywnioskować: środowisko jest bezpieczne, naprawa mieści się w zakresie działań, a on może kontynuować pracę. W ten sposób ustalone granice lepiej kierują decyzjami niż ogólne zakazy typu „nigdy nie rozszerzać zakresu”.

Jeden ze sposobów podziału odpowiedzialności w praktyce:

Wymagają zatwierdzenia przez człowieka:

  • Usuwanie danych produkcyjnych.
  • Zmiana polityki autoryzacji.
  • Naruszenie umowy publicznego API.
  • Wprowadzenie migracji wiążącej się z ryzykiem operacyjnym.

Agent zazwyczaj może kontynuować z:

  • Naprawianiem testów, które zostały uszkodzone przez jego własną zmianę.
  • Aktualizowaniem pobliskich lokalnych typów.
  • Formatowaniem plików, które modyfikował.
  • Ponownym uruchamianiem dotkniętych lokalnych testów.

Różnice wynikają z konsekwencji tych działań – nie wszystkie sądzące są równie wymagające tego samego poziomu zatwierdzenia.

Zdefiniuj, co oznacza zakończenie, zanim opiszesz drogę

Starsze polecenia często opisują trasę:

Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.

To może pomóc, gdy proces pracy jest naprawdę kruchy, ale zdolny agent zazwyczaj odnosi większe korzyści z jasnego punktu końcowego. Porównaj prosty żądanie

Implement the avatar endpoint.

wersja z linią mety:

Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.

Drugi element nigdy nie określa, który plik należy otworzyć najpierw. Podaje jedynie, jak powinien wyglądać wynik końcowy. Ta różnica staje się coraz bardziej wyraźna, gdy modele nabierają wystarczającej zdolności oceny, by same wybrać drogę w bazie kodu. Ludzie ustalają cel i niebezpieczne obszary, a agent oblicza trasę.

Zachowaj świadomą hierarchię instrukcji

Uporządkowana struktura składa się z trzech oddzielnych warstw. Pierwszą jest plik repositoria:

AGENTS.md
    ↓
Repository invariants
Safety boundaries
Global permissions

Drugi zawiera umiejętności:

Skills
    ↓
Specialized workflows
Loaded only when relevantTask prompt
    ↓
Immediate objective
Local constraints
Definition of done

Trzecim elementem jest sam prompt zadania. Problemy pojawiają się, gdy poszczególne warstwy zaczynają się przenikać: jednorazowy proces realizacji zadania wprowadzony do pliku AGENTS.md, globalna zasada bezpieczeństwa ukryta w umiejętności, której model może w ogóle nie załadować, umiejętność, która przeradza się w encyklopedię, lub prompt zadania powtarzający informacje z repozytorium, które model już posiada. W miarę wzrostu możliwości modeli ta duplikacja staje się coraz droższa.

Badanie zaległości w promptach przy zmianach modelu

Uaktualnienie modelu powinno wywołać audyt instrukcji. Nie dlatego, że każda stara instrukcja jest błędna, ale dlatego, że założenia leżące u jej podstaw mogły ulec zmianie. Skuteczny audyt składa się z czterech etapów.

Przeprowadzenie inwentaryzacji historycznych kompensacji

Zbierz wszystko, co wpływa na zachowanie agenta:

  • AGENTS.md
  • opisy umiejętności
  • treść umiejętności
  • prompty repozytorium na poziomie systemu
  • instrukcje powtarzane w szablonach zadań

Dla każdej zasady sprawdź, dlaczego istnieje i jaki błąd skłonił kogoś do jej dodania.

Rozróżnij prawdziwe niezmienniki od nawyków

Zadaj sobie pytanie, czy kompetentny inżynier mógłby bezpiecznie i tanio wywnioskować tę zasadę z repozytorium. Jeśli tak, sprawdź, czy można ją usunąć. Jeśli nie, zachowaj ją. Zasady dotyczące ryzyka w produkcji, generowanych artefaktów, ukrytego zachowania infrastruktury oraz niewidocznych ograniczeń operacyjnych wymagają szczególnej uwagi.

Przekształć zaawansowane umiejętności w narzędzia pomocnicze

Jeśli jedna umiejętność jest potrzebna w kilku procesach, zmniejsz punkt wejścia do niej. Podawaj instrukcje migracji tylko w przypadku migracji, a procedury odzyskiwania tylko wtedy, gdy jest to konieczne. Specjalistyczna wiedza pozostaje, nie musi być wprowadzana do każdego pobliskiego zadania.

Przeczytaj ponownie każdą zasadę zakazową, aby zrozumieć kryjące się za nią ryzyko

Zasady w stylu „NIGDY nie dotykaj X”, „ZAWSZE pytaj przed Y” lub „Tylko modyfikuj Z” mogą nadal być słuszne, ale każdą z nich należy sprawdzić pod kątem konsekwencji, których miała zapobiec. Czasami lepsza zasada stanowi, że X można swobodnie modyfikować podczas rozwoju lokalnego, ale w środowisku produkcyjnym wymaga uprzedniego pytania, albo że regresje spowodowane własnymi zmianami agenta można naprawić, podczas gdy zmiany szerszego zakresu wymagają zatwierdzenia.

Celem nie jest maksymalna autonomia. Chodzi o to, by skupić ludzką uwagę tam, gdzie konsekwencje tego wymagają.

Co powinno przetrwać każdą aktualizację

Nawet najlepsze modele wymagają niektórych instrukcji. Wdrożenie może potrzebować nieudokumentowanego flaga typu legacy. Generowane pliki mogą wyglądać na edytowalne, mimo że wszelkie zmiany są nadpisywane. Środowisko lokalne może przypominać środowisko produkcyjne przy użyciu tymczasowych elementów. Migracja może musieć działać w dwóch działających wersjach aplikacji. Mają one duże znaczenie, ponieważ sama inteligencja nie pozwala na ich pewne wykrycie.

Filtrem, który należy zastosować, jest wartość informacyjna. Jeśli instrukcja obejmuje coś, czego model nie może bezpiecznie odkryć, należy ją zachować. Jeśli opisuje jedynie to, jak starszy model musiał wykonać zwykłe zadanie inżynieryjne, należy to ponownie przemyśleć. Duża liczba instrukcji nie jest przyczyną „długu promptowego”. Dług ten pochodzi od tych instrukcji, których powód istnienia już nie istnieje.

Stary podejście do programowania agentów polegało na szczegółowym opisywaniu każdego kroku procesu. W miarę udoskonalania się modeli lepiej sprawdza się prostszy projekt: należy zachować niezmienne elementy, ustalić uprawnienia i jasno określić, co oznacza zakończenie zadania. Resztę powinien załatwić agent, a po wprowadzeniu nowego modelu należy najpierw przejrzeć zasady, zanim napisze się coś nowego.