Jak připravit projekt na vývoj s AI agenty

Čím dál víc vývoje dnes vzniká s pomocí AI. Už nejde jen o doplnění jedné funkce nebo rychlé vysvětlení kusu kódu. Agenti dnes zvládnou projít větší část codebase, navrhnout změnu, upravit několik souborů, doplnit testy a část práce i sami ověřit.

S tím se ale mění i nároky na samotný projekt.

U malého úkolu často stačí dobré zadání. U větší aplikace už agent potřebuje chápat, jak systém funguje, kde jsou důležitá business flow, které části jsou citlivé a hlavně proč jsou některé věci navržené právě tak, jak jsou.

V reálném projektu totiž často existují kompromisy, historická rozhodnutí a technický dluh, které z pohledu samotného kódu nemusí dávat okamžitě smysl. Bez tohoto kontextu může agent navrhnout řešení, které je technicky čistší, ale pro konkrétní systém horší.

Příprava projektu na AI agenty proto podle mě není hlavně o výběru nástroje. Je o tom dát agentovi dost kontextu, aby dokázal pochopit nejen co má změnit, ale i proč systém funguje právě takhle a jaké trade-offy je potřeba při změně respektovat.

Projekt musí být čitelný i pro AI agenta

Než začnete psát AGENTS.md, CLAUDE.md nebo pravidla pro konkrétní nástroj, je potřeba si ujasnit jednu základní věc: co musí agent o projektu vědět, aby v něm dokázal dělat dobrá rozhodnutí.

Nejde přitom jen o strukturu složek nebo seznam příkazů. Důležitější jsou věci, které ze samotného kódu nemusí být na první pohled vidět. Kde žije business logika, jak fungují kritická flow, které části systému jsou citlivé, jaké kompromisy se v minulosti udělaly a proč.

Právě to je dnes často označované jako context engineering. Nejde jen o lepší prompt, ale o to, aby měl agent ve správnou chvíli k dispozici správné informace.

Context engineering is the art and science of curating what will go into the limited context window. — Anthropic

U větších nebo starších projektů je to ještě důležitější. Některé části systému mohou působit zvláštně, nečistě nebo zbytečně složitě, ale často za nimi stojí konkrétní důvod — historická data, omezení externí služby, výkon, účetní pravidla nebo zkušenost z provozu.

Bez tohoto kontextu může agent velmi snadno „opravit“ něco, co ve skutečnosti funguje správně právě díky těmto kompromisům. Výsledek může být čistší z pohledu kódu, ale horší pro samotný systém.

Proto bych se nesnažil začít dlouhou dokumentací. Mnohem větší hodnotu má praktická mapa projektu: hlavní domény, důležitá flow, riziková místa, zdroje pravdy a rozhodnutí, která se nemají bez dalšího kontextu měnit.

Teprve z toho má smysl vytvořit konkrétní instrukce pro agenta. Ty pak nejsou obecný seznam best practices, ale zkratka k tomu, jak projekt skutečně funguje.

Dobré instrukce popisují projekt, ne best practices

Dobré instrukce pro agenta podle mě nezačínají větami typu „piš čistý kód“, „dodržuj best practices“ nebo legendárním „make no mistakes“. Kdyby to fungovalo, měli bychom vyřešenou půlku softwarového vývoje.

Tohle už model většinou ví. Mnohem důležitější je říct mu, jak se tyhle principy promítají právě do konkrétní codebase.

Například že nová business logika nepatří do controlleru, pricing se vždy počítá přes existující službu, auth nebo billing se nemění bez review a legacy kód mimo rozsah úkolu se nerefactoruje jen proto, že by mohl být hezčí.

Stejně důležité je popsat i špatné směry, do kterých agent nemá sklouznout. Pokud se v projektu často duplikuje logika, ukažte mu zdroj pravdy. Pokud má tendenci vytvářet zbytečné abstrakce, řekněte mu, kdy je naopak nechcete. Pokud není chování systému jasné, je lepší, aby nejdřív upozornil na nejasnost, než aby si doplnil vlastní předpoklad.

Dobré instrukce nejsou další obecná metodika vývoje. Jsou to zkratky k rozhodnutím, která už v projektu existují.

A právě proto by se měly průběžně měnit podle toho, kde agent v reálné práci chybuje. Ne podle toho, co dobře zní v dokumentaci.

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

U menší aplikace může stačit jeden společný soubor s pravidly. U většího projektu už ale začne být užitečné rozdělit instrukce podle částí systému.

Billing, objednávky, autentizace nebo integrace mají jiné rizikové body a jiné věci, které agent potřebuje vědět. Globální pravidla mohou popsat architekturu projektu, testy, základní konvence a místa, která vyžadují review. Detailní pravidla by ale měla být blíž konkrétní doméně.

U objednávek třeba kde se počítá cena, jaké stavy existují a co se spouští při jejich změně. U billing části zase lifecycle předplatného, webhooky, grace period, proration nebo vztah mezi stavem platby a přístupem uživatele.

Tím se z instrukcí nestane obrovský univerzální prompt, který agent stejně celý nevyužije. Dostane jen kontext, který potřebuje pro část systému, na které právě pracuje.

Za mě je to logicky nejlepší pokračování po sekci o kvalitě instrukcí: nejdřív jak mají pravidla vypadat, potom jak je strukturovat v reálném projektu.

Agent musí vědět, kde je zdroj pravdy

Ani dobře připravené instrukce nestačí, pokud agent pracuje s neaktuálními nebo neúplnými informacemi.

U frameworku, balíčku nebo externího API bych nechtěl, aby se spoléhal jen na obecnou znalost modelu. Projekt může používat jinou verzi, vlastní konfiguraci nebo integraci, která se od běžného příkladu liší.

Proto je dobré mít jasno v tom, co je v projektu zdrojem pravdy. Interní dokumentace může vysvětlovat business kontext, kód a testy ukazují skutečné chování systému a u frameworků nebo externích služeb by měl agent vycházet z oficiální dokumentace odpovídající konkrétní verzi.

Důležité je i to, co se má stát při rozporu. Pokud dokumentace říká něco jiného než kód, agent by neměl potichu jednu variantu vybrat a pokračovat. Měl by na rozdíl upozornit a ověřit, která informace je stále platná.

Právě tady dávají smysl nástroje, které agentovi zpřístupní dokumentaci, schéma databáze, logy nebo další kontext projektu. Ne proto, aby měl přístup ke všemu, ale aby nemusel důležité věci odhadovat.

Čím méně musí agent hádat, tím větší část práce mu lze rozumně svěřit.

Agent potřebuje spolehlivou zpětnou vazbu

Ani dobře připravený kontext a pravidla nejsou jednorázová věc. Projekt se mění, agenti narážejí na nové situace a postupně se ukazuje, které informace jim chybí nebo které instrukce jsou příliš obecné.

Část zpětné vazby může být automatická. Testy, statická analýza, lint, build nebo CI dokážou rychle odhalit, že změna něco rozbila nebo nesplňuje základní pravidla projektu. Důležité ale je, aby agent věděl, co má podle typu změny skutečně spustit a co musí projít, než označí práci za hotovou.

Stejně důležitá je zpětná vazba od lidí.

Když agent opakovaně umisťuje logiku na špatné místo, nestačí to pokaždé opravit v code review. Je lepší upravit instrukce. Pokud nerozumí určitému business flow, doplnit dokumentaci. Pokud přehlíží konkrétní side effect nebo historický trade-off, zachytit ho tam, kde ho při příští změně najde.

Dobré je také chtít, aby agent na konci práce jasně uvedl, co ověřil a co ne. Pokud například nešlo spustit integrační testy nebo chyběl přístup k externí službě, je to důležitá informace pro review, ne detail, který má zapadnout.

Žádná jedna kontrolní vrstva nedokáže zachytit všechno. Spolehlivost vzniká kombinací automatických kontrol a lidského hodnocení.

Příprava projektu na AI agenty proto podle mě není stav, kterého jednou dosáhnete. Je to průběžný feedback loop mezi agentem a lidmi, kteří projekt znají.

Každé špatné rozhodnutí agenta je zároveň informace o tom, co v projektu není dostatečně jasné. Někdy je potřeba upravit instrukci, jindy dokumentaci, test nebo samotnou strukturu systému.

Čím víc se tyhle zkušenosti vracejí zpátky do projektu, tím méně stejných chyb musí člověk řešit znovu při každém dalším úkolu.

Za mě je to takhle čistší. A jako další samostatnou sekci bych už šel spíš na oprávnění a rizikové operace, protože to je nové téma a neopakuje předchozí části.

Závěr

Připravit projekt na AI agenty podle mě neznamená přidat pár pravidel do AGENTS.md a očekávat, že tím je hotovo.

Mnohem důležitější je, aby agent dostal kontext, rozuměl hlavním flow, znal důvody důležitých rozhodnutí a měl jasno v tom, co je v projektu zdrojem pravdy. Stejně tak musí mít možnost svoji změnu ověřit a dostávat zpětnou vazbu, podle které se budou instrukce i dokumentace dál zpřesňovat.

Čím větší část vývoje chceme agentům svěřit, tím méně prostoru by mělo zůstávat pro hádání a domýšlení.

Cílem není projekt připravit tak, aby v něm AI dokázala dělat úplně všechno sama. Cílem je vytvořit prostředí, ve kterém dokáže dělat správná rozhodnutí častěji, konzistentněji a s menší potřebou zásahu člověka.

A právě v tom podle mě leží skutečný rozdíl mezi tím AI jen používat a skutečně ji zapojit do vývoje jako dalšího technického partnera.