AGENTS.md dla lokalnych agentów kodujących: najtańsza poprawa jakości, jaką możesz wprowadzić

Autor: Jakub Rusinowski · Ostatnia aktualizacja 2026-08-04 · Wartości sprzętowe wyliczone naszym silnikiem VRAM

AGENTS.md to zwykły plik Markdown w katalogu głównym repozytorium, mówiący agentom kodującym, jak budować, testować i zmieniać twój projekt. W 2026 czyta go natywnie większość agentów, a lokalnym modelom pomaga bardziej niż tym z czołówki, bo mały model nie wydedukuje twoich konwencji z kilku plików. Trzymaj go poniżej mniej więcej 100 linijek poleceń i twardych reguł — przy oknie 16–32K rozdęty plik z regułami kosztuje więcej, niż uczy.

Każdy agent kodujący potrzebuje tej samej garści faktów, zanim przyda się w twoim repozytorium: jak uruchomić testy, jak zbudować projekt, gdzie co leży i czego nigdy nie wolno ruszać. Bez nich model zgaduje — a lokalny model zgaduje gorzej, bo ma mniej ogólnej wiedzy o twoim stacku, na której mógłby się oprzeć, i mniejsze okno na eksplorację.\n\nLekarstwem jest plik. AGENTS.md w katalogu głównym stał się międzynarzędziową konwencją: otwarty plik instrukcji w formacie Markdown, który agenty czytają automatycznie, przyjęty szeroko w całym ekosystemie narzędzi w ciągu 2026 (natywnie czytają go Codex, Cursor, Copilot, Aider, Gemini CLI, Zed i inne) i utrzymywany jako otwarty standard, a nie format jednego dostawcy. Claude Code trzyma się własnej konwencji CLAUDE.md, spinanej importem albo dowiązaniem symbolicznym.\n\nDla lokalnych konfiguracji to najlepszy stosunek zyskanej jakości do włożonego wysiłku — kilkaset tokenów napisanych raz, które przerywają powtarzanie tych samych trzech błędów w każdej sesji.

Dlaczego małe modele zależą od niego bardziej

Model z czołówki często zdoła odtworzyć twoje konwencje z plików, które przeczyta. Model 8–27B, z ułamkiem okna i mniejszą utajoną wiedzą o idiomach twojego frameworka, w większości przypadków nie. Cztery konkretne skutki:\n\n- Wymyśla polecenia. Poproszony o uruchomienie testów spróbuje npm test w projekcie używającym pnpm vitest run, zobaczy porażkę i spędzi trzy tury na wychodzeniu z niej. Jedna linijka w pliku z regułami usuwa cały ten objazd.\n- Eksploruje, zamiast pracować. Bez podpowiedzi o układzie projektu czyta pliki, żeby ustalić, gdzie co jest — kosztowne w małym oknie, a każdy nieistotny plik rozcieńcza uwagę.\n- Domyślnie pisze w uśrednionym stylu internetu. Komponenty klasowe, ORM, który usunąłeś, biblioteka do logowania, której nigdy nie używałeś. Lokalny model cofa się do średniej swoich danych treningowych, o ile nie powiesz mu inaczej.\n- Powtarza błędy między sesjami. Nie ma pamięci między uruchomieniami; plik z regułami *jest* tą pamięcią. Każda spisana powracająca korekta to poprawka, której nie musisz robić drugi raz — „metapętla” poziomu 4 z loop engineeringu, wykonana ręcznie.

Szablon, który mieści się w małym oknie

Najpierw polecenia i twarde reguły — to tokeny o najwyższej wartości i te, które najpewniej przetrwają kompaktowanie. Proza na końcu albo wcale.

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- Test (fast, use this in loops): `pnpm vitest run src/`
- Test (full): `pnpm test`
- Types: `pnpm tsc --noEmit`
- Lint: `pnpm lint`
Run types + fast tests after every change. Both must pass before you report done.

## Layout
- `src/lib/` — pure logic, unit-tested. Put new business rules here.
- `src/components/` — React components, no data fetching.
- `src/server/` — API handlers. Never import from components/.
- Tests live beside the code as `*.test.ts`.

## Conventions
- TypeScript strict. No `any`. No default exports.
- Existing patterns win over your preferences — read a neighbouring file first.
- Errors: throw typed errors from lib/, handle at the server boundary.

## Never
- Never edit files under `generated/` or `*.snap`.
- Never modify tests to make them pass. Fix the code.
- Never add a dependency without asking.
- Never touch `.env`, migrations, or CI config.

To jakieś 250 tokenów, a usuwa większość powracających awarii. Sam plik zostaw po angielsku: czyta go model, nie człowiek, a modele kodujące trzymają się angielskich instrukcji wyraźnie lepiej. Zwróć uwagę na dwie linijki, które robią tu najcięższą robotę: szybkie polecenie testowe jawnie oznaczone jako to do pętli oraz „never modify tests to make them pass” — zabezpieczenie przed najczęstszym sposobem, w jaki agent produkuje zielony i bezwartościowy wynik.

Czego nie wpisywać

Pliki z regułami gniją w duplikaty README. Każdy token wydany na tło to token niewydany na twój kod, a przy oknie 16K ten bilans jest brutalny.\n\n- Żadnej historii projektu ani uzasadnień. Agent nie musi wiedzieć, dlaczego zeszliście z Webpacka.\n- Żadnych treści, które agent przeczyta szybciej, niż ty je zaktualizujesz. Nie wklejaj schematu bazy; napisz, gdzie leży plik ze schematem.\n- Żadnych pobożnych życzeń. „Pisz elegancki, idiomatyczny kod” nie zmienia nic. „Bez domyślnych eksportów” zmienia coś.\n- Żadnego dublowania konfiguracji narzędzi. Jeśli .eslintrc już to wymusza, agent dostanie błąd z lintera — taniej i pewniej niż akapit.\n- Żadnych nieaktualnych poleceń. Złe polecenie jest gorsze niż jego brak: agent mu ufa, ponosi porażkę i musi się z niej wygrzebywać. Przeglądaj plik za każdym razem, gdy zmieniasz skrypty.\n\nReguła kciuka przy lokalnych modelach: poniżej 100 linijek, a każda linijka to polecenie, ścieżka albo zakaz. Jeśli nie potrafisz powiedzieć, której awarii dana linijka zapobiega, usuń ją.

AGENTS.md, CLAUDE.md i cała reszta

Rozplenienie plików per narzędzie — .cursorrules, CLAUDE.md, .github/copilot-instructions.md — jest dokładnie tym, czemu AGENTS.md miał położyć kres.

Domyślne podejście w 2026: napisz AGENTS.md, a plik pod konkretne narzędzie dodaj dopiero, gdy natkniesz się na prawdziwe ograniczenie. Tam, gdzie narzędzie upiera się przy własnej nazwie, rób dowiązanie zamiast duplikatu — dwa pliki z regułami, które się nie zgadzają, to gorsza awaria niż brak jakiegokolwiek, bo nie zauważysz, który z nich agent przeczytał.

# Zamiast utrzymywać dwa pliki, zepnij Claude Code ze wspólnym
ln -s AGENTS.md CLAUDE.md

Uwaga przy lokalnych modelach: niezależnie od tego, który plik czyta twój agent, sprawdź, czy on faktycznie trafia do promptu. Jeśli złożony kontekst przekracza serwowane okno, plik z regułami — zwykle blisko początku — zostaje odcięty jako pierwszy. To najczęstszy powód, dla którego poprawny plik z regułami sprawia wrażenie ignorowanego; zobacz context engineering.

Skalowanie na monorepo

Pliki zagnieżdżone działają: AGENTS.md w podkatalogu obowiązuje przy pracy wewnątrz niego, a pierwszeństwo ma plik najbliższy. Przy monorepo trzymaj w pliku głównym to, co naprawdę uniwersalne (jak zainstalować, konwencja commitów, globalna lista zakazów), a polecenia specyficzne dla pakietu umieść przy pakietach.\n\nPrzy lokalnych modelach ma to większe znaczenie niż przy hostowanych, z tego samego powodu co zawsze: plik główny niosący polecenia builda wszystkich pakietów to w danym zadaniu w większości nieistotne tokeny. Zagnieżdżanie utrzymuje robocze okno małym — ta sama zasada, co przy dobieraniu zestawu roboczego, zastosowana do instrukcji.

Traktuj go jak żywy dokument

Plik z regułami zarabia na siebie utrzymaniem, nie napisaniem. Nawyk, który działa:\n\n1. Za każdym razem, gdy poprawiasz agenta drugi raz w tej samej sprawie, zapisz regułę. To jest wyzwalacz. Nie „agent się pomylił”, tylko „agent pomylił się znowu tak samo”.\n2. Przeczytaj plik raz w miesiącu i wyrzuć to, co się zdezaktualizowało. Złe polecenia aktywnie szkodzą.\n3. Trzymaj go w systemie kontroli wersji i przeglądaj w pull requestach. Kształtuje generowany kod, więc zasługuje na tę samą uwagę co konfiguracja lintera.\n4. Testuj go tanio. Zacznij świeżą sesję i poproś agenta, żeby podał polecenie testowe i katalogi, których nie wolno mu ruszać. Jeśli nie potrafi, plik albo nie jest czytany, albo jest za długi, by przetrwać kompaktowanie.\n\nW połączeniu z poleceniem weryfikującym i sandboxem utrzymywany plik z regułami to większość tego, co dzieli lokalnego agenta, który pomaga, od takiego, którego porzucasz po tygodniu.

Najczęstsze pytania

Co dalej

• Prompty systemowe i persony dla lokalnych modeli
• Kodowanie i debugowanie — przepływ pracy z promptami
• Konfiguracja lokalnego asystenta kodowania
• Agent harness: co właściwie zamienia lokalny model w agenta kodującego
• Context engineering dla lokalnych agentów kodujących: budżetowanie okna, za które płacisz
• Lokalny agent kodujący od zera do działania: Ollama + Qwen3-Coder + VS Code
• Sandbox dla lokalnego agenta kodującego: autonomia bez promienia rażenia
• Lokalny asystent kodowania — cały dział