Anexa B - Template-uri

Nouă template-uri de copiat și lipit, la care se face referire pe tot parcursul manualului. Toate sunt puncte de plecare; adaptează-le pentru echipa ta.

Template-urile B.1 și B.2 rămân integral în engleză: sunt artefacte pe care le consumă agentul, iar prompturile se scriu în engleză.

B.1 Promptul de architecture review

Analyze the architecture of this codebase. Produce a structured architecture review document covering:

1. Purpose. What does this service do? Who uses it? What business problem does it solve?
2. Top-level structure. Major modules, packages, or folders. One paragraph per major component.
3. Data model. Primary entities, relationships, persistence. Cite specific files and line numbers.
4. Request flows. For the three most important external entry points, trace from entry to persistence. Cite files and lines at each step.
5. Cross-cutting concerns. Authentication, authorization, logging, error handling, configuration. Where do they live?
6. Dependencies. External services, databases, message brokers, third-party APIs.
7. Test posture. Test structure, coverage, gaps.
8. Build and deployment. Cite the configuration files.
9. Risks and unknowns. Fragile code, inconsistent conventions, deprecated dependencies, unresolved patterns.

Cite specific files and line numbers throughout. Where the codebase is ambiguous, say so explicitly. Where you encounter patterns the team should formalize, suggest the convention.

B.2 Scheletul AGENTS.md

Template-ul funcționează fie ca AGENTS.md (standardul neutru față de vendor), fie ca CLAUDE.md (varianta Claude Code). Numele fișierului diferă de la agent la agent; formatul markdown, nu. Ține-l pe la o sută de linii; harta structurii stă în docs/, nu aici.

# AGENTS.md

Precedence: the task prompt wins over this file; this file wins over any skill.

## Forbidden patterns
- Never construct SQL by string concatenation. Use bound parameters. (Reason: SQL injection.)
- Never log PII fields. (Reason: data minimization compliance.)
- Never roll your own cryptography. Use the team's approved crypto wrapper. (Reason: AES-CBC with hardcoded IV shipped to production in 2024; we are not doing that again.)
- Never modify migration history. Migrations are append-only.

## Mistake journal
- 2026-03-03: agent generated JPQL query that bypassed the multi-tenant filter. Fix: queries extend MultiTenantQueryBuilder base class which enforces tenant filtering. Rule added.

## Conventions
- Constructor injection only, not field injection.
- @Transactional only on service methods that mutate state.
- Repositories extend BaseRepository<Entity>.
- DTOs at controller boundary use Bean Validation.

## Build and test
- Build: mvn clean verify
- Run tests: mvn test
- Run linting: mvn spotless:check
- Run security scan: mvn dependency-check:check

## Where the map lives
- Repository layout and module map: docs/architecture.md (read before touching an unfamiliar module)

## Domain glossary
- "Customer" = end user. "Counterparty" = corporate client.
- "Transfer" = intra-bank or inter-bank. "Wire" = inter-bank only.
- "Hold" = short-term reservation. "Block" = long-term legal restriction.

B.3 Checklist-ul buclei în șase faze (one-pager)

RESEARCH
- Agentul produce nota de research (2-4 pagini)
- Nota numește: fișierele de atins, convențiile de urmat, riscurile, întrebările deschise
- Review uman: se potrivește cu modelul meu mental despre munca asta?

PLAN
- Agentul produce un plan la nivel de fișier, fiecare task de 2-5 minute
- Planul numește schimbările de teste pentru orice schimbare de cod
- Planul spune ce înseamnă „gata” pentru întreaga modificare, nu doar per task
- Review uman: vreun task prea vag, prea mare, ordonat greșit? Ridică obiecții. Aprobă.

EXECUTE
- Gate de împărțire: subagenți în paralel doar pentru fișiere sau module independente; un singur scriitor per fișier
- Fork pe workeri (moștenesc istoricul orchestratorului); izolare pe revieweri (context proaspăt)
- Bloc de autonomie: termină task-ul înainte să închei tura; fără confirmări pentru acțiuni reversibile
- Bloc de scop: doar fișierele numite de plan; oprește-te și raportează pentru orice altceva
- Agentul trimite subagenți per task, în context izolat
- Fiecare subagent: citește, implementează, verifică, raportează; ține fișierul de note de implementare
- Orchestratorul integrează rezultatele
- Dacă un task eșuează: orchestratorul decide retry / ocolire / escaladare

REVIEW (doi revieweri, în ordine; rundele plafonate)
- Reviewerul de conformitate cu specificația: implementarea respectă spec-ul?
- Reviewerul de corectitudine: ce e greșit, după standardele echipei? Nu vede niciodată verdictele primului
- Executorul acceptă sau respinge fiecare constatare; urmărește rata de reparare, nu acuratețea reviewerului
- Plafon la trei-patru runde; rundele târzii redeschid muncă tranșată

VERIFY
- Testele noi rulează. Testele existente rulează (ca parte din execute).
- Setul de teste held-out pe care agentul nu-l vede rulează aici, scris din intenție
- Istoric de git sigilat, rețea oprită cât rulează verify
- Hook-ul blochează editările la configurația de lint și de teste și commit --no-verify
- Test picat: agentul explică de ce înainte să aibă voie să repare
- Pentru UI: Playwright cu accessibility tree, nu pixeli.
- Niciun „done” fără dovezi din teste.

SHIP
- Mesaj de commit structurat + push + PR cu descriere structurată
- Revieweri etichetați conform CODEOWNERS
- Tichetul Jira legat e actualizat; Slack e notificat
- Pull request-ul trece prin review-ul normal al echipei

B.4 Fișa de punctare a kill signals

Pentru fiecare codebase, punctează fiecare semnal: 0 (semnal absent) / 0.5 (parțial) / 1 (semnal prezent).

Semnalul 1 - Fără teste
- 0: > 70% line coverage ȘI testele rulează la fiecare commit
- 0.5: 30-70% coverage SAU testele există, dar nu rulează de rutină
- 1: < 30% coverage SAU nicio suită de teste automate

Semnalul 2 - Fără documentație
- 0: document de arhitectură la zi + comentarii în cod + decision records
- 0.5: documentație parțială, posibil învechită
- 1: nicio privire de ansamblu arhitecturală; doar autorul original știe

Semnalul 3 - Cuplare strânsă
- 0: granițe clare între module; modulele pot fi schimbate izolat
- 0.5: ceva cuplare; developerii cu experiență se descurcă, dar noii veniți se chinuie
- 1: ghem; editezi un fișier, se sparg alte trei

Semnalul 4 - Reguli de business împrăștiate
- 0: o singură sursă de adevăr pentru fiecare regulă de business
- 0.5: ceva duplicare, dar documentată
- 1: aceeași regulă exprimată în 3+ locuri, adesea inconsistent

Semnalul 5 - Constrângeri de reglementare
- 0: controale standard; mecanismul de audit existent acoperă schimbările
- 0.5: domeniu reglementat, dar echipa are workflow-ul pus la punct
- 1: controale stricte + echipa nu are un workflow integrat; matricele de sign-off lipsesc

Semnalul 6 - Echipa nu poate evalua output-ul
- 0: echipa are expertiză senior pentru fiecare domeniu din codebase
- 0.5: expertiza senior există, dar e fragilă (o singură persoană, posibil indisponibilă)
- 1: echipa nu poate evalua fiabil output-ul agentului într-un anumit domeniu

Semnalul 7 - Potrivirea model-context
- 0: codebase-ul e într-un limbaj/framework popular, cu amprentă publică substanțială
- 0.5: nișă, dar suficient de documentată cât agentul să aibă ceva context
- 1: DSL proprietar, framework intern sau limbaj rar, fără corpus public

Semnalul 8 - Viteza schimbării
- 0: framework-ul și dependențele sunt stabile; nicio migrare majoră în desfășurare
- 0.5: churn de versiuni minore în curs, dar echipa ține situația sub control
- 1: migrare majoră la jumătate; codebase-ul stă călare pe versiunea veche și pe cea nouă

Rotunjește la cel mai apropiat întreg.

Semaforul:
- 0-1: VERDE (lucrul condus de agent e potrivit)
- 2-3: GALBEN (condus de om, cu sprijinul agentului)
- 4+: ROȘU (repară întâi codebase-ul)

Semnalul 6 cântărește mai greu: orice codebase cu 1 la semnalul 6 e ROȘU pentru munca afectată, indiferent de restul semnalelor. Ține agentul departe de munca aceea până când golul de competență e închis.

B.5 Calendarul de adopție în 90 de zile (one-pager)

CHAMPION (inginerul cu curiozitate)

Luna 1
- Săptămâna 1: instalează agentul. Architecture review pe un codebase familiar. Dă commit artefactului.
- Săptămâna 2: schițează primul AGENTS.md al echipei, < 50 de linii.
- Săptămânile 3-4: rulează bucla în șase faze pe trei feature-uri mici.

Luna 2: rulează bucla în șase faze pe trei feature-uri medii. Atrage alți ingineri în faze individuale.

Luna 3: predă rolul de champion unui succesor. AGENTS.md e acum al echipei, nu al championului.

---

LEAD (decide ce proiecte primesc agentul)

Săptămâna 1: clasifică top 5 proiecte după cele 8 kill signals. Pune clasificările pe hârtie. Împărtășește-le echipei.

Săptămânile 2-4: pentru câte un proiect din fiecare culoare, documentează ce ar trebui să se schimbe ca să-l muți.

Luna 2: urmărește metricile. Cycle time, rată de defecte, timp de reviewer.

Luna 3: prezintă rezultatele. Date oneste. Recomandă ajustări.

---

MANAGER (deține bugetul, achizițiile, angajările)

Lunile 1-2: protejează echipa. Fără metrici de productivitate per inginer, fără
proiecții de ROI, fără benchmark-uri de vendor deocamdată. Practica abia se construiește.

Zilele 61-67: preia handoff-ul de la Champion/Lead. Verifică dacă metricile din
dashboard sunt reale (ponderea PR-urilor atinse de agent, cycle time vs baseline, rata defectelor vs baseline).

Zilele 68-74: închide decizia de achiziție seat-vs-enterprise cu grila din
Anexa A. Potrivește nivelul cu utilizarea, nu cu uniformitatea.

Zilele 75-81: one-pager-ul de guvernanță (hook-uri, sandbox, secrete, telemetrie).
Championul schițează; managerul editează și semnează.

Zilele 82-90: update către leadership - două fraze și un număr. Apără
metrica operațională; lasă veniturile în seama cui deține veniturile. Treci la
o cadență trimestrială.

---

ARCUL GRASSROOTS (pentru echipe care nu au toate cele trei roluri)

Luna 1: championul folosește agentul doar pentru productivitatea personală. Fără anunțuri.
Luna 2: championul își pune rezultatele pe hârtie. Le prezintă în ședința de echipă.
Luna 3: un coleg întreabă cum. Championul îl învață. Demo-ul în doi ingineri invită lead-ul.
Lunile 4-6: lead-ul recrutează managerul cu baza de dovezi a celor doi ingineri.

De două ori mai lung decât arcul ideal; merge în companii care nu sunt încă pregătite pentru cel ideal.

B.6 Contractul outer-loop (one-pager)

Înainte de orice rulare nesupravegheată, completează fiecare linie. O linie goală înseamnă că bucla nu e gata.

MUNCA
- Queue: ______ (fișier sau listă de issue-uri în repo; câte o unitate mică, similară, reversibilă per element)
- Eligibilitate: codebase VERDE (scor B.4 0-1) / fiecare unitate verificabilă de mașină / fiecare unitate revertibilă

CONDIȚIA DE OPRIRE (evaluabilă de mașină; bucla se oprește singură)
- Done când: ______ (queue gol / suita verde / N unități gata de review)
- Buget: max ______ tokeni sau $______ sau ______ iterații sau ______ ore - ce se atinge primul
- Regula de eșec: aceeași unitate eșuează de două ori -> sari peste ea și marcheaz-o; trei unități sărite -> oprește tot

FIECARE ITERAȚIE
- Context proaspăt; starea se citește din queue + jurnalul din repo, nu din istoricul sesiunii
- O unitate per iterație; termin-o sau notează în jurnal de ce nu - nimic lăsat aplicat pe jumătate
- Gate: ______ (teste / lint / typecheck / build) rulează în afara razei agentului (CI sau hook)
- Reguli de deny: agentul nu poate edita configurația de teste, configurația de lint, workflow-ul de CI, regulile de hook sau marker-ele de done din jurnal

IZOLARE
- Worktree și branch propriu; niciodată branch-ul default
- Sandbox pornit; fără credențiale de producție în environment; rețea oprită sau pe allowlist

REVIEW-UL DE DIMINEAȚĂ (pragul uman minim)
- Fiecare PR e citit pentru corectitudine de business și potrivire arhitecturală - nu bifat din ochi
- Verificarea de kill înainte de relansare: diff-uri care oscilează? buget consumat, dar queue-ul nu e mai scurt?
  același eșec a treia oară? gate-ul a fost atins?
  Orice „da” -> nu relansa. Citește jurnalul, repară întâi cauza.

B.7 Igiena contextului (one-pager)

ÎNCĂRCARE
- Doar context relevant pentru task; tot ce e încărcat concurează cu raționamentul
- Pointere, nu payload-uri: linkuiește documentul de arhitectură, numește fișierele, nu le lipi
- AGENTS.md sub 200 de linii - stratul mereu-încărcat e spațiul cel mai scump

SESIUNE
- O unitate de muncă per sesiune
- Pornește curat la fiecare unitate; nu duce istoricul unui task terminat în următorul
- Starea durabilă trăiește în fișiere - nota de research, planul, jurnalul - ținute în repo prin commit-uri

DE URMĂRIT (semne de contaminare)
- Agentul răspunde din nou la o întrebare rezolvată deja în sesiune
- Agentul citează o versiune învechită a unui fișier pe care l-a editat mai devreme
- Agentul uită o constrângere pe care o respecta mai devreme
- Calitatea editărilor scade târziu într-o sesiune lungă

CÂND E CONTAMINAT
- Nu te certa cu sesiunea - nu poți readuce o fereastră la coerență prin dispută
- Dă commit la starea durabilă -> încheie sesiunea -> pornește de la zero
- Sesiunea proaspătă recitește progresul din repo, fără zgomot

COMPACTARE
- O predare, nu o continuare - rezumarea pierde detalii (măsurat)
- Preferă mascarea output-urilor vechi de tool-uri în locul rezumării; consolidează înainte să continui
- Istoricul e append-only pe Fable 5.1 - nu edita niciodată turele anterioare; încheie și repornește
- Input-ul din cache e ieftin; a compacta devreme ca să economisești e, de regulă, schimbul greșit
- Dă-i compactorului o listă de păstrat: planul, întrebările deschise, devierile, comenzile care au mers
- Tratează-o ca pe predarea muncii unui inginer nou
- Tot ce contează și nu e într-un fișier sau pe lista de păstrat până atunci s-a pierdut

SUBAGENȚI
- Izolează fiecare task în propriul context; confuzia unui task nu ajunge niciodată la următorul
- Citește rezumatele de predare cu scepticismul cu care ai citi standup-ul unui junior

B.8 Ordinea de citire a unui diff de agent (one-pager)

ÎNAINTE DE COD
- Diff-stat-ul raportat la plan, întâi - citește forma înainte de o linie de cod
- Schimbarea atinge ce a numit cererea, și doar atât?
- Fișierele pe care planul nu le-a numit niciodată sunt primul semnal - un diff care depășește scopul a decis ceva în locul tău

ÎNTÂI TESTELE
- Citește ce afirmă, nu dacă trec - verdele e semnalul pe care îl ai deja
- Aserțiunea trebuie să vină din intenție, nu din implementare
- Un test scris pornind de la cod va fi de acord cu codul

GRANIȚE
- Verifică regulile pe care echipa le-a scris - pattern-urile interzise din AGENTS.md, convențiile de strat
- Agentul încalcă o convenție sigur pe el și în stil fluent
- O trecere de graniță arată curat pe pagină - stilul fluent o ascunde de cititul pe stil

NUME NOI
- Dă grep pe fiecare API, funcție sau cheie de config pe care diff-ul o introduce și pe care n-o recunoști
- Zero rezultate în codebase sau în dependențe -> numele s-ar putea să nu existe
- Apelul inventat se citește la fel de plauzibil ca cel real

ABIA APOI LINIE CU LINIE
- Stratul mecanic pe care agenții de review l-au măturat deja - conformitatea cu spec-ul, calitatea codului
- Nu le repeta trecerea - cheltuiește minutele pe care ți le-au cumpărat
- Minutele merg unde agenții nu pot: corectitudinea de business și potrivirea arhitecturală

CALIBRARE
- Fluența nu e corectitudine
- Un bug de agent arată ca acel cod pe care un inginer bun l-ar scrie pentru un task ușor diferit
- Citirea umană devine mai scurtă și mai ascuțită pe măsură ce tooling-ul se îmbunătățește - niciodată sărită

QUIZ-UL
- Înainte să aprobi, pune agentul să-ți dea un quiz despre modificare - margini, ownership, moduri de eșec
- Poți răspunde -> aprobarea înseamnă ceva; nu poți -> ăla era rubber-stamping
- Un minut la gate bate descoperirea degradării în producție

B.9 Checklist-ul de migrare între modele (one-pager)

ÎNAINTE DE SCHIMBARE
- Baseline: cinci task-uri reprezentative pe modelul curent; păstrează costul, rezultatul, nivelul de effort folosit
- Citește ghidul vendorului pentru modelul nou - fiecare generație pensionează o parte din harness

EFFORT
- Sweep de effort per tip de task pe modelul nou (low / medium / high); alege per fază, nu per sesiune
- Numele nivelurilor de effort nu se transferă între modele - „high” de trimestrul trecut e o ghicitoare acum

PROMPTURI ȘI FIȘIERE DE INSTRUCȚIUNI
- Scoate majusculele emfatice și liniile „verify your work” - scrise pentru un model care avea nevoie de ele
- Scoate parametrii de sampling și de dirijare pe care modelul nou îi respinge: temperature, prefill, forced tool choice
- Nu cere niciodată raționamentul modelului în răspuns - o categorie de refuz pe Fable 5
- Auditează skill-urile pentru supra-prescriere: o listă de pași de care avea nevoie modelul vechi e o cușcă pentru cel nou
- Păstrează linia de precedență (B.2); recitește AGENTS.md pentru reguli pe care modelul nou nu le mai încalcă

TOOL-URI
- Retestează fiecare schemă de tool custom cu decodare strictă pornită; caută câmpuri inventate
- Renumără tool-urile vizibile; amână tot ce te lasă harness-ul nou să amâni

ISTORIC
- Ține istoricul conversației append-only; nu edita și nu reordona niciodată turele anterioare
- Reverifică setările de compactare - schimbul de cost s-a mutat odată cu prețul input-ului din cache

DUPĂ SCHIMBARE
- Rerulează cele cinci task-uri de baseline; compară costul și rezultatul per fază
- Codebase verde care dă rezultate galbene -> checklist-ul ăsta înainte de kill signals (Capitolul 8)