Problem: dlaczego AI ciągle wywala się w tym samym miejscu

Każdy, kto używa Cursora, Windsurfa albo Claude Code, zna ten moment załamania: AI generuje cały blok kodu, wklejasz go, odpadasz — build się sypie, testy świecą na czerwono, zależności wylądowały w złym katalogu. To nie kwestia inteligencji AI. Ono po prostu nie zna „niepisanych zasad” twojego projektu.

AGENTS.md to plik Markdown w katalogu głównym projektu, napisany specjalnie dla AI. Mówi mu, jak budować, jak testować, jakich standardów przestrzegać. README.md jest dla ludzi — pełne opisów projektu, wytycznych dla kontrybutorów, historii marki. AI czyta to jak nowy pracownik, któremu pierwszego dnia wręczono firmowy folder reklamowy i kazano natychmiast pisać kod. Wie, czym zajmuje się firma, ale nie zna komend builda, nie wie, gdzie są testy, nie ma pojęcia o regułach ESLinta. Efekt? W każdej rozmowie musisz powtarzać: „użyj pnpm, nie npm”, „testy są w packages/web”, „nie zapomnij o lincie”. Powtarzasz to setny raz, a projekt dalej jest bałaganem.

Przy zleceniach strata jest jeszcze bardziej konkretna. Bierzesz projekt Next.js + Prisma, przyspieszasz pracę Cursorem, a AI odpala npm install — konfiguracja workspace pnpm idzie do kosza. Nie wie, gdzie trzymasz schemat bazy danych, generuje plik migracji, który od razu wywala błąd. Klient naciska na termin, a ty spędzasz trzy godziny na debugowaniu kodu napisanego przez AI. Tak się nie zarabia.

Trzy klasyczne sceny, w których AI nie zna reguł projektu: ① zły menedżer pakietów (projekt działa na pnpm, AI domyślnie odpala npm install), zależności lądują w złym miejscu, workspace przestaje działać; ② nie można znaleźć testów (testy są w packages/web, AI odpala pnpm test w katalogu głównym i dostaje „nie znaleziono testów”); ③ niespójny styl kodu (projekt używa ESLint + Prettier, AI generuje kod ze złymi wcięciami i cudzysłowami, CI od razu wywala build).

Szansa: AGENTS.md oddziela „dokumentację dla ludzi” od „dokumentacji dla maszyn”

Projekt open source AGENTS.md na GitHubie (repo: github.com/agentsmd/agents.md, około 24 tys. gwiazdek na 25.08.2026) rozwiązuje dokładnie ten problem. Pomysł jest banalnie prosty: wrzuć do katalogu głównego plik Markdown, który mówi AI, jak budować, jak testować i jakiego stylu kodu się trzymać.

To nie zamiennik README, tylko uzupełnienie. README służy ludziom, AGENTS.md służy agentom AI. Role są jasne, zero konfliktów.

Według źródła AGENTS.md został przyjęty przez dziesiątki tysięcy projektów open source (dokładna liczba do weryfikacji), obejmując VS Code, Cursor, Windsurf, Aider, GitHub Copilot i inne popularne narzędzia AI (potwierdzone); dodatkowo, według opinii społeczności, wsparcie oferują też OpenAI Codex i Google Jules (⚠️ niezweryfikowane). Jeśli się tego nie nauczysz teraz, pozwalasz AI mówić do ciebie gwarą, której nie rozumiesz.

Ścieżka 1: napisz minimalny AGENTS.md ręcznie

Koszt prawie zerowy. Tworzysz plik, piszesz trzy sekcje i wystarczy.

Kontekst: poniższe przykłady używają pnpm (oszczędza miejsce na dysku, wspiera workspace monorepo), turbo to narzędzie do orkiestracji zadań w monorepo, a parametr --filter ogranicza działanie do wybranego podpakietu, żeby nie ruszać całego repozytorium.

Sekcja pierwsza „Dev environment tips”: powiedz AI, jakiego menedżera pakietów używa projekt, jak przeskakiwać między podpakietami, jak tworzyć nowe moduły. Przykład z oficjalnego szablonu:

• pnpm dlx turbo run where <nazwa_projektu> — przechodzi bezpośrednio do katalogu podpakietu, bez przekopywania się przez ls
• pnpm install --filter <nazwa_projektu> — instaluje zależności tylko dla jednego podpakietu, nie rusza całego monorepo
• pnpm create vite@latest <nazwa_projektu> -- --template react-ts — tworzy nowy podpakiet React + Vite z kontrolą typów TypeScript

AI samo tych komend nie wymyśli. Ale jak je zapiszesz, będzie ich używać.

Sekcja druga „Testing instructions”: powiedz AI, jak odpalać testy, gdzie jest harmonogram CI, jakie checki muszą przejść przed commitem. Oficjalny przykład zawiera:

• pnpm turbo run test --filter <nazwa_projektu> — odpala wszystkie checki dla wybranego podpakietu
• pnpm vitest run -t "<nazwa_testu>" — odpala pojedynczy test pasujący do nazwy
• „Fix any test or type errors until the whole suite is green” — nie przestawaj, dopóki całość nie jest zielona
• „Add or update tests for the code you change, even if nobody asked” — to ostatnie zdanie jest kluczowe. Bez niego AI regularnie olewa pisanie testów

Sekcja trzecia „PR instructions”: ujednolić format tytułów commitów, wymusić lint i testy. Oficjalny przykład: Title format: [<nazwa_projektu>] <Tytuł> oraz „Always run pnpm lint and pnpm test before committing”.

Te trzy sekcje to mniej niż 50 linijek, ale znacząco podnoszą skuteczność AI przy pierwszym podejściu (według opinii społeczności, dokładne liczby do weryfikacji).

Ścieżka 2: zagnieżdżanie w dużym monorepo

Jeśli bierzesz projekt enterprise, gdzie kod ma strukturę monorepo (kilka powiązanych projektów w jednym repozytorium Git — frontend, backend, współdzielony kod, każdy w osobnym katalogu), pojedynczy AGENTS.md nie wystarczy. AGENTS.md wspiera zagnieżdżanie: w każdym podkatalogu umieszczasz dedykowany plik, a AI automatycznie czyta „ten najbliższy”.

Jak to zrobić: w katalogu głównym AGENTS.md zawiera globalne zasady (menedżer pakietów, proces CI, kwestie bezpieczeństwa), a w packages/web/, packages/api/, packages/shared/ lądują osobne pliki z komendami builda, wejściami do testów i specyficznymi zależnościami danego podpakietu. Przykładowo pakiet frontendowy potrzebuje wpisu: „komponenty z shadcn, style z Tailwind, ikony z lucide-react”; pakiet backendowy: „migracje bazy przez Prisma, trasy API w src/routes, autoryzacja przez JWT”.

Gdy AI pracuje w podkatalogu, automatycznie ładuje najbliższy AGENTS.md, który ma wyższy priorytet niż plik główny. Dzięki temu w jednym projekcie asystent frontendowy i backendowy dostają zupełnie inne instrukcje i nie wchodzą sobie w drogę.

Ścieżka 3: zrób z tego przewagę przy zleceniach

Rynek zleceń AI zrobił się czerwony od konkurencji — każdy umie używać Cursora, ale jakość dostaw leży. Jeśli w ofercie napiszesz: „Projekt ma skonfigurowany standard AGENTS.md, rozwój wspierany przez AI działa zgodnie z regułami projektu”, masz większe szanse niż gość, który mówi tylko „piszę kod z AI”.

Konkretny plan: po przyjęciu zlecenia poświęć 30 minut na zrozumienie struktury projektu klienta, potem napisz spersonalizowany AGENTS.md. Ten dokument jest częścią dostawy — klient dostaje go razem z kodem i w przyszłości sam będzie łatwiej utrzymywał projekt z pomocą AI.

Wycena usługi konfiguracji AGENTS.md (kwoty orientacyjne, dostosuj do lokalnego rynku): wersja podstawowa 300 zł (pojedynczy plik + instrukcja README), wersja enterprise 1800 zł (zagnieżdżone monorepo + zasady bezpieczeństwa + szkolenie zespołu). Zakres dostawy: ① spersonalizowany plik AGENTS.md ② 30 dni wsparcia mailowego ③ 10-minutowe nagranie szkoleniowe. Dla kogo: klienci, którzy mają już Cursor/Windsurf, ale nie widzą efektów. Nie dla: klientów, którzy dalej klepią kod ręcznie i nie wprowadzili narzędzi AI.

Case: AGENTS.md i jego fosa kompatybilności

AGENTS.md jest na licencji MIT (potwierdzone w materiałach), utrzymywany przez społeczność (szczegóły zarządzania do weryfikacji), strona: agents.md.

Kompatybilność to jego największa fosa: potwierdzono, że VS Code, Cursor, Windsurf, Aider i GitHub Copilot czytają AGENTS.md; według opinii społeczności wsparcie oferują też OpenAI Codex, Claude Code, Gemini CLI i Google Jules (⚠️ niezweryfikowane). Piszesz jeden plik, a działają z nim wszystkie główne asystenty AI — nie musisz tworzyć osobnej konfiguracji dla każdego narzędzia.

Porównaj z alternatywami: .cursorrules działa tylko w Cursorze, przy zmianie na Windsurf traci sens; CLAUDE.md służy wyłącznie Claude; system instrukcji GitHub Copilot to znowu inna bajka. Właściwość „napisz raz, uruchamiaj wszędzie” to powód, dla którego AGENTS.md tak szybko zdobył popularność.

Koszt migracji między narzędziami spada do zera. Dziś używasz Cursora, jutro przechodzisz na Windsurf — AGENTS.md działa dalej, zero przepisywania reguł.

Wezwanie do działania: dodaj projektowi instrukcję dla maszyny jeszcze dziś

Checklista na 5 minut: ① otwórz katalog główny projektu ② utwórz AGENTS.md ③ skopiuj oficjalny szablon (github.com/agentsmd/agents.md) ④ wpisz trzy komendy (build, test, lint) ⑤ przy następnym generowaniu kodu obserwuj różnicę.

Jeśli pracujesz na monorepo, dorzuć dziś 20 minut na zagnieżdżone pliki w każdym podpakiecie. Jutro rano zauważysz, że kod od AI nie wymaga już ciągłych poprawek.

AGENTS.md to obecnie konfiguracja AI z najwyższym ROI — 30 minut pracy, a oszczędzasz godziny debugowania co miesiąc.