Blog

V určitom bode vývoja produktu sa začne objavovať rovnaký vzorec. Nie preto, že by tím robil chyby, ale preto, že produkt prirodzene rastie. Pribúdajú nové funkcionality, menia sa procesy, tímy sa rozširujú. Vývoj ide dopredu rýchlejšie než sa stíha aktualizovať dokumentácia, dizajn reaguje na nové potreby a dokumentácia sa postupne mení na historický záznam.

Výsledkom je prostredie, v ktorom už nikto nemá úplnú istotu:

• či dokumentácia odráža aktuálnu realitu,
• či dizajn vo Figme zodpovedá produkcii,
• a či sa všetci v tíme pozerajú na ten istý „source of truth“.

Presne v tomto bode sme si uvedomili, že problém nie je v množstve dokumentácie, ale v chýbajúcom systéme, ktorý by ju dlhodobo udržiaval konzistentnú.

Dokumentácia nie je text. Je to produktový systém.

Produktová dokumentácia nie je jeden dokument ani jeden nástroj. V skutočnosti ide o celý ekosystém rozprestretý naprieč viacerými systémami.

Obsahuje technické a funkčné špecifikácie, UX a interakčné popisy, biznis pravidlá, edge cases, ale aj historický kontext rozhodnutí. Ak sa tieto vrstvy nevyvíjajú spoločne, vzniká chaos, ktorý sa prejaví až neskôr - pri onboardingu, refaktoringu alebo väčších zmenách produktu.

Manuálne udržiavať konzistenciu medzi kódom, dizajnom a dokumentáciou je pri komplexnom produkte dlhodobo neudržateľné. Preto sme sa rozhodli zapojiť AI nie ako generátor textu, ale ako systematickú kontrolnú a porovnávaciu vrstvu.

Prečo AI agent a nie „len AI nástroj“

Bežné AI nástroje fungujú reaktívne - odpovedajú na prompt. Ale nám to nestačilo.

Potrebovali sme riešenie, ktoré:

• pracuje s reálnymi dátami z viacerých systémov,
• rozumie rozdielu medzi zámerom a realitou,
• a dokáže upozorniť na nekonzistencie skôr, než sa stanú produkčným problémom.

Preto sme navrhli špecializovaného AI agenta, ktorého úlohou nie je tvoriť obsah, ale udržiavať produktovú konzistenciu.

---

Technologický základ: Claude Code a MCP

Agent je postavený na Claude Code, ktorý umožňuje pracovať s veľkým kontextom a robiť analytické porovnania bez straty súvislostí.

Kľúčovou súčasťou architektúry je MCP (Model Context Protocol) - vrstva, ktorá umožňuje AI bezpečne a kontrolovane pracovať s reálnymi systémami.

Pomocou MCP má agent priamy prístup k:

• dizajnovým podkladom vo Figme,
• produktovej dokumentácii v Confluence,
• zdrojovému kódu v GitHube.

Vďaka tomu AI nepracuje s výňatkami ani odhadmi, ale s rovnakým stavom systému, s akým pracuje celý tím.

---

Jednotná šablóna špecifikácií ako základ škálovania

Aby mal agent jasný rámec, vytvorili sme jednotnú produktovú šablónu pre všetky špecifikácie.

Každá špecifikácia dnes vzniká podľa rovnakej logiky:

začína prehľadom funkcionality, pokračuje popisom reálneho správania, vysvetľuje dizajnový a UX zámer z Figmy, definuje stavy a edge cases, popisuje biznis pravidlá a končí otvorenými otázkami. Táto štruktúra je dôležitá nielen pre ľudí, ale aj pre AI.

Agent ju používa ako referenciu a kontrolný checklist. Ak niektorá časť chýba alebo je nejasná, agent na to upozorní a aktívne sa pýta, čo má byť doplnené.

Dokumentácia sa tak stáva živým procesom, nie pasívnym zápisom.

---

Figma ako most medzi zámerom a realitou

V tomto systéme má Figma jasnú rolu.

Nie je zdrojom pravdy, ale zdrojom zámeru.

AI agent porovnáva:

• čo je navrhnuté vo Figme,
• čo je implementované v kóde,
• a čo je opísané v dokumentácii.

Rozdiely automaticky neoznačuje ako chyby.

Vníma ich ako signály, že je potrebné urobiť rozhodnutie - a práve v tomto bode má AI najväčšiu hodnotu.

---

AI ako „content governance layer“

Inšpirovali sme sa prístupom, kde AI funguje ako governance vrstva nad obsahom.

To v praxi znamená, že agent:

• kontroluje konzistenciu terminológie,
• dohliada na štruktúru dokumentácie,
• identifikuje chýbajúce informácie,
• a robí predbežnú kontrolu ešte pred ľudským review.

AI nerozhoduje. AI upozorňuje, sumarizuje a kladie otázky.

---

Architektúra riešenia (high-level)

Celé riešenie je postavené ako vrstvený systém:

• Zdrojové systémy: GitHub (kód), Figma (dizajn), Confluence (dokumentácia)
• MCP vrstva: bezpečné konektory k jednotlivým systémom
• AI agent layer: Claude Code + pravidlá + šablóny
• Výstupy: report nekonzistencií, návrh špecifikácie, otázky pre tím

Agent nikdy nepristupuje priamo k systémom - všetko ide cez MCP, čo zabezpečuje kontrolu prístupu a auditovateľnosť.

---

Ako vyzerá jeden „run“ agenta v praxi

Proces začína výberom scope - napríklad konkrétnej funkcionality alebo flowu.

Agent si načíta pravidlá, šablónu špecifikácie a následne si cez MCP vyžiada dáta z GitHubu, Figmy a Confluence.

Tieto dáta normalizuje, snaží sa spárovať entity (komponenty, stavy, názvy) a následne vykoná porovnanie. Výsledkom nie je hotové riešenie, ale jasný prehľad rozdielov, chýbajúcich častí a otázok, ktoré je potrebné vyriešiť v tíme.

Tento agent nie je autorom dokumentácie.

Je systematickým partnerom, ktorý pomáha tímu udržať poriadok v komplexite.

---

Biznis hodnota pre firmu

Z pohľadu firmy tento prístup prináša vyššiu dôveru v dokumentáciu, rýchlejší onboarding nových ľudí, menšie riziko pri zmenách a lepšiu pripravenosť na škálovanie produktu.

AI sa tak nestáva experimentom, ale stabilnou súčasťou produktových procesov.

---

Záver

AI nám nepomohla robiť produkt namiesto ľudí, avšak pomohla nám udržať produkt pochopiteľný aj v čase, keď rastie.

A práve v tom vidíme jej najväčší prínos - ako nástroja, ktorý pomáha tímom robiť lepšie rozhodnutia na pevných základoch.