Většina našich článků se věnuje IAM (Identity and Access Management) tematice, dnes ale uděláme malou odbočku. Představíme vám našeho nového pomocníka – „Šelmostroj“.

Existuje jeden úkol, který v každém softwarovém týmu sice všichni uznávají za důležitý, ale málokdo se do něj s nadšením hrne: psaní technické dokumentace. Čím složitější je produkt, tím větší je propast mezi tím, co by v dokumentaci mělo být, a tím, co tam skutečně je.

Znáte to – seniorní vývojář sedí nad prázdným dokumentem, ví přesně, jak daný systém funguje, ale psát o tom je to poslední, co chce v tu chvíli dělat. Pokud to neudělá on, neudělá to nikdo – nebo to bude špatně. Právě proto vznikl nástroj interně nazývaný Šelmostroj.

Od naivních začátků k preciznosti

Naše první pokusy s generováním dokumentace byly vcelku naivní. Prostě jsme AI zadali prompt: „Vytvoř dokumentaci pro modul XYZ“. Výstup nebyl hrozný, ale ani skvělý. AI sice napsala plynulý text, správně identifikovala klíčová témata a používala relevantní terminologii, ale dokumentace trpěla klasickými neduhy:

• příliš mnoho balastu a vaty;
• irelevantní sekce, které nikdo nepotřebuje;
• halucinace (vymyšlená fakta);
• rozdílný formát oproti existující dokumentaci.

RAG: Fakta místo dojmů

Mezi jedny z hlavních problémů AI patří vymyšlená fakta a správné určení kontextu, s kterým má pracovat (příliš velký kontext zvyšuje šanci na chybovost a spotřebu dostupných AI zdrojů – tokenů). Tyto nedostatky jsme vyřešili v Šelmostroji implementací RAG architektury (Retrieval-Augmented Generation).

Tento mechanismus umožňuje AI přesně přistupovat ke zdrojovým kódům aplikace, konfiguraci a získávat důležitá metadata. Díky tomu stojí Šelmostroj na pevném pilíři: evidenci důkazů. AI umí přistupovat k předgenerovaným informacím – přehledům (moduly a jejich routy, konfigurační soubory) a na základě toho může přesněji přistupovat ke specifickým souborům ve zdrojovém kódu a ukládat nezbytné důkazy jako použitá čísla řádků ve třídách, atd. To má i vedlejší efekt, že AI tak nemusí procházet celou codebase a tím se šetří tokeny a zvyšuje přesnost dokumentace.

MCP servery: Most mezi AI a kódem

RAG a přístup k dalším zdrojům potřebným pro generaci dokumentace byl v našem řešení implementován pomocí MCP serverů. MCP (Model Context Protocol) je standard, který propojuje AI (vytváří “most”) k externím zdrojům, nástrojům a službám. Pro Šelmostroj jsme vytvořili sadu specializovaných MCP serverů:

• Source: přístup ke zdrojovému kódu – vyhledávání tříd, čtení konkrétních řádků, fulltextové vyhledávání;
• Javadoc:  extrakce Javadoc komentářů tříd a metod;
• Maven-modules: inventář modulů aplikace (informace o tom co aplikace umí);
• Routes: statická analýza registrovaných routes v aplikačních modulech;
• Config: přístup k výchozím konfiguračním souborům včetně vytváření hash otisků;
• Docs: přístup ke stávající existující dokumentaci;
• Artifacts: čtení a zápis workspacových souborů (důkazy, reporty, záznamy o úpravách). Soubory fungují jako paměť celého řešení, což umožní generovat dokumentaci i napříč více sessions.

Čtyři agenti, jeden tým

Teď když máme představu o základních stavebních kamenech Šelmostroje, můžeme si povědět, jak to funguje spolu dohromady. Šelmostroj není jeden AI agent, ale tým čtyř AI agentů. Každý agent plní ve workflow svoji specifickou roli. Agenti mají definované své vlastnosti, schopnosti, povolené MCP servery, relevantní předgenerované soubory a úkony, které mají vykonávat. Tím mají definovaná přesná pravidla, která nesmějí porušovat, a v procesu jsou tak správně rozděleny odpovědnosti.

Pravidla ale nejsou vytesaná do kamene. Vývojář může agentům kdykoliv dodat dodatečný kontext nebo chování přepsat: specifikovat typ dokumentace, zodpovědět otevřené otázky, omezit přístup k určitým zdrojům nebo zakázat konkrétní akce. Agenti to berou jako závazný vstup. Tento mechanismus umožňuje vývojáři předat také tzv. leady – informace, které musí agent před jejich zakomponováním do dokumentace prověřit.

Kdo je kdo

• Doc Author: Hlavní agent – zkušený specialista. Provádí generování dokumentace, opravy dokumentace na základě zpětné vazby, vytváření evidence důkazů.
• Evidence QA (Quality Assurance): Auditor. Kontroluje draft dokumentace a navázané důkazy (existuje citovaný soubor? Sedí čísla řádků? Dává důkaz smysl?). Draft neopravuje, jen vytváří zpětnou vazbu pro Doc Authora.
• Doc Editor: Stylistický agent – nekontroluje fakta, ale kontroluje jazyk, strukturu, konzistenci s existující dokumentací. Vytváří report s návrhy změn pro Doc Authora.
• Integrator: Agent, který simuluje externího uživatele – někoho, kdo chce dokumentaci použít. Kontroluje smysluplnost, existenci klíčových informací a vytváří review pro Doc Authora s návrhy na vylepšení a blokery, které se před vydáním dokumentace musí změnit.

Workflow v praxi

Samotné workflow se pak skládá ze spouštění agentů ve správném pořadí. Agenti umí detekovat mód, ve kterém mají pracovat, na základě existujících souborů, ale uživatel Šelmostroje může i specifikovat mód, ve kterém má například Doc Author pracovat (oprava evidence QA / integračního review). Základní průchod tak vypadá takto:

1. Spustí se Doc Author pro specifickou problematiku. Zjistí, že ještě neexistuje draft. Získá potřebné informace, vytvoří draft a evidenci důkazů.
2. Evidence QA udělá kontrolu vygenerovaného draftu a navazujících důkazů.
3. Pokud QA selže, tak se spustí znovu Doc Author, který odhalí, že má provést opravy. V případě, že kontrola projde, přecházíme na krok 4.
4. Doc Editor zkontroluje vytvořený draft oproti existující dokumentaci a navrhne stylistické úpravy.
5. Pokud je potřeba něco upravit, zavolá se Doc Author, když je vše v pořádku, tak se jde na krok 6.
6. Integrátor zkontroluje smysluplnost a použitelnost dokumentace.
7. V případě, že jsou nalezeny problémy Integrátorem, začíná se znovu od kroku 1. S tím rozdílem, že Doc Author pozná, že má změnit draft na základě integračních připomínek a nevytvářet novou dokumentaci.

Výsledky a další cesta

Šelmostroj zatím funguje nad očekávání. Dokumentace, která z něj vychází, odpovídá představám seniorních vývojářů – jejich role se posunula od přepisování k review. To samo o sobě stojí za to. Ale nejzajímavější moment přišel při předvádění: Šelmostroj při procházení kódu narazil na feature, kterou senioři neměli zmapovanou a aktivně nevyužívali. Dokumentační nástroj jako skener slepých míst – to jsme nečekali.

Dalším krokem je plná automatizace: agenti spuštění bez nutné interakce s uživatelem, dokumentace generovaná průběžně jak se produkt vyvíjí. Technických detailů je pod kapotou ještě hodně, to je však téma na samostatný článek.