Cara Melacak dan Memulihkan Malfungsi Agent AI dalam Codebase
makedream2026年7月30日
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
Saat Anda mengintegrasikan agent AI seperti Claude Code atau Codex ke dalam repositori backend dengan lebih dari 100.000 baris kode, awalnya Anda akan terkesima dengan kecepatannya. Namun, pada suatu saat ketika petunjuk salah dimasukkan meski hanya beberapa baris, AI dapat menembus batas pertahanan dan bahkan menyentuh utility bersama atau file konfigurasi lingkungan. Log sesi membengkak hingga berukuran beberapa megabita, proses build gagal, dan saat Anda menghabiskan waktu berjam-jam memindai Git Diff untuk mencari file penyebab masalah, muncul pemikiran bahwa lebih baik Anda yang menuliskannya sendiri dari awal.
Untuk memberikan otonomi kepada agent sekaligus mencegah kerusakan file yang tidak perlu, diperlukan isolasi keras yang jelas dan sistem pemulak pelacakan (trace) yang tervisualisasi.
File instruksi bahasa alami seperti CLAUDE.md atau .aiignore sering kali diabaikan oleh agent begitu jendela konteks (context window) menjadi semakin panjang. Permintaan di tingkat prompt hanyalah sekadar rekomendasi, sehingga begitu kehilangan konteks, eksekusi tool oleh agent akan tanpa ragu melompati pagar pembatas.
Untuk memblokir akses agent secara fisik, Anda harus menempatkan mesin kontrol izin deterministik .claude/settings.json secara langsung di root proyek.
`json
{
"permissions": {
"deny": [
"Edit(src/core/config/)",
"Edit(src/shared/utils/)",
"Read(./.env*)",
"Bash(rm -rf *)"
],
"ask": [
"Edit(src/api/v1/legacy/**)"
]
}
}
`
Setelah menetapkan aturan pemblokiran eksplisit, jauh lebih aman untuk menguncinya sekali lagi di tingkat sistem file. Ada baiknya Anda mencabut izin tulis di tingkat OS untuk skrip build produksi atau file kunci keamanan.
.claude/settings.json di root proyek.permissions.deny.chmod 444 .env* di terminal.Dengan mengontrol izin seperti ini, Anda dapat memangkas sebagian besar build error yang disebabkan oleh AI yang mendadak mengubah modul bersama.
Jika log sesi (.jsonl) hanya disimpan di lingkungan lokal masing-masing pengembang, akan sulit untuk mengidentifikasi penyebabnya ketika efek samping muncul di kemudian hari. Susun alur kerja GitHub Actions untuk mengompresi dan memverifikasi trace sesi pada saat Pull Request (PR) dibuat.
`yaml
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
`
Jika Anda menggabungkan mesin analisis berbasis Rust atau Tree-sitter untuk memeriksa apakah agent keluar dari cakupannya (scope), Anda dapat segera menggagalkan CI build apabila terjadi modifikasi modul tingkat atas yang melebihi batas toleransi.
Daripada hanya menghitung jumlah baris kode biasa, pendekatan yang menghitung risiko perubahan berdasarkan konektivitas node terbukti sangat berguna.
Di sini adalah jumlah file yang dimodifikasi, dan adalah rata-rata konektivitas 3D dari node yang diubah. Jika melewati ambang batas, buat sistem untuk mengirimkan tautan peta visualisasi 3D melalui notifikasi Slack, sehingga reviewer dapat langsung memahami tingkat risikonya.
Ketika agent membuat kekacauan, alih-alih menghapus seluruh commit, Anda harus melacak garis waktu dan memulihkan file yang terkontaminasi secara selektif. Setelah Anda mengekstrak rentang waktu tertentu saat malfungsi dimulai, gunakan jq untuk mengambil prompt dan jalur inferensi pada titik waktu tersebut dari log JSONL.
`bash
jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") |
{timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}'
./.claude/sessions/session_abc123.jsonl
`
Setelah mengonfirmasi penyebabnya, pemulihan dibagi menjadi 3 langkah berikut.
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)Dengan menggunakan metode ini, Anda dapat memungut file yang rusak dengan bersih tanpa insiden terhapusnya kode yang berfungsi dengan baik.
Dalam lingkungan monorepo, ketika jumlah node membengkak hingga puluhan ribu, alat visualisasi itu sendiri bisa mengalami crash. Jika browser melambat, proses debugging pun menjadi tidak menyenangkan. Untuk memangkas direktori yang tidak perlu dari target rendering, Anda harus mengatur filter pengecualian mindwalk.config.json dengan pasti.
`json
{
"visualization": {
"excludePatterns": [
"/node_modules/",
"/vendor/",
"/.git/",
"/dist/",
"/coverage/",
"/*.log",
"/*.pb.go"
],
"maxDepth": 5,
"groupingStrategy": "directory-segmented"
}
}
`
Terakhir, saat menjalankan pipeline visualisasi atau alat analisis sebagai kontainer Docker di latar belakang (background), Anda harus membatasi alokasi sumber daya agar IDE lokal tidak membeku.
mindwalk.config.json untuk mengecualikan node direktori dependensi dari target visualisasi.--cpus="1.5" dan --memory="2g" saat menjalankan kontainer.--nice=19 di akhir perintah eksekusi proses latar belakang untuk menurunkan prioritas CPU ke tingkat terendah.