Mengapa Coding Agent Mengabaikan Instruksi Anda
Instruksi berhenti tetap diabaikan agent? Pahami empat penyebabnya, termasuk aturan yang tak masuk context window dan efek compaction, lalu diagnosis sebelum menulis ulang.
Mengapa coding agent mengabaikan instruksi Anda
Coding agent mengabaikan instruksi Anda karena empat alasan, dan tidak satu pun disebabkan oleh cara Anda menyampaikannya yang terlalu sopan. Aturan tersebut tidak pernah masuk ke context window. Aturan itu terlalu samar sehingga tidak dapat digunakan untuk memeriksa suatu tindakan. Ada hal lain dalam context yang bertentangan dengan aturan tersebut, biasanya kode yang baru saja dibaca oleh agent. Atau aturan masih dimuat, tetapi berada jauh di belakang giliran saat ini, sehingga agent bekerja berdasarkan informasi yang letaknya paling dekat.
Setiap penyebab memiliki perbaikannya sendiri. Karena itu, tugas pertama adalah membedakannya. Penggunaan huruf kapital dan kata IMPORTANT bukan diagnosis. Penjelasan berikut menggunakan Claude Code sebagai contoh, karena perilaku pemuatan dan compaction-nya telah didokumentasikan secara terperinci hingga Oktober 2026. Tool lain dapat berbeda dalam detail, tetapi secara umum berperilaku dengan cara yang sama.
Pertama, dua istilah. Context window adalah blok teks yang dilihat model pada giliran tertentu: system prompt, file instruksi Anda, percakapan, dan setiap file yang telah dibaca agent. Harness adalah program di sekitar model, yaitu komponen yang membaca file dari disk dan menyusun blok tersebut. Hampir semua keluhan dalam tulisan ini sebenarnya merupakan keluhan tentang harness, bukan model.
File instruksi adalah pesan, bukan pengaturan
File instruksi bukan konfigurasi. Tidak ada komponen runtime yang membaca CLAUDE.md lalu menegakkannya. Harness membaca file tersebut dari disk dan menempelkan teksnya ke dalam percakapan. Di Claude Code, konten itu dikirim sebagai pesan pengguna setelah system prompt, sehingga model melihat aturan Anda dengan cara yang sama seperti melihat teks lain yang Anda masukkan.
Hal ini menimbulkan konsekuensi yang tidak nyaman. Aturan Anda bersaing dengan setiap teks lain di jendela percakapan dalam kedudukan yang sama. Sebuah aturan adalah klaim. File yang baru saja dibuka agen adalah bukti. Jika keduanya berbeda, bukti sering kali menang, dan tidak ada error yang muncul karena dari sudut pandang model tidak ada yang salah.
Dokumentasi resmi menyatakan hal ini secara jelas: file instruksi diperlakukan sebagai konteks, bukan konfigurasi yang ditegakkan. Untuk memblokir suatu tindakan terlepas dari keputusan model, Anda memerlukan hook, bukan kalimat. Ingat prinsip tersebut. Sebagian besar perbaikan di bagian akhir tulisan ini menerapkan prinsip itu pada kasus tertentu.
File instruksi yang dimuat dan waktunya
Claude Code menelusuri hierarki direktori ke atas, mulai dari direktori tempat Anda menjalankannya. Setiap CLAUDE.md dan CLAUDE.local.md dari root sistem berkas hingga direktori kerja Anda dimuat sepenuhnya saat peluncuran. File-file tersebut digabungkan sesuai urutan itu. Dengan demikian, file yang paling dekat dengan lokasi peluncuran dibaca terakhir, dan dalam satu direktori, file .local ditambahkan setelah file utama.
File dalam subdirektori di bawah direktori kerja Anda berperilaku berbeda. File tersebut tidak dimuat saat peluncuran. File tersebut dimuat ketika agent membaca file dalam direktori itu. Hal yang sama berlaku untuk aturan dengan cakupan path dalam .claude/rules/ yang memiliki field frontmatter paths:: aturan tersebut masuk ke konteks ketika file yang cocok dibaca, bukan pada setiap giliran. Sejak v2.1.309, file yang dimuat dengan cara ini juga memiliki batas ukuran per file, yaitu 40,000 karakter pada jendela konteks 200K. Agent hanya menerima bagian awal file yang lebih panjang, sehingga aturan di dekat akhir file bersarang yang besar mungkin tidak pernah masuk ke konteks.
Perbedaan ini menjelaskan sebagian besar kegagalan yang dilaporkan. Anda menempatkan aturan dalam packages/api/CLAUDE.md, mengajukan pertanyaan tentang API, lalu agent menjawab tanpa pernah membuka file di bawah packages/api/. Aturan tersebut tidak diabaikan. Aturan itu memang tidak pernah ada dalam konteks. Jika repositori Anda membagi panduan ke dalam file instruksi per paket dalam monorepo, periksa hal ini terlebih dahulu setiap kali.
Ada satu masalah pemuatan lain yang memengaruhi repositori yang telah menggunakan AGENTS.md sebagai standar. Sejak v2.1.277, Claude Code membaca AGENTS.md sebagai instruksi proyek secara default, tetapi hanya jika tidak ada CLAUDE.md, .claude/CLAUDE.md, atau CLAUDE.local.md di direktori kerja Anda maupun direktori mana pun di atasnya. ~/.claude/CLAUDE.md pribadi Anda tidak dihitung. Tambahkan salah satu dari file tersebut, bahkan CLAUDE.local.md untuk catatan pribadi, dan Claude Code akan membaca file CLAUDE.md Anda sebagai gantinya serta sepenuhnya mengabaikan AGENTS.md. Untuk memuat keduanya, atur Project instructions ke claude-md-and-agents-md dalam /config. Pada versi sebelum v2.1.277, atau jika Anda ingin tetap menggunakan CLAUDE.md, gunakan CLAUDE.md dengan @AGENTS.md pada baris pertamanya. File tersebut mengimpor file terkait saat peluncuran, dan Anda dapat menambahkan catatan khusus Claude di bawahnya. Symlink juga dapat digunakan jika tidak ada tambahan yang perlu ditulis. Menentukan isi file tersebut merupakan pertanyaan terpisah, yang dibahas dalam memisahkan instruksi agent dari dokumentasi manusia.
Konfirmasi bahwa file dimuat sebelum menulis ulang isinya
Jangan mengubah redaksinya sebelum Anda memastikan bahwa agent dapat melihat file tersebut. Ada dua pemeriksaan, dan pemeriksaan yang lebih sederhana dilakukan terlebih dahulu.
Jalankan /context di dalam session. Perintah ini menampilkan jendela saat ini berdasarkan kategori, dan daftar Memory files mencantumkan setiap file instruksi yang dimuat saat peluncuran. File yang tidak ada dalam daftar tersebut tidak dimuat saat peluncuran. Karena itu, apa pun yang Anda tulis di dalamnya tidak akan berpengaruh sampai file tersebut dimuat. File bertingkat di subdirektori tidak pernah muncul dalam daftar itu karena dimuat sesuai kebutuhan. Saat file tersebut dimuat, baris Loaded beserta path-nya muncul di terminal. /memory mencantumkan lokasi file dan membukanya untuk diedit, termasuk file yang belum ada.
Untuk mendapatkan jawaban yang lebih mendalam, catat proses pemuatan file. Event hook InstructionsLoaded berjalan setiap kali CLAUDE.md atau file aturan masuk ke context. Matcher-nya menunjukkan alasan file tersebut dimuat: session_start, nested_traversal, path_glob_match, include, atau compact. Masukkan konfigurasi berikut ke dalam .claude/settings.json:
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}Hook menerima payload dalam format JSON melalui standard input. Karena itu, cat menambahkan seluruh record. Pantau file tersebut dengan tail -f /tmp/instructions-loaded.log selama Anda bekerja. Status keluar dari event ini diabaikan. Jadi, hook hanya dapat mengamati dan tidak dapat memblokir. Jika file bertingkat Anda tidak pernah muncul dalam log selama session yang seharusnya memuatnya, hentikan pengubahan redaksi. Masalahnya terletak pada penempatan file. Ada satu pengecualian: AGENTS.md yang dibaca langsung oleh Claude Code tidak memicu event ini. Karena itu, cari path-nya di /memory. AGENTS.md yang diimpor dari CLAUDE.md tetap memicu event tersebut.
Dampak sesi panjang terhadap aturan Anda
Dua efek terpisah berlaku di sini, dan masing-masing memerlukan respons yang berbeda.
Jarak. Sebelum compaction berjalan, aturan yang ditulis pada turn 1 masih berada dalam context window pada turn 90. Namun, aturan tersebut kini bersaing dengan teks dari 90 turn yang lebih baru dan lebih spesifik terhadap pekerjaan yang sedang Anda lakukan. Setelah compaction berjalan, aturan yang hanya Anda ketikkan ke chat mungkin sudah tidak ada dalam context window sama sekali. Dokumentasi Claude Code sendiri memperingatkan bahwa instruksi dari awal percakapan dapat hilang. Inilah efek kedua di bawah. Anda tidak dapat mengonfigurasi jarak, tetapi Anda dapat mengukurnya. Jalankan tugas yang sama dalam sesi baru. Jika aturan tersebut berlaku dalam sesi baru tetapi gagal setelah sesi berjalan lama, penyebabnya adalah jarak atau compaction.
Compaction. Saat context window penuh, harness merangkum percakapan hingga saat itu lalu melanjutkan dari ringkasan tersebut. Hal yang bertahan adalah hal yang dianggap penting oleh peringkas. Hal ini belum tentu sama dengan hal yang Anda anggap penting. Claude Code mendokumentasikan hasilnya untuk setiap mekanisme, dan perbedaannya besar. Project root CLAUDE.md dan aturan tanpa cakupan dimuat ulang dari disk setelah compaction. Auto memory dimuat ulang dari disk. Aturan dengan frontmatter paths: hilang sampai file yang sesuai dibaca kembali. File CLAUDE.md bertingkat dalam subdirektori hilang sampai sebuah file dalam subdirektori tersebut dibaca kembali.
Urutkan instruksi Anda berdasarkan tabel tersebut. Urutan kerapuhannya akan terlihat. Aturan yang hanya Anda ketikkan ke chat adalah hal yang paling rapuh dalam sesi. Aturan tersebut hanya bertahan jika ringkasan kebetulan mempertahankannya. Aturan dalam packages/api/CLAUDE.md berada di urutan berikutnya karena aturan itu dimuat sekali, dirangkum hingga hilang, lalu kembali hanya saat pembacaan berikutnya di direktori tersebut. Aturan dalam file project root adalah yang paling tahan lama karena dibaca ulang dari disk setiap kali.
Jadi, jika sebuah instruksi harus berlaku sepanjang sesi, tempatkan instruksi tersebut dalam file project root tanpa frontmatter paths:. Hal lainnya merupakan trade-off yang harus Anda tentukan secara sengaja. Mengelola hal yang tetap berada dalam context window membahas /compact dengan argumen focus dan /clear di antara tugas yang tidak berkaitan. Keduanya memengaruhi seberapa sering peringkas dapat menentukan aturan yang Anda miliki.
Mengapa kode di sekitarnya lebih kuat daripada aturan
Inilah kegagalan yang paling sering dijelaskan orang, tetapi paling jarang didiagnosis. File Anda menyatakan bahwa akses database harus melalui lapisan repository. Agent menulis handler yang memanggil ORM (object relational mapper) secara langsung. Anda bukan diabaikan karena alasan gaya penulisan. Anda kalah oleh bukti.
Aturan menyatakan preferensi. Kode menunjukkan salah satunya. Saat agent membuka tiga file dalam modul yang akan diedit dan ketiganya memanggil ORM secara langsung, konteks berisi satu kalimat abstrak di satu sisi dan tiga contoh konkret, terbaru, serta sesuai dengan tugas di sisi lain. Menyalin pola lokal biasanya merupakan perilaku yang benar. Dalam kasus ini, tindakan tersebut salah hanya karena Anda mengetahui sesuatu yang tidak diketahui konteks: file-file itu adalah kode lama.
Jadi, tuliskan hal tersebut ke dalam aturan. Aturan yang menyebutkan bukti penyanggahnya sendiri dapat bertahan saat diterapkan pada repository nyata. Aturan yang hanya menyatakan preferensi tidak dapat melakukannya.
Akses database baru harus melaluiapp/repositories/. File di bawahapp/legacy/masih memanggil ORM secara langsung. Itu adalah kode lama, bukan polanya. Jangan menirunya.
Kalimat kedua menjalankan fungsi utama. Kalimat tersebut memberi tahu agent hal yang akan ditemukannya dan cara membacanya sebelum agent menemukannya. Perbaikan yang sama berlaku untuk aturan apa pun yang secara nyata dilanggar oleh repository Anda: gaya commit yang tidak diikuti oleh histori Anda, tata letak pengujian yang diabaikan oleh separuh test suite, atau konvensi import yang hanya berlaku pada kode baru. Jika kode tidak sesuai dengan isi file, sebutkan ketidaksesuaian tersebut di dalam file.
Aturan yang tidak jelas tidak dapat diperiksa, sehingga tidak dapat diikuti
"Write clean code." "Do not over engineer." "Keep it simple." "Be careful with migrations." Tidak satu pun dari aturan ini dapat diuji terhadap tindakan tertentu, baik oleh agent maupun oleh Anda. Agent yang diberi aturan yang tidak dapat digunakan untuk memeriksa outputnya sendiri hanya menebak, lalu Anda menilai tebakan tersebut berdasarkan perasaan.
Berikut pengujian yang harus diterapkan pada setiap baris dalam file Anda. Tulis perintah shell yang akan keluar dengan status non-zero ketika aturan tersebut dilanggar. Jika Anda tidak dapat menulis perintah itu, berarti aturan tersebut tidak dapat diperiksa. Bandingkan pasangan berikut:
- Tidak dapat diperiksa: "Keep functions small." Dapat diperiksa: "A function longer than 60 lines needs a comment above it explaining why."
- Tidak dapat diperiksa: "Test your changes." Dapat diperiksa: "Run
npm testand paste the failure count before calling a task done." - Tidak dapat diperiksa: "Keep files organised." Dapat diperiksa: "HTTP handlers live in
src/api/handlers/. Nothing else goes in that directory." - Tidak dapat diperiksa: "Format code properly." Dapat diperiksa: "Use 2 space indentation in
.tsfiles."
"Do not over engineer" adalah aturan yang paling cepat ditinggalkan orang, karena perbaikannya bukan kalimat yang lebih singkat, melainkan kalimat yang lebih panjang: menjelaskan secara rinci arti perubahan terkecil yang benar-benar berfungsi memberikan kriteria yang dapat digunakan agent untuk memeriksa diff-nya sendiri.
Ukuran file menimbulkan masalah yang sama dalam bentuk berbeda. Panduan Claude Code menargetkan kurang dari 200 baris untuk setiap file instruksi dan menyatakan secara langsung bahwa file yang lebih panjang mengurangi kepatuhan. File 700 baris bukanlah instruksi yang lebih tegas. File tersebut berisi 700 baris klaim dengan lebih banyak kemungkinan untuk saling bertentangan, dan seluruh isinya dihitung ke dalam window Anda pada setiap giliran, yang langsung terlihat dalam penggunaan token Anda. Menyusun file agar setiap aturan berada di bawah heading yang dapat dipindai pembaca dibahas dalam menulis file instruksi yang dapat ditindaklanjuti oleh agent. Lebih baik lagi, hapus bagian yang hanya menjelaskan, bukan memberikan instruksi: uraian direktori yang menunjukkan lokasi handler dan model adalah struktur yang dapat dicari agent saat diperlukan dari peta repository yang telah diuraikan, alih-alih terus membawanya dalam window pada setiap giliran.
Cara mendiagnosisnya dalam sepuluh menit
Jalankan perintah berikut secara berurutan. Melewati langkah terakhir adalah penyebab orang berakhir dengan file panjang berisi aturan yang ditulis dengan huruf kapital, tetapi tetap tidak berfungsi.
- Pastikan aturan dimuat. Jalankan
/contextdan baca daftar Memory files, atau untuk file bertingkat, cari barisLoadeddi terminal. Jika file tidak ada, perbaiki lokasinya dan berhenti. Tidak ada langkah lain dalam daftar ini yang berlaku sebelum itu. - Reproduksi dalam sesi baru. Mulai sesi baru dan berikan tugas terkecil yang seharusnya memicu aturan tersebut. Jika aturan berfungsi pada tahap ini, tetapi gagal dalam sesi yang panjang, masalahnya kemungkinan terkait jarak atau compaction. Jika aturan juga gagal di sini, masalahnya ada pada aturan itu sendiri.
- Hilangkan persaingan. Minta perubahan yang sama di direktori yang kode yang sudah ada di dalamnya mengikuti aturan tersebut. Jika kepatuhan kembali, kode di sekitarnya telah mengalahkan instruksi Anda.
- Cari konflik. Dua file yang memberikan panduan berbeda untuk perilaku yang sama merupakan kegagalan yang terdokumentasi: model dapat memilih salah satunya secara acak dan tidak akan memberi tahu Anda bahwa hal itu terjadi.
- Buat aturan dapat diperiksa, lalu uji kembali. Tulis ulang aturan dengan path konkret dan kondisi yang jelas. Peningkatan kepatuhan yang besar menunjukkan bahwa penyebabnya adalah perumusan kalimat.
Langkah 4 hanya memerlukan satu perintah. Gunakan Grep pada setiap sumber instruksi untuk mencari topik tersebut, bukan hanya pada file yang sedang Anda edit:
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/nullJika dua file memberikan instruksi yang berbeda, itulah bug Anda. Hapus salah satunya. Jangan mencoba menentukan prioritas dengan perumusan yang lebih tegas, karena tidak ada mesin pemeringkatan yang dapat digunakan. Pada Claude Code v2.1.283 atau yang lebih baru, /doctor prompt-audit menjalankan versi pencarian yang lebih luas pada instruction files, rules, dan skills Anda, lalu melaporkan kontradiksi beserta usulan edit tanpa mengubah apa pun sampai Anda memintanya.
Perbaikan berdasarkan tingkat efektivitas
Setiap langkah di bawah ini memberikan pengaruh yang lebih besar daripada langkah sebelumnya dan membutuhkan biaya penyiapan yang lebih tinggi. Mulailah dari atas saat aturan mudah diubah redaksinya. Turun ke langkah berikutnya segera setelah aturan tersebut cukup penting sehingga kegagalan sesekali tidak dapat diterima.
- Buat aturan menjadi konkret. Sebutkan path, command, atau kondisi. Tambahkan bukti tandingan yang akan ditemukan agent di repository, seperti ditunjukkan sebelumnya. Cara ini tidak memerlukan biaya dan memperbaiki banyak kasus yang tidak terduga.
- Dekatkan aturan dengan hal yang diaturnya. Gunakan
CLAUDE.mdbertingkat, aturan berdasarkan path dalam.claude/rules/, atau comment di bagian atas file itu sendiri. Dengan demikian, aturan dibaca bersamaan dengan code yang diaturnya. Terima konsekuensinya: apa pun yang dimuat dengan cara ini akan hilang pada compaction berikutnya dan muncul kembali pada pembacaan berikutnya yang sesuai. - Pindahkan penegakan aturan ke hook. Prosa hanya meminta. Hook yang memutuskan. Hook berjalan sebagai code pada event lifecycle tertentu dan berlaku terlepas dari kesimpulan model.
- Serahkan aturan kepada tool deterministik dan hapus prosanya. Formatting, urutan import, panjang baris, import yang dilarang, serta format commit message. Gunakan
ruff format,prettier --write,eslint, atau hookpre-commit. Formatter selalu benar dan tidak menghabiskan token. Kalimat biasanya benar dan menghabiskan token pada setiap giliran.
Langkah 3 secara lengkap. Misalkan file migrasi tidak boleh diedit oleh agent. Tambahkan ini ke .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}Tambahkan ini ke .claude/hooks/guard-migrations.sh:
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0Jalankan chmod +x .claude/hooks/guard-migrations.sh, lalu mulai session baru dan minta agent mengedit file di bawah migrations/. Edit tersebut ditolak, dan pesan Anda dikembalikan sebagai alasannya. Exit status 2 pada PreToolUse memblokir pemanggilan tool sebelum dijalankan, dan teks stderr Anda diberikan kepada model sebagai pesan pemblokiran. ${CLAUDE_PROJECT_DIR} mengarah ke root project, sehingga hook berfungsi dari direktori mana pun tempat agent berada. Agent tidak perlu menyetujui aturan, mengingat aturan, atau masih memiliki aturan tersebut dalam context. Edit tersebut tidak terjadi.
Untuk larangan sederhana tanpa logic, permissions.deny dalam settings Anda menjalankan fungsi yang sama tanpa script yang perlu dipelihara, dan mode permission menentukan hal yang berjalan tanpa meminta persetujuan Anda terlebih dahulu. Jika sebuah instruksi memang harus berada pada tingkat system prompt, bukan dalam user message, --append-system-prompt menempatkannya di sana. Namun, --append-system-prompt adalah launch flag yang harus diteruskan kembali pada setiap session baru, sehingga lebih sesuai untuk script daripada pekerjaan interaktif.
Hal yang tidak dapat Anda atasi hanya dengan instruksi
Jelaskan bagian mana yang menjadi tanggung jawab Anda. Penempatan, perumusan, konflik antarfile, dan ukuran file adalah masalah penulis yang harus diperbaiki oleh penulis. Selebihnya merupakan perilaku model, dan perumusan yang lebih baik tidak akan menghilangkannya.
Persetujuan bukan kepatuhan. Agent dapat mengakui suatu aturan, mengulanginya kembali dengan benar, lalu melanggarnya dua panggilan tool kemudian. Pengakuan itu tidak memerlukan biaya apa pun dan tidak memprediksi apa pun. Jangan menganggapnya sebagai perbaikan, dan jangan menghitungnya sebagai pengujian.
Beberapa kebiasaan bersifat menetap. Menambahkan komentar, menambahkan penanganan error defensif, menulis ringkasan penutup, atau menjalankan perintah berikutnya yang sudah jelas. Semua ini akan muncul kembali ketika ada aturan yang melarangnya, meskipun dengan tingkat yang lebih rendah, bukan menjadi nol. Anda dapat mengukur tingkatnya sendiri: jalankan tugas yang sama sepuluh kali dalam session baru, lalu hitung pelanggarannya. Jika jumlah tersebut harus nol, aturan itu harus dikeluarkan dari prompt. Menyatakan tugas selesai ketika sebagian tugas masih belum dikerjakan memiliki pola yang sama. Perbaikannya bersifat struktural, bukan verbal: skill unlazy mengganti kalimat tersebut dengan Depth Tree dan file gate yang harus diselesaikan agent sebelum dapat menyatakan tugas selesai.
Session Anda sendiri menjadi contoh. Jika agent melanggar aturan pada turn 12 dan Anda membiarkannya, pelanggaran tersebut kini berada dalam context sebagai demonstrasi, dan posisinya jauh lebih baru daripada aturan itu. Perbaiki pelanggaran segera setelah Anda melihatnya. Pelanggaran yang tidak diperbaiki mengajarkan perilaku tersebut kepada seluruh session.
File instruksi bukan batas keamanan. File tersebut membentuk perilaku, tetapi tidak menegakkannya. Hal-hal yang berisiko jika terlewat, seperti kredensial atau perintah destruktif, harus ditangani melalui permissions atau hook. Menjauhkan secret dari jangkauan agent menerapkan prinsip yang sama pada data: jangan meminta agent untuk tidak membaca suatu file; atur agar file tersebut tidak dapat dibaca.
Versi singkatnya: buktikan bahwa file telah dimuat, buat aturan dapat diperiksa, letakkan aturan di dekat hal yang diaturnya, dan jika tingkat pelanggaran masih penting, keluarkan aturan tersebut dari teks instruksi. Aturan yang tidak dapat diabaikan agent adalah aturan yang sejak awal tidak pernah diminta dari agent.
FAQ
Mengapa Claude Code mengabaikan CLAUDE.md saya?
Periksa apakah file tersebut dimuat sebelum menyimpulkan bahwa file itu diabaikan. Jalankan /context dan lihat daftar Memory files; file yang tidak tercantum di sana tidak dimuat saat peluncuran. File instruksi dikirim sebagai pesan pengguna setelah system prompt dan diperlakukan sebagai konteks, bukan konfigurasi yang diberlakukan, sehingga tidak ada jaminan kepatuhan yang ketat. Dalam praktiknya, penyebabnya biasanya salah satu dari empat hal: file berada di subdirektori yang tidak pernah dibaca oleh agent, dua file berisi aturan yang berbeda dan model memilih salah satunya secara arbitrer, aturan terlalu samar untuk digunakan dalam memeriksa suatu tindakan, atau kode di sekitarnya menunjukkan hal yang berlawanan dengan aturan tersebut.
Apakah mengedit file instruksi di tengah sesi mengubah sesuatu?
Tidak untuk salinan yang sudah ada dalam percakapan. File di atas working directory dimuat secara penuh saat peluncuran, sehingga teks yang dipegang model adalah teks pada saat peluncuran. Untuk memuat perubahan, mulai sesi baru atau minta agent membaca file tersebut dengan file tools normalnya. Tindakan itu memasukkan versi terbaru ke dalam percakapan sebagai pesan baru. Setelah compaction, file project root dibaca ulang dari disk, sehingga versi baru juga masuk pada saat itu.
File mana yang berlaku jika CLAUDE.md di root dan file bertingkat berisi aturan yang berbeda?
Tidak ada yang dapat diandalkan. File yang ditemukan digabungkan ke dalam konteks, bukan saling menimpa. Urutannya dimulai dari root filesystem hingga working directory, sehingga file yang paling dekat hanya dibaca terakhir. Tidak ada precedence engine yang menyelesaikan pertentangan, dan dokumentasi Claude Code menyatakan bahwa aturan yang bertentangan dapat diselesaikan secara arbitrer. Tulis file bertingkat sebagai tambahan yang menyebutkan path yang diaturnya, lalu hapus pertentangannya alih-alih mencoba membuatnya memiliki prioritas lebih tinggi.
Apakah instruksi saya tetap berlaku setelah /compact?
Bergantung pada cara instruksi tersebut dimuat. Project root CLAUDE.md, aturan tanpa cakupan, dan auto memory dimasukkan kembali dari disk setelah compaction. Aturan dengan paths: frontmatter dan file CLAUDE.md bertingkat di subdirektori akan hilang sampai file yang sesuai dibaca lagi. Apa pun yang hanya Anda ketikkan ke chat hanya tetap ada jika summariser kebetulan mempertahankannya. Jika aturan harus berlaku sepanjang sesi, letakkan aturan tersebut di file project root tanpa paths: frontmatter.
Kapan sebuah aturan sebaiknya menjadi hook, bukan prosa?
Saat pemeriksaannya deterministik dan biaya jika terlewat lebih besar daripada biaya menulis script kecil. Pembatasan path file, command yang wajib dijalankan sebelum commit, dan pemanggilan tool yang dilarang termasuk dalam kategori ini. Hook PreToolUse yang keluar dengan status 2 langsung memblokir pemanggilan tool dan meneruskan teks stderr Anda kepada model sebagai alasannya, sehingga aturan tersebut tetap berlaku terlepas dari apakah aturan itu masih ada dalam konteks. Apa pun yang dapat diputuskan oleh formatter atau linter harus ditangani oleh tool tersebut dan dihapus sepenuhnya dari file instruksi.