"Flow" buildera¶

Toto je odporúčaný postup pre buildera, ktorý premieňa overenú analýzu na implementačne pripravené Delivery packagey, sady inštrukcií a build output. Používajte ho vtedy, keď chcete prejsť od analytických artefaktov k delivery bez straty traceability. Je dôležitý preto, že builder-side artefakty na seba nadväzujú v konkrétnom poradí: najprv Architecture, potom Guardrails, potom Delivery packagey a až nakoniec buildy. Pred začiatkom si overte, že máte správnu implementation a prípadné analytické vstupy, od ktorých závisíte. Prvé prečítanie zvyčajne trvá 15 až 25 minút a neskôr už oveľa menej.

Ak ešte nie sú názvy artefaktov zrejmé, najprv si prečítajte koncepty: Implementation, Feature, Architecture, Pattern, Feature flow, Guardrails, Delivery target, Delivery package, Instruction Set a Build.

Prehľad "Flow"¶

Otvoriť alebo vytvoriť implementation.
Vytvoriť feature a prepojiť ju so správnym epic-om a use case-mi.
Vytvoriť alebo vygenerovať Architecture.
Skontrolovať a finalizovať Architecture.
Vytvoriť a upraviť guardrails.
Vytvoriť Delivery package.
Vygenerovať sady inštrukcií a renderované artefakty.
Skontrolovať vygenerované sady inštrukcií a spustiť build.
Skontrolovať výsledok buildu.

Stránky používané v tomto "Flow"¶

Vstupný kontext: stránka Implementations, stránka Project a stránka Implementation
Plánovanie feature: stránka Feature
Architektonická práca: stránka Architecture, stránka Feature flow a stránka Guardrails
Delivery orchestrácia: stránka Delivery package a stránka Instruction Set
Kontrola execution: stránka Build

1. Otvorte implementation workspace¶

Použité stránky: stránka Implementations, stránka Project a stránka Implementation

Choďte do Implementations alebo otvorte zoznam implementations zo stránky projektu. Použite Workspace v riadku implementation, keď chcete najprv sprievodný prehľad pred vstupom do pokročilej stránky Implementation. Implementation workspace ukáže odporúčaný ďalší krok, pripravenosť Architecture, stav Feature flow, delivery setup a posledné výsledky.

Ak treba, vytvorte novú implementation a pripojte ju k príslušnej specification. Ak je zapnutá repository-backed execution, overte repozitárové nastavenia ešte predtým, než sa na build automatizáciu začnete spoliehať.

2. Vytvorte feature¶

Použité stránky: stránka Implementation a stránka Feature

Vo vnútri implementation vytvorte Feature a prepojte ju s:

implementation kontajnerom
epic-om, ktorý nesie biznisový scope
voliteľnými use case-mi s behaviorálnym detailom

Tento krok je hlavný traceability most medzi analytickým výstupom a builder prácou.

3. Vytvorte alebo vygenerujte Architecture¶

Použité stránky: stránka Implementation, stránka Feature, stránka Architecture a stránka Feature flow

Implementačný Architecture spravujte zo stránky implementation a feature-level Feature flow zo stránky feature.

Keď je zapnutý FEATURE_FLOW_DESIGN_MODEL, pozerajte sa na model v dvoch vrstvách:

vytvorte alebo upravte implementačný Architecture zo stránky implementation
vytvorte alebo upravte feature-level Feature flow vo flow workspace danej feature

Architecture zostáva autoritatívny. Feature flow má odkazovať na koncepty z Architecture-u a na jeden konkrétny Pattern, nie lokálne redefinovať architektúru.

Každý Feature flow patrí presne jednej Feature. Súrodenecké Features pod tým istým Epicom majú samostatné flowy, históriu generovania a delivery packages; odstránenie Feature odstráni iba flow artefakty danej Feature.

Keď je zapnutý FEATURE_FLOW_DESIGN_GENERATION, feature workspace navyše umožní generovať draft Feature flow-u z jedného povinného Patternu, zdrojových Use Case-ov, voliteľných inštrukcií pre generovanie a náhľadu kontextu Architecture. Kontext môže byť Recommended, All alebo Manual. Výsledok sa spracuje asynchrónne a pred apply prejde review. Neúspešný run si uloží štruktúrovanú fázu zlyhania a error code, aby workspace rozlíšil chybu konfigurácie promptu, tvaru AI odpovede, Architecture scope alebo AI požiadavky.

Režimy kontextu Architecture:

Recommended použije AI na návrh zameraných fragmentov Architecture ešte pred generovaním; náhľad musí byť aktuálny pred zaradením draftu do frontu
All zahrnie každý fragment z aktuálneho Architecture-u
Manual umožní vybrať konkrétne fragmenty Architecture v jednom vyhľadávači

Voľba Patternu pre feature-level flow vychádza z implementačného Architecture-u:

vo feature flow workspace je možné vybrať iba aktívne Patterny uvedené ako Allowed na Architecture-e
Patterny označené ako Preferred sa zobrazujú ako prvé odporúčania
preferred neznamená povinný; stále je možné vybrať ľubovoľný allowed Pattern
každý manuálny aj generovaný Feature flow stále ukladá presne jeden konkrétny pattern_ref pre flow
generovanie odosiela stabilný key alebo code Patternu, vyrieši ho iba raz a pred vytvorením runu odmietne neznámy, neaktívny alebo nepovolený Pattern
každý run uloží snapshot kanonického odkazu na Pattern a revíziu jeho obsahu; identifikátory krokov v AI-generovaných draftoch prideľuje deterministicky server a nepreberá ich z výstupu modelu

Máte dve praktické cesty:

Manuálna Architecture, keď už štruktúru poznáte
AI-generated Architecture, keď chcete štruktúrovaný východiskový návrh z requirement a Ubiquitous Language kontextu

Stránka Implementation štandardne ukazuje jeden Current Architecture. Ak existuje final Architecture, je aktuálny; inak je aktuálny najnovší nearchivovaný draft. Ostatné implementačné Architecture záznamy zostávajú v Version history. Ak ešte neexistuje aktuálny Architecture, použite New architecture alebo Generate architecture with AI na vytvorenie prvého. Keď už aktuálny Architecture existuje, použite New draft version na vytvorenie draft verzie z jeho obsahu alebo Generate draft version na nový AI-generated draft z prijatého Ubiquitous Language.

AI architecture cesta je závislá od prijatých termínov Ubiquitous Language pre príslušnú špecifikáciu. Prijaté entities, values, processes, events, policies, vzťahy a kontextové hints seedujú generovanú Architecture tak, aby draft začínal z riadeného business slovníka namiesto exploratívneho clusterovania.

Requirements v stave deferred sú z týchto implementačných vstupov vylúčené, takže neovplyvňujú generovaný architecture, kontext pre instructions ani supporting set requirements pre build.

Ak spustíte AI generovanie Architecture a modal sa zavrie hneď, kliknite na AIKOZO logo v hornom paneli a v popup-e Background jobs sledujte, či je úloha vo fronte, beží, je dokončená alebo zlyhala.

Keď je dostupný panel implementačného sémantického vyhľadávania, môžete ho použiť aj na rýchly preskok na najbližší zodpovedajúci fragment Architecture, flow-u alebo guardrails ešte pred manuálnym refinementom architektúry.

4. Skontrolujte a finalizujte Architecture¶

Použité stránky: stránka Implementation, stránka Architecture a stránka Feature flow

Na stránke implementačného Architecture-u skontrolujte:

kontextový strom nad workspace-om s projektom, implementation, feature, Architecture a počtami fragmentov
key, name a description
referenciu na prompt template
záložku Overview s grafmi entít, modulov a vzťahov medzi komponentmi a rozhraniami
tlačidlo Patterns vo workspace-i, ak implementation potrebuje znovupoužiteľné architektonické vzory
záložky Modules, Components, Interfaces, Entities, Values, Processes, Events, Policies a ADRs pre fragmentovú kontrolu
históriu vylepšení a preview ešte pred použitím AI výstupu
tlačidlo Raw YAML vo workspace-i pre manuálnu korekciu

V modale Patterns:

Allowed Patterny určujú, ktoré Patterny môžu feature-level Feature flowy používať pod týmto Architecture-om
Preferred Patterny sú odporúčaná podmnožina allowed sady
označenie Patternu ako preferred ho zobrazí ako prvý pri plánovaní a generovaní flow, ale neblokuje ostatné allowed Patterny
odstránenie Patternu z Allowed ho odstráni aj z picker-a vo feature flow workspace

AI refinement na stránke Architecture je selektívny a review-driven. Vyberte jednu artefaktovú záložku, označte jeden alebo viac fragmentov rovnakého typu, zvoľte Validate, Align alebo Enhance a zaraďte preview akciu do frontu. Keď potrebujete rýchlo zmeniť celý viditeľný výber, použite na aktívnej artefaktovej záložke Select all alebo Deselect all. V paneli histórie vylepšení si najprv skontrolujte badge s akciou, typom artefaktu a stavom a podľa potreby si rozbaľte Validation, Before a After. Sekcia After zobrazuje celý vylepšený fragmentový set pre vybraný typ artefaktu a zoznam histórie je viazaný na aktívnu artefaktovú záložku. Ak chcete ďalší variant, použite Re-run, potom preview Apply alebo Discard. Edit použite iba vtedy, keď treba opraviť YAML manuálne.

Pole Optional query teraz zobrazuje aj najviac tri uložené rýchle frázy pre aktívnu kombináciu akcie a artefaktovej záložky. Frázy sa pamätajú oddelene pre jednotlivé bucket-y, takže napríklad Validate -> Modules ostáva oddelené od Align -> Modules alebo Enhance -> Entities. Kliknutím na uloženú frázu okamžite vyplníte query bez ďalšieho písania.

Detailné stránky Requirement, Use case a Test case používajú rovnaký vzor rýchlych fráz pre usmernenie akcie Enhance. Tieto frázy sa ukladajú v samostatných bucket-och Specification workspace, takže sa nemiešajú s Architecture guidance.

Ak chcete hlbšie pochopiť, kedy použiť jednotlivé AI akcie, ako fungujú review cykly a ako používať findings ako follow-up kroky, prečítajte si Príručku AI pre Architecture. Finalizujte až vtedy, keď je Architecture dostatočne koherentná pre ďalšiu prácu s Guardrails a generovaním Delivery packageov.

Ak je zapnutý nový model, skontrolujte aj feature-level Feature flow:

key, name a description
stav draft, candidate, final alebo archived
alignment badge ukazujúci, či sú referencie stále platné
záložky Overview, Flows a Raw YAML
či sa každý referencovaný koncept korektne vyrieši voči implementačnému Architecture-u
či zvolený pattern_ref a roly v jednotlivých krokoch stále sedia k Architecture-u

So stavom final narábajte úsporne. Na jednu implementation môže byť finálny iba jeden implementačný Architecture a na jeden epik iba jeden Feature flow. Povýšenie draft Architecture verzie na final z nej spraví aktuálny Architecture; staršie drafty a archivované záznamy zostávajú vo Version history.

Keď implementation už má aktuálny finálny Architecture a použiteľné finálne Feature flowy, vráťte sa na stránku Implementation a použite Gap analysis na porovnanie implementačného Architecture-u s finálnymi Feature flowmi. Aditívne odporúčania runtime fragmentov tam najprv skontrolujte a až potom ich aplikujte po jednom.

5. Vytvorte a upravte guardrails¶

Použité stránky: stránka Feature a stránka Guardrails

Vo feature vytvorte Guardrails naviazané na vybranú Architecture. Použite Guardrails vtedy, keď potrebujete delivery guardraily, nie architektonickú štruktúru.

Na stránke guardrails-u môžete:

zaradiť preview vylepšenie z cielenej query do frontu
voliteľne vybrať jeden feature-local Feature flow, alebo legacy feature architecture v compatibility režime, a jeho fragmenty ako read-only kontext
vo fokusovanom kontexte vybrať iba tie fragmenty, ktoré majú slúžiť ako read-only vstup
skontrolovať Validation, Before a After pred použitím výsledku
použiť Re-run, keď chcete ďalší variant preview
upravovať YAML priamo
vrátiť sa na default guardrails
posunúť artefakt z draft do final, keď sú guardraily jasné

Kvalita guardrails je dôležitá, pretože priamo ovplyvňuje výstup Delivery packageu a neskôr aj výsledok buildu.

5a. Nakonfigurujte delivery targety, keď je potrebné delivery routovanie¶

Použité stránky: stránka Implementation

Keď je zapnutý CAP_EXECUTION_TARGET_MANAGEMENT, ešte pred vytvorením Delivery packageov otvorte v implementation workspace záložku Delivery targets, ak sa delivery bude smerovať do repozitárov alebo do JIRA. Delivery target spravuje cieľ delivery, nie samotný pracovný obsah.

Typické builder akcie sú:

vytvoriť GitHub, GitLab alebo JIRA targety
otvoriť detail targetu a skontrolovať usage a poslednú validáciu
spustiť Validate target z detailového modalu
aktivovať alebo deaktivovať existujúci target
upraviť alebo odstrániť nepoužívané targety
otvoriť Execution mapping, keď máte aspoň dva Git repository targety a potrebujete smerovať moduly do rôznych repozitárov

Pri JIRA targetoch teraz vyberáte spôsob autentifikácie explicitne. Atlassian service-account token potrebuje URL stránky aj Cloud ID a validuje sa cez gateway api.atlassian.com/ex/jira/{cloudId}, nie cez lokálnu site REST URL.

V modale Execution mapping používajte Module mapping ako bežné priradenie repozitára a Component overrides (when one component belongs elsewhere) iba vtedy, keď sa jeden komponent doručuje do iného repozitára než jeho modul.

Nový Delivery target je predvolene dostupný iba v aktuálnom projekte. Tenant scope zvoľte iba vtedy, keď má byť cieľ dostupný vo všetkých projektoch tenantu.

Delivery targety sa oplatí udržiavať čisté ešte pred tým, než sa začnete spoliehať na routovanie cez Delivery packagey. Target, ktorý je stále referencovaný mappingmi alebo vygenerovanými artefaktmi, nie je možné odstrániť.

Pri GitHub targetoch, ktoré budú spúšťať buildy, skontrolujte, že vybraný token vie pushovať branche a otvárať pull requesty. Ak generovaný výstup môže pridať alebo zmeniť GitHub Actions workflowy pod .github/workflows/, token potrebuje aj GitHub workflow oprávnenie. Pozrite Nastavenie GitHub a GitLab tokenu.

6. Vytvorte Delivery package¶

Použité stránky: stránka Feature, stránka Feature flow a stránka Delivery package

Vo feature vytvorte Delivery package z jedného Feature flow-u a zvolených flowov, ktoré sa majú posunúť do delivery.

Pri vytvorení Delivery packageu systém uloží snapshot:

alignment stavu Feature flow-u
vyriešeného implementačného Architecture-u a verzií Patternov
execution-target mappingu pre referencované moduly, komponenty a rozhrania
source traceability späť na flowy, requirements a use case-y

Delivery package je rodičovský orchestration artefakt. Pre súčasný build runner a detailné stránky generuje potomkov typu instruction_sets.

7. Vygenerujte sady inštrukcií a renderované artefakty¶

Použité stránky: stránka Delivery package a stránka Instruction Set

Otvorte Delivery package a použite Generate.

Skontrolujte:

generation progress
vygenerované child sady inštrukcií rozdelené podľa targetov
vygenerovaný child intent: agent-bootstrap, repo-init, feature work alebo human review
Codex-ready aj human-readable výstup
renderované artefakty ako skill.md na child stránke sady inštrukcií
delivery targety a source traceability

Generation sa riadi stavom repozitára:

Prázdny repozitár: vygeneruje agent-bootstrap, repo-init, blokovanú feature sadu inštrukcií a human review/task sadu.
Repozitár iba s guidance súbormi: vygeneruje repo-init, blokovanú feature sadu inštrukcií a human review/task sadu. agent-bootstrap vygeneruje tiež vtedy, keď chýba scoped agent guidance ako AGENTS.md.
Runnable repozitár: vygeneruje feature sadu inštrukcií a human review/task sadu. agent-bootstrap vygeneruje tiež vtedy, keď chýba scoped agent guidance.
Neoverený repozitár: generation sa zastaví. Validujte connection execution targetu a regenerujte.

agent-bootstrap vytvára markdown guidance pre ľudí a agentov. Neurobí z repozitára runnable scaffold. repo-init vytvára runnable baseline. Feature sada inštrukcií môže byť viditeľná na kontrolu ešte pred existenciou baseline-u, ale execution ostáva blokované, kým sa repo-init nedostane do repozitára a Delivery package sa znovu nevygeneruje.

Práve tu sa AI výstup stáva najviac operatívnym. Pred execution krokom ho treba dôkladne skontrolovať.

Pri dlhších behoch kliknite na AIKOZO logo v hornom paneli. Popup Background jobs je najrýchlejšie miesto na kontrolu aktuálneho stavu úlohy a návrat na súvisiacu stránku.

8. Skontrolujte vygenerované sady inštrukcií a spustite build¶

Použité stránky: stránka Instruction Set

Z Delivery packageu otvorte vygenerovanú child sadu inštrukcií, ktorá má riadiť ďalší repozitárový krok, a z nej spustite build. Keď sú tieto children prítomné, postupujte v poradí:

Najprv spustite agent-bootstrap.
Potom spustite repo-init.
Výstup každého repo build-u skontrolujte ako bežnú Git zmenu. Ak build otvoril pull request, skontrolujte ho, počkajte na požadované kontroly a merge-nite alebo landnite ho do target branch-u skôr, než spustíte ďalšiu závislú repozitárovú sadu inštrukcií.
repo-init je povinná závislosť pre feature prácu. Feature sadu inštrukcií nespúšťajte proti nezmergovanému repo-init pull requestu. Najprv merge-nite alebo landnite výstup repo-init.
Ak agent-bootstrap vytvoril guidance zmeny ako AGENTS.md, merge-nite alebo landnite tento výstup pred repo-init, keď je to možné, aby repo-init agent videl aktuálnu repository guidance.
Regenerujte Delivery package, aby sa feature sada inštrukcií reclassifikovala ako executable.
Spustite feature sadu inštrukcií.
Skontrolujte a merge-nite alebo landnite výstup feature buildu skôr, než delivery označíte za dokončené alebo začnete následnú prácu, ktorá závisí od týchto zmien.
Vytvorte alebo dokončite human review/task položku podľa delivery workflowu.

Nezávislé target repozitáre môžu postupovať paralelne, ale každý repozitár potrebuje vlastný Git landing point predtým, než ďalšia závislá sada inštrukcií použije jeho stav.

Instruction Set je balík, ktorý kontrolujete. Build je záznam o tom, čo sa stalo po jeho spustení.

Build preberá repository kontext z implementation nastavení. Na stránke build-u sledujte:

execution status
build log
changed files
pull request referenciu
error detaily pri zlyhaní

Build dispatch používa samostatný Celery front, ktorý spracúvajú iba sandbox runnery. Build je v stave queued, kým čaká, a do stavu running prejde, keď ho runner atomicky prevezme tesne pred vykonaním.

9. Skontrolujte výsledok buildu a uzavrite builder loop¶

Použité stránky: stránka Build

Builder flow je hotový až vtedy, keď sa implementačný výstup porovná s pôvodnou analýzou.

Dobré záverečné kontroly:

feature je stále zosúladená s epic-om a use case-mi
Architecture a guardrails vysvetľujú build výsledok
vygenerované súbory sú použiteľné, nielen formálne prítomné
problémy zistené pri build review sa vracajú späť do analýzy alebo Architecture

Aj tu platí selektívna AI. AI pomáha pripraviť návrhy Architecture, Delivery packageu a sady inštrukcií, ale builder nesie zodpovednosť za kvalitu toho, čo sa nakoniec vykoná.