Jak připravit software na práci s AI agenty

AI agenti dokážou výrazně zrychlit vývoj softwaru. Umí najít souvislosti v codebase, navrhnout změnu, upravit soubory, doplnit testy a spustit příkazy. Čím větší část práce jim ale svěříme, tím víc záleží na tom, v jakém prostředí pracují.

U malého izolovaného úkolu může stačit dobré zadání. U většího projektu už ne. Agent potřebuje vědět, jak je aplikace postavená, kam patří nová logika, jaké části jsou citlivé, jak se ověřuje správnost změn a které postupy se v projektu nemají obcházet.

Jinak velmi snadno vznikne změna, která na první pohled funguje, ale dlouhodobě do projektu nezapadá. Agent použije jiný styl, zopakuje existující logiku, vytvoří druhou cestu v procesu nebo přidá abstrakci, kterou projekt nepotřebuje. Aplikace kvůli tomu nemusí spadnout hned, ale přibude další výjimka, kterou bude někdo při další změně chápat, testovat a udržovat.

Příprava projektu na AI agenty proto není o výběru nejlepšího nástroje. Je o tom připravit projekt tak, aby agent dostal správný kontext, jasné hranice a spolehlivou zpětnou vazbu. Teprve potom dávají smysl věci jako AGENTS.md, CLAUDE.md, Cursor rules, permissions, scopes, hooks nebo MCP nástroje.

Nejdřív je potřeba zmapovat projekt

Příprava projektu pro AI agenty nezačíná souborem AGENTS.md nebo CLAUDE.md. Tyto soubory jsou až finálním výstupem. Nejdřív je potřeba definovat, co má agent o projektu vědět.

U menšího projektu může stačit pár jasných pravidel. U větší aplikace je potřeba zmapovat, kde je hlavní business logika, jaké části systému jsou citlivé, jaké konvence se v projektu dodržují, jak se spouští testy, co hlídá CI/CD pipeline a které změny musí vždy projít člověkem.

Nejde jen o strukturu složek. Důležité je popsat i hlavní procesy projektu. Objednávka, platba, předplatné, rezervace, registrace, změna oprávnění, fakturace nebo napojení na externí API nejsou jen soubory v repozitáři. Jsou to procesy s konkrétními pravidly, výjimkami a dopady na provoz.

U těchto částí nestačí vědět, kde jsou napsané. Agent by měl chápat, jak mají fungovat, proč jsou navržené právě tímto způsobem a jaké trade-offy se v projektu vědomě přijaly.

To je důležité hlavně u starších nebo déle rozvíjených projektů. Některá rozhodnutí mohou na první pohled vypadat zvláštně, ale mají důvod: historická data, požadavek klienta, omezení externí služby, výkon, kompatibilita, účetní proces, právní požadavek nebo provozní zkušenost. Pokud agent tenhle kontext nezná, může takové místo „vylepšit“ způsobem, který je technicky čistší, ale rozbije reálné chování systému.

Výstupem nemá být dlouhá dokumentace, kterou nikdo nebude udržovat. Stačí praktická mapa projektu:

• kde je hlavní doménová logika,
• jak fungují kritické procesy a proč,
• jaké historické rozhodnutí a trade-offy je potřeba respektovat,
• kam patří nové funkce a kam naopak ne,
• které části jsou rizikové,
• jaké příkazy ověřují kvalitu změny,
• jaké postupy se nemají obcházet,
• kdy se má agent zastavit a požádat o potvrzení.

Teprve z toho má smysl připravovat konkrétní instrukce a mantinely pro daný nástroj. Jinak vznikne jen obecný prompt nalepený na projekt. Může vypadat dobře, ale agentovi nepomůže poznat, jak se má změna udělat správně právě v této codebase.

Dobré instrukce jsou konkrétní, krátké a hlídají špatné směry

Jedna z častých chyb je napsat agentovi obecné instrukce typu „piš čistý kód“, „dodržuj best practices“ nebo „mysli na bezpečnost“. Takové věty zní správně, ale agentovi moc nepomohou. Neříkají mu nic o tom, jak je postavený konkrétní projekt, kde jsou jeho riziková místa a jaká rozhodnutí nemá obcházet.

Špatně:

- Piš čistý, moderní a udržitelný kód.
- Dodržuj best practices.
- Dbej na bezpečnost a výkon.

Lépe:

- Nová business logika nepatří přímo do controllerů.
- Nepřidávej produkční závislosti bez schválení.
- Neměň autentizaci, oprávnění, platby, fakturaci ani migrace databáze bez potvrzení.
- Preferuj malé změny, které respektují současnou strukturu projektu.
- Nevytvářej novou abstrakci pro jeden konkrétní případ.
- Nerefaktoruj legacy kód mimo rozsah úkolu. Pokud narazíš na problematické místo, upozorni na něj a navrhni další postup.
- Neřeš chybu workaroundem, pokud není jasné, proč vznikla.
- Pokud měníš databázové dotazy, zkontroluj dopad na výkon a možné N+1 problémy.
- Pokud měníš integraci na externí službu, řeš timeouty, chybové stavy a logování.
- Pokud přidáváš testy, nemockuj klíčové chování jen proto, aby test prošel.

Dobré pravidlo agentovi neříká jen to, že má psát kvalitně. Říká mu, jak kvalitní změna vypadá právě v tomto projektu. Kam nová logika patří, které části systému jsou citlivé, jaké zkratky nejsou přijatelné a kdy se má zastavit místo toho, aby pokračoval špatným směrem.

Neznamená to psát jen zákazy. Znamená to nastavovat konkrétní mantinely podle reálných rizik projektu. U AI agentů často nefunguje říct jen „dělej to správně“. Lepší je přesně popsat, jaké změny jsou nežádoucí, kdy má agent zastavit práci a kdy je nutné zapojit člověka.

Například u Laravel projektu mohou být instrukce ještě konkrétnější:

- Controllery drž tenké: request, autorizace, volání action třídy, response.
- Business use-cases patří do action tříd, ne přímo do controllerů.
- Orchestrace nepatří do Eloquent modelů.
- Neduplikuj pricing, billing, permission ani status-transition logiku.
- Pro vícekrokové změny, které musí zůstat konzistentní, použij transakci.
- Side effecty drž explicitně: jobs, eventy, notifikace a externí API volání musí navazovat na existující flow.
- Auth, billing, payment states, permissions a migrace neměň bez potvrzení.
- Při změnách peněz, přístupů, objednávek, předplatného nebo externích integrací doplň testy.

Dobré instrukce by měly být konkrétní, krátké, ověřitelné a udržované. Pokud pravidlo neodpovídá realitě codebase, je horší než žádné pravidlo.

Zároveň by měly instrukce vycházet z toho, co se v projektu reálně kazí. Pokud agent přidává zbytečné abstrakce, napište mu, kdy je nesmí vytvářet. Pokud duplikuje logiku, ukažte mu zdroj pravdy. Pokud refaktoruje mimo zadání, omezte rozsah změny. A pokud píše testy jen podle vlastní implementace, nastavte pravidlo, že test má ověřovat očekávané business chování.

Pravidla musí kopírovat domény a flow projektu

Jedna sada pravidel pro celý projekt většinou nestačí. Větší aplikace má části, které fungují jinak, mají jiná rizika a vyžadují jiný způsob práce. Objednávkový proces, předplatné, platby, registrace, fakturace, administrace nebo API integrace nepotřebují stejné instrukce.

Základní projektové instrukce mohou sloužit jako vstupní mapa projektu: co je to za aplikaci, jak je rozdělená, jak se spouští lokální prostředí, jaké jsou hlavní příkazy, jak fungují testy a které části systému vyžadují opatrnost. Neměly by ale suplovat detailní dokumentaci celé aplikace.

Detailnější pravidla dávají smysl až na úrovni konkrétní domény nebo flow. Objednávky potřebují popsat, kde vzniká objednávka, kde se počítá cena, jak fungují slevy, jak se mění stav platby, kdy se posílají e-maily a co se nesmí upravovat bez review. Předplatné má jiné citlivé body: trial období, změny plánu, proration, neúspěšné platby, přístup uživatele po selhání platby, webhooky od billing providera, fakturaci a rušení služby.

Například pravidla pro objednávkový proces mohou vypadat takto:

# Order flow rules

- Order creation starts in `app/Domain/Orders`.
- Price calculation must use the existing pricing service.
- Do not duplicate discount, VAT or shipping logic.
- Do not change payment states without reviewing the payment provider flow.
- Do not add fallback behavior unless the failure mode is explicitly defined.
- If you touch order status transitions, update or add tests for all affected states.
- If behavior is unclear, stop and ask instead of inventing a workaround.

Pravidla pro předplatné budou řešit jiné věci:

# Subscription flow rules

- Subscription state is driven by billing provider webhooks, not only by local UI actions.
- Do not change subscription status transitions without reviewing the full billing lifecycle.
- Plan changes must respect existing upgrade, downgrade and proration rules.
- Failed payments must not immediately remove user access unless the grace period rules allow it.
- Do not duplicate billing, tax or access-control logic outside the existing subscription layer.
- If you change webhook handling, preserve idempotency and logging.
- If you change access rules, update or add tests for active, trialing, past_due, canceled and expired states.
- If billing behavior is unclear, stop and ask instead of adding fallback logic.

Tohle je rozdíl mezi obecnými „AI pravidly“ a skutečnou přípravou projektu. Agent pak nehádá, jestli má přidat logiku do controlleru, služby, listeneru nebo existující doménové vrstvy. Dostává konkrétní vodítka pro konkrétní část systému.

Agent musí vědět, kde hledat dokumentaci

Častá chyba je spoléhat se na to, že model „nějak zná“ použitý framework, knihovnu nebo API. U běžných věcí to může stačit. U reálného projektu je to ale slabé místo. Frameworky, balíčky i externí služby se mění a agent může navrhnout řešení podle starší verze, jiného ekosystému nebo obecného příkladu, který do projektu nepatří.

Pravidla pro agenta by proto měla řešit i práci s dokumentací. Agent by měl vědět, kde najde interní dokumentaci, jakou verzi frameworku nebo balíčku má použít, které dokumenty jsou stále platné a kdy si má postup ověřit v oficiálních zdrojích.

Do instrukcí se dá přidat například:

## Documentation and source of truth

- Use project documentation as context, but verify important behavior against the code and tests.
- Use official documentation for framework and package behavior.
- Check installed package versions before using framework-specific APIs.
- Before changing third-party integrations, check the provider documentation and existing project integration.
- If internal documentation conflicts with code, mention the conflict and do not silently choose one.
- If documentation is missing or outdated, explain the assumption before making the change.
- Do not introduce APIs, methods or configuration options that are not supported by the installed version.

U externích služeb se mi osvědčilo být ještě konkrétnější. Pokud projekt používá platební bránu, účetní systém, rezervační API, dopravce nebo jinou důležitou integraci, dávám agentovi přímo odkaz na konkrétní dokumentaci. AI agenti si ji často dokážou sami projít přes dostupné nástroje, například přes curl, a nemusí se spoléhat jen na obecnou znalost modelu.

To je důležité hlavně u služeb, kde se API mění, existuje více verzí dokumentace nebo jsou některé části chování specifické pro konkrétní účet, režim nebo integraci. Agent pak nemá hádat, jak by měla platební brána fungovat. Má si ověřit aktuální postup v dokumentaci, porovnat ho s existující implementací v projektu a upozornit na případný rozpor.

U Laravel projektů je v tomhle zajímavý Laravel Boost. Poskytuje agentům kontext ke konkrétní Laravel aplikaci, včetně dokumentace podle nainstalovaných balíčků, konfigurace, databáze nebo logů. To je výrazně užitečnější než obecná znalost frameworku, protože agent pracuje s tím, co projekt opravdu používá.

U větších změn používejte plan mode

U jednoduché úpravy může agent začít implementovat rovnou. U větší změny je to riziko. Čím více částí systému úkol zasahuje, U větších změn používejte plan mode

U jednoduché úpravy může agent začít implementovat rovnou. U větší změny je ale lepší nejdřív použít plan mode. Codex i Claude Code dnes umí režim, ve kterém agent nejdřív projde relevantní části projektu, navrhne postup a teprve po schválení začne upravovat soubory.

To je důležité hlavně u změn, které zasahují více částí systému. Agent by měl před implementací ukázat, jaké soubory nebo moduly chce měnit, proč zvolil daný přístup, jaká rizika vidí a jak výsledek ověří. Díky tomu lze zachytit špatný směr ještě před tím, než vznikne velký diff.

Do instrukcí se dá přidat například:

## Before changing code

- For non-trivial changes, use plan mode first.
- Identify affected files, modules and flows.
- Explain why the selected approach fits the existing architecture.
- Prefer existing patterns over introducing a new approach.
- If the task touches auth, billing, payments, permissions, database migrations or production config, ask for confirmation before editing.
- If the expected behavior is ambiguous, stop and describe the uncertainty before implementing.

Plan mode ale není náhrada za review. Je to mezikrok, který pomáhá zkontrolovat směr práce. Velké změny je pořád lepší rozdělit na menší části: analýza, plán, úprava jedné oblasti, testy a review. Menší diff se lépe kontroluje, lépe se vrací zpět a je menší šance, že se v něm schová změna, která vůbec neměla vzniknout.

Agent potřebuje zpětnou vazbu

AI agent může změnu napsat rychle, ale bez automatických kontrol jen těžko pozná, jestli je opravdu správná. Nestačí, že kód vypadá dobře a projde jeden testovaný scénář. U větší aplikace je potřeba ověřit, že změna respektuje pravidla projektu, nerozbíjí existující chování a projde základními kontrolami.

Proto by měl mít projekt jasně dané, co se po změně spouští: testy, statická analýza, lint, formátování, build aplikace a případně kontrola závislostí. Konkrétní nástroje se liší podle technologie, ale princip je stejný. Agent musí vědět, jak změnu ověřit a co musí projít, než ji označí za hotovou.

Do instrukcí se dá přidat například:

## Validation

Before marking the task as done:

- Run the relevant test suite.
- Run static analysis if the changed area supports it.
- Run linting and formatting checks.
- Run the application build if frontend or assets were changed.
- Report which checks passed.
- If a check could not be run, explain why and what risk remains.

For this project, use:

- `composer test` for the test suite
- `composer analyse` or `vendor/bin/phpstan analyse` for static analysis
- `composer lint` or `vendor/bin/pint --test` for code style
- `npm run build` when frontend assets were changed
- `npm run lint` if frontend linting is configured

Bez této zpětné vazby agent často jen vyrábí změny, které vypadají hotově. S ní má alespoň základní mantinely a člověk při review lépe vidí, co bylo ověřené a kde zůstává riziko.

Testy napsané agentem je potřeba číst

AI agent dokáže testy doplnit rychle, ale procházející test ještě neznamená, že změna je správně. Důležité je, co test skutečně ověřuje.

Častý problém je test, který jen potvrzuje nově napsanou implementaci. Agent doplní funkci a k ní vytvoří test podle toho, jak ji sám navrhl. Test projde, ale nemusí chránit skutečné business pravidlo.

Proto má smysl dát agentovi pravidla i pro samotné testování. Neměl by ověřovat jen ideální průchod, ale také hraniční stavy, chybové scénáře, oprávnění, validace, prázdná data, opakované spuštění, selhání externí služby nebo stav, který může nastat v reálném provozu. Přesně tak k testům přistupuje zkušený vývojář: neověřuje jen to, že nová funkce funguje za ideálních podmínek, ale i to, co se stane, když vstupy, data nebo okolní služby nejsou perfektní.

U důležitých částí projektu je potřeba číst testy stejně pečlivě jako produkční kód. Test má ověřovat očekávané chování systému, ne vnitřní strukturu implementace.

AI může testování zrychlit. O tom, co je správné chování aplikace, ale musí pořád rozhodovat zadání, doména a člověk, který projektu rozumí.

Legacy projekty je potřeba nejdřív stabilizovat

U starších projektů bývá největší lákadlo pustit agenta rovnou do refaktoru. Právě tam je ale potřeba největší opatrnost.

Legacy projekt často nemá dobré testy, jasnou dokumentaci, aktuální dependency, staging prostředí nebo spolehlivý deployment. Může obsahovat roky historických rozhodnutí, ručních zásahů, pluginů, integrací a výjimek, které nejsou nikde popsané.

První krok proto není velký AI refaktor. První krok je stabilizace:

• zprovoznit lokální prostředí,
• ověřit zálohy,
• připravit staging,
• doplnit základní monitoring,
• zmapovat kritické procesy,
• přidat testy kolem částí, které se mají měnit,
• nastavit alespoň základní CI kontrolu.

U legacy projektu totiž není hlavní problém napsat nový kód. Hlavní problém je poznat, jestli nový kód nerozbil staré chování, na kterém projekt pořád stojí.

Minimum pro projekt připravený na AI agenty

Projekt nemusí být dokonalý, aby se na něm dali AI agenti používat. Měl by ale mít alespoň základní mantinely:

• aktuální README a projektové instrukce pro agenty,
• jasná pravidla pro práci s codebase,
• popsané rizikové části systému,
• permissions a scopes podle rizika,
• testy alespoň pro kritické části,
• CI kontrolu pro testy, lint, statickou analýzu a build,
• oddělený staging,
• hooks nebo jiné automatické kontroly pro důležité workflow,
• jasně určené zdroje dokumentace,
• ochranu secrets a produkčních přístupů,
• povinné human review pro auth, billing, platby, migrace a bezpečnost.

Tohle není zbytečná režie. Je to rozdíl mezi tím, jestli AI agent projekt zrychlí, nebo do něj jen rychleji zanese další technický dluh.

Závěr

AI agenti mohou výrazně změnit způsob, jakým se software vyvíjí. Nejsou ale zkratka kolem architektury, testů, dokumentace, bezpečnosti a technického vedení projektu.

V dobře připraveném projektu dokážou pomoct s orientací v codebase, navrhnout změny, doplnit testy a převzít část rutinní práce. V projektu bez jasných pravidel a kontrol ale mohou rychle vyrábět změny, které sice vypadají funkčně, ale dlouhodobě zvyšují technický dluh.

Největší přínos AI agentů nepřichází ve chvíli, kdy dostanou přístup ke všemu. Přichází ve chvíli, kdy mají správný kontext, jasné hranice a spolehlivou zpětnou vazbu.