Anexa B - Template-uri

Șase 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.

# AGENTS.md

## 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 things live
- Services: src/main/java/com/team/service/
- Repositories: src/main/java/com/team/repository/
- DTOs: src/main/java/com/team/dto/
- Tests: src/test/java/com/team/ (parallel package structure)
- Migrations: src/main/resources/db/migration/ (Flyway)

## 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
- Review uman: vreun task prea vag, prea mare, ordonat greșit? Ridică obiecții. Aprobă.

EXECUTE
- Agentul trimite subagenți per task, în context izolat
- Fiecare subagent: citește, implementează, verifică, raportează
- Orchestratorul integrează rezultatele
- Dacă un task eșuează: orchestratorul decide retry / ocolire / escaladare

REVIEW (doi revieweri, în ordine)
- Reviewerul de conformitate cu specificația: implementarea respectă spec-ul?
- Reviewerul de calitate a codului: e cod bun, după standardele echipei?

VERIFY
- Testele noi rulează. Testele existente rulează (ca parte din execute).
- 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.