Autonomous coding agent (seperti Aider, Claude Code, atau Cursor Agent) menghabiskan sebagian besar konsumsi token dan waktu eksekusinya bukan pada generasi kode, melainkan fase eksplorasi. Pada monorepo atau repositori berukuran besar, agen mengeksekusi instruksi seperti grep, ripgrep, atau traversal Abstract Syntax Tree (AST) secara berulang hanya untuk memetakan dependensi file, definisi antarmuka, dan lokasi simbol target.
Eksplorasi berulang yang tidak terkelola ini memicu dua masalah utama: latensi respons agen membengkak drastis, dan biaya konsumsi context window LLM meningkat secara tidak efisien. Solusi deterministik untuk masalah ini adalah memindahkan riwayat penelusuran struktur ke dalam sebuah lookup ledger lokal yang disinkronisasikan oleh siklus hidup Git melalui Git hooks.
Arsitektur Lookup Ledger: Menyimpan Jejak Konteks
Pola ini terinspirasi dari model eksekusi berbasis hook seperti capn-hook, di mana status sistem deviasi disinkronkan langsung pada lifecycle layer Git. Alih-alih membiarkan agen memindai ulang disk pada setiap prompt, agen diarahkan untuk membaca indeks terstruktur (ledger) terlebih dahulu.
Lookup ledger dapat diwujudkan dalam berkas lokal tunggal (misalnya .agent/symbol-cache.json) yang dipetakan berdasarkan hash SHA-1/SHA-256 berkas. Jika agen membutuhkan referensi ke sebuah fungsi atau kelas, agen hanya perlu menanyakan ledger tanpa mengeksekusi subprocess shell pencarian.
- Index Structure: Menyimpan relasi jalur berkas, hash konten, daftar definisi simbol (fungsi, kelas, ekspor), dan ringkasan eksternal.
- Validasi Deterministik: Memastikan entri cache hanya valid jika hash berkas pada disk identik dengan hash yang tersimpan di ledger.
- Git Integration: Memperbarui atau membersihkan entri secara otomatis ketika developer atau agen melakukan commit, switch branch, atau pull.
Implementasi Git Hooks untuk Sinkronisasi State
Dua siklus hidup Git utama yang krusial untuk sinkronisasi state agen adalah post-checkout (saat berpindah branch atau checkout commit) dan pre-commit (sebelum perubahan disimpan).
1. Hook post-checkout
Hook ini mendeteksi apakah terjadi perpindahan commit/branch (argumen flag $3 == 1) dan menjalankan sinkronisasi untuk membuang entri ledger yang berkas aslinya telah berubah.
#!/usr/bin/env bash
# .git/hooks/post-checkout
PREV_HEAD=$1
NEW_HEAD=$2
IS_BRANCH_CHECKOUT=$3
if [ "$IS_BRANCH_CHECKOUT" -eq 1 ]; then
echo "[agent-cache] Branch switch detected. Syncing code index..."
python3 scripts/agent_indexer.py --clean-stale
fi
2. Hook pre-commit
Hook ini memastikan berkas yang dimodifikasi oleh developer atau agen diindeks ulang sehingga state cache selalu sinkron sebelum masuk ke pohon commit.
#!/usr/bin/env bash
# .git/hooks/pre-commit
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|ts|js|go|rs)$')
if [ -n "$STAGED_FILES" ]; then
echo "[agent-cache] Updating index for modified staged files..."
echo "$STAGED_FILES" | xargs python3 scripts/agent_indexer.py --update
fi
Implementasi Skrip Indexer Minimal
Berikut adalah implementasi Python sederhana berbasis pustaka standar untuk mengekstrak definisi kelas/fungsi (menggunakan regex ringan sebagai pendekatan lazier alternative terhadap AST parsers penuh) dan menyimpannya ke ledger lokal deterministik.
#!/usr/bin/env python3
# scripts/agent_indexer.py
import os
import sys
import json
import hashlib
import re
LEDGER_PATH = os.path.join(".agent", "symbol-cache.json")
SYMBOL_REGEX = re.compile(r"^[ \t]*(?:async\s+def|def|class|function|export\s+function)\s+([a-zA-Z0-9_]+)", re.MULTILINE)
def hash_file(filepath):
hasher = hashlib.sha256()
with open(filepath, "rb") as f:
while chunk := f.read(8192):
hasher.update(chunk)
return hasher.hexdigest()
def extract_symbols(filepath):
try:
with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
content = f.read()
return SYMBOL_REGEX.findall(content)
except OSError:
return []
def load_ledger():
if os.path.exists(LEDGER_PATH):
try:
with open(LEDGER_PATH, "r", encoding="utf-8") as f:
return json.load(f)
except json.JSONDecodeError:
pass
return {"files": {}}
def save_ledger(data):
os.makedirs(os.path.dirname(LEDGER_PATH), exist_ok=True)
with open(LEDGER_PATH, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2)
def update_files(filepaths):
ledger = load_ledger()
for fp in filepaths:
if not os.path.isfile(fp):
continue
fhash = hash_file(fp)
# ponytail: regex parsing; upgrade to tree-sitter or language ast for nested scope tracking
symbols = extract_symbols(fp)
ledger["files"][fp] = {
"hash": fhash,
"symbols": symbols
}
save_ledger(ledger)
def clean_stale():
ledger = load_ledger()
updated = {}
for fp, meta in ledger.get("files", {}).items():
if os.path.isfile(fp):
if hash_file(fp) == meta.get("hash"):
updated[fp] = meta
save_ledger({"files": updated})
if __name__ == "__main__":
action = sys.argv[1] if len(sys.argv) > 1 else ""
if action == "--update":
targets = sys.argv[2:] if len(sys.argv) > 2 else sys.stdin.read().splitlines()
update_files(targets)
elif action == "--clean-stale":
clean_stale()
Catatan Git Tracking: Tambahkan.agent/symbol-cache.jsonke dalam.gitignore. Ledger ini dirancang sebagai transient context cache lokal per mesin pengembang, bukan artifak yang dikomit ke upstream.
Trade-offs dan Pertimbangan Praktis
- Regex vs AST Parser: Implementasi di atas menggunakan pendekatan regex. Pendekatan ini sangat cepat dan memiliki nol dependensi eksternal, namun rentan false-positive pada string multiline atau komentar. Jika tim membutuhkan presisi scope atau tipe data parameter, gantikan fungsi ekstraksi dengan
tree-sitter. - Overhead Waktu Pre-commit: Mengekstrak ribuan berkas staged sekaligus dapat memperlambat loop commit. Batasi ekstraksi hanya pada berkas target yang terpengaruh diff menggunakan
git diff --cached --name-only. - Instruksi System Prompt Agen: Beri tahu agen di instruksi sistemnya (seperti
AGENT.mdatau.cursorrules) bahwa berkas.agent/symbol-cache.jsonselalu akurat dan harus diperiksa sebelum menjalankan subproses pencarian shell manual.
Komentar
0 komentar
Masuk ke akun kamu untuk ikut berkomentar.
Belum ada komentar
Jadilah yang pertama ikut berdiskusi!