Duncan Davidson cikke szerint az Architectural Decision Records (ADRs) — azaz az architekturális döntésfeljegyzések — hasznos eszközök mind emberi csapatok, mind kódoló ügynökök számára: rögzítik a jelentős tervezési választásokat, azok kontextusát és az érvényesítést alátámasztó indokokat. Mivel az ügynökök gyakran korlátozott memóriával és csak szűk rálátással érkeznek egy kódbázisra, a dokumentált döntések segítenek megérteni a szándékot anélkül, hogy az ügynöknek ki kellene bogarásznia azt hibajegyekből, chat-archívumokból vagy a kód régészeti vizsgálatából.
Mi a probléma azzal, ha túl részletesek az ADR-ek?
Davidson tapasztalata szerint kétirányú kockázat társul az ADR-ekhez, ha azokat ügynökök alkalmazzák:
-
Az ügynökök hajlamosak az ADR-eket merevebben betartani, mint az emberek; előfordult, hogy egy ügynök fenntartott egy elavult tárolási absztrakciót egy új funkció mellett, mert az ADR még kötelezőnek írta le. Az ügynök ezért nem jelezte a nézeteltérést, hanem egy további réteget adott hozzá, hogy technikailag kompatibilis maradjon a régi döntéssel.
-
Ha az ügynökök módosíthatják vagy pontosíthatják az ADR-eket, gyakori az „overlitigation” jelensége: minden tisztázás újabb módosító bejegyzést szül, és a magyarázatok önmaguk miatt bonyolódnak. Kisebb implementációs részletek szabállyá nőnek, kereszt-hivatkozások ismétlésekkel telítődnek, és az eredmény emberi olvasásra kevésbé alkalmas, nehézkes szöveg lesz.
Gyakorlatias javaslatok: egyszerűség és világos jogosultságok
A megoldás Davidson szerint kettős:
-
Adjunk az ügynököknek egyértelmű jogosultságot arra, hogy kérdőjelezzék meg a hatályos döntéseket, ha azok már nem illeszkednek a feladathoz; és figyeljük azokat a jeleket, amelyek azt mutatják, hogy az ügynök túl mereven ragaszkodik egy ADR-hez.
-
Tartsuk az ADR-eket tömören és olvashatóan, kerüljük a folyamatos módosítások fejezetben történő részletes naplózását — engedjük, hogy a Git tárolja a változásokat.
Davidson saját projektjeiben explicit utasításokat helyezett el az AGENTS.md fájlokban. Ennek egy részlete a cikkből (rövidített formában):
- ADR-ek Markdown fájlokként találhatók a docs/decisions könyvtárban. Az elfogadott ADR-ek kötelező erejűek; a javasolt ADR-ek kontextust adnak, de nem kötelező érvényűek; a felülírt ADR-ek történelmi kontextust képeznek és nem irányítják a jelenlegi munkát.
- Ha egy feladat ellentmond egy elfogadott ADR-nek, álljunk meg és beszéljük meg, hogy a feladat vagy az ADR változzon-e, majd javasoljunk módosítást. Új ADR-eket vagy meglévők frissítését akkor javasoljuk, ha egy tartós termék- vagy architekturális döntés változik.
- Tartsuk az ADR-eket tömören: minden ADR csak a jelenlegi szöveget tartalmazza; a Git története a változásnapló, ezért ne tartsunk külön módosítási naplót az ADR-fejlécekben.
- Amikor egy elfogadott ADR-t érdemben megváltoztatunk, adjunk hozzá vagy frissítsünk egy Updated: dátum sort a Date: után — ez jelzi, hogy van történet, és a Git részletezi azt. Egy felülírt ADR esetén használjunk Superseded-On: dátumot, amely megfelel a Supersedes: mezőnek.
- Egy szabályt egyszer fogalmazzunk meg abban az ADR-ben, amelyik tulajdonosa; más ADR-ekből hivatkozzunk rá ahelyett, hogy újra megismételnénk.
Alkalmazkodás a projektek igényeihez
A szerző megjegyzi, hogy ezek az utasítások projektenként változhatnak: egyes csapatok az immutable (módosíthatatlan) ADR-modellt részesítik előnyben, amelynél a régi ADR-eket felülírják új dokumentumokkal, míg nála a Git története elégséges. A fontos alapelv viszont mindkét esetben azonos: minden hatályos ADR-nek világosan el kell írnia a jelenleg érvényben lévő döntést, és elegendő indoklást kell adnia a döntés alkalmazásához. Az ügynököknek nem kell az összes vita jegyzőkönyvét megkapniuk, elegendő a határozat és az egyértelmű jogosultság arra, hogy leálljanak, ha a döntés nem illeszkedik többé.
Összegzés
ADRs értéket adnak a kódoló ügynököknek azzal, hogy explicit kontextust biztosítanak, de túl részletes, vitákat megőrző dokumentációkkal együtt a haszon elvész. Davidson ajánlása: tartsuk az ADR-eket tömörek és emberileg olvashatóak, használjuk a Gitet történetkezelésre, és a projekt AGENTS.md-jében adjunk világos instrukciókat az ügynökök jogosultságairól és viselkedéséről.
