RFC vs ADR: az egyik beszélgetés, a másik nyugta

Képzeljünk el egy repository-t, benne egy adr/ mappával és 14 fájllal. Tizenegy közülük hat-tizenkét oldalas, tele nyitott kérdésekkel, beillesztett komment-szálakkal és "Discussion" című fejezetekkel. Ha megkérdezzük, mi lett végül eldöntve bármelyikben, senki sem tudja megmondani.

A mappa az egyik dokumentumtípusról kapta a nevét, a tartalma viszont a másik. Elég gyakori felállás, és nem puszta elnevezési szőrszálhasogatás: a két dokumentum más kérdésre válaszol, más az életútja, és másképp romlik el.

Írtam már arról, hogy az ADR csak akkor ér valamit, ha formálja a döntést, és arról is, hogy az AI-generált ADR utólag racionalizál. Ez a poszt a határvonalról szól: hol ér véget az RFC, hol kezdődik az ADR, és mit csináljunk, ha csak az egyikre van energiánk.

Röviden

Az RFC (Request for Comments) egy még nyitott javaslat. A döntés előtt írjuk, hogy összegyűjtsük az ellenvetéseket, felszínre hozzuk az alternatívákat, és az érintetteket egy asztalhoz ültessük. A név az internetes szabványosítási folyamatból ered, a cégek később átvették belső javaslatokra; közismert nyilvános példa a Rust projekt. Életciklusa nagyjából: draft, review, elfogadva vagy elutasítva.

Az ADR (Architecture Decision Record, Michael Nygard tette népszerűvé) egy már meghozott döntés feljegyzése. Azért írjuk, hogy aki két év múlva csatlakozik, fél oldalból megértse, miért néz ki így a rendszer. Van benne kontextus, döntés és következmények, és elfogadás után nem szerkesztjük. Ha a döntés megváltozik, új ADR születik, ami felváltja (supersede-olja) a réginek, így a lánc végigolvasható marad.

	RFC	ADR
Kérdés	Mit csináljunk?	Mit döntöttünk, és miért?
Időpont	A döntés előtt	A döntéskor, utána megőrizve
Hossz	Gyakran több oldal, nyitott kérdésekkel	Egy oldal vagy kevesebb
Közönség	Akik befolyásolhatják a kimenetet	Akik együtt élnek a kimenettel
Életciklus	Draft, review, elfogadva vagy elutasítva	Proposed, accepted, superseded
Változtathatóság	A review alatt módosul	Elfogadás után immutábilis

Ha csak egyet jegyzünk meg: az RFC egy beszélgetés, az ADR egy nyugta.

Egy döntés, mindkét dokumentum

Az elvont definíciókra könnyű bólogatni, nézzünk inkább egy konkrét esetet.

Egy termék rendeléseit MySQL adatbázis tárolja. Három csapat nyúl hozzá: az orders csapat birtokolja a sémát, a billing számlákat olvas és ír bele, a reporting pedig nehéz analitikai lekérdezéseket futtat egy replikán. Az orders csapat PostgreSQL-re szeretne váltani, főleg a jobb JSON-kezelés és a részleges indexek miatt, amiket azonnal használnának.

Az RFC

Egy közös adatbázis költöztetése drága, nehezen visszafordítható, és három csapatot érint. Ez tipikusan RFC-terep. Az orders csapat által körbeküldött dokumentum nagyjából így nézhet ki:

# RFC: Az orders adatbázis költöztetése MySQL-ről PostgreSQL-re

Státusz: Draft · Szerző: orders csapat · Review határidő: 2026-11-14

## Probléma
A rendelések metaadatai JSON szövegként ülnek egy TEXT oszlopban; minden
szűrés teljes scan. A Q1-re tervezett három feature-nek kell ez a szűrés.

## Opciók
A. Maradunk MySQL-en, az oszlopot natív JSON típusra migráljuk
B. Költözés PostgreSQL-re, átmeneti dual-write időszakkal
C. Költözés PostgreSQL-re, change-data-capture alapú átkapcsolással

## Nyitott kérdések
- Támaszkodik-e a reporting MySQL-specifikus SQL-re? (reporting csapat válaszol)
- Elbír-e a billing 10 perc csak olvasható állapotot az átkapcsoláskor? (billing válaszol)
- Ki viszi az üzemeltetési runbookot az első három hónapban?

## Költségek, amiket ismerünk / amiket nem
...

Érdemes észrevenni, mi van benne: megválaszolatlan kérdések, mellettük névvel, valóban nyitott opciók és egy review határidő. Itt szabad bizonytalannak lenni.

A review során olyan dolgok derülnek ki, amiket az orders csapat nem tudhatott. A reporting nagyjából negyven lekérdezésben használ MySQL-specifikus függvényt, ezért a B opció dual-write időszaka megduplázná az átírási munkájukat. A billing szerint a tíz perc csak olvasható állapot rendben van, de a hó végi zárás idején nem. Valaki rámutat, hogy az A opció a JSON-problémát töredék munkával megoldja, a részleges indexeket viszont nem adja.

Ez a visszajelzés az RFC létezésének teljes értelme. Ha az orders csapat egyszerűen eldönti és bejelenti, a negyven lekérdezést a reporting csak élesben találja meg.

Az ADR

Két hét múlva lezárul a review. A csapat a C opciót választja, az átkapcsolást hó végi zároláson kívülre ütemezve. Az RFC elvégezte a dolgát, és amit a szervezetnek meg kell őriznie, az ennél sokkal kevesebb:

# ADR-014: Az orders adatbázis PostgreSQL-re költözik CDC átkapcsolással

Státusz: Accepted · 2026-11-18 · Felváltja: ADR-003 (MySQL mint elsődleges tároló)

## Kontextus
A rendelések metaadatainak szűréséhez JSON-lekérdezés és részleges index kell.
Az adatbázist három csapat használja (orders, billing, reporting).
A billing hó végi zároláson kívül elvisel 10 perc csak olvasható állapotot.

## Döntés
Change-data-capture-rel migrálunk PostgreSQL-re, az átkapcsolás a hó végi
zárást követő első héten történik. A reporting az átkapcsolás előtt írja át
a MySQL-specifikus lekérdezéseit, nem utána.

## Következmények
- A migráció idejére eggyel több adatbázis-motort üzemeltetünk.
- A reporting ~40 lekérdezést ír át; beütemezve a Q1-ükbe.
- Visszalépés lehetséges, amíg a CDC stream le nincs állítva (lásd RFC-021).

Rövid, a döntést rögzíti a vita helyett, és visszalinkel az RFC-re annak, aki a teljes történetet akarja. Két év múlva, amikor egy új mérnök megkérdezi, miért PostgreSQL fut, ha a régebbi service-ek MySQL-en vannak, ez az oldal egy perc alatt válaszol. A negyven kommentes RFC egy délutánt vinne el, és a kimenetet akkor sem árulná el egyértelműen.

Figyeljük meg a Felváltja: ADR-003 sort is. A régi ADR-t nem szerkesztjük és nem töröljük. Továbbra is azt mondja, hogy "MySQL mint elsődleges tároló", és ez igaz volt az írása idején. A történetet a lánc meséli el.

Amikor elég egy dokumentum

Nem minden döntéshez kell mindkettő. Nagyjából ezt a szabályt követem:

• Kicsi, lokális, visszafordítható: elég egy ADR, vagy akár egy jól megírt commit message.
• Csapatokon átível, drága vagy nehezen visszafordítható, sok érintett: előbb RFC. A kimenete egy ADR, néha több, ha az RFC döntéscsomagot tárgyalt.
• Olcsón visszacsinálható, magától értetődő, vagy konvenció már lefedi: egyik sem.

Az alsó végére példa az API-verziózás. Egy csapat birtokol egy belső API-t, amit csak a saját frontendje használ. El kell dönteniük, hogyan verziózzák a törő változásokat: /v2/ előtaggal vagy headerrel. A csapaton kívül senkit nem érdekel, és ha rosszul választanak, egy sprint alatt átállhatnak, mert mindkét oldalt ők kezelik. Egy tízsoros ADR, amit abban a pull requestben írnak meg, amelyik az első /v2/ endpointot bevezeti, pont megfelelő méret.

Most változtassunk meg egy tényt: ugyanez az API nyilvános lesz, külső ügyfelekkel, akik egyszer integrálnak, és ritkán frissítenek. A verziózási séma innentől évekig betartandó ígéret, a supportnak magyaráznia kell, a gateway csapatnak pedig véleménye van az útvonalválasztásról. Ugyanaz a kérdés, mégis más a tévedés ára. Ide RFC kell, az ADR pedig utána jön.

A dokumentum mérete a tévedés költségéhez igazodjon, ne ahhoz, mennyire fontos a téma a szerzőnek.

A harmadik kategória is számít. Dátumkönyvtár választása, csomag átnevezése vagy egy linter kiválasztása nem ér meg egyik dokumentumot sem. Ha a döntés egy délután alatt visszacsinálható, az írás a drágább megoldás.

Miért mosódik össze mégis?

Ha a különbség ennyire tiszta, miért tűnik el a határ olyan sok csapatnál? Tapasztalatom szerint öt ok tér vissza újra és újra.

A sablonok egyformák. Kontextus, opciók, döntés. Egy ADR- és egy RFC-sablon fejezetei nagyrészt egyeznek, ezért könnyű az egyiket a másikra használni. Ráadásul egyes ADR-sablonok (például a MADR) tartalmaznak "considered options" és "pros and cons" részeket, amitől az ADR vitára hívogat.

Az ADR lesz a vitafórum. Az ADR-t beemelő pull requestben olvassák el végre a javaslatot, ezért a vita a review kommentekben zajlik. A merge egy döntést rögzít, az érdemi érvelés viszont egy PR-szálban marad, amit senki sem fog megtalálni. Maga az ADR pedig egyoldalú pitchnek hat, hiszen az ellenvetéseket máshol rendezték.

Az RFC-t nem zárják le. A review időszak lejár, a dokumentum pedig örökre "Draft" marad. Mindenki azt valósítja meg, amit a leghangosabb komment javasolt. Nincs elfogadott státusz, nincs feljegyzett kimenet, fél év múlva pedig egy új vitában mindkét fél az RFC-re hivatkozik. Ez a hiba termeli az eleji adr/ mappát: senki nem zárja le a kört, ezért a nyitott dokumentumok oda gyűlnek, ahová a döntéseknek kellene.

Ugyanarra más nevek. A Google-stílusú csapatok "design doc"-ot írnak, mások "proposal"-t vagy "tech spec"-et, és vannak RFC-k, amik valójában spec-ek. Ahol minden cég a saját szótárát használja, az emberek a korábbi munkahelyük szokásait viszik magukkal, és a címkék elveszítik a jelentésüket.

Az AI-generált dokumentumok mindkettő akar lenni. Ha ADR-t kérünk egy modelltől, gyakran hibridet kapunk: hosszú opcióelemzést, egy döntést és egy "status: accepted" sort, mind egy menetben. Úgy olvasható, mint egy review nélkül maradt RFC és egy döntés nélküli ADR. Ahogy az AI-generált ADR-ekről szóló posztban is írtam, ami hiányzik, az azok beszélgetése, akik vitatkoztak volna.

Egy folyamat, ami szétválasztja őket

Nehézkes governance nem kell hozzá, a legtöbb csapatnak ennyi elég:

1. Döntsük el, kell-e RFC. Használjuk a fenti hármas szabályt. A legtöbb döntéshez nem kell.
2. Ha kell, nyissuk meg határidővel és megnevezett reviewerekkel. A kérdéseknek legyen gazdájuk. A határidő nélküli RFC csak egy kívánság.
3. Zárjuk le kifejezetten. A szerző elfogadottra, elutasítottra vagy visszavontra állítja a státuszt, és ír egy mondatot az okáról. Ezt a lépést hagyják ki a csapatok.
4. A kimenetből írjuk meg az ADR-t. Maradjon egy oldalnál rövidebb. Az ADR linkeljen az RFC-re, az RFC fejlécébe pedig kerüljön be az ADR száma. Így az olvasó bármelyik irányba el tud indulni.
5. Ha a döntés változik, új ADR készül, ami felváltja a réginek. A történelmet ne írjuk át.

Ha lehet, tartsuk őket külön helyen: rfcs/ és adr/ a repositoryban, vagy két szekció a wikiben. Meglepően sok félreértést megelőz már maga a mappastruktúra.

Jelek, hogy rossz formát használtok

Néhány tünet, amire érdemes figyelni:

• Az ADR-jeitek hosszabbak két oldalnál, vagy van bennük "Discussion" fejezet.
• Nyitott kérdéseket találtok egy "Accepted" státuszú ADR-ben.
• Az RFC kimenetére senki sem tud rámutatni a kommentek végigolvasása nélkül.
• A döntések az RFC komment-szálában születnek, a dokumentumot pedig soha nem frissítik.
• Az RFC-knek nincs határidejük, nincsenek megnevezett reviewereik, és egy hónapnál régebben vannak draftban.
• Az ADR azután készült, hogy a kód élesedett, az érvelést pedig emlékezetből rekonstruálták.
• Egy mérnök megkérdezi, miért így van, a válasz pedig egy 40 kommentes pull request linkje.

Ha ezek közül három vagy több ismerős, valószínűleg nem a sablonnal van a baj. A csapat egy dokumentummal végeztet el két feladatot, és egyik sem sikerül jól.

Zárszó

Az RFC-vel megtudjuk, mi legyen a döntés, az ADR-rel megjegyezzük, mi volt. Ha nem vagyunk biztosak benne, melyiket írjuk, kérdezzük meg magunktól: van még valami, amit nem tudunk? Ha igen, ez javaslat, és kellenek hozzá a kommentek. Ha nem, ez feljegyzés, és egy oldal elég.