Pracovný podklad pre predstavu o AI-assisted vývoji. Popisuje opakovateľný postup s dôrazom na verifikačné slučky, včasné riešenie kritických aktivít (shift-left) a prierezové vrstvy.
1. Účel dokumentu
Cieľom je opísať opakovateľný postup vývoja softvéru, v ktorom je AI plnohodnotným nástrojom naprieč celým životným cyklom — od discovery cez architektúru a špecifikáciu až po implementáciu a nasadenie — pri zachovaní kontroly človeka na kritických miestach.
Dokument je zámerne technologicky konkrétny tam, kde to dáva zmysel (NotebookLM, OpenSpec, Quarkus, Angular/React, KMP, GitLab CI, k8s/OpenShift), ale princípy sú prenositeľné.
2. Základné princípy
Tieto princípy sú dôvodom, prečo je poradie krokov nižšie také, aké je.
- Spec-driven vývoj. Špecifikácia je primárny artefakt, z ktorého AI generuje a voči ktorému sa výstup overuje. Dobrá spec dáva agentovi štruktúrovaný kontext a robí jeho výstup verifikovateľným.
- Človek v slučke (human-in-the-loop). AI generuje, človek rozhoduje a schvaľuje. AI dokáže vyprodukovať vierohodne vyzerajúci, ale nesprávny kód — preto po každom podstatnom výstupe nasleduje kontrola.
- Verifikačné slučky. Každý výstup má mať automatický spôsob overenia (testy, kontrakty, scan). Bez slučky, ktorá povie „hotovo/nehotovo“, sa AI-generovaný kód nedá bezpečne škálovať.
- Malé vertikálne rezy namiesto „big bang“. Radšej generovať a kontrolovať funkciu po funkcii (end-to-end), než celý systém naraz. Veľké generácie sa ťažko reviewujú a ľahšie skrývajú chyby.
- Shift-left. Testovanie, bezpečnosť a nasaditeľnosť sa riešia od začiatku, nie na konci. Čím neskôr sa problém objaví, tým drahšie sa opravuje.
- Iteratívnosť. Postup nie je jednosmerný vodopád — kroky sa opakujú a spec sa vyvíja spolu s produktom.
3. Prierezové vrstvy
Nasledujúce oblasti nie sú samostatným krokom na konci, ale prebiehajú počas celého vývoja a premietajú sa do viacerých fáz.
3.1 Testovanie a verifikácia
Acceptance kritériá a testovacie scenáre sú súčasťou špecifikácie (Fáza 3). Pri implementácii sa uplatňuje TDD alebo test-along prístup — test dáva AI agentovi jasný cieľ a verifikačnú slučku („generuj, kým neprejdú tieto testy“). Pyramída: unit → integračné → contract → e2e.
3.2 Bezpečnosť
Threat modeling už pri architektúre; správa secretov (nie v repo, ale vo vault/secret store); automatizované brány v pipeline — SAST, DAST, SCA (scan závislostí). AI-generovaný kód má známe úskalia (injection, chybné autorizačné kontroly), preto sú tieto brány povinné. Keďže ide o EÚ a rieši sa autentifikácia (OIDC), patrí sem aj data-privacy / GDPR pohľad: čo, kde a ako dlho sa ukladá.
3.3 Observability
Logging, metriky, distributed tracing a alerting sa zavádzajú spolu s prostrediami, nie až po nasadení. Pri distribuovanom systéme z viacerých komponentov je to jediný spôsob, ako v produkcii nebyť slepý.
3.4 Synchronizácia spec ↔ kód
OpenSpec pomáha, ale potrebuje disciplínu, ktorá drží špecifikáciu aktuálnu, ako sa kód vyvíja. Zmena kódu, ktorá mení správanie, musí aktualizovať spec (ideálne ako súčasť Definition of Done a review). Inak sa zo špecifikácií stane zastaraný balast a stratia hodnotu pre AI aj pre ľudí.
3.5 Konvencie pre AI agenta
Každé repo obsahuje inštrukcie pre AI (napr. CLAUDE.md / AGENTS.md / .cursorrules podľa nástroja) so style guidom, konvenciami, technologickými rozhodnutiami a odkazom na spec. Zabezpečuje to konzistentný výstup naprieč mnohými repozitármi namiesto toho, aby každý vyzeral inak.
3.6 Rozhodnutia a review
Kľúčové architektonické rozhodnutia sa zaznamenávajú ako ADR (Architecture Decision Records) — diagram zachytáva čo, ADR zachytáva prečo. Zmeny idú cez PR/MR s jasnou branching stratégiou a definovaným schvaľovateľom, vrátane AI-generovaných zmien.
3.7 Kontrakty medzi komponentmi
Kontrakt medzi komponentmi má dve úrovne a nie sú zameniteľné. Štruktúrne, provider-driven kontrakty (OpenAPI pre REST, protobuf/gRPC) opisujú celý tvar rozhrania — endpointy, typy, polia. Behaviorálne, consumer-driven kontrakty (Pact) zachytávajú, ktorú podmnožinu rozhrania daný consumer reálne používa a aké konkrétne očakávania má voči odpovediam. Prvé hovoria „takto vyzerá celé API“, druhé „toto z neho naozaj konzumujem“.
Odporúčaný prístup je vrstvenie, nie buď-alebo:
- Základ je spec-first. protobuf/gRPC pre komunikáciu backend-to-backend, OpenAPI pre REST voči klientom (Angular, React, KMP). Definuje sa v architektúre (Fáza 2) a je zdrojom, z ktorého sa generuje kód aj testy.
- Nad tým lacné brány proti driftu. Detekcia breaking changes a conformance testy v CI pokryjú väčšinu nesúladu rozhraní s minimálnou réžiou (Fáza 5).
- Pact selektívne. Len tam, kde má jeden provider viac nezávislých consumerov a kde sa oceňuje
can-i-deploy(matica kompatibility verzií naprieč prostrediami). Nemá zmysel nasadzovať ho plošne.
OpenAPI je slabší základ, gRPC silnejší. OpenAPI sa často píše ručne a drift-uje od implementácie — je to dokument, nie záruka, takže špecifikácia môže tvrdiť jedno a bežiaci provider vracať druhé. protobuf/gRPC je oproti tomu contract-first zo svojej podstaty (bez .proto sa nezaobídeš), takže štruktúrny nesúlad sa stáva compile-time chybou; má aj explicitné pravidlá wire-kompatibility (číslovanie a rezervovanie polí, bezpečné pridanie optional poľa). Nech je základ akýkoľvek, drift proti nemu strážia dve lacné brány, pričom každá rieši iný druh driftu.
Prvá brána — detekcia breaking changes — rieši evolučný drift, teda zmenu schémy, ktorá by porušila existujúcich consumerov. Je to statický diff dvoch verzií schémy: baseline (main branch alebo publikovaná schéma) a novej navrhovanej. Nástroj označí zmeny rozbíjajúce klientov — zmenu čísla či typu poľa, odstránenie používaného poľa, zmazanie enum hodnoty, nový povinný parameter, zúžený typ. Pri protobufe to robí Buf (buf breaking), pri OpenAPI oasdiff alebo openapi-diff. V CI beží ako brána: ak diff obsahuje breaking change, pipeline spadne alebo si vyžiada explicitné schválenie či major verziu. Lacné je to preto, že ide len o porovnanie dvoch textových súborov — beží v sekundách, je deterministické, nepotrebuje bežiacu službu a nepíšeš žiadne testy; jediná réžia je mať baseline na porovnanie (publikovaná schéma, git tag alebo schema registry).
Druhá brána — conformance testovanie — rieši spec-vs-kód drift, teda rozídenie bežiacej implementácie s vlastnou schémou. Schemathesis prečíta OpenAPI, sám vygeneruje množstvo požiadaviek vrátane hraničných prípadov (property-based / fuzzing) a overí, že status kódy aj telá odpovedí sedia so schémou. Dredd ide skôr príkladovo — prejde endpointy podľa schémy a porovná reálne odpovede. Ani tu nepíšeš testovacie prípady ručne, nástroj si ich odvodí zo schémy; marginálna cena na endpoint je takmer nulová a potrebuješ len bežiacu inštanciu providera, ktorú CI aj walking skeleton aj tak spúšťajú. Je to o kúsok viac setupu než čisto statická detekcia (treba beh a prípadne auth/fixtures), no stále rádovo lacnejšie než ručne písané integračné testy alebo plný Pact suite.
Spolu pokryjú väčšinu nesúladu, lebo chytia dve najčastejšie zlyhania — porušil si kontrakt voči klientom a tvoj kód nesedí s kontraktom — a to bez consumer-driven mašinérie. Ich hranica je v tom, že nevedia, ktoré polia ktorý consumer reálne používa: breaking-change nástroje sú preto konzervatívne a každé odstránenie poľa označia za breaking, aj keď ho nikto nekonzumuje, a conformance kontroluje schému, nie semantické očakávania konkrétneho consumera voči hodnotám a scenárom. Túto medzeru zapĺňa Pact.
Čo Pact pridáva aj nad gRPC: vieš, ktoré polia consumeri naozaj používajú (a teda čo môžeš bezpečne deprekovať alebo odstrániť); semantické očakávania voči konkrétnym hodnotám a scenárom, nielen voči tvaru; a can-i-deploy ako deployment gate. Provider-verifikácia navyše beží proti reálnemu provideru, nie proti dokumentu. Za to sa platí réžiou — broker (Pact Broker alebo hosťovaný PactFlow), písanie a údržba consumer testov a verifikácia v CI.
4. Postup po fázach
Fáza 0 — Príprava znalostnej bázy a princípov
Zber čo najväčšieho množstva podkladov, noriem, príkladov a existujúcich dokumentov a ich vloženie do NotebookLM. Vzniká znalostná báza, ktorá slúži na konzultáciu počas brainstormingu a v ďalších fázach. Súčasne sa dohodnú prierezové princípy z kapitoly 3, aby platili od začiatku.
Účastníci: tím, AI, NotebookLM.
Fáza 1 — Požiadavky a Definition of Done
Spísanie requirementov s konzultáciou AI, NotebookLM a architektov. Už na tejto úrovni sa definuje Definition of Done a acceptance kritériá, ktoré sa neskôr premietnu do špecifikácie a testov. Bez nich nie je jasné, kedy je čokoľvek „hotové“.
Účastníci: architekti, biznis, AI, NotebookLM.
Fáza 2 — Architektúra a kontrakty
High-level diagram v draw.io (konzultácia AI, NotebookLM, architekti), po ktorom nasleduje rozdelenie na komponenty — diagram aj slovný popis. Rozdelenie zároveň rieši veľkosť kontextu pre AI, keďže vznikajú menšie, ohraničené celky.
Súčasťou fázy je definícia explicitných API kontraktov a event schém medzi komponentmi, a to spec-first: protobuf/gRPC pre komunikáciu backend-to-backend a OpenAPI pre REST rozhrania voči klientom (Angular, React, KMP). Tieto schémy sú samotný kontrakt, z ktorého sa neskôr generuje kód aj testy. Pri samostatných repo a paralelnom vývoji je udržanie konzistentných rozhraní známy problém, ktorý kontrakty ohraničujú (podrobnejšie prierezová vrstva 3.7). Kľúčové rozhodnutia (voľba technológie, spôsob komunikácie, hranice komponentov) sa zaznamenávajú ako ADR, aby ostal zachovaný ich kontext. Na úrovni architektúry sa robí aj threat modeling (prierezová vrstva 3.2).
Účastníci: architekti, AI, NotebookLM.
Fáza 3 — Špecifikácia (spec-driven)
Spísanie špecifikácie pre celý systém aj pre jednotlivé komponenty pomocou OpenSpec (+ store). Špecifikácia obsahuje aj acceptance kritériá a testovacie scenáre pre každý komponent — testy tak nie sú dodatok na konci, ale súčasť zadania, z ktorého sa neskôr generuje aj overuje.
Od tohto bodu je špecifikácia zdrojom pravdy a musí sa udržiavať v synchronizácii s kódom (prierezová vrstva 3.4).
Účastníci: architekti, AI, NotebookLM.
Fáza 4 — Scaffolding a walking skeleton
Vytvorenie repozitárov pre komponenty a inicializácia OpenSpec v každom z nich. Do každého repo sa pridávajú konvencie pre AI agenta (CLAUDE.md / AGENTS.md, prierezová vrstva 3.5) a inicializuje sa prostredie s požadovanými technológiami pre daný komponent: Quarkus app, PostgreSQL + Flyway migrácie, OIDC, Angular app, React app, KMP mobile app, Java library, npm library a ďalšie.
Hneď po scaffoldingu sa postaví walking skeleton — end-to-end kostra, kde jeden triviálny endpoint prejde celou cestou: build → CI pipeline → nasadenie do k8s/OpenShift. Keď je celá cesta od commitu po beh v prostredí funkčná na prakticky prázdnom systéme, každá ďalšia funkcia sa už len pridáva do overeného potrubia a integračné aj deployment problémy sa odhalia včas. Minimálna verzia CI/CD a nasadenia tak vzniká už tu a v ďalších fázach len dozrieva.
Účastníci: architekti, DevOps, AI.
Fáza 5 — Iteratívna implementácia
Systém sa generuje zo špecifikácie pomocou AI po vertikálnych rezoch — jedna funkcia end-to-end vrátane testov — s tesnou review slučkou po každom reze. Po generovaní nasleduje kontrola programátorom a prípadná intervencia, následne manuálne úpravy s podporou AI a opäť review.
Testy zo špecifikácie slúžia ako cieľ a verifikačná slučka pre AI (TDD / test-along, prierezová vrstva 3.1). Drift rozhraní medzi komponentmi sa rieši vrstvene (prierezová vrstva 3.7): v CI beží detekcia breaking changes voči schémam (Buf pre protobuf, oasdiff / openapi-diff pre OpenAPI) a pri REST aj conformance testy (Schemathesis, Dredd), ktoré overujú, že provider naozaj zodpovedá svojej OpenAPI špecifikácii. Pact sa nasadzuje selektívne tam, kde má jeden provider viac nezávislých consumerov — jeho provider-verifikácia beží proti reálnemu provideru a can-i-deploy slúži ako brána pred nasadením. Súčasťou Definition of Done je priebežná synchronizácia špecifikácie s kódom (prierezová vrstva 3.4) a všetky zmeny idú cez PR/MR s jasným schvaľovaním (prierezová vrstva 3.6).
Účastníci: programátori, AI, review.
Fáza 6 — Dozretie CI/CD, nasadení a prevádzky
Základ vznikol už vo walking skeletone a v tejto fáze dozrieva na plnú úroveň. Dobuduje sa buildovanie pre každý komponent cez GitLab CI a vzniknú DevOps repozitáre s configom pre nasadenie do orchestračných nástrojov spolu s nasadzovacími pipeline (k8s, OpenShift a ďalšie).
Do pipeline sa pridávajú bezpečnostné brány — SAST, DAST, SCA a kontrola secretov (prierezová vrstva 3.2) — a tam, kde sa používa Pact, aj kontrola can-i-deploy, ktorá pred nasadením overí, že daná verzia je kompatibilná s tým, čo beží v cieľovom prostredí (prierezová vrstva 3.7). Deployment setup zahŕňa observability, teda logging, metriky, tracing a alerting (prierezová vrstva 3.3). Prostredia dev / staging / prod sa udržiavajú v čo najväčšej parite, aby sa ich správanie líšilo minimálne.
Účastníci: DevOps, programátori, AI.
Fáza 7 — Kontinuálna iterácia
Postupné zmeny, ladenie, testovanie a pridávanie funkcií — opakovanie predchádzajúcich fáz. Každá nová funkcia prechádza rovnakým cyklom: aktualizácia špecifikácie → vertikálny rez s testami → review → nasadenie cez overené potrubie. Prierezové vrstvy platia v každej iterácii.
Účastníci: celý tím, AI.