Účel a pracovný model¶
AIKOZO je určené pre tímy, ktoré potrebujú disciplínu v Requirements, traceabilitu dodávky a praktickú podporu AI v jednom pracovnom priestore.
Túto stránku si otvorte vtedy, keď chcete pochopiť slovník, z ktorého vychádza zvyšok príručky. Vysvetľuje hlavné artefakty, prečo existujú a ako do seba zapadajú ešte skôr, než začnete sledovať analytický alebo builder flow. Nepotrebujete nič špeciálne okrem prístupu do aplikácie a prvé prečítanie zvyčajne trvá približne desať minút.
Účel produktu¶
Platforma spája stranu "čo" so stranou "ako":
- Špecifikačná práca zachytáva biznisový zámer ako špecifikácie, Epics, Requirements a Use Cases.
- Plánovacia práca premieňa validovaný scope špecifikácie na prijaté planning baseline-y, signály pripravenosti, hrubé effort rozsahy a allocation guidance.
- Implementačná práca premieňa tento zámer na features, architektúru, guardrailsy, Delivery packagey, sady inštrukcií a build joby.
Hodnota nie je len v generovaní. Dôležité je, že vygenerované výstupy zostávajú naviazané na projektovú štruktúru, dajú sa kontrolovať, prepájať, upravovať a neskôr znovu použiť.
Základný pracovný model¶
Specification workspace používa rovnaké produktové termíny ako detailné stránky: Epic, Requirement, Use Case, Test Case a Ubiquitous Language. Nového používateľa vedie postupom od návrhu cez kontrolu, prepájanie a validáciu až po handoff, bez zavádzania ďalších pomenovaní pre tie isté artefakty.
| Entita | Účel |
|---|---|
| Projekt | Hlavná hranica pracovného priestoru pre analytickú aj implementačnú prácu. |
| Specification | Zoskupenie na úrovni špecifikácie pre Epics. |
| Epic | Oblasť biznisovej schopnosti v rámci Specification. |
| Requirement | Kontrolovateľný Requirement, zvyčajne po enhancement-e a finalizácii pred ďalším použitím. |
| Use Case | Štruktúrovaný scenár, ktorý pokrýva jeden alebo viac Requirements. |
| Test Case | Kontrolovateľný validačný scenár prepojený na Use Case a jeden alebo viac Requirements. |
| Plan | Plánovací kontajner viazaný na specification, ktorý združuje Planning Scopes pre vybrané Epics. |
| Planning Scope | Plánovacia jednotka pre jeden Epic v Plane. Vlastní assessmenty, stav prijatého baseline a effort allocation. |
| Scope Assessment | Vygenerovaný a kontrolovateľný planning odhad s readiness, effort, confidence, drivermi, chýbajúcimi informáciami a klasifikáciami scope itemov. |
| Effort Allocation | Rozdelenie prijatého Scope Assessment odhadu medzi prepojené špecifikačné artefakty. |
| Implementácia | Implementačný kontajner pre features a buildy. |
| Funkcia | Realizačný slice naviazaný späť na Epic a voliteľne na Use Cases. |
| Architecture | Autoritatívny implementačný architektonický artefakt, zvyčajne reprezentovaný a kontrolovaný v YAML. |
| Pattern | Znovupoužiteľná architektonická šablóna priradená na úrovni Architecture-u, ktorá usmerňuje feature-level flowy. |
| Feature flow | Artefakt na úrovni feature. Obsahuje iba flows a odkazuje sa na koncepty z Architecture-u namiesto ich lokálnej redefinície. |
| Guardrails | Hranice a pravidlá, ktoré formujú implementačné riešenie. |
| Delivery target | Spravovaný delivery cieľ používaný na routovanie generovanej práce do repozitárov alebo work-management systémov. |
| Delivery package | Rodičovská execution jednotka vytvorená z výberu Feature flow-u, target mappingu a traceability snapshotov. |
| Sada inštrukcií | Generovaný potomok používaný na generovanie implementácie, renderované artefakty a build execution. |
| Build | Spustiteľný run s logmi a zoznamom zmenených súborov. |
Keď je zapnutý FEATURE_FLOW_DESIGN_MODEL, Architecture a Feature flow sú
oddelené artefakty. Interné route názvy a API payloady môžu počas rollout-u
naďalej používať legacy technické názvy, ale používateľský slovník má používať
názvy v tabuľke vyššie.
Builder koncepty¶
Builder "Flow" sa číta ľahšie, keď od seba oddelíte kontajnerové artefakty, architektonické artefakty, delivery artefakty a execution artefakty.
Implementation¶
Implementation je builder-side kontajner pre jedno plánované riešenie. Združuje features, implementačnú Architecture, spravované delivery targety a súvisiace buildy pre rovnaké delivery úsilie.
Použite ho vtedy, keď chcete jedno miesto, ktoré prepája stranu "ako" späť na zdrojovú specification.
Pozrite tiež: krok 1 vo Flow buildera, stránku Implementations a stránku Implementation.
Feature¶
Feature je delivery slice vnútri implementation. Je to bod, kde sa builder práca znovu pripája k analytickým artefaktom, ako sú zdrojový Epic a vybrané Use Cases.
Použite ju vtedy, keď chcete formovať jeden súvislý kus delivery scope bez miešania nesúvisiacich flowov a guardrails.
Pozrite tiež: krok 2 vo Flow buildera a stránku Feature.
Architecture¶
Architecture je autoritatívny implementačný architektonický artefakt. Definuje znovupoužiteľné štrukturálne koncepty, od ktorých sa feature-level práca smie odvíjať: moduly, komponenty, rozhrania, entity, ADRs a Patterny.
Použite ho na popis stabilnej implementačnej štruktúry. Nepoužívajte ho na feature-špecifické execution kroky.
Pozrite tiež: krok 3 vo Flow buildera, krok 4 vo Flow buildera a stránku Architecture.
Pattern¶
Pattern je znovupoužiteľná architektonická šablóna priradená na úrovni Architecture-u. Popisuje preferovaný štrukturálny štýl pre flow alebo feature, napríklad aké komponenty a rozhrania sa majú zúčastniť.
Použite ho na usmernenie tvaru a generovania Feature flow-u. Pattern nie je samotný flow a nie je ani vykonateľný delivery výstup.
Pozrite tiež: krok 3 vo Flow buildera, krok 4 vo Flow buildera, stránku Architecture a stránku Feature flow.
Feature flow¶
Feature flow je feature-level flow artefakt. Definuje poradie krokov, aktorov a referencií na koncepty z Architecture-u potrebné pre jednu feature, pričom zostáva zarovnaný s implementačným Architecture-om.
Použite ho vtedy, keď chcete popísať, ako má feature fungovať. Nepoužívajte ho na redefinovanie architektúry, ktorú už vlastní Architecture.
Pozrite tiež: krok 3 vo Flow buildera, krok 4 vo Flow buildera, krok 6 vo Flow buildera, stránku Feature a stránku Feature flow.
Guardrails¶
Guardrails je guardrail artefakt pre jednu feature. Zachytáva limity, pravidlá a non-goals, ktoré majú formovať downstream generovanie a delivery.
Použite ho na explicitné určenie hraníc pred generovaním Delivery packageov alebo instruction obsahu.
Pozrite tiež: krok 5 vo Flow buildera a stránku Guardrails.
Delivery target¶
Delivery target je spravovaný delivery cieľ, napríklad GitHub repository, GitLab repository alebo JIRA projekt. Ukladá routing metadata a validačný stav, aby sa delivery artefakty poslali na správne miesto.
Delivery targety sú predvolene scopenuté na projekt. Tenant scope zvoľte, keď má byť rovnaký spravovaný cieľ dostupný pre každý projekt v tenante.
Použite ho vtedy, keď treba delivery scopiť na repository alebo work-management systém. Je to routing konfigurácia, nie samotná generovaná práca.
Pozrite tiež: krok 5a vo Flow buildera a stránku Implementation.
Delivery package¶
Delivery package je rodičovský delivery orchestration artefakt vytvorený z Feature flow-u a vybraných flowov. Pri vytvorení uloží snapshot relevantných verzií Architecture-u a Patternov, traceability väzieb a vyriešeného execution-target mappingu.
Použite ho vtedy, keď chcete stabilný, kontrolovateľný delivery balík pred štartom generovania alebo execution.
Pozrite tiež: krok 6 vo Flow buildera, krok 7 vo Flow buildera a stránku Delivery package.
Instruction Set¶
Instruction Set je generovaný child execution balík pod Delivery packageom. Obsahuje konkrétny výstup pripravený pre zvolenú delivery cestu, napríklad codex-ready instructions, renderované artefakty a build vstup.
Použite ho vtedy, keď chcete skontrolovať skutočný vygenerovaný execution payload pred build alebo delivery akciou.
Repozitárové instruction sety majú rôzne intenty. agent-bootstrap zapisuje
markdown guidance, repo-init vytvára runnable scaffold pre nový repozitár alebo
repozitár iba s guidance súbormi a feature instruction sety implementujú zvolenú
flow prácu až po existencii scaffold-u. Vygenerovaná feature sada môže byť
viditeľná ešte pred dokončením repo-init, ale execution ostáva blokované, kým sa
výstup repo-init nemergne alebo inak nedostane do target branch-u a Delivery
package sa znovu nevygeneruje.
Pozrite tiež: krok 7 vo Flow buildera, krok 8 vo Flow buildera a stránku Instruction Set.
Build¶
Build je execution záznam vygenerovaného delivery runu. Zachytáva runtime stav, logy, changed files a prípadné výsledky pull requestu.
Použite ho na monitoring execution a potvrdenie, čo sa po spustení Instruction Setu zmenilo.
Pozrite tiež: krok 8 vo Flow buildera, krok 9 vo Flow buildera a stránku Build.
Selektívna AI, nie bezobslužná automatizácia¶
AIKOZO používa AI cielene. Cieľom je znížiť manuálne písanie a opakovanú analýzu, nie nahradiť zodpovedné inžinierske rozhodovanie.
AI použite vtedy, keď chcete silný prvý návrh, pomoc s klastrovaním, discovery alebo asistovanú transformáciu medzi artefaktmi. Manuálny postup zvoľte tam, kde je dôležitá presnosť, politika alebo biznisová nuansa.
Typický vzor:
- Vygenerujte alebo vylepšite draft.
- Kriticky ho skontrolujte.
- Upravte text, väzby a coverage.
- Finalizujte až vtedy, keď je artefakt dôveryhodný.
Disciplína stavov¶
Bežné pracovné stavy sú:
| Badge | Význam |
|---|---|
| new | Nové, neskontrolované položky. |
| draft | Upravené alebo AI-vylepšené položky, ktoré ešte potrebujú revíziu. |
| final | Artefakty, ktoré tím považuje za prijaté. |
| deferred | Stále platné, ale vedome odložené, odovzdané tretej strane alebo ponechané skôr ako aktuálne nerelevantný kontext. |
| ... | Medzistav spravidla pokrývajúci generating, enhancing, building alebo podobnú prácu na pozadí. |
| error | Položka alebo job skončili v chybovom stave. |
| failed | Položka alebo job sa nepodarili úspešne dokončiť. |
Marker bookmarked je samostatný marker, nie životný stav. Použite ho na položky, ku ktorým sa chcete vrátiť neskôr bez straty informácie, či sú new, draft, final alebo deferred.
Farebný význam v aktuálnom UI:
- sivá pre new
- jantárová pre draft
- zelená pre final
- tmavá grafitová s čiernym textom pre deferred
- modrá pre priebežný stav ...
- červená pre error a failed
Finalizácia je dôležitá, pretože ďalšie kroky predpokladajú, že finalizované artefakty sú dostatočne stabilné pre downstream použitie.
Architecture a Feature flowy používajú životné stavy draft, candidate, final a
archived. V jednej implementation môže byť iba jeden final Architecture a v
jednom Epic iba jeden final Feature flow. Feature flow navyše sleduje alignment
stav, aby bolo vidieť, či sú referencie stále up_to_date,
needs_alignment alebo broken_reference.
Delegované Requirements zostávajú viditeľné a vyhľadateľné vrátane sémantického vyhľadávania, ale sú vylúčené z downstream generovania a delivery pomôcok ako generovanie Use Cases, analýzy Ubiquitous Language, gap analysis a implementačné vstupy.
Popup úloh na pozadí¶
Mnohé AI akcie bežia asynchrónne. Typické príklady sú:
- enhancement Requirement-ov alebo Use Cases
- generovanie Epics, Use Cases, architecture, Delivery packageov alebo sád inštrukcií
- analýza Ubiquitous Language
- gap analysis a podobné dlhšie bežiace podporné úlohy
Na sledovanie týchto behov otvorte popup Background jobs kliknutím na AIKOZO logo v hornom paneli.
Popup ukazuje:
- či je úloha vo fronte, beží, je dokončená alebo zlyhala
- kedy bola naposledy aktualizovaná a ako dlho beží
- stručné a praktické zhrnutie pri zlyhaní úlohy; štruktúrovaná diagnostika a interné identifikátory sa nezobrazujú
- odkaz späť na súvisiacu stránku, ak je priama navigácia dostupná
Použite ho vždy, keď spustíte operáciu a stránka sa zavrie okamžite alebo keď artefakt ostáva dlhšie v modrom stave ....
Bilingválne projekty¶
Projekt môže byť nastavený na anglický alebo slovenský používateľský vstup. Requirements a Use Cases podporujú bilingválne ukladanie:
- lokálny používateľský text sa zachováva
- kanonická angličtina ostáva interným referenčným základom pre reasoning a sémantické spracovanie
Pre používateľa to znamená:
- môžete pracovať v jazyku projektu
- AI výstup treba stále dôsledne kontrolovať
- finalizovaný text má byť zrozumiteľný v lokálnom jazyku aj v kanonickej angličtine, ak ide o bilingválny výstup
Pohľad podľa rolí¶
Najdôležitejšie sú tri praktické roly:
- Analyst sa sústreďuje na biznisový zámer, kvalitu Requirements, Use Cases a coverage.
- Builder sa sústreďuje na implementačnú štruktúru, guardrails, Delivery packagey, sady inštrukcií a build execution.
- Manager sa sústreďuje na nastavenie projektu, hranice prístupu, tenant-level viditeľnosť a prevádzkový dohľad.
Ten istý projekt môže plynulo prejsť cez všetky tri roly bez straty traceability.