ADR pentru agenții AI. Cum păstrăm motivele deciziilor de arhitectură

Într-un magazin online există un coș de cumpărături obișnuit și un modul separat pentru rezervarea produselor în ediție limitată. Ambele lucrează cu produse și comenzi, așa că o parte din logică este duplicată.

Un dezvoltator îi cere unui agent AI să modifice modulul de rezervări. Agentul analizează repository-ul, găsește două implementări asemănătoare și propune să le unească. Ar fi mai puțin cod duplicat, tratarea erorilor ar fi comună și întreținerea ar deveni mai simplă.

Doar că echipa analizase deja această variantă cu câteva luni înainte și renunțase la ea.

Coșul obișnuit păstrează produsele alese, dar nu rezervă stocul. În cazul unui produs în ediție limitată, serverul îl rezervă pentru cumpărător timp de câteva minute. Dacă acesta nu finalizează comanda, rezervarea expiră.

Echipa a mutat această logică într-un modul separat ca să nu complice coșul obișnuit și să nu afecteze procesul de cumpărare existent.

Agentul nu știe nimic despre asta. Vede duplicarea și propune un refactoring fără să cunoască motivele deciziei inițiale.

Am putea căuta în istoricul Git, în vechiul tichet sau în comentariile unui pull request. Poate găsim explicația. Sau poate decizia a fost luată într-o ședință și nu a fost documentată nicăieri.

La ce folosește un ADR

Un Architecture Decision Record (ADR) este o înregistrare scurtă a unei decizii de arhitectură. Michael Nygard a descris abordarea încă din 2011, în articolul Documenting Architecture Decisions.

Un ADR păstrează motivele deciziei, alternativele analizate și consecințele. Pentru exemplul nostru, ar fi suficient ceva de genul acesta.

# ADR-014: Modul separat pentru rezervări

Task: SHOP-284
Status: Accepted
Module: DropReservation

## Context
Coșul obișnuit nu rezervă stocul.
Produsele în ediție limitată necesită
rezervare pe server, cu termen de expirare.

## Decision
Păstrăm rezervările separat de Cart.

## Alternatives
Extinderea coșului existent.
Am renunțat deoarece ar afecta cumpărăturile
obișnuite și ar complica tratarea rezervărilor.

## Consequences
O parte din logică va fi duplicată.
Modulele pot evolua independent.

## Revisit
Reanalizăm dacă apare un mecanism
comun de rezervare.

Un ADR nu trebuie să descrie detaliile implementării. Nu are rost să enumerăm clase, metode și protocoale. Acestea există deja în cod și se pot schimba la următorul refactoring. E suficient să păstrăm decizia și motivul ei. Altfel, documentul crește și devine repede depășit.

Nici repovestirea sarcinii nu e necesară. În ADR trebuie să rămână ceea ce codul nu poate spune clar, adică de ce s-a ales tocmai această soluție și de ce s-a renunțat la alternative. Exact acest „de ce” se pierde cel mai des mai târziu.

Cu un astfel de ADR, un dezvoltator sau un agent AI poate înțelege de ce două module asemănătoare au rămas separate. Decizia poate fi revizuită, dar cunoscând constrângerile inițiale.

Abordarea lui Matt Pocock

În repository-ul de skills al lui Matt Pocock există skill-ul domain-modeling, care include și crearea ADR-urilor.

Skill-ul propune crearea unui ADR doar dacă sunt îndeplinite toate cele trei condiții.

1. Ar fi dificil sau costisitor să revenim asupra ei.
2. Fără context, un viitor cititor nu ar înțelege de ce s-a ales această abordare.
3. Au existat alternative reale între care a trebuit să alegem.

Îmi place că Pocock nu propune să documentăm orice detaliu. În ADR-FORMAT.md acceptă chiar și un ADR de un singur paragraf. Dacă motivul poate fi explicat în câteva propoziții, nu trebuie să lungim documentul doar ca să completăm un șablon.

Eu aș ajusta puțin procesul. La finalul fiecărei sarcini merită verificat dacă au apărut decizii care trebuie păstrate, chiar dacă inițial nu erau prevăzute schimbări de arhitectură.

Uneori, o modificare mică duce la o decizie ale cărei consecințe devin vizibile mult mai târziu. De exemplu, corectarea unui bug poate scoate la iveală o limitare a unui modul și obligă echipa să renunțe la mecanismul comun de tratare a erorilor. Astăzi motivul e evident. Peste șase luni, diferența poate părea o greșeală.

Asta nu înseamnă că fiecare bug fix are nevoie de ADR. Dacă nu s-a luat nicio decizie tehnică importantă, încă un document înseamnă doar zgomot.

Când devine ADR-ul definitiv

Un ADR poate fi scris înainte de implementare. Ajută la discutarea arhitecturii și la consemnarea alegerii inițiale. Dar pe parcurs pot apărea constrângeri care schimbă planul.

Eu aș păstra un draft actualizat pe durata sarcinii. În el rămân motivele alegerii, alternativele importante și schimbările semnificative ale planului inițial.

Pentru mine, ADR-ul devine un artefact definitiv atunci când sarcina este încheiată, de regulă după merge.

În acel moment codul a trecut prin review și putem verifica ce decizii au ajuns efectiv în implementare. Agentul pregătește versiunea finală din draft și istoricul lucrului, iar dezvoltatorul îi verifică conținutul.

E mai riscant să generăm ADR-ul de la zero pornind doar de la codul final. Agentul AI poate inventa o explicație convingătoare, deși echipa a ales arhitectura din alte motive.

De aceea e important să verifici singur ADR-ul, chiar dacă agentul l-a scris pe baza draftului. Poate repovesti sarcina în loc să dea motive sau poate descrie convingător un motiv care nu a existat. O explicație greșită încurcă mai mult decât lipsa ei.

Aș păstra documentul final lângă sarcină, măcar ca un comentariu separat în Jira, Linear sau alt sistem de urmărire a sarcinilor.

Dacă agentul nu are acces la acel sistem, ADR-ul ar trebui păstrat și în repository sau pus la dispoziție printr-o integrare. Altfel, la următoarea sarcină nu îl va găsi.

Instrumente existente

Pe lângă skill-ul lui Matt Pocock, există deja instrumente care generează ADR-uri automat.

auto-adr funcționează cu Claude Code. Comanda /adr creează un document din istoricul sesiunii curente. Astfel pot fi păstrate deciziile discutate în timpul dezvoltării, fără a le reconstrui exclusiv din cod.

docflow propune un proces mai formal. Include skills pentru crearea ADR-urilor, gestionarea sarcinilor și verificarea documentelor la finalizarea lucrului.

Andrew Connell descrie un alt exemplu în Architecture Decision Records as Long-Term Memory for an AI Coding Agent.

După câteva luni de lucru cu Claude Code, proiectul lui avea 141 de ADR-uri. El a adăugat o regulă prin care agentul propune înregistrarea deciziilor importante după finalizarea unui plan, iar autorul le aprobă.

Connell păstrează separat regulile proiectului, specificațiile și ADR-urile. Regulile îi spun agentului cum să lucreze, specificațiile descriu cerințele, iar ADR-urile păstrează motivele deciziilor de arhitectură.

La modificarea codului vechi, agentul poate consulta aceste înregistrări în loc să propună din nou variante respinse anterior.

Formatul și regulile de creare a ADR-urilor trebuie totuși adaptate echipei. Un skill universal cu greu poate acoperi felul în care lucrează toate proiectele.

Cum se poate configura

Pentru început nu e nevoie de un instrument separat. Ajunge o regulă scurtă în AGENTS.md sau CLAUDE.md, pe care agentul o citește în fiecare sesiune. Am scris despre astfel de instrucțiuni în articolul despre AGENTS.md pentru Codex și Claude Code.

## ADR

În timpul sarcinii, ține un draft al deciziilor
în docs/adr/drafts/<task-id>.md.
Notează varianta aleasă,
alternativele respinse și motivul.

Înainte de a încheia sarcina, verifică trei condiții.
1. Decizia este costisitoare sau greu de schimbat.
2. Fără context, nu ar fi clar de ce s-a făcut așa.
3. Au existat alternative reale.

Dacă toate trei sunt îndeplinite, pregătește un ADR final
din draft și din istoricul sarcinii.
Nu repovesti sarcina, explică motivele deciziei.
Nu inventa motive care nu au apărut în discuție.
Nu salva ADR-ul fără confirmarea mea.
Dacă condițiile nu sunt îndeplinite, șterge draftul.

Unde păstrăm înregistrarea finală depinde de ce poate accesa agentul. Dacă lucrează cu Jira sau Linear printr-o integrare, ADR-ul poate fi un comentariu la sarcină. Dacă nu, e mai comod un folder docs/adr/ în repository, cu un număr și un nume scurt în numele fișierului, de exemplu 0014-drop-reservation.md. Agentul găsește apoi înregistrările printr-o căutare obișnuită în cod, iar în sarcină rămâne un link către fișier.

Regula în sine e bine să rămână scurtă. Șablonul ADR poate sta într-un fișier separat sau într-un skill și se încarcă doar când e nevoie de o înregistrare. Altfel instrucțiunile pentru agent cresc mai repede decât deciziile.

Concluzie

Înainte de o sarcină, pregătim cu grijă contextul pentru agentul AI, adică cerințe, specificații, documentație și părțile relevante din repository. După finalizare, motivele multor decizii rămân doar în istoricul sesiunii.

Un ADR păstrează această informație într-o notă scurtă. Draftul este actualizat în timpul dezvoltării, versiunea finală este verificată după merge și rămâne atașată sarcinii.

Poate că majoritatea acestor înregistrări nu vor fi citite niciodată. Dar când, peste un an, cineva va întreba de ce două module asemănătoare nu au fost unite, e mai simplu să citească un ADR decât să reconstituie o discuție veche.