Hooks Claude Code: Guardrail Agen yang Deterministik

Meminta agen untuk selalu menjalankan formatter berhasil sampai satu kali ia lupa, dan pada agen coding satu kali itu mendarat di diff Anda. Instruksi dalam prompt adalah saran yang mungkin diikuti model, mungkin juga tidak. Hooks adalah kebalikannya: perintah shell yang dijalankan runtime untuk Anda, setiap saat, terlepas dari apa yang diputuskan model.

Panduan ini menjelaskan apa itu hooks Claude Code, event lifecycle mana yang bisa Anda kaitkan, pola guardrail mana yang layak ditambahkan lebih dulu, dan bagaimana sebuah hook memblokir tindakan berbahaya sebelum berjalan. Mekanismenya khusus Claude Code, tetapi gagasan gerbang deterministik di sekitar agen yang non-deterministik bersifat universal.

Apa itu hook sebenarnya

Hook adalah perintah shell yang dijalankan Claude Code otomatis ketika event tertentu terpicu, dikonfigurasi di settings.json Anda alih-alih di prompt. Model tidak pernah memutuskan apakah sebuah hook berjalan; runtime yang memutuskan. Sifat tunggal itulah yang membuat hooks berguna, karena ia mengubah harapan menjadi jaminan: bukan tolong lint ini, melainkan ini sudah di-lint.

Hooks menerima JSON terstruktur tentang event pada standard input, sehingga sebuah skrip hook bisa memeriksa persis tool mana yang akan berjalan dan dengan argumen apa. Tiga hal membedakannya dari mekanisme steering lain:

• Hooks bersifat deterministik. Event yang sama selalu memicu perintah yang sama, sehingga perilaku tidak bergeser sepanjang sesi panjang seperti yang bisa terjadi pada instruksi prompt.
• Hooks menjalankan kode Anda sendiri, jadi pemeriksaan apa pun yang bisa Anda ungkapkan sebagai skrip shell atau program bisa menjadi gerbang, mulai dari formatter sampai mesin kebijakan buatan sendiri.
• Hooks terpicu pada event lifecycle, bukan pada penilaian model, itulah sebabnya hooks adalah tool yang tepat ketika Anda butuh sesuatu terjadi tanpa gagal.

Event lifecycle yang bisa Anda kaitkan

Hooks dikelompokkan berdasarkan event di settings.json. Yang paling sering dipakai adalah PreToolUse, yang berjalan sebelum sebuah tool dipanggil dan bisa memblokirnya; PostToolUse, yang berjalan setelah sebuah tool berhasil dan ideal untuk memformat atau me-lint berkas yang baru saja berubah; dan Stop, yang berjalan saat Claude selesai merespons dan menjadi gerbang mutu yang alami. Ada juga event untuk pengiriman prompt, notifikasi, dan awal sesi.

Setup awal yang umum memformat setiap berkas yang disunting dan menyaring tiap perintah Bash melalui skrip penjaga kecil:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\"" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/guard-bash.sh" }
        ]
      }
    ]
  }
}

Pola guardrail yang layak ditambahkan lebih dulu

Anda tidak butuh banyak hooks untuk merasakan manfaatnya. Beberapa yang dipilih dengan baik sudah menutup kesalahan yang paling sering dibuat agen.

• Format otomatis saat menulis: hook PostToolUse yang menjalankan Prettier, gofmt, atau Black pada berkas yang berubah, sehingga gaya tidak pernah menjadi tugas model.
• Path terlindungi: hook PreToolUse yang memblokir suntingan ke lockfile, kode ter-generate, atau konfigurasi CI, dengan menolak tulisan alih-alih mempercayai model membiarkannya.
• Gerbang tes di Stop: hook Stop yang menjalankan perintah tes cepat Anda dan melaporkan kegagalan, memberi agen sinyal otomatis untuk terus bekerja alih-alih mendeklarasikan menang terlalu dini.
• Log audit: hook yang menambahkan tiap perintah Bash ke sebuah berkas, sehingga Anda bisa meninjau setelahnya persis apa yang dijalankan agen.

Bagaimana sebuah hook memblokir tindakan berbahaya

Hook PreToolUse adalah titik penegakan. Sebelum Claude Code menjalankan tool yang cocok, ia menjalankan hook Anda dan membaca hasilnya. Jika hook keluar dengan status pemblokir, panggilan tool ditolak dan alasannya diumpankan kembali ke model, yang lalu harus memilih jalur berbeda. Beginilah cara Anda menghentikan sebuah tindakan secara deterministik alih-alih meminta model untuk tidak melakukannya.

Karena hook melihat seluruh input tool sebagai JSON, keputusannya bisa presisi: izinkan perintah Bash yang hanya membaca, tolak yang menyalurkan skrip jarak jauh ke shell, dan biarkan sisanya lewat. Model tidak bisa berkelit melewati sebuah hook, itulah persis alasan aturan yang relevan dengan keamanan berada di sini dan bukan di instruksi CLAUDE.md.

Jaga hooks tetap cepat dan terprediksi

Hooks berada di jalur kritis loop agen, jadi hook yang lambat atau labil membuat seluruh sesi terasa lambat. Beberapa kebiasaan menjaganya tetap tidak mengganggu.

• Jaga tetap cepat. Hook PostToolUse yang berjalan pada setiap suntingan sebaiknya selesai jauh di bawah satu detik, jadi targetkan berkas yang berubah, bukan build seluruh proyek.
• Gagal dengan jelas. Ketika sebuah hook memblokir tindakan, cetak alasan singkat ke standard error agar model mendapat penjelasan yang berguna alih-alih kegagalan yang buram.
• Versikan bersama repo. Commit hooks proyek di settings Anda agar seluruh tim mendapat guardrail yang sama, dan simpan yang pribadi di user settings Anda.

Hooks adalah cara Anda berhenti mengulang koreksi yang sama ke agen. Apa pun yang Anda dapati harus diminta setiap sesi, seperti format ini, jangan sentuh itu, atau jalankan tesnya sebelum berhenti, adalah kandidat untuk hook, dan begitu menjadi hook, ia terjadi entah model mengingatnya atau tidak. Mulailah dengan formatter dan gerbang tes, lalu tambahkan penjaga seiring Anda belajar di mana agen Anda tergelincir.