Apa Itu Claude Code Hooks dan Bagaimana Cara Menggunakannya

Bagi Vibe Coders, alat seperti Claude Code dari Anthropic mengubah cara pengembang menulis, men-debug, dan mengelola proyek mereka. Claude Code bertindak sebagai "alat pengkodean agentik" yang berada di terminal Anda, mampu memahami seluruh basis kode Anda, berinteraksi dengan sistem file Anda, menjalankan perintah, dan bahkan menjelajahi web untuk dokumentasi. Ia unggul dalam tugas-tugas seperti menulis fitur baru, memperbaiki bug, dan merefaktor kode melalui prompt bahasa alami.

Namun, karakteristik inti dari Model Bahasa Besar (LLM) adalah sifat probabilistiknya. Meskipun ini memungkinkan pemecahan masalah yang kreatif, kadang-kadang dapat menyebabkan ketidakpastian. Anda mungkin ingin tindakan tertentu—seperti memeriksa lint file setelah diubah atau menjalankan pengujian setelah fungsi baru ditulis—terjadi setiap saat tanpa gagal. Mengandalkan LLM untuk mengingat melakukan ini di setiap contoh bisa jadi tidak konsisten.

Di sinilah Claude Code Hooks berperan. Hooks adalah fitur canggih yang menyediakan kontrol deterministik dan terprogram atas perilaku Claude Code, memastikan tindakan tertentu selalu terjadi daripada mengandalkan LLM untuk memilih menjalankannya.

Artikel ini berfungsi sebagai panduan komprehensif untuk memahami, mengkonfigurasi, dan memanfaatkan Claude Code Hooks untuk menciptakan alur kerja pengembangan yang sepenuhnya otomatis dan efisien.

Apa Itu Claude Code Hooks?

Pada intinya, Claude Code Hooks adalah perintah shell yang ditentukan pengguna yang dieksekusi secara otomatis pada titik-titik tertentu dalam siklus hidup Claude Code. Mereka bertindak sebagai pemicu yang dapat Anda konfigurasikan untuk aktif sebelum atau setelah tindakan tertentu, memungkinkan Anda menyuntikkan logika kustom, skrip, dan perintah Anda sendiri langsung ke dalam operasi Claude.

Hooks menjembatani kesenjangan antara bantuan berbasis AI dan otomatisasi berbasis aturan. Mereka memungkinkan Anda untuk menegakkan standar, mengotomatiskan tugas-tugas berulang, dan mengintegrasikan alat eksternal dengan mulus ke dalam alur kerja Anda dengan keandalan penuh.

Ada empat peristiwa siklus hidup utama di mana sebuah hook dapat dipicu:

1. PreToolUse: Dieksekusi sebelum Claude menggunakan alat tertentu (misalnya, sebelum menulis ke file).
2. PostToolUse: Dieksekusi setelah alat berhasil digunakan (misalnya, setelah file dimodifikasi).
3. Notification: Dieksekusi setiap kali Claude mengirimkan notifikasi (misalnya, ketika membutuhkan masukan pengguna atau telah menyelesaikan tugas yang panjang).
4. Stop: Dieksekusi ketika Claude selesai menghasilkan responsnya dan berhenti.

Dengan menargetkan peristiwa-peristiwa ini, Anda dapat membuat otomatisasi canggih yang mencerminkan praktik terbaik pengembangan perangkat lunak modern, seperti pemeriksaan integrasi berkelanjutan (CI), tetapi dengan kecepatan pengembangan lokal.

Anatomi Claude Code Hooks: Penyelaman Konfigurasi Mendalam

Untuk menggunakan hooks, Anda perlu menentukannya di file pengaturan Claude Code Anda. Ini dilakukan dengan menambahkan tabel [[hooks]] ke file settings.toml Anda, yang terletak di direktori .claude/ di dalam proyek Anda. Setiap konfigurasi hook memiliki beberapa komponen kunci.

# Example Hook in .claude/settings.toml

[[hooks]]
# The event that triggers the hook.
event = "PostToolUse" 

# (Optional) Conditions for the hook to run.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# The shell command to execute.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optional) Whether to run the command in the background.
run_in_background = false 

Mari kita bedah setiap bagian secara detail.

Bidang event dalam Claude Code Hooks (Wajib)

String ini menentukan peristiwa siklus hidup mana dari keempatnya yang akan memicu hook.

• "PreToolUse"
• "PostToolUse"
• "Notification"
• "Stop"

Bidang hooks.matcher dalam Claude Code Hooks (Opsional)

Matcher adalah yang memungkinkan Anda menentukan secara tepat kapan sebuah hook harus berjalan. Jika Anda menghilangkan matcher, hook akan berjalan untuk setiap instance dari event yang ditentukan. Misalnya, hook PostToolUse tanpa matcher akan aktif setelah setiap panggilan alat.

Matcher memiliki tiga bidang yang dapat Anda gunakan untuk memfilter peristiwa:

• tool_name: Sebuah string yang cocok dengan nama alat yang digunakan. Ini sempurna untuk menargetkan tindakan tertentu seperti edit_file, git_commit, atau run_command.
• file_paths: Sebuah array string yang berisi pola glob. Hook hanya akan berjalan jika file yang terlibat dalam penggunaan alat cocok dengan salah satu pola ini. Misalnya, ["*.py"] menargetkan semua file Python, sedangkan ["src/components/**/*.jsx"] menargetkan file JSX di direktori tertentu.
• query: Sebuah string yang cocok dengan masukan yang diberikan ke alat. Ini berguna untuk pemicu yang lebih spesifik, seperti menjalankan hook hanya ketika alat run_command digunakan dengan perintah yang menyertakan npm.

Bidang command untuk Claude Code Hooks (Wajib)

Ini adalah inti dari hook—perintah shell yang akan dieksekusi ketika kondisi pemicu terpenuhi. Perintah ini berjalan dengan izin yang sama dengan akun pengguna Anda, sehingga dapat melakukan apa pun yang dapat Anda lakukan di terminal Anda.

Untuk membuat perintah menjadi dinamis, Claude Code menyediakan serangkaian variabel lingkungan yang diisi dengan konteks dari peristiwa yang memicu hook.

Variabel Lingkungan yang Tersedia:

• $CLAUDE_EVENT_TYPE: Jenis peristiwa (PreToolUse, PostToolUse, dll.).
• $CLAUDE_TOOL_NAME: Nama alat yang digunakan (misalnya, edit_file).
• $CLAUDE_TOOL_INPUT: Parameter masukan mentah yang diteruskan ke alat dalam format JSON.
• $CLAUDE_FILE_PATHS: Daftar jalur file yang dipisahkan spasi yang relevan dengan panggilan alat. Ini sangat berguna untuk meneruskan file ke pemformat, linter, atau pelari pengujian.
• $CLAUDE_NOTIFICATION: Konten pesan notifikasi (hanya untuk peristiwa Notification).
• $CLAUDE_TOOL_OUTPUT: Output dari eksekusi alat (hanya untuk peristiwa PostToolUse).

Pengaturan run_in_background untuk Claude Code Hooks (Opsional)

Ini adalah nilai boolean (true atau false). Jika diatur ke true, perintah hook akan dieksekusi dalam proses terpisah, dan Claude tidak akan menunggu hingga selesai sebelum melanjutkan. Ini ideal untuk tugas yang berjalan lama seperti rangkaian pengujian komprehensif atau proses build yang tidak ingin Anda blokir tindakan Claude selanjutnya. Nilai defaultnya adalah false.

Kasus Penggunaan Praktis dan Contoh untuk Claude Code Hooks

Kekuatan sejati hooks terungkap ketika Anda menerapkannya pada alur kerja pengembangan dunia nyata. Berikut adalah beberapa contoh praktis untuk memulai.

1. Linting dan Pemformatan Otomatis dengan Claude Code Hooks

Terapkan gaya kode yang konsisten di seluruh proyek Anda secara otomatis. Hook ini menjalankan linter ruff dan pemformat black pada setiap file Python yang diedit oleh Claude.

File: .claude/settings.toml

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]

# Command to lint, fix, and format the edited Python files.
command = "echo 'Running auto-formatter...' && ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

2. Menjalankan Pengujian Otomatis dengan Claude Code Hooks

Praktik inti dari pengembangan berbasis pengujian (TDD) adalah menulis pengujian dan kemudian menulis kode untuk melewati pengujian tersebut, berulang hingga semuanya berfungsi. Anda dapat mengotomatiskan langkah "jalankan pengujian" dengan hook. Contoh ini menjalankan pytest setiap kali file di direktori src/ atau tests/ dimodifikasi.

File: .claude/settings.toml

[[hooks]]
event = "PostToolUse"
run_in_background = true # Tests can be slow, run in background.

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["src/**/*.py", "tests/**/*.py"]

# Command to run the test suite.
command = "pytest"

3. Notifikasi Desktop Kustom melalui Claude Code Hooks

Jika Anda meminta Claude untuk melakukan tugas yang berjalan lama, Anda mungkin menjauh dari komputer Anda. Hook ini menggunakan alat baris perintah seperti ntfy (layanan notifikasi pub-sub berbasis HTTP sederhana) untuk mengirimkan notifikasi push ke ponsel atau desktop Anda ketika Claude membutuhkan perhatian Anda.

File: .claude/settings.toml

[[hooks]]
event = "Notification"

# Sends the notification content to a public ntfy.sh topic.
# You can host your own for privacy.
command = 'ntfy publish my-claude-alerts "$CLAUDE_NOTIFICATION"'

4. Pemeriksaan Kewarasan Pra-Commit Menggunakan Claude Code Hooks

Mirip dengan Git hooks, Anda dapat menggunakan Claude Code Hooks untuk memastikan kualitas sebelum commit dibuat. Contoh ini menjalankan skrip kustom untuk memeriksa kunci API atau melakukan langkah validasi lainnya tepat sebelum Claude diizinkan menggunakan alat git_commit.

File: .claude/settings.toml

[[hooks]]
event = "PreToolUse"

[hooks.matcher]
tool_name = "git_commit"

# Command to run a pre-commit check script.
# The script should exit with a non-zero code to halt the commit.
command = "sh ./.claude/pre-commit-checks.sh"

Pengaturan dan Debugging Claude Code Hooks Anda

Memulai dengan hooks itu mudah, tetapi verifikasi dan debugging adalah kunci untuk memastikan mereka berfungsi seperti yang diharapkan.

1. Buat Konfigurasi Anda: Pastikan Anda memiliki file .claude/settings.toml di direktori root proyek Anda. Tambahkan konfigurasi [[hooks]] Anda di sana.
2. Verifikasi Konfigurasi: Setelah menyimpan file settings.toml Anda, jalankan perintah /hooks di dalam antarmuka terminal Claude Code. Perintah khusus ini akan menampilkan konfigurasi hook yang sedang dimuat, memungkinkan Anda untuk langsung melihat apakah Claude telah menguraikannya dengan benar.
3. Periksa Kesalahan:

• TOML Tidak Valid: Pastikan file settings.toml Anda memiliki sintaks yang valid. Tanda kurung atau kutipan yang salah tempat dapat mencegahnya dimuat.
• Masalah Perintah: Uji command Anda langsung di shell Anda untuk memastikan berfungsi seperti yang diharapkan. Periksa kesalahan ketik dan pastikan eksekusi yang diperlukan (black, pytest, ntfy, dll.) ada di PATH sistem Anda.
• Variabel Debugging: Untuk melihat nilai apa yang dimiliki variabel lingkungan, gunakan echo untuk menuliskannya ke file log. Contoh: command = "echo 'Tool: $CLAUDE_TOOL_NAME, Files: $CLAUDE_FILE_PATHS' >> /tmp/claude_hook.log"

Kesimpulan: Kekuatan Claude Code Hooks

Claude Code Hooks mengangkat alat ini dari asisten pengkodean yang sangat cakap menjadi mitra pengembangan yang terintegrasi penuh dan deterministik. Dengan mendefinisikan aturan yang sederhana namun kuat, Anda dapat mengotomatiskan bagian-bagian yang membosankan namun penting dari alur kerja Anda, membebaskan Anda untuk fokus pada aspek-aspek kompleks dan kreatif dari rekayasa perangkat lunak. Baik itu menegakkan kualitas kode, menyederhanakan loop TDD Anda, atau berintegrasi dengan layanan pihak ketiga, hooks menyediakan kerangka kerja yang kuat yang diperlukan untuk menyesuaikan Claude Code dengan kebutuhan Anda yang tepat.

Saat Anda semakin terbiasa dengan kemampuan Claude Code, mulailah dari yang kecil dengan hook pemformatan sederhana dan kemudian jelajahi otomatisasi yang lebih kompleks. Anda akan segera menemukan bahwa fitur ini penting untuk membangun lingkungan pengembangan yang dibantu AI yang dapat diprediksi, efisien, dan benar-benar personal.