RAG kódon: AST-darabolás, repótérképek és kódbeágyazások ágensekhez

A RAG kódon olyan visszakereséssel kiegészített generálás, ahol a korpusz egy repó, és másképp hibázik, mint a dokumentumokon futó RAG. A kódnak éles határai vannak (függvények, osztályok, importok), pontos azonosítói, amelyek többet számítanak a parafrázisnál, és hívási gráfja, amely összeköti a fájlokat. Ha prózaként daraboljuk, a modell fél függvényt kap importok nélkül; ha egyszer indexeljük és elfelejtjük, az ágens magabiztosan olvas olyan kódot, amelyet tegnap töröltek.

Ez a cikk a tree-sitterrel végzett szerkezeti darabolással, a beágyazás nélküli repótérképekkel, azzal, hogyan tartja frissen az indexet a Cursor és a Kilo Code, a 2026 októberében elérhető kódbeágyazó modellekkel, a saját repón végzett mérés módjával, és azzal foglalkozik, mikor jobb a grep bármilyen indexnél. Hogy mi kerüljön egyáltalán egy ágens kontextusába, azt az AGENTS.md, skillek, MCP és CLI döntési mátrix írja le; ez a cikk arról szól, hogyan találjuk meg a kódot.

Miért bukik el a soralapú darabolás kódon

A soralapú darabolás azért bukik el, mert a kód határai nem fix sorszámokra esnek. Egy 40 soros ablak középen vág el egy függvényt, egy dekorátort az egyik darabban, az osztályát a következőben hagyja, és elválasztja az importokat az őket használó kódtól. A visszakereső ezután olyan töredékeket rangsorol, amelyek önmagukban már nem jelentenek semmit.

A cAST-tanulmány megmérte a hatást. A soralapú heurisztikákról azt írja, hogy „gyakran szétvágják a szemantikai szerkezeteket, kettéosztják a függvényeket vagy összevonják az össze nem tartozó kódot”, és az absztrakt szintaxisfa mentén végzett rekurzív darabolással váltja ki őket, a kis testvércsomópontokat egy méretkorlátig összevonva. Ez 4,3 ponttal javította a Recall@5-öt a RepoEval visszakeresésen és 2,67 ponttal a Pass@1-et a SWE-bench generáláson (cAST). A javulás abszolút értékben szerény, de egy elemzőből jön, nem egy nagyobb modellből.

A kódkeresés egy második ok miatt sem szövegkeresés: a lekérdezések keverik a természetes nyelvet a pontos azonosítókkal. Egy olyan kérdéshez, mint „hol próbáljuk újra az ERP-hívást”, szemantikus egyezés kell, a „ki hívja a createSalesOrder-t” kérdéshez viszont pontos szimbólumkeresés. Egy jó rendszer mindkettőt kiszolgálja, ezért kombinálja a lenti rendszerek többsége a szerkezetet a kereséssel.

AST-darabolás tree-sitterrel

A tree-sitter a közös elemző ezekben a rendszerekben: konkrét szintaxisfává elemzi a fájlt, a tags.scm-hez hasonló lekérdezőfájlok pedig nyelvenként meghatározzák, mi számít definíciónak vagy hivatkozásnak (Aider). A daraboló végigmegy a legfelső szintű csomópontokon, a függvényeket, osztályokat és metódusokat darabként adja ki, összevonja a kis szomszédokat, hogy egy rövid segédfüggvényekből álló fájlból ne legyen ötven apró darab, a túl nagy csomópontokat pedig a gyerekeikbe lépve osztja fel.

# Sketch: AST chunks with sibling merging, the idea behind cAST
from tree_sitter import Language, Parser
import tree_sitter_python as tspython

parser = Parser(Language(tspython.language()))
MAX_CHARS = 1000  # Kilo Code documents 100 to 1,000 characters per block

def chunks(src: bytes, path: str):
    buf = []
    for node in parser.parse(src).root_node.children:
        text = src[node.start_byte:node.end_byte].decode()
        if len(text) > MAX_CHARS and node.child_count:
            yield from split_children(node, src, path)   # oversized: recurse
        elif sum(len(t) for t, _ in buf) + len(text) <= MAX_CHARS:
            buf.append((text, node))                     # merge small siblings
        else:
            yield emit(buf, path)                        # path, lines, symbol, signature
            buf = [(text, node)]
    if buf:
        yield emit(buf, path)

A Cline és Roo vonalból származó Kilo Code konkrét beállításokat dokumentál ehhez: tree-sitter-elemzés 100 és 1000 karakter közötti szemantikai blokkokra, a nagy függvények felosztása, és soralapú tartalék azokhoz a fájlokhoz, amelyeket az elemző nem ért (Kilo Code). A méretkorlátoktól függetlenül minden darabhoz tároljon metaadatot: a fájl útvonalát, a sortartományt, a szimbólum nevét és a szignatúrát. Az ágensnek az útvonal és a sorok kellenek a valódi fájl megnyitásához, a szignatúra pedig a törzs nélkül is olvashatóvá teszi a darabot egy találati listában.

Repótérképek: szimbólumkontextus beágyazás nélkül

Egy repótérkép vektorindex nélkül adja meg a modellnek a repó alakját. Az Aider tree-sitterrel építi: a legfontosabb osztályok és függvények típusokkal és hívási szignatúrákkal. Hogy mi fér bele a tokenkeretbe, egy gráfrangsoroló algoritmus dönti el egy olyan gráfon, ahol minden fájl egy csomópont, a függőségek pedig élek. A --map-tokens beállítás alapértéke 1k token, és a térkép bővül, amíg még nincs fájl hozzáadva a csevegéshez (Aider dokumentáció).

A térkép szignatúrákat tartalmaz, nem törzseket, ezért olcsó. Az Aider 2023-as tervezési jegyzete elmagyarázza, hogy a tree-sitter azért váltotta le a ctagset, mert közvetlenül a forrásból mutat teljes szignatúrákat, és telepíthető csomagként szállítja a nyelvi támogatást (Aider blog). A visszakeresési minta: előbb a jelölők. A modell elolvassa a térképet, kiválasztja a szükséges fájlokat, és csak azután olvassa el őket teljesen. Egy ismert repóban sok feladathoz ez elég, és semmit sem kell újra beágyazni.

A nyelvi szerverek egy lépéssel tovább mennek. A Serena egy MCP-eszközkészlet szimbólumszintű visszakereséshez és szerkesztéshez, amelynek alapértelmezett háttere a Language Server Protocol, több mint 40 nyelvvel (Serena). Az ágens szövegkeresés helyett egy szimbólum definícióját vagy hivatkozásait kéri, és pontos választ kap. Hogy ez a gyakorlatban mennyit spórol, azt a kódoló ágensek tokenspóroló eszközeiről szóló cikk mutatja be.

Hogyan indexelik a kódot a kereskedelmi ágensek

A Cursor Merkle-fával indexel. Minden fájl SHA-256 hasht kap, minden mappa pedig a gyerekei hashét, így egy módosítás után csak a megváltozott ágak térnek el, és csak azokat kell szinkronizálni. Egy 50 000 fájlos munkaterületen pusztán a fájlnevek és hashek nagyjából 3,2 MB-ot tesznek ki. A megváltozott fájlokat szintaktikai darabokra bontja, a beágyazásokat a darab tartalma szerint gyorsítótárazza, egy hasonlósági hash pedig újrahasznosítható meglévő indexet keres, tartalmi bizonyítékokkal, hogy egy kliens csak olyan fájlokra kapjon találatot, amelyeket ténylegesen olvashat (Cursor).

A mögötte álló vektorréteg a turbopuffer, amely szerint a Cursor visszakeresése több mint egybillió vektort kezel, kódbázis-példányonként külön névtérrel, a Cursor saját modelljével beágyazva. Egy meglévő névtér másolása egy új checkouthoz az első lekérdezésig eltelt medián időt 7,87 másodpercről 525 milliszekundumra, a p99-et pedig 4,03 óráról 21 másodpercre csökkentette (turbopuffer). Ez minden kódindex beüzemelési gondja: egy nagy repó első indexelése a lassú rész.

A Kilo Code ugyanezt a mintát adja helyi telepítéshez: alapból LanceDB, külső tárként Qdrant, beágyazási szolgáltatók, köztük az Ollama a teljesen helyi felépítéshez, fájlfigyelés és hash-alapú gyorsítótárazás a növekményes frissítéshez, valamint az ágváltások kezelése. Alapértékei között szerepel a 0,4-es minimális keresési pontszám és legfeljebb 50 találat (Kilo Code). Maga a Cline ezzel szemben jelenleg beépített eszközöket dokumentál, például read_files és search_codebase, beágyazási indexet nem (Cline dokumentáció).

Kódbeágyazó modellek 2026-ban

2026 októberében három gyakorlati út van. Hosztolt és kódra hangolt: a Voyage a voyage-code-4-et jelöli aktuális kódmodelljeként millió tokenenként 0,12 dollárért, 200 millió ingyenes tokennel, míg a voyage-code-3 0,18 dolláros áron a régebbi modellek közé került (Voyage). Saját üzemeltetésű: a Qwen3-Embedding 0.6B, 4B és 8B méretben érhető el 32k kontextussal, Matryoshka-dimenziókkal, és több mint 100 nyelvet támogat, a programozási nyelveket is beleértve (Qwen).

A harmadik út egy általános multimodális vagy hosszú kontextusú modell. A jina-embeddings-v4 egyetlen 2048 dimenziós vektort vagy késői interakcióhoz tokenszintű vektorokat tud kiadni, 71,59-et jelent a CoIR kódbenchmarkon, és a Qwen Research License alatt érhető el, ami kereskedelmi felhasználásnál számít (Jina). A Cohere Embed v4 128k kontextust és 256-tól 1536 dimenzióig terjedő Matryoshka-kimenetet kínál millió tokenenként 0,12 dollárért (Cohere). A modellválasztás általános kérdés, ezt a beágyazó modell kiválasztásáról szóló cikk tárgyalja; kódnál a hosszú kontextus azért számít, mert egész fájlok és hosszú függvények is beleférnek.

Néhány százezer soros repónál ezeken az árakon kicsi a beágyazási számla; a valódi költség a változások utáni újrabeágyazás és az a fejlesztési munka, amely helyesen tartja az indexet. A kódra hangolás ott térül meg leginkább, ahol a lekérdezések természetes nyelvűek, a kód pedig olyan szakmai neveket használ, amelyeket az általános modell sosem látott.

A kódkeresés mérése és frissen tartása

A saját repóján mérjen, a nyilvános benchmarkokat csak józansági ellenőrzésnek használja. Az ACL 2025-ön megjelent CoIR tíz adathalmazt fog össze nyolc visszakeresési feladaton és hét területen, és a szerzők szerint még a legkorszerűbb modelleknek is jelentős nehézségeik voltak a kódkereséssel (CoIR). Az Ön lekérdezései, azonosítói és konvenciói nincsenek benne, ezért építsen saját kis készletet.

1. Gyűjtsön 30–50 valódi kérdést jegyekből és kódellenőrzésekből, mindegyikhez a választ adó fájllal és szimbólummal.
2. Keverje a természetes nyelvű kérdéseket a pontos névkeresésekkel, mert ezek más-más visszakeresőt terhelnek.
3. Mérje a recallt 5-nél és 10-nél minden darabolási és modellváltozatra, és tartsa a készletet a repóban.
4. Futtassa újra modellváltás és nagyobb refaktorálás után, ne csak egyszer.

A frissesség ugyanannyi tervezést igényel, mint a minőség. A bevált minták: fájlfigyelők tartalom-hash gyorsítótárral (Kilo Code), csak a megváltozott ágakat szinkronizáló Merkle-fák (Cursor) és memoizált folyamatok. A CocoIndex fájlonként és feldolgozási lépésenként kulcsolja a gyorsítótárát, így egy néhány fájlt érintő commit csak azokat ágyazza be újra, a törölt fájlok sorai eltűnnek, az index pedig vagy felzárkóztató futásként a CI-ban, vagy élő módban, a munkakönyvtárat körülbelül egy másodperces késéssel figyelve fut (CocoIndex). A törlések azok az esetek, amelyeket a legtöbb rendszer elront, így jut el egy ágens oda, hogy már eltávolított kódra hivatkozik. A késői darabolás és a kontextuális visszakeresés ezen felül kontextussal egészíti ki a darabokat, lásd kontextuális visszakeresés és késői darabolás.

Mikor jobb az ágensalapú grep egy indexnél, és egy ellenőrzőlista

A grep akkor jobb egy indexnél, ha a repó elég kicsi a gyors kereséshez, folyamatosan változik, vagy nem hagyhatja el a gépet. Az Anthropic hibridként írja le a Claude Code-ot: a CLAUDE.md előre betöltődik, és „az olyan primitívek, mint a glob és a grep, lehetővé teszik, hogy bejárja a környezetét és igény szerint töltsön be fájlokat, gyakorlatilag megkerülve az elavult indexek és a bonyolult szintaxisfák problémáit”. Ugyanez az írás megjegyzi, hogy a futásidejű felfedezés lassabb, mint az előre kiszámolt visszakeresés (Anthropic). A Claude Code Grep eszköze ripgrepre épül, mellette ott a Glob (Claude Code dokumentáció).

A Claude Code-ot, az opencode-ot és a Codexet párhuzamosan használom, és a kompromisszum a mindennapokban is látszik: a grepet előnyben részesítő ágensek egy ismeretlen területen több keresési és olvasási körre költenek tokent, de sosem adnak vissza olyan kódot, amely már nem létezik. Az index költsége ennek a fordítottja: tárhely, beágyazási költség és a fenti frissességi gépezet, cserébe kevesebb kör a jelentés szerint megfogalmazott kérdéseknél.

• Repóméret: amíg a ripgrep azonnal válaszol, kezdjen greppel és repótérképpel.
• Változási ütem: gyakori változásnál a grep vagy az LSP előnyös; egy indexnek törléseket is kezelő növekményes frissítés kell.
• Monorepó: sok csapat és ismeretlen terület az index mellett szól, lehetőleg megosztva és checkoutok között újrahasznosítva.
• Megfelelőség: ha a kód nem hagyhatja el a gépet, használjon helyi beágyazót és helyi tárat, vagy hagyja ki az indexet.
• Alapból hibrid: grep a pontos nevekhez, LSP a definíciókhoz és hivatkozásokhoz, index a jelentéshez.

Ha visszakeresést épít egy kódoló ágenshez vagy belső kódasszisztenshez, a MI-mérnöki munkám az ilyen rendszereket fedi le a darabolástól a kiértékelésig.

Források

1. cAST: AST-based chunking for code RAG (arXiv 2506.15655)
2. Aider docs: repository map
3. Aider blog: building a better repository map with tree-sitter (2023)
4. Anthropic Engineering: effective context engineering for AI agents (Sep 2025)
5. Cursor blog: securely indexing large codebases (Jan 2026)
6. turbopuffer: Cursor customer story
7. Kilo Code docs: codebase indexing
8. Serena on GitHub
9. Voyage AI docs: pricing
10. Qwen blog: Qwen3-Embedding (Jun 2025)
11. CoIR: a benchmark for code information retrieval (arXiv 2407.02883)
12. CocoIndex blog: indexing a codebase