Plik z instrukcjami dla agenta: 28 procent szybciej, ale nie mądrzej

Rada „dodaj do repo plik z instrukcjami dla agenta” powtarza się dziś w każdym poradniku. Zwykle bez liczby, za to z obietnicą: AI wreszcie zrozumie Twój projekt.

Od stycznia jest pomiar. Sześcioro badaczy wzięło 10 repozytoriów i 124 prawdziwe pull requesty, po czym uruchomiło na nich Codex i Claude Code dwa razy: raz z plikiem AGENTS.md w repo, raz bez. Każde zadanie porównano więc samo ze sobą.

Wynik jest dobry, tylko dotyczy czegoś innego, niż obiecuje większość poradników.

Co dokładnie zmierzono

Ostatni wiersz jest tym, o którym się nie mówi. Plik z instrukcjami sprawił, że agent pracował szybciej i taniej, a nie że częściej trafiał.

To nie jest wada badania ani rozczarowanie. To jest właściwa definicja tego, do czego ten plik służy.

Dlaczego akurat tak, a nie inaczej

Zastanów się, na co agent bez instrukcji marnuje pierwsze tury.

Szuka, czym się buduje projekt. Otwiera package.json, żeby zgadnąć komendę testów. Sprawdza, czy katalog nazywa się src, czy app. Próbuje npm test, dostaje błąd, próbuje pnpm test. Zanim dotknie właściwego zadania, ma za sobą kilka wywołań narzędzi, z których żadne nie dotyczyło problemu.

Plik instrukcji usuwa dokładnie tę klasę pracy. Nie pomaga w myśleniu, bo nie ma jak: model rozumuje tak samo dobrze albo tak samo źle niezależnie od tego, czy zna komendę budowania.

To jest też odpowiedź na pytanie, czy warto. Skoro zysk jest kosztowy i czasowy, to opłacalność liczy się jak przy każdej innej optymalizacji: ile razy ten plik zostanie przeczytany. W repozytorium, w którym agent pracuje codziennie, zwraca się w tydzień. W projekcie ruszanym raz na kwartał nie ma czego optymalizować.

Standard się ustabilizował

Przez dwa lata każde narzędzie miało własny plik. To się skończyło.

AGENTS.md powstał w sierpniu 2025 jako otwarta specyfikacja, przy udziale OpenAI, Google, Cursora i Factory. W grudniu 2025 trafił pod opiekę Agentic AI Foundation przy Linux Foundation, razem z Model Context Protocol i projektem goose. W połowie 2026 był obecny w ponad 60 tysiącach publicznych repozytoriów.

Praktyczny wniosek dla zespołu: jedno źródło prawdy zamiast czterech plików, które się rozjeżdżają. Claude Code używa własnej nazwy CLAUDE.md, ale obsługuje dowiązanie symboliczne do AGENTS.md, więc da się to sprowadzić do jednego pliku dla wszystkich narzędzi.

Popularny szablon działa przeciwko Tobie

Tu zaczyna się część, w której trzeba się pospierać z tym, co krąży po internecie.

Typowy „wzorowy plik reguł” wygląda tak: nagłówek „Jesteś seniorem programistą”, lista technologii z numerami wersji, a potem ściana zakazów. Nie używaj any. Nie usuwaj komentarzy TODO. Nie modyfikuj plików konfiguracyjnych. Zakaz pisania czystego CSS. Zawsze zwracaj kompletny kod.

Ten szablon powstał dla modeli z 2023 roku, które trzeba było przekrzykiwać. Dziś ma cztery problemy.

Zakazy są słabszym narzędziem niż opis celu. Anthropic pisze w swoim przewodniku po promptowaniu, że najnowsze modele są trenowane do precyzyjnego wykonywania instrukcji i mocniej reagują na prompt systemowy niż poprzednie. Sformułowania, które miały ośmielić starsze modele do sięgania po narzędzia, dziś wywołują nadgorliwość. Zamiast „KRYTYCZNE: MUSISZ użyć tego narzędzia, gdy…” przewodnik radzi pisać zwyczajnie: „Użyj tego narzędzia, gdy…”. A zakaz czynności, której model i tak by nie wykonał, nie jest neutralny, bo wprowadza ją do kontekstu jako temat.

Aktualizacja z 11 września 2026: Anthropic przeniósł te wskazówki z przewodnika migracji do przewodnika po promptowaniu. Zmieniłem odnośnik w źródłach i sformułowanie, żeby oddawało aktualny tekst.

Wielkie litery przestają cokolwiek znaczyć, gdy jest ich dziesięć. Jeśli pięć reguł ma prefiks „KRYTYCZNE”, żadna go nie ma. Nacisk jest narzędziem punktowym, na jedną naprawdę niedoważoną instrukcję, a nie domyślnym rejestrem całego pliku.

Numery wersji gniją. Szablon z sierpnia 2026 wciąż każe używać React 18 i Next.js 14. Plik instrukcji ma opisywać architekturę, granice i komendy, a nie zamrażać stan package.json, który i tak jest w repo i jest prawdziwszy.

„Jesteś seniorem programistą” nie jest kontekstem. Jedno zdanie roli jest w porządku. Problem zaczyna się, gdy zastępuje informacje, których model naprawdę nie ma: co to za produkt, dla kogo, co jest w tym systemie nietypowe, gdzie przebiega granica, za którą nie wolno wchodzić.

Co zostawić, a co wyciąć

Kryterium jest jedno: czy model może to wiedzieć bez Ciebie.

Zostaw to, co wie tylko autor:

• Komendy budowania i testów, dokładnie, z flagami. To jest ta pozycja, która realnie kupuje te 28 procent.
• Układ katalogów i konwencje nazewnicze, jeśli odbiegają od oczywistych.
• Granice: pliki i katalogi, których agent nie ma ruszać, oraz co wymaga Twojej zgody.
• Kontekst produktu i poziom jakości. System medyczny i wewnętrzne narzędzie do raportów zasługują na inne domyślne decyzje.
• Powody. Reguła z uzasadnieniem przenosi się na sytuacje, których nie przewidziałeś, a sama reguła nie.

Wytnij to, co model już wie: ogólne cnoty w rodzaju „pisz czytelny kod”, wykłady z podstaw języka, powtórzenia tej samej zasady w trzech sekcjach i listy zakazów bez powodu.

Format też się zmienił

Jeżeli pracujesz w Cursorze i masz w repo .cursorrules, to jest format przestarzały od końca 2024 roku. Nadal jest czytany, więc nic się nie psuje, ale nie dostaje nowych możliwości.

Następca to katalog .cursor/rules/ z plikami .mdc, w których nagłówek YAML steruje tym, kiedy reguła w ogóle wchodzi do kontekstu:

---
description: Standardy komponentów Reacta
globs: ["**/*.tsx", "**/*.jsx"]
alwaysApply: false
---

Różnica jest kosztowa, a nie kosmetyczna. Monolit ładuje się w całości przy każdej interakcji, także wtedy, gdy poprawiasz skrypt w Pythonie. Reguły z globs wchodzą tylko tam, gdzie dotyczą.

To ta sama logika, co przy cache'u po stronie dostawcy: plik instrukcji jedzie w każdym zapytaniu, więc jego długość jest podatkiem płaconym bez przerwy, a nie jednorazowym kosztem.

Od czego zacząć

1. Napisz sam pierwszą wersję, nie generuj jej automatem. Polecenie inicjalizacyjne w narzędziu wypluje streszczenie repozytorium, czyli rzeczy, które agent i tak sobie przeczyta. Wartość jest w tym, czego w repo nie widać.
2. Zacznij od komend. Budowanie, testy, lint, dokładnie tak, jak je wpisujesz. To jedna sekcja i ona odpowiada za większość zysku.
3. Dopisz granice. Czego nie ruszać i co wymaga pytania. Krótko, z powodem.
4. Utnij wszystko, co jest prawdą o programowaniu w ogóle. Zwykle wypada połowa.
5. Zmierz u siebie. Zrób to samo zadanie z plikiem i bez, porównaj czas i liczbę wywołań narzędzi. Badanie mierzyło 124 przypadki na cudzych repozytoriach, Twoje jest jedno i konkretne.

Punkt piąty jest ważniejszy, niż wygląda. Cała ta rada opiera się na jednym badaniu z niewielką próbą, w którym autorzy sami zaznaczają, że wynik dotyczy zadań typu pull request i jest wstępny. Liczby są dobrą przesłanką, nie dowodem na Twój przypadek.

Podsumowanie

Plik instrukcji jest tanią, mierzalną optymalizacją kosztu i czasu. Nie jest sposobem na to, żeby agent zaczął podejmować lepsze decyzje, i szkoda go na to męczyć.

Reguła, którą bym zapamiętał: każde zdanie w tym pliku ma odpowiadać na pytanie, które agent inaczej musiałby sobie zadać. Reszta to koszt doliczany do każdego zapytania.

Pokrewne teksty: higiena kontekstu o tym, dlaczego więcej kontekstu potrafi szkodzić, oraz cache po stronie dostawcy o cenie długiego, stałego prefiksu.