Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?

Strategie z raportu:

• Mierzenie rzeczywistego wpływu kontekstu: Zamiast zakładać, że dodatkowe pliki typu AGENTS.md zawsze pomagają AI, należy mierzyć ich wpływ na konkretne zadania. Badania wykazały, że dodawanie obszernego, generowanego kontekstu często wręcz obniża wskaźnik sukcesu rozwiązywania problemów o kilka procent.

• Skupienie się na interwencji chirurgicznej (Surgical Intervention): Pliki kontekstowe powinny rozwiązywać tylko te niejednoznaczności, z którymi kod i wbudowane narzędzia agenta nie radzą sobie samodzielnie. Raport nakazuje traktowanie tych plików jako zbiór "drogich prawd", a nie uniwersalną dokumentację.

• Ścisłe monitorowanie kosztów (Inference Cost Tracking): Należy kontrolować zużycie tokenów przy korzystaniu z plików kontekstowych. Raport dowodzi, że ich obecność prowokuje agenta do nadmiernej analizy kodu i wydłuża proces, co zwiększa koszty operacyjne aż o 20%.

  
  

Dobre praktyki:

• Ręczne tworzenie plików przez ludzi: Zamiast zlecać AI generowanie plików kontekstowych, powinny one być pisane ręcznie przez programistów znających projekt. Raport wykazuje, że tylko zwięzłe, ludzkie pliki przynoszą marginalne korzyści (ok. 4% wzrostu wydajności).

• Utrzymywanie ekstremalnej zwięzłości (Keep it Lean): Pliki kontekstowe powinny być maksymalnie krótkie. Najlepsze efekty i oszczędności uzyskuje się, ograniczając objętość pliku do minimum – profesjonalne zespoły często mieszczą się w zaledwie 60 liniach.

• Unikanie dublowania informacji o strukturze: Nie marnuj miejsca i tokenów w plikach kontekstowych na mapowanie katalogów czy opisywanie podstawowych funkcji. Agenci programistyczni doskonale radzą sobie z samodzielnym przeszukiwaniem drzewa plików za pomocą własnych narzędzi.

Czego unikać?

• Polegania na auto-generowanym kontekście (LLM-generated context): Zdecydowanie unikaj używania narzędzi i skryptów, które automatycznie budują obszerne pliki AGENTS.md na podstawie analizy repozytorium. Taki wygenerowany "szum" obniża skuteczność AI średnio o 3%.

• Przeładowywania kontekstu (Context Pollution): Unikaj przekraczania granicy kilkuset linii w plikach z wytycznymi. Długie pliki powodują zjawisko interferencji i sprawiają, że asystenci AI gubią kluczowe priorytety zadań pod nawałem instrukcji.

• Wymuszania nieproporcjonalnych procesów: Unikaj instrukcji, które nakładają na agenta sztywne i ciężkie wymogi dla każdego zadania (tzw. over-compliance). Agent zmarnuje czas i tokeny na niepotrzebne kroki, zamiast od razu dostarczyć rozwiązanie małego problemu.