Problém: Proč AI kodér pokaždé selže na stejném místě

Každý, kdo píše projekty přes Cursor, Windsurf nebo Claude Code, zažil ten samý kolaps: AI vyplodí celý blok kódu, vy ho zkopírujete, spustíte — build hází chyby, testy svítí červeně, závislosti se instalují špatně. Problém není v inteligenci AI, ale v tom, že nezná „nepsaná pravidla” vašeho projektu.

AGENTS.md je Markdown soubor v kořenu projektu, psaný přímo pro AI. Říká jí, jak buildovat, jak testovat, jaké dodržovat konvence. README.md je pro lidi — plný popisu projektu, návodu pro přispěvatele, brandového příběhu. Když AI přečte tohle, je to jako nováček první den v práci, kterému hodíte firemní brožuru a rovnou řeknete „piš kód”. Ví, čím se firma zabývá, ale nezná build příkaz, neví, jak se spouští testy, netuší pravidla ESLintu. Výsledek? V chatu pořád dokola opakujete: „použij pnpm, ne npm”, „testy jsou v packages/web”, „nezapomeň na lint”. Sto opakování a projekt je pořád bordel.

Ve freelance praxi je ztráta ještě přímější: vezmete zakázku na Next.js + Prisma, chcete zrychlit přes Cursor, ale AI nainstaluje závislosti přes npm install, čímž rozseká pnpm workspace konfiguraci; neví, kde je schéma databáze, takže generované migrace rovnou padají. Klient tlačí na termín, vy strávíte tři hodiny debugováním kódu od AI — těžce vydělané peníze.

Tři typické scénáře, kdy AI nezná pravidla projektu: ① Špatný package manager (projekt jede na pnpm, AI defaultně použije npm install), závislosti skončí jinde, workspace konfigurace selže; ② Testy nelze najít (testy jsou v packages/web, AI spustí pnpm test v kořenu a dostane „no test files found”); ③ Nekonzistentní styl kódu (projekt používá ESLint + Prettier, AI generuje kód se špatným odsazením a uvozovkami, CI okamžitě spadne).

Příležitost: AGENTS.md oddělí „lidskou dokumentaci” od „strojové dokumentace”

Open-source projekt AGENTS.md na GitHubu (repozitář github.com/agentsmd/agents.md, k 2026-08-25 cca 24 000 stars) řeší přesně tento problém. Jádro je triviální: v kořenu projektu leží Markdown soubor, který AI říká, jak buildovat, testovat a jaký styl dodržovat.

Nenahrazuje README, doplňuje ho. README slouží lidským přispěvatelům, AGENTS.md slouží AI agentům. Jasné role, žádné překryvy.

Podle zdrojového příspěvku AGENTS.md už adoptovaly desítky tisíc open-source projektů (přesné číslo k ověření), pokrývá všechny hlavní AI programátorské nástroje — VS Code, Cursor, Windsurf, Aider, GitHub Copilot (ověřený závěr); komunita navíc hlásí podporu v OpenAI Codex a Google Jules (⚠️ neověřeno). Pokud se to nenaučíte teď, AI s vámi bude mluvit cizím nářečím.

Cesta 1: Ručně napsat minimální použitelný AGENTS.md

Náklady minimální. Nový soubor, tři sekce a máte hotovo.

Předpoklady: příklady níže používají pnpm (úspornější na disk než npm, podporuje monorepo workspace), turbo je nástroj na orchestraci úloh v monorepu, parametr --filter omezí akci jen na konkrétní balíček, aby se zbytek repozitáře nepoškodil.

Sekce 1 „Dev environment tips”: řekněte AI, jaký package manager projekt používá, jak se přepnout do sub-balíčku, jak založit nový modul. Příklad z oficiální šablony:

• pnpm dlx turbo run where <project_name> — skočí rovnou do adresáře daného sub-balíčku, žádné ruční ls
• pnpm install --filter <project_name> — nainstaluje závislosti jen pro jeden balíček, zbytek monorepa nechá na pokoji
• pnpm create vite@latest <project_name> -- --template react-ts — založí nový React + Vite sub-balíček s TypeScript kontrolou

Tyto příkazy AI sama nevymyslí, ale jakmile je napíšete, poslechne.

Sekce 2 „Testing instructions”: jak spouštět testy, kde je CI pipeline, co musí proběhnout před commitem. Oficiální příklad obsahuje:

• pnpm turbo run test --filter <project_name> — spustí všechny kontroly pro daný balíček
• pnpm vitest run -t "<test name>" — spustí jen jeden test podle názvu
• „Fix any test or type errors until the whole suite is green” — dokud není vše zelené, nepřestávej
• „Add or update tests for the code you change, even if nobody asked” — tahle věta je klíč; bez ní AI testy často vynechá

Sekce 3 „PR instructions”: formát commit zprávy, povinný lint a test. Oficiální příklad: Title format: [<project_name>] <Title> a „Always run pnpm lint and pnpm test before committing”.

Tři sekce, do 50 řádků, ale úspěšnost AI kódu na první pokus viditelně stoupne (dle zpětné vazby komunity, konkrétní čísla k ověření).

Cesta 2: Vnořené použití ve velkém monorepu

Pokud berete enterprise zakázku a kód je monorepo (více provázaných projektů v jednom Git repozitáři — třeba frontend, backend a sdílený kód jako samostatné adresáře), jeden AGENTS.md nestačí. AGENTS.md podporuje vnořování: do každého podadresáře dáte vlastní AGENTS.md a AI automaticky načte „ten nejbližší”.

Postup: AGENTS.md v kořenu popíše globální pravidla (package manager, CI proces, bezpečnostní pokyny), pak do packages/web/, packages/api/, packages/shared/ přidáte vlastní verze s build příkazy, testovacími vstupy a specifickými závislostmi. Frontend balíček třeba potřebuje vědět „komponenty přes shadcn, styly přes Tailwind, ikony přes lucide-react”; backend balíček zase „migrace databáze přes Prisma, API routy v src/routes, autentizace přes JWT”.

Když AI pracuje v podadresáři, načte nejbližší AGENTS.md s vyšší prioritou než kořenový. Frontend AI asistent a backend AI asistent tak dostanou zcela odlišné instrukce a nebudou si lézt do zelí.

Cesta 3: Prodejte AGENTS.md jako konkurenční výhodu

Trh s AI zakázkami je dnes rudý oceán — Cursor umí každý, ale kvalita dodávek se různí. Pokud do nabídky napíšete „Projekt je vybaven standardizovanou dokumentací AGENTS.md, AI asistent dodržuje pravidla projektu”, vyhrajete víc tendrů než konkurenti, kteří jen řeknou „píšu kód přes AI”.

Konkrétní postup: po přijetí zakázky strávte 30 minut čtením struktury projektu klienta a napište AGENTS.md na míru. Tenhle soubor je sám o sobě součástí dodávky — klient ho pak využije i při vlastní AI údržbě kódu.

Nacenění služby konfigurace AGENTS.md (orientační, přizpůsobte lokálnímu trhu): základní verze 1 800 Kč (jeden konfigurační soubor + README návod), enterprise verze 9 000 Kč (monorepo vnoření + bezpečnostní pravidla + školení týmu). Co dostanete: ① AGENTS.md na míru ② 30 dní e-mailové podpory ③ 10minutové video-školení. Pro koho to sedí: klienti, kteří mají předplatné Cursor/Windsurf, ale neumí ho pořádně využít. Pro koho ne: klienti, kteří stále jedou čistě manuálně a AI nástroje neřeší.

Případová studie: Kompatibilita jako konkurenční výhoda AGENTS.md

AGENTS.md je pod MIT licencí (potvrzeno ze zdrojových materiálů), spravuje ho komunita (konkrétní governance k ověření), oficiální web je agents.md.

Největší konkurenční výhoda je kompatibilita: ověřený závěr potvrzuje, že VS Code, Cursor, Windsurf, Aider a GitHub Copilot umí AGENTS.md číst; komunita hlásí podporu i v OpenAI Codex, Claude Code, Gemini CLI a Google Jules (⚠️ neověřeno). Napíšete jeden soubor a funguje ve všech hlavních AI asistentech — žádné separátní konfigurace pro každý nástroj.

Srovnejte s alternativami: .cursorrules v Cursoru platí jen pro Cursor, přechod na Windsurf znamená začít od nuly; CLAUDE.md v Claude Code slouží jen Claudovi; instrukční systém GitHub Copilota je zase úplně jiný. Vlastnost „napiš jednou, použij kdekoli” je hlavní důvod, proč AGENTS.md tak rychle prorazil.

Nulové náklady na přechod nástrojů. Dnes jedete na Cursoru, zítře přejdete na Windsurf — AGENTS.md funguje dál, žádné přepisování pravidel.

Výzva k akci: Dnes večer přidejte projektu strojní manuál

Akční checklist na 5 minut: ① Otevřete kořen projektu ② Vytvořte AGENTS.md ③ Zkopírujte oficiální šablonu (github.com/agentsmd/agents.md) ④ Doplňte tři příkazy (build, test, lint) ⑤ Příště, co necháte AI psát kód, sledujte výsledek.

Pokud jedete monorepo, přidejte dnes večer dalších 20 minut na vnořenou konfiguraci pro každý balíček. Zítra ráno zjistíte, že AI kód už nevyžaduje neustálé opravy.

AGENTS.md je aktuálně nejlepší ROI mezi AI programátorskými konfiguracemi — 30 minut práce vám ušetří hodiny debugování každý měsíc.