AI Coding Harness (Perancah Keamanan Coding AI)

Apa itu ini

AI coding harness adalah perancah penegakan aturan dan verifikasi yang kamu bangun di sekeliling agen coding, supaya agen itu bisa bekerja secara otonom tanpa merusak apa pun. Kalau guardrail (pagar pengaman) adalah kebiasaan yang harus kamu ingat sendiri (jalankan tes, baca diff), harness adalah mesin yang mengingatnya untukmu: ia duduk di antara niat agen dan dunia nyata, dan pada setiap langkah berbahaya ia mencatat, memperingatkan, atau memblokir. dancinlab/harness adalah mesin referensi yang tidak terikat pada satu proyek — sebuah inti TypeScript bersama, di mana setiap repo hanya berbeda lewat satu harness.config.json plus beberapa file data .harness/*.json.

Kelebihan

Mengubah guardrail-mu dari kebiasaan opsional menjadi aturan yang ditegakkan oleh kode — agen tidak bisa melewatkannya begitu saja.
Menjaga seluruh siklus hidup tool: sebelum sebuah perintah dijalankan, sebelum sebuah file ditulis, pada saat , pada saat , dan pada saat push.
Sebuah ledger (buku catatan) di sini ibarat notebook yang hanya pernah kamu tambahkan baris baru dan tidak pernah kamu hapus baris lama. Ledger ini ditulis dalam format JSONL ( Lines — satu objek JSON per baris) dan memberi catatan yang anti-manipulasi (tamper-evident) atas semua yang dilakukan agen. Menulisnya murah dan mengauditnya mudah.
Bisa dipasang ke repo mana pun: perilakunya diatur oleh config dan data, bukan kode yang di-fork.
Dirancang untuk tetap diam ketika semuanya baik-baik saja, supaya peringatan yang muncul masih benar-benar berarti.

Trade-off (kompromi)

Ini adalah pipa ledeng, bukan sihir: harness membuat kesalahan murah untuk ditangkap, bukan membuat AI-nya jadi benar.
Butuh setup awal dan config yang disetel sesuai zona bahaya proyekmu.
Aturan yang terlalu ketat menimbulkan friksi; disiplin "bitter-gate" (pensiunkan aturan yang sudah tidak aktif sebelum menambah aturan baru) ada justru untuk melawan hal ini.
Paling bernilai pada proyek nyata dengan pengguna nyata — berlebihan untuk sekadar prototipe sekali pakai.

Paling cocok untuk

Vibe coding serius, di mana kamu membiarkan agen membuat perubahan multi-file dan menjalankan perintah secara sebagian besar tanpa pengawasan, dan kamu butuh biaya dari satu tindakan buruk tetap mendekati nol.

Lima prinsip (H1–H5)

H1 Sukses diam, gagal ribut — tidak ada noise yang akan membuatmu belajar untuk mengabaikannya.
H2 Jangan pernah auto-fix — usulkan, blokir, atau peringatkan; manusia atau agen yang sudah diberi informasi yang memutuskan.
H3 Bitter-gate — pensiunkan aturan yang sudah tidak aktif sebelum menambah aturan baru.
H4 Berbasis config — satu mesin, harness.config.json per proyek.
H5 AI-native — ledger JSONL append-only (hanya-tambah), mustahil ditulis ulang secara diam-diam.

Bentuknya seperti apa

Sketsa config minimal:

// harness.config.json
{
  "lockedPaths": ["src/auth/**", "infra/**", ".github/**"],
  "blockCommands": ["rm -rf", "git push --force", "curl * | sh"],
  "verify": ["npm run lint", "npm run typecheck", "npm test"],
  "ledger": ".harness/ledger.jsonl"
}

Dan alur hook pre/post di sekitar satu tindakan agen:

agent intends an action
        │
   ┌────▼─────────────┐
   │ pre  (PreToolUse) │  block dangerous? warn? → else allow
   └────┬─────────────┘
        │  command runs / file is written
   ┌────▼──────────────┐
   │ post (PostToolUse) │  record to JSONL · warn if a locked file was touched
   └────┬──────────────┘
        │  at commit / push
   ┌────▼─────┐
   │  verify  │  lint · typecheck · tests (parallel) → green or stop
   └──────────┘

Agen itu tidak pernah bisa melewati gerbang ini — itulah inti keseluruhannya.