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.json ke 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.md atau .cursorrules) bahwa berkas .agent/symbol-cache.json selalu akurat dan harus diperiksa sebelum menjalankan subproses pencarian shell manual.