Príručka AI pre Architecture¶

Táto stránka vysvetľuje, ako pomocou AI vytvárať a upravovať Architecture na stránke Architecture. AI flow pre Architecture v AIKOZO nie je iba voľný prompt box a nie je to ani iba rigidný formulár. Kombinuje:

explicitný výber fragmentov
štandardizovanú voľbu akcie: Validate, Align alebo Enhance
voliteľné usmernenie v poli Optional query
rýchle znovupoužiteľné frázy
asynchrónny preview, review a apply/discard flow
findings, ktoré môžu odporučiť ďalšiu akciu

Túto stránku používajte vtedy, keď chcete pomoc AI, ktorá ostane viazaná na jasný Architecture kontext a zároveň ponechá finálne rozhodnutie na používateľovi. Je dôležitá preto, že výsledok nezávisí len od promptu, ale aj od správne zvolenej akcie a scope-u. Pred začiatkom by ste už mali vedieť, na ktorom Architecture alebo flow fragmente chcete pracovať a aký problém sa snažíte vyriešiť. Súvislé prečítanie trvá približne desať minút a najrýchlejšie pochopenie prinesie reálny príklad v strede stránky.

Rovnaký model akcií teraz platí aj na stránke Feature flow, kde je cieľovým typom vždy Flows.

Začnite výberom akcie¶

Ešte pred písaním query si určte, aký typ pomoci vlastne potrebujete.

Záložky Architecture zobrazujú akcie v bežnom pracovnom poradí: Validate, Align, potom Enhance. Začnite read-only diagnózou, potom riešte findings o fit-e alebo reuse a až po správnej štruktúre vylepšujte vyjadrenie.

Akcia	Na čo slúži	Očakávaný výstup	Mení Architecture?
Validate	Nájsť problémy, nejasnosti, chýbajúce väzby, slabé ownership, duplicity alebo nezhody.	Iba findings.	Nie.
Align	Priblížiť vybrané fragmenty k existujúcim architektonickým konvenciám, reuse vzorom a susednému kontextu.	Preview zarovnaných fragmentov a findings.	Áno, po review a apply.
Enhance	Zlepšiť zrozumiteľnosť, wording, štruktúru, responsibilities a úplnosť vybraných fragmentov.	Preview vylepšených fragmentov a findings.	Áno, po review a apply.

Validate¶

Zvoľte Validate, keď si ešte nie ste istí, čo je zle, čo chýba alebo čo by mal byť ďalší krok.

Dobré použitie:

overiť, či má interface správnych owners
odhaliť slabé module boundaries
skontrolovať, či feature komponent naozaj reusuje shared štruktúry namiesto duplicitného návrhu
potvrdiť, či sú entity a interface vzťahy koherentné

Čo očakávať:

Architecture content sa nemení
dostanete findings, ktoré sa dajú skontrolovať a často použiť v ďalšom kroku
niektoré findings môžu ponúknuť odporúčanú akciu Align alebo Enhance

Align¶

Zvoľte Align, keď vybrané fragmenty dostatočne nesedia k okolitej Architecture.

Dobré použitie:

napojiť flow-local interface na správny owner alebo publisher komponent
nahradiť lokálnu duplicitu reuse-om existujúcich konceptov z implementačného Architecture-u
zosúladiť naming, placement a references s okolitou Architecture
propagovať malú, ale potrebnú opravu do blízkych fragmentov

Čo očakávať:

upraviť sa môžu iba vybrané fragmenty
nevybrané fragmenty ostávajú bez zmeny
kontext implementačného Architecture-u ostáva read-only referenciou, nie zapisovateľným cieľom

Enhance¶

Zvoľte Enhance, keď sú vybrané fragmenty v zásade správne, ale potrebujú byť jasnejšie, úplnejšie alebo explicitnejšie.

Dobré použitie:

spresniť responsibilities komponentu
spriehľadniť kontrakt rozhrania
zlepšiť definície entít a vzťahov, ktoré sú už v Architecture naznačené
odstrániť nejasnosť alebo slabý wording

Čo očakávať:

upraviť sa môžu iba vybrané fragmenty
nevybrané fragmenty ostávajú bez zmeny
výsledok má stále pôsobiť lokálne a ohraničene, nie ako široký rewrite

Ako funguje AI flow na stránke Architecture¶

Stránka je usporiadaná tak, aby ostala AI práca kontrolovateľná.

Otvorte jednu artefaktovú záložku: Modules, Components, Interfaces, Entities, ADRs alebo na stránke Feature flow vyberte Flows.
Vyberte jeden alebo viac fragmentov rovnakého typu.
Zvoľte akciu, ktorú naozaj potrebujete: Validate, Align alebo Enhance.
Voliteľne doplňte usmernenie do Optional query.
Spustite akciu do frontu.
Skontrolujte výsledok v histórii vylepšení pre aktívnu záložku.
Po review použite Re-run, Apply alebo Discard.

Táto štruktúra je dôležitá. AIKOZO je navrhnuté tak, aby ste problém nemuseli zakaždým popisovať úplne od nuly. Vybrané fragmenty, aktívna záložka, read-only scope-ovaný kontext a optional query spolu tvoria jeden riadený vstup.

Čo v praxi znamená „scope-ovaný kontext“¶

Ide o novšiu, prísnejšiu podobu toho, čo staršia dokumentácia označovala ako current architecture context.

AI stále dostáva podporný kontext, ale tento kontext je read-only.

Current scoped context obsahuje iba minimum súvisiacej informácie, ktoré je potrebné na pochopenie vybraných fragmentov.
Kontext implementačného Architecture-u je dodatočný read-only kontext, najmä užitočný pri alignovaní Feature flow-u.

To znamená:

Validate ostáva read-only.
Enhance a Align môžu meniť iba vybrané položky.
nevybrané fragmenty ostávajú nezmenené, aj keď sú viditeľné v kontexte.

Reálny príklad: oprava notifications flow¶

Predstavte si Feature flow pre order processing. Máte:

integračné rozhranie if.int.notifications
kandidáta na publisher cmp.orders.api
lokálneho consumer-a cmp.notifications
modul mod.messaging

Typický problém vyzerá takto:

interface existuje
publisher a consumer nie sú modelované koherentne
ownership je neúplný
fragmenty spolu očividne súvisia, ale nechcete spustiť široký rewrite

Krok 1: začnite Validate¶

Otvorte Interfaces, vyberte if.int.notifications a spustite Validate.

Užitočná query môže byť:

Skontroluj ownership, publisher-consumer zrozumiteľnosť a či toto rozhranie sedí k okolitej messaging Architecture.

Prečo začať tu:

najprv chcete diagnózu
ešte neviete, či ďalší krok má byť Align alebo Enhance

Findings si pozorne prejdite. Ak finding obsahuje odporúčanú akciu, vie pre vás otvoriť už predvyplnený follow-up modal.

Krok 2: použite odporúčanú Align akciu¶

Predstavte si, že finding odporučí zarovnať interface ku konkrétnemu publisherovi a blízkemu messaging kontextu.

Kliknite na tlačidlo Align na finding-u.

Modal sa otvorí už s:

korektnou cieľovou záložkou
správne vybranými cieľovými fragmentmi
odporúčaným textom v Optional query

Práve tu je flow viac než iba „prompt only“ UX. Ďalšia akcia nie je iba text, ale scope-ované pokračovanie predchádzajúceho review kroku.

Krok 3: skontrolujte Align preview¶

Keď queued run dobehne, otvorte položku v histórii a skontrolujte:

Validation
Before
After

V tomto príklade by dobrý Align preview mohol:

napojiť if.int.notifications na správny owner alebo publisher fragment
zachovať koherenciu modulu a naming konvencií
upraviť iba tie blízke messaging fragmenty, ktoré sú nutné pre konzistenciu

Ak je smer správny, ale výsledok ešte nie je review-ready, použite Re-run.

Krok 4: použite Enhance až keď je štruktúra správna¶

Keď sú vzťahy koherentné, spustite Enhance na najrelevantnejšom fragmente, často v záložke Components alebo Interfaces.

Užitočná query môže byť:

Spresni responsibilities event publishera a urob kontrakt explicitný bez zmeny celkovej architektúry.

Toto je dobrá Enhance query, lebo žiada lepšie vyjadrenie, nie štrukturálne hľadanie problému.

Krok 5: dokončite to ešte jedným Validate kolom¶

Keď je lokálny refinement hotový, spustite Validate ešte raz na finálnom fragmente alebo fragmentech, na ktorých vám záleží.

Tento posledný krok odpovie na:

sú responsibilities teraz jasnejšie
sú owners a references koherentné
nezanechala predchádzajúca akcia novú nejasnosť

Ak findings ostanú už len minor alebo informačné, ste blízko k apply a finalizácii.

Ako písať lepší text do Optional query¶

Pole Optional query má run zúžiť, nie nahradiť vstavaný kontext.

Dobré query:

Clarify ownership and event flow, but keep current IDs and module structure.
Validate whether these components reuse shared notifications patterns instead of duplicating them.
Align naming and references with the surrounding messaging context.
Enhance the interface contract so downstream consumers are explicit.

Slabé query:

Make it better.
Refactor everything.
Do whatever makes sense.
Rework the whole module.

Lepší vzor je:

povedať, aký typ problému riešite
povedať, čo má zostať stabilné
udržať požiadavku lokálnu

Používajte saved phrases zámerne¶

Saved phrases sú najužitočnejšie tam, kde tím opakuje rovnaké review pohyby.

Príklady:

merge these and propagate updates to references to keep consistency
clarify ownership and dependency direction
validate reuse against surrounding implementation architecture
tighten responsibilities without expanding scope

Dôležité detaily:

frázy sa pamätajú oddelene pre akciu a artefaktovú záložku
v modale sa zobrazia najviac tri návrhy
obľúbené frázy majú prioritu
na stránke Profile môžete frázy označiť ako obľúbené alebo ich odstrániť

Saved phrases berte ako znovupoužiteľné steering hints, nie ako náhradu review.

Findings čítajte ako decision support¶

Finding nie je vždy príkaz na okamžité použitie.

Findings používajte tromi spôsobmi:

ako review dôkaz
ako vstup pre follow-up akciu
ako signál, že aktuálny scope je príliš úzky alebo príliš široký

Keď finding obsahuje odporúčanú akciu:

prečítajte si odporúčanie cez hover na tlačidle Align alebo Enhance
kliknite na tlačidlo, keď chcete otvoriť ďalšiu scope-ovanú akciu
pred submitom si stále skontrolujte selection aj query

Kontrolný zoznam pred Apply¶

Pred použitím AI výsledku na stránke Architecture skontrolujte:

sedí zvolená akcia s úmyslom: Validate, Align alebo Enhance
ostali zmenené fragmenty stále lokálne k zamýšľanej časti Architecture
ukazujú sekcie Before a After koherentné references
zlepšil run zrozumiteľnosť, nielen nepridal viac slov
je graph v Overview po zmene ľahšie vysvetliteľný
čítajú sa findings už skôr ako minor follow-up než ako štrukturálne varovania

Bežné chyby¶

Použiť Enhance, keď v skutočnosti potrebujete Validate¶

Ak ešte neviete, v čom je problém, najprv ho diagnostikujte. Inak riskujete zmeny skôr, než pochopíte skutočný problém.

Napísať do Optional query celý Architecture brief¶

Stránka už poskytuje štruktúru. Query má slúžiť na steering, nie na opísanie celej Architecture od nuly.

Aplikovať prvé preview príliš rýchlo¶

Použite Re-run, keď je smer správny, ale výsledok ešte nie je review-ready.

Vybrať príliš veľa naraz¶

AI akcie nad Architecture fungujú najlepšie vtedy, keď je scope dostatočne malý na jasné review. Ak výsledok pôsobí príliš široko alebo vágne, zmenšite selection a skúste to znova.

Odporúčaný pracovný vzor¶

Pre väčšinu reálnej práce s Architecture je spoľahlivý tento vzor:

Validate na odhalenie skutočného problému.
Align, keď je hlavný problém fit, reuse alebo konzistencia.
Enhance, keď je štruktúra už správna, ale vyjadrenie slabé.
Validate ešte raz pred finálnym apply lokálnej zmeny.

Tento cyklus je praktickým jadrom craftingu Architecture s AI v AIKOZO.