Documentație portabilă, iterație controlată și dezvoltare software asistată de IA. Când vorbim despre IA în programare, discuția ajunge foarte repede la cod. Cât cod poate genera? Cât de repede poate implementa un feature? Cât de mult ne poate crește productivitatea?
Pentru mine, în rolul de arhitect software, cea mai interesantă schimbare nu a apărut însă în momentul în care IA-ul a început să scrie cod, ci înainte de cod. A apărut în felul în care pot clarifica o idee, pot explora alternative, pot formula cerințe, pot construi context și pot transforma o conversație într-un artefact util pentru echipă.
Folosesc IA-ul ca pe un partener de brainstorming. Nu ca pe o autoritate și nu ca pe un înlocuitor al gândirii tehnice, ci ca pe un interlocutor rapid, disponibil oricând, cu care pot itera pentru a rezolva probleme complexe. Îi dau o idee, primesc o variantă de structură, o modific, o restrâng, o folosesc ca input pentru următorul prompt, apoi repet procesul.
În timp, am observat un efect interesant: IA-ul nu m-a făcut să documentez mai puțin. Din contră, m-a făcut să documentez mai mult, dar într-un mod mai natural și mai util.
Rezultatul nu este doar o conversație salvată într-un chat. Rezultatul este context: specificații, requirements, diagrame, ADR-uri, note de design și planuri de implementare.
În zona aceasta apar câțiva termeni care pot suna ca buzzwords: Async Agile, Vibe Programming sau Vibe Coding. Nu sunt termeni pe care să îi presupunem ca fiind evidenți, mai ales pentru un programator junior.
Prin Async Agile putem înțelege o formă de colaborare Agile în care feedbackul și clarificările nu se întâmplă doar în întâlniri sincrone. În loc ca toate deciziile să fie discutate într-un call, o parte din muncă se mută în documente, comentarii, diagrame și propuneri scrise. Echipa lucrează în același context, dar nu depinde mereu de același moment în calendar.
Explicat simplu: un document bun poate reduce o ședință; o diagramă bună poate evita multe întrebări repetate; un ADR bun poate explica peste șase luni de ce am ales o anumită soluție.
Prin Vibe Programming sau Vibe Coding se înțelege, în general, programarea asistată de IA prin conversație și iterație. Spui ce vrei, primești o propunere, o ajustezi, ceri alternative, testezi, revii cu feedback și continui.
Important este că acest mod de lucru nu înseamnă să lași IA-ul să decidă în locul tău. Cel puțin pentru mine, înseamnă să folosesc IA-ul pentru a produce material de lucru. Decizia, filtrarea și responsabilitatea rămân la om și la echipă.
După această clarificare, nu cred că este util să repetăm obsesiv termenii. Ei descriu doar cadrul. Partea interesantă este practica.
Un proiect software nu este doar o colecție de fișiere sursă. Este un set de decizii, constrângeri, convenții, compromisuri și obiective de business.
Un developer care primește un task nu are nevoie doar de o frază de tipul "implementează checkoutul nou". Are nevoie să înțeleagă de ce se schimbă flow-ul, ce scenarii sunt importante, ce constrângeri există, ce sisteme sunt afectate, ce riscuri apar și cum va fi validată soluția.
Același lucru este valabil și pentru IA.
Dacă îi cerem unui model să implementeze ceva fără context, va umple golurile cu presupuneri. Uneori presupunerile sunt bune. Alteori sunt complet nepotrivite pentru sistemul nostru. IA-ul poate produce rapid o soluție care arată bine, dar care nu respectă arhitectura, convențiile echipei sau realitatea produsului.
De aceea, folosesc IA-ul tot mai mult înainte de implementare. Îl folosesc pentru întrebări precum:
ce nu este clar în această cerință?
ce întrebări ar trebui puse către product owner?
ce variante de arhitectură avem?
ce trade-offuri există între variante?
ce riscuri de securitate, performanță sau mentenanță apar?
Răspunsurile utile nu le las în chat. Le transform în documente.
Una dintre cele mai mari provocări pentru mine a fost să găsesc un format de documentație care să fie flexibil, accesibil și reutilizabil.
Documentația trebuie să fie clară pentru product owner, utilă pentru programator, suficient de precisă pentru arhitect și ușor de folosit ca input pentru IA. În același timp, nu ar trebui să fie captivă într-un singur tool sau într-o singură platformă.
Aici am ajuns să apreciez formatele portabile.
Folosesc Markdown pentru text: specificații, requirements, ADR-uri, note de design. Este simplu, ușor de citit, ușor de modificat și poate sta lângă cod. Poate fi versionat în Git, revizuit în pull request, copiat într-un prompt sau folosit ca input pentru un agent IA.
Folosesc Mermaid pentru diagrame rapide, când vreau să exprim un flow, o secvență, o relație între componente sau o dependență. Avantajul este că diagrama este tot text. Poate fi modificată ușor, comparată în diff și regenerată în mai multe tooluri.
Folosesc și draw.io atunci când am nevoie de diagrame mai vizuale sau mai ușor de consumat într-un context corporate. Se integrează bine în pagini de Confluence, poate fi folosit direct din browser și, foarte important, fișierele .drawio pot fi păstrate ca XML. Asta înseamnă că diagrama nu este doar o imagine finală, ci un artefact editabil, portabil și, cel puțin în principiu, accesibil și pentru tooluri IA.
Nu spun că PowerPoint, Confluence sau alte platforme nu sunt utile. Sunt utile. Problema apare când documentația importantă există doar în formate greu de reutilizat: slide-uri, imagini, pagini protejate de tokenuri corporate sau conținut pe care IA-ul nu îl poate accesa și parsa ușor.
Dacă vrem ca documentația să fie context activ, nu doar arhivă, atunci ea trebuie să circule ușor între oameni, cod și IA.
O structură simplă poate arăta așa:
/docs
/adr
0001-use-event-driven-integration.md
0002-cache-strategy.md
/architecture
context.md
components.md
data-flow.md
/requirements
checkout-flow.md
reporting-module.md
/diagrams
checkout-sequence.mmd
service-dependencies.mmd
domain-overview.drawioNu este o structură spectaculoasă. Tocmai acesta este avantajul. Este simplă, portabilă și ușor de înțeles.
O metaforă care îmi place pentru acest mod de lucru este cea a două mâini care se desenează una pe alta.
În cazul meu, nu este vorba despre desen, ci despre context. Scriu un prompt, IA-ul generează o variantă de răspuns, eu o modific, extrag ce este util, transform rezultatul într-un document, iar documentul devine input pentru următorul prompt.
Promptul generează context. Contextul îmbunătățește următorul prompt.
Aici apare controlul. Nu îi dau IA-ului libertate totală de la început până la final. Îi dau o bucată de context, primesc o propunere, o verific, o adaptez și decid ce merge mai departe. Cu fiecare iterație, reduc ambiguitatea.
Fluxul arată cam așa:
flowchart TD
A[Idee sau problemă] --> B[Prompt inițial]
B --> C[Propunere generată de AI]
C --> D[Revizie umană]
D --> E[Context actualizat în Markdown / diagrame]
E --> F[Prompt mai bun]
F --> C
E --> G[ADR / specificație / plan de implementare]
G --> H[Cod și teste]
Această buclă este foarte utilă pentru idei complexe. Nu trebuie să rezolv totul într-un singur prompt. Pot merge incremental: întâi clarific problema, apoi opțiunile, după aceea riscurile, apoi decizia și, la final, planul de implementare.
IA-ul este rapid, dar direcția rămâne la mine.
Unul dintre lucrurile importante pe care le-am învățat este că outputul IA nu trebuie tratat ca rezultat final. Este un draft. Uneori un draft bun, alteori unul mediocru, alteori unul greșit.
Documentul este locul în care recâștig controlul.
În chat, conversația curge repede și poate deveni greu de urmărit. Într-un fișier Markdown, pot edita. Pot șterge. Pot reorganiza. Pot adăuga constrângeri. Pot formula mai clar o decizie. Pot transforma o idee vagă într-o secțiune coerentă.
Apoi pot folosi acel document ca input pentru următoarea iterație cu IA-ul.
Acesta este un detaliu important: nu folosesc IA-ul doar ca să genereze output, ci și ca să mă ajute să generez următorul input. Practic, îmi construiesc treptat propriul context de lucru.
În acest mod, IA-ul nu conduce procesul. Participă la proces.
Un ADR, Architecture Decision Record, este un document scurt care explică o decizie arhitecturală: context, opțiuni, decizie și consecințe.
IA-ul poate ajuta mult aici. Poate genera un prim draft, poate formula alternative, poate identifica riscuri sau poate propune consecințe pe care nu le-am scris încă explicit.
Dar valoarea reală nu este că IA-ul scrie ADR-ul în locul nostru. Valoarea este că reduce fricțiunea inițială. În loc să pornesc de la o pagină goală, pornesc de la un draft pe care îl pot critica.
Un ADR bun nu trebuie să fie lung. Trebuie să răspundă clar la câteva întrebări:
ce problemă rezolvăm?
ce opțiuni am analizat?
ce decizie am luat?
de ce am ales această variantă?
Dacă aceste răspunsuri sunt într-un fișier text, ele pot fi citite de un developer nou, discutate într-un review, folosite într-un prompt sau reevaluate când sistemul se schimbă.
Nu folosesc IA-ul mereu în același mod. Uneori îl las să exploreze. Alteori îl constrâng.
Pentru brainstorming pot întreba: "propune trei abordări și explică trade-offurile". Pentru validare pot cere: "critică această soluție din perspectiva securității și mentenanței". Pentru implementare pot fi mult mai strict: "respectă acest ADR, nu introduce dependențe noi, păstrează contractul API existent".
Diferența contează. Dacă nu definesc rolul IA-ului, modelul va încerca să fie util în felul lui. Asta poate însemna că inventează detalii, schimbă prea mult sau ignoră constrângeri importante.
Întrebarea bună nu este doar "ce prompt scriu?", ci "ce grad de libertate este potrivit pentru etapa asta?".
Câștigul nu este doar viteză. Pentru mine, câștigul principal este claritatea.
Ideile nu mai rămân doar în discuții informale. Deciziile nu mai sunt doar în mintea câtorva oameni. Contextul nu mai este pierdut între chat, meeting notes și tichete incomplete.
O specificație în Markdown poate fi citită de product owner. Un ADR poate fi discutat de arhitecți și developeri. O diagramă Mermaid sau draw.io poate explica rapid un flow. Același material poate deveni context pentru IA.
Acesta este motivul pentru care portabilitatea contează. Documentația bună nu ar trebui să fie prizonieră într-un tool. Ar trebui să poată circula între oameni, repository, wiki, editor și IA.
IA-ul nu elimină nevoia de arhitectură, documentație sau ownership. Dimpotrivă, le face mai importante.
Când codul devine mai ușor de generat, contextul devine mai valoros. Când implementarea se accelerează, deciziile trebuie să fie mai clare. Când IA-ul poate produce rapid variante, omul trebuie să fie mai explicit în privința criteriilor după care alege.
Pentru mine, modul sănătos de a folosi IA-ul în software development este să îl transform într-un partener de explorare, nu într-un pilot automat. Îl folosesc pentru a genera idei, întrebări, variante și drafturi. Apoi transform ce este valoros în artefacte portabile: Markdown, Mermaid, draw.io, ADR-uri și specificații.
Aceasta este partea care îmi dă control. Nu promptul perfect, nu toolul perfect, nu promisiunea de productivitate magică, ci faptul că la final rămâne un context clar, editabil și reutilizabil.
IA-ul poate genera multe lucruri. Dar noi trebuie să decidem ce merită păstrat, ce merită schimbat și ce merită transformat în decizie.