Dokumentáció, amit tényleg frissítesz majd

A mérés, ami megdöntött egy közhiedelmet

Egy 2026 februári vizsgálat pontosan azt tette fel kérdésnek, amit mindenki magától értetődőnek hisz: segít-e a repó szintű kontextusfájl a kódoló agentnek?

A módszertan gondos. Két feladatkészlet: egy saját, 138 feladattal, tizenkét friss és kevéssé ismert repóból — szándékosan nem népszerűekből, hogy a modellmemóriája ne segítsen —, plusz egy bevett, 300 feladatos készlet. Négy agent, négy modell. És kétféle kontextusfájl: géppel generált, illetve fejlesztő által kézzel írt.

A lépésszám minden beállításban nőtt, átlagosan két-négy lépéssel. És a navigációra sincs hatás: a kontextusfájl nem csökkentette érdemben, hány lépésből jut el az agent a releváns fájlokig.

A szerzők következtetése szó szerint: „a repóbemutatók — bár népszerűek, és a modellszolgáltatók ajánlják őket — nem segítenek."

És van egy részeredmény, ami mindennél árulkodóbb. Amikor a dokumentációt eltávolították a repóból, a géppel generált kontextusfájlok átlagosan 2,7%-kal javították a teljesítményt — és jobbak lettek a fejlesztő által írt dokumentációnál is.

Vagyis a fájl akkor hasznos, ha nincs más dokumentáció. Különben csak duplikál.

Ez nem mond ellent a másik mérésnek

Érdemes rögtön tisztázni, mert a két eredmény elsőre ütközni látszik.

Egy másik, párosított kísérlet azt találta, hogy a projektutasítás-fájl 20%-kal csökkenti a tokenfogyasztást és a futásidőt. Ez a mérés a repókban már meglévő, fejlesztők által írt fájlokat használta.

A mostani mérés pedig azt mutatja, hogy a géppel generált fájl ront és drágít.

A kettő együtt egy tanulságot ad: nem a fájl léte számít, hanem hogy ki írta és mi van benne. A generált repóbemutató a legrosszabb eset — hosszú, a kódból amúgy is látszik, és minden futásban ott van a kontextusban. Erről bővebben a projektutasítások poszt szól.

Mit jelent ez pénzben

Számoljuk ki egy csapatra. Tegyük fel, hogy havonta 300 agent-feladatot futtattok, feladatonként fél dollár alapköltséggel.

Alapköltség:                          300 × 0,50  = $150 / hó
Géppel generált fájllal (+23%):       150 × 1,23  = $184,50 / hó
Többletköltség:                                      $34,50 / hó

Sikerarány-változás:                  −2 százalékpont
Elvesztett megoldás:                  300 × 0,02  = 6 feladat / hó

(Saját számítás a publikált arányokból.)

Havi harmincöt dollár többlet, és hat kevesebb megoldott feladat. Nem katasztrófa — de fordított előjelű annál, mint amiért az egészet csináltad.

A rossz dokumentáció rosszabb, mint a semmilyen

Ez a cikk legfontosabb állítása, és kísérlet támasztja alá.

Egy 2024-es vizsgálat ugyanazt a 164 függvényt adta oda öt változatban: dokumentáció nélkül; eredeti dokumentációval; egy másik függvényből vett, oda nem illő dokumentációval; átírt változónevekkel; és részleges dokumentációval.

Két eredmény jött ki belőle:

• A hibás dokumentáció súlyosan ront. Véletlen, oda nem illő kommentekkel a sikerarány a gyengébb modellnél 22,1%-ra, az erősebbnél 68,1%-ra esett. Statisztikailag szignifikáns.
• A hiányzó dokumentáció alig számít. A kommentezett és a komment nélküli alapváltozat között nem volt szignifikáns különbség.

Ehhez jön egy másik mérés, egy teljesen más feladaton: ott a kommentek eltávolítása javította a modellek találati arányát.

Két független mérés, ugyanaz az irány. A dokumentáció, amit nem fogsz frissíteni, nem semleges tartozás, hanem aktív kockázat. Aki a dokumentálást ingyenesnek hiszi, rosszul számol.

Az elavult komment akkor a legveszélyesebb, amikor friss

Ez a legellentétesebb megállapítás az ösztönös elvárással.

Egy 32 Apache-projektet elemző vizsgálat szerint az olyan változtatások, ahol a kód és a komment széttart, egy héten belül 1,52-szer, két héten belül 1,14-szer nagyobb eséllyel vezetnek hibát okozó committhoz.

És itt jön a lényeg: a hatás közvetlenül a széttartás után a legnagyobb, és idővel csökken.

Az elavult komment nem attól lesz veszélyes, hogy régi. Akkor veszélyes, amikor még valaki hisz neki. Utána a csapat megtanulja figyelmen kívül hagyni — csak épp a modell nem tanulja meg.

Mit írj bele, és mit ne

A gyártói ajánlás és a fenti mérés ugyanoda jut ki. Ez a táblázat közvetlenül használható:

A jobb oldali oszlop lényegében az, amit a mérés „repóbemutatónak" nevez — és amiről kimutatta, hogy nem használ.

Az öntesztelő kérdés minden sorra: „Ha ezt kitörölném, hibázna tőle?" Ha nem, töröld.

Ami nem avul: a döntésnapló

Van egy dokumentációtípus, ami definíció szerint nem évül el: az építészeti döntésnapló.

A logika egyszerű. Egy bejegyzés egy döntést rögzít egy időpontban, a kontextusával és a mérlegelt alternatívákkal együtt. Ha a döntés később megváltozik, nem átírod — hanem új bejegyzést írsz, ami a régit felülírja.

Ettől lesz olyan dokumentáció, aminek a frissítése nem kötelesség, hanem egy új sor. És ettől marad igaz: a régi bejegyzés akkor is pontos, ha a döntés már nem érvényes, mert azt rögzíti, hogy akkor mit gondoltunk és miért.

(Őszinte korlát: a döntésnapló hasznáról nem találtunk mérést. Ami van, az a sablonok összehasonlítása egy 33 fős, hallgatói kísérletben — ott a két vizsgált sablon között szignifikáns különbség volt, de a mintából ipari következtetést nem lehet levonni.)

Ami elavulhat, azt tedd futtathatóvá

Ez a cikk legpraktikusabb mechanizmusa.

A dokumentációba írt példa akkor marad igaz, ha lefut. A Python szabványkönyvtárában van erre eszköz: a dokumentációs szövegben lévő interaktív példákat kikeresi, lefuttatja, és összeveti a leírt várt kimenettel. Más nyelvekben is van hasonló, ahol a dokumentáció példái a tesztkészlet részeként futnak.

Ez az egyetlen forma, ahol az elavuló dokumentáció piros tesztként jelentkezik, nem csendben rohad el.

Ugyanez a logika kiterjeszthető: ha egy magyarázat valamilyen viselkedésről szól, akkor annak a viselkedésnek legyen tesztje — és a teszt neve legyen a magyarázat. A tesztek írásáról a teszt mint biztonsági háló poszt szól részletesebben.

A recept

1. NE GENERÁLTASS REPÓBEMUTATÓT.
   Mért hatás: -0,5 és -2 százalékpont sikerarány,
   +20-23% költség, +2-4 lépés feladatonként.

2. AMIT A KÓDBÓL MEGÉRT, AZT NE ÍRD LE.
   Kérdés soronként: "ha kitörölném, hibázna tőle?"

3. AMI ELAVULHAT, AZT TEDD FUTTATHATÓVÁ.
   Példa a dokumentációban -> futó teszt.
   Viselkedés magyarázata -> teszt, beszédes névvel.

4. A DÖNTÉSEKET RÖGZÍTSD, NE AZ ÁLLAPOTOT.
   Döntésnapló: kontextus, alternatívák, döntés, dátum.
   Változáskor ÚJ bejegyzés, nem átírás.

5. AZ ELAVULT KOMMENTET TÖRÖLD, NE HAGYD OTT.
   A hibás dokumentáció mérhetően rosszabb, mint a semmilyen.

6. AMIKOR SZÉTTART, AKKOR JAVÍTSD.
   A hibaokozási hajlam közvetlenül a széttartás után
   a legnagyobb, nem hónapokkal később.

Egy szám, ami hiányzik

A tisztesség kedvéért: kerestük, és nem találtunk mérést arról, hogy a géppel generált dokumentáció hány százaléka téves vagy elavult.

Ami van, az a hatás mérése — hogy a hibás dokumentáció rontja a megértést. A gyakoriságról nincs publikált adat. Aki ilyen számot idéz, valószínűleg becsül.

Tipikus félreértések

• „Az agentnek kell dokumentáció, hogy értse a repót." A mérés szerint a repóbemutató nem segít, és a navigációra sincs hatása.
• „Generálok egy áttekintőt, az legalább van." Két százalékponttal rosszabb sikerarány és 23%-kal magasabb költség. A semmi jobb lett volna.
• „Az elavult komment idővel válik veszélyessé." Fordítva: a hibaokozási hajlam közvetlenül a széttartás után a legnagyobb.
• „A hiányzó dokumentáció komoly hátrány." A kontrollált kísérletben a hiányzó dokumentáció nem okozott szignifikáns romlást. A hibás igen.
• „A dokumentálás ingyen van." A rossz dokumentáció aktív kockázat, és a kontextusfájl minden futásban fizetteti magát.

Amit érdemes elvinni

A jó dokumentáció ismérve 2026-ban nem az, hogy mennyit fed le, hanem hogy mi történik vele, amikor a kód megváltozik. Ami futtatható, az szól: piros lesz a teszt. Ami döntést rögzít, az nem avul. Ami repóbemutató, azt a mérés szerint jobb meg sem írni — a modell úgyis elolvassa a kódot, csak most már fizetsz is érte.

Hogy az agent hogyan tájékozódik a kódban a dokumentáció helyett, azt az örökölt kódbázis megértése poszt járja körül.