Catatan editor: Pada Januari 2026, keluhan Andrej Karpathy tentang Claude dalam menulis kode memicu munculnya sebuah file yang tampak kecil, tetapi sangat krusial dalam alur kerja pemrograman AI: CLAUDE.md. Forrest Chang kemudian merangkum masalah-masalah ini menjadi 4 aturan perilaku, berusaha membatasi kesalahan umum Claude saat memprogram: asumsi diam-diam, rekayasa berlebihan, merusak kode yang tidak terkait, dan kurangnya standar keberhasilan yang jelas.

Namun beberapa bulan kemudian, skenario penggunaan Claude Code sudah tidak lagi hanya “meminta model menulis sepotong kode”. Dengan munculnya Agent multi-langkah, hook yang memicu rantai, pemuatan skill, dan kolaborasi multi-repo sebagai hal yang umum, pola kegagalan baru pun mulai muncul: model kehilangan kendali dalam tugas panjang, pengujian berhasil tetapi tidak memverifikasi logika nyata, migrasi selesai tetapi melewati kesalahan secara diam-diam, dan gaya kode berbeda digabungkan secara salah.

Penulis artikel ini menguji 30 repositori dalam 6 minggu dan menambahkan 8 aturan baru berdasarkan 4 aturan awal Karpathy, berusaha mencakup masalah-masalah baru yang muncul setelah pemrograman AI berpindah dari pelengkapan tunggal menuju kolaborasi berbasis Agent.

Berikut adalah teks aslinya:

Pada akhir Januari 2026, Andrej Karpathy mengirimkan serangkaian tweet yang mengeluhkan cara Claude menulis kode. Ia menunjukkan tiga kategori masalah umum: membuat asumsi salah tanpa penjelasan, memperumit secara berlebihan, dan menyebabkan kerusakan yang tidak relevan pada kode yang seharusnya tidak diubah.

Forrest Chang melihat rangkaian tweet ini, mengorganisir keluhan-keluhan tersebut menjadi 4 aturan perilaku, menulisnya ke dalam file terpisah bernama CLAUDE.md, dan mempublikasikannya di GitHub. Proyek ini mendapatkan 5.828 star pada hari pertama peluncurannya, dikoleksi 60.000 kali dalam dua minggu, dan kini telah mencapai 120.000 star, menjadi repositori kode satu file dengan pertumbuhan tercepat di tahun 2026.

Selanjutnya, saya mengujinya pada 30 repositori dalam waktu 6 minggu.

Empat aturan ini memang efektif. Kesalahan yang sebelumnya muncul sekitar 40% waktu, pada tugas-tugas yang sesuai untuk aturan-aturan ini, turun menjadi di bawah 3%. Namun, masalahnya adalah, template ini awalnya dirancang untuk mengatasi kesalahan yang terjadi saat Claude menulis kode pada bulan Januari.

Pada Mei 2026, masalah yang dihadapi oleh ekosistem Claude Code telah berbeda: konflik antar agen, pemicuan hook berantai, konflik pemuatan skill, dan gangguan alur kerja multi-langkah lintas sesi.

Jadi, saya menambahkan 8 aturan lagi. Berikut adalah versi lengkap 12 aturan CLAUDE.md: mengapa setiap aturan layak ditambahkan, serta di mana versi asli template Karpathy akan gagal secara halus di 4 tempat.

Jika Anda ingin melewati penjelasan dan langsung menyalin untuk digunakan, file lengkap ada di akhir.

Mengapa ini penting

CLAUDE.md dari Claude Code adalah file yang paling diremehkan dalam seluruh tumpukan teknologi pemrograman AI. Sebagian besar pengembang biasanya melakukan tiga kesalahan:

Pertama, anggap sebagai tempat sampah preferensi, masukkan semua kebiasaanmu ke dalamnya, hingga akhirnya meledak menjadi lebih dari 4000 token, dan tingkat kepatuhan aturan turun menjadi 30%.

Kedua, sama sekali tidak menggunakannya dan selalu meminta ulang setiap kali. Ini akan menyebabkan pemborosan token sebesar 5 kali lipat, serta kurangnya konsistensi di antara sesi yang berbeda.

Ketiga, setelah menyalin sebuah template, Anda tidak pernah memperhatikannya lagi. Mungkin berfungsi selama dua minggu, tetapi seiring perubahan kodebase, ia akan gagal tanpa Anda sadari.

Dokumen resmi Anthropic menyatakan dengan jelas: CLAUDE.md pada dasarnya bersifat rekomendasi. Claude akan mengikuti sekitar 80% waktu. Setelah melebihi 200 baris, tingkat kepatuhan akan menurun secara signifikan karena aturan penting akan tenggelam oleh noise.

Template Karpathy menyelesaikan masalah ini: satu file, 65 baris, 4 aturan. Ini adalah batas minimum.

Namun, batas atas masih bisa lebih tinggi. Setelah menambahkan 8 aturan berikut ini, cakupannya tidak lagi hanya mencakup masalah penulisan kode yang dikeluhkan oleh Karpathy pada Januari 2026, tetapi juga mencakup masalah pengaturan Agent yang baru muncul pada Mei 2026—masalah-masalah ini belum ada ketika template asli dibuat.

4 aturan asli

Jika Anda belum melihat repositori Forrest Chang, lihat versi dasar ini:

Aturan 1: Pikirkan terlebih dahulu sebelum mengkode.

Jangan membuat asumsi diam-diam. Jelaskan asumsi Anda, ungkapkan titik-titik kompromi. Tanyakan terlebih dahulu sebelum menebak. Saat ada solusi yang lebih sederhana, ajukan keberatan secara aktif.

Aturan 2: Prioritaskan kesederhanaan.
Gunakan kode paling sedikit yang bisa menyelesaikan masalah. Jangan tambahkan fitur yang dibayangkan. Jangan buat lapisan abstraksi untuk kode sekali pakai. Jika insinyur berpengalaman menganggapnya terlalu kompleks, maka sederhanakan.

Aturan 3: Modifikasi bedah.
Hanya ubah bagian yang harus diubah. Jangan secara spontan 'mengoptimalkan' kode, komentar, atau format yang berdekatan. Jangan merekonstruksi hal-hal yang tidak rusak. Pertahankan konsistensi dengan gaya yang ada.

Aturan 4: Eksekusi berorientasi tujuan.
Tentukan kriteria keberhasilan terlebih dahulu, lalu lakukan iterasi berulang hingga verifikasi selesai. Jangan beri tahu Claude cara melakukan setiap langkah, tetapi beri tahu hasil keberhasilan yang diharapkan, biarkan ia mengiterasi sendiri.

Empat aturan ini dapat menyelesaikan sekitar 40% pola kegagalan yang saya lihat dalam sesi Claude Code tanpa pengawasan. Sisanya sekitar 60% masalah tersembunyi di wilayah kosong di bawah ini.

Saya menambahkan 8 aturan baru, dan mengapa

Setiap aturan berasal dari momen nyata: Empat aturan asli Karpathy sudah tidak cukup lagi. Di bawah ini, saya akan menjelaskan skenario tersebut terlebih dahulu, lalu memberikan aturan yang sesuai.

Aturan Karpathy tidak mencakup hal ini. Akibatnya, model mulai memutuskan masalah-masalah yang seharusnya ditangani oleh kode deterministik: apakah akan mencoba ulang panggilan API, bagaimana merutekan pesan, dan kapan melakukan upgrade pemrosesan. Hasilnya, keputusan setiap minggu berbeda-beda. Anda mendapatkan sebuah if-else yang tidak stabil, dengan biaya $0,003 per token.

Pada saat itu, ada kode yang memanggil Claude untuk "menentukan apakah harus mencoba ulang saat menghadapi 503". Awalnya berjalan dengan baik selama dua minggu, lalu tiba-tiba menjadi tidak stabil karena model mulai memperlakukan badan permintaan sebagai konteks penilaian. Strategi pencobaan ulang menjadi acak karena prompt itu sendiri bersifat acak.

CLAUDE.md tanpa batasan anggaran sama dengan cek kosong. Setiap siklus berpotensi kehilangan kendali dan berubah menjadi penumpahan konteks 50.000 token. Model tidak akan berhenti sendiri.

Pada saat itu, sesi debugging berlangsung selama 90 menit. Model terus berulang kali mengiterasi pesan kesalahan 8KB yang sama dan secara perlahan melupakan solusi apa saja yang sudah pernah dicoba. Pada akhirnya, ia mulai mengusulkan solusi yang sudah saya tolak 40 pesan sebelumnya. Jika ada anggaran token, proses ini seharusnya sudah dihentikan pada menit ke-12.

Ketika dua bagian dalam kode saling bertentangan, Claude akan mencoba menyenangkan kedua belah pihak, sehingga menghasilkan kode yang tidak koheren.

Pada saat itu, ada dua pola penanganan kesalahan di dalam repositori kode: satu menggunakan async/await dengan try/catch eksplisit, dan yang lainnya menggunakan global error boundary. Kode baru yang ditulis oleh Claude menggunakan keduanya. Akibatnya, penanganan kesalahan dilakukan dua kali. Saya membutuhkan waktu 30 menit untuk memahami mengapa kesalahan tersebut ditangkap dua kali.

Modifikasi "bedah" Karpathy memberi tahu Claude untuk tidak mengubah kode yang berdekatan. Namun, ia tidak memberi tahu Claude: pahami terlebih dahulu kode yang berdekatan. Tanpa ini, Claude akan menulis kode baru yang bertentangan dengan kode yang sudah ada sejauh 30 baris.

Pada saat itu, Claude menambahkan fungsi yang sepenuhnya identik di samping fungsi yang sudah ada, karena ia tidak membaca fungsi aslinya terlebih dahulu. Kedua fungsi melakukan hal yang sama. Namun, karena urutan import, fungsi baru menimpa fungsi lama, padahal fungsi lama telah menjadi satu-satunya standar faktual selama 6 bulan.

“Pengambilan tindakan berbasis tujuan” Karpathy menyiratkan bahwa pengujian dapat berfungsi sebagai standar keberhasilan. Namun dalam praktiknya, Claude akan menjadikan “pengujian berhasil” sebagai satu-satunya tujuan, sehingga menulis kode yang dapat melewati pengujian dangkal tetapi merusak hal-hal lain.

Pada saat itu, Claude menulis 12 pengujian untuk fungsi otentikasi, dan semuanya lulus. Namun, logika otentikasi di lingkungan produksi rusak. Pengujian-pengujian tersebut hanya memverifikasi bahwa fungsi "mengembalikan sesuatu", bukan memverifikasi apakah ia mengembalikan sesuatu yang benar. Fungsi tersebut lulus pengujian karena mengembalikan nilai konstan.

Template Karpathy secara default bersifat interaktif sekali pakai. Namun, pekerjaan Claude Code yang sebenarnya biasanya melibatkan beberapa langkah: merekonstruksi lintas 20 file, membangun fitur dalam satu sesi, dan debugging lintas beberapa commit. Tanpa checkpoint, satu kesalahan langkah dapat menyebabkan seluruh kemajuan sebelumnya hilang.

Pada saat itu, tugas rekonstruksi 6 langkah mengalami kesalahan di langkah ke-4. Ketika saya menyadarinya, Claude sudah melanjutkan langkah ke-5 dan ke-6 di atas status kesalahan tersebut. Waktu yang dibutuhkan untuk menganalisis dan memperbaiki lebih lama daripada harus mengerjakan ulang seluruh tugas. Jika ada checkpoint, masalah di langkah ke-4 bisa terdeteksi.

Di dalam kodebase yang sudah memiliki pola yang matang, Claude suka memperkenalkan gaya penulisannya sendiri. Bahkan jika gayanya "lebih baik", memperkenalkan dua pola sekaligus jauh lebih buruk daripada hanya satu pola tunggal.

Pada saat itu, Claude memperkenalkan hooks ke dalam kodebase React yang berbasis class component. Memang berjalan, tetapi sekaligus merusak pola pengujian yang ada, karena pengujian tersebut bergantung pada componentDidMount. Akhirnya butuh setengah hari untuk menghapus dan menulis ulang kode tersebut.

Kegagalan paling mahal dari Claude sering kali adalah kegagalan yang tampak seperti keberhasilan. Sebuah fungsi "berjalan", tetapi mengembalikan data yang salah; sebuah migrasi "selesai", tetapi melewati 30 catatan; sebuah pengujian "lulus", tetapi hanya karena asersinya sendiri salah.

Pada saat itu, Claude mengatakan bahwa migrasi database telah "berhasil selesai". Namun, sebenarnya ia secara diam-diam melewati 14% catatan yang menyebabkan konflik constraint. Perilaku melewati ini dicatat dalam log, tetapi tidak diungkapkan secara eksplisit. 11 hari kemudian, ketika data laporan mulai tidak normal, kami baru menemukan masalah tersebut.

Saya melacak 50 tugas representatif yang sama selama 6 minggu, mencakup 30 repositori kode, dan menguji tiga konfigurasi.

Tingkat kesalahan merujuk pada: tugas perlu diperbaiki atau ditulis ulang agar sesuai dengan niat aslinya. Kesalahan yang dihitung mencakup: asumsi diam-diam, rekayasa berlebihan, gangguan tidak relevan, kegagalan diam-diam, pelanggaran konvensi, kompromi konflik, dan melewatkan titik pemeriksaan.

Compliance rate refers to: when a rule applies, the probability that Claude will explicitly apply that rule.

Hasil yang benar-benar menarik bukan hanya penurunan tingkat kesalahan dari 41% menjadi 3%. Lebih penting lagi, dengan perluasan dari 4 aturan menjadi 12 aturan, beban kepatuhan hampir tidak bertambah, tingkat kepatuhan hanya turun dari 78% menjadi 76%, tetapi tingkat kesalahan turun lagi sebesar 8 poin persentase. Aturan baru ini mencakup pola kegagalan yang tidak ditangani oleh 4 aturan sebelumnya, dan mereka tidak bersaing untuk anggaran perhatian yang sama.

Di mana saja template Karpathy akan gagal secara diam-diam

Meskipun tidak menambahkan aturan baru, empat template aturan asli setidaknya tidak cukup di 4 tempat.

Pertama, tugas Agent yang berjalan lama.
Aturan Karpathy terutama berlaku saat Claude sedang menulis kode. Namun, apa yang terjadi ketika Claude menjalankan pipeline multi-langkah? Template asli tidak memiliki aturan anggaran, aturan checkpoint, maupun aturan 'gagal dengan keras'. Akibatnya, pipeline perlahan-lahan akan menyimpang.

Kedua, konsistensi multi-repo.
「Menyesuaikan gaya yang ada」 secara default hanya memiliki satu gaya. Namun dalam monorepo dengan 12 layanan, Claude harus memilih gaya mana yang akan disesuaikan. Aturan asli tidak memberi tahu cara memilihnya. Akibatnya, ia entah memilih secara acak, atau mencampur rata-rata beberapa gaya.

Ketiga, kualitas pengujian.
“Berorientasi pada tujuan” menganggap “uji berhasil” sebagai keberhasilan, tetapi tidak menjelaskan bahwa uji itu sendiri harus bermakna. Akibatnya, Claude menulis beberapa uji yang hampir tidak memverifikasi apa pun, tetapi uji-uji ini membuatnya salah percaya bahwa ia sangat yakin.

Keempat, perbedaan antara lingkungan produksi dan tahap prototipe.
Empat aturan yang sama dapat mencegah kode produksi menjadi terlalu kompleks, tetapi juga bisa memperlambat pengembangan prototipe. Karena pada tahap prototipe, terkadang memang diperlukan 100 baris kerangka eksploratori untuk terlebih dahulu memahami arahnya. Prinsip "sederhana dulu" Karpathy cenderung terlalu sering terpicu pada kode awal.

Delapan aturan baru ini bukan untuk menggantikan empat aturan asli Karpathy, melainkan untuk mengisi kekosongan mereka: template asli dirancang untuk skenario penulisan kode yang cenderung otomatis pada Januari 2026; namun pada Mei 2026, Claude Code telah memasuki lingkungan yang didorong oleh Agent, dengan kolaborasi multi-langkah dan multi-repo, sehingga masalah yang dihadapi keduanya berbeda.

Metode mana yang tidak berhasil

Sebelum menetapkan 12 aturan ini, saya juga mencoba beberapa solusi lain.

Tambahkan aturan yang saya lihat di Reddit / X.
Sebagian besar di antaranya hanya mengulangi empat aturan asli Karpathy dengan cara yang berbeda, atau merupakan aturan spesifik domain yang tidak dapat digeneralisasi, seperti "selalu gunakan class Tailwind". Semuanya akhirnya dihapus.

Lebih dari 12 aturan.
Saya paling banyak menguji hingga 18 aturan. Setelah melebihi 14 aturan, tingkat kepatuhan turun dari 76% menjadi 52%. Batas 200 baris adalah nyata. Setelah melebihi panjang ini, Claude akan mulai melakukan pencocokan pola sebagai "ada aturan di sini", bukan benar-benar membaca aturan satu per satu.

Aturan yang bergantung pada keberadaan alat tertentu.
Misalnya, "selalu gunakan eslint", jika di dalam proyek tidak ada eslint yang terinstal, aturan ini akan gagal, dan gagal secara diam-diam. Kemudian saya mengubahnya menjadi ekspresi yang tidak bergantung pada alat tertentu, misalnya mengganti "menggunakan eslint" menjadi "mengikuti gaya yang sudah diberlakukan di repositori kode".

Contoh ada di CLAUDE.md, bukan aturan.
Contoh lebih mendominasi konteks daripada aturan. Tiga contoh menghabiskan konteks yang kira-kira setara dengan 10 aturan, dan Claude mudah mengalami overfitting terhadap contoh. Aturan bersifat abstrak, sedangkan contoh bersifat spesifik. Oleh karena itu, sebaiknya gunakan aturan.

Hati-hati. Pikirkan dengan serius. Fokus.
Semua ini adalah noise. Tingkat kepatuhan terhadap instruksi semacam ini turun menjadi sekitar 30% karena tidak dapat diuji. Kemudian saya menggantinya dengan aturan perintah yang lebih spesifik, seperti "jelaskan asumsi secara jelas".

Beritahu Claude untuk bertindak seperti 'insinyur berpengalaman'.
Ini tidak berguna. Claude sudah merasa seperti insinyur berpengalaman. Masalah sebenarnya bukan pada apakah ia merasa demikian, tetapi pada apakah ia melakukannya. Aturan imperatif dapat mempersempit kesenjangan ini, sedangkan petunjuk identitas tidak bisa.

Versi lengkap 12 aturan CLAUDE.md

Berikut adalah versi lengkap yang dapat langsung disalin dan ditempel.

Konten ini tidak dapat ditampilkan di luar dokumen Feishu sementara waktu

Simpan sebagai CLAUDE.md di direktori akar repositori. Di bawah 12 aturan ini, tambahkan aturan khusus proyek, seperti teknologi stack, perintah pengujian, pola kesalahan, dll. Secara keseluruhan jangan melebihi 200 baris, karena setelah melebihi batas tersebut, tingkat kepatuhan terhadap aturan akan menurun secara signifikan.

Bagaimana cara menginstal

Hanya dua langkah:

1. Tambahkan 4 aturan dasar Karpathy ke dalam file CLAUDE.md Anda
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Tempelkan aturan 5–12 dalam artikel ini di bawah ini

Simpan file di direktori root repositori. >> sangat penting, fungsinya adalah menambahkan ke CLAUDE.md yang sudah ada, bukan menimpa aturan khusus proyek yang sudah Anda tulis.

CLAUDE.md bukan daftar keinginan, melainkan kontrak perilaku yang digunakan untuk menutup pola kegagalan spesifik yang telah Anda amati.

Setiap aturan harus menjawab satu pertanyaan: Apa kesalahan yang dicegahnya?

Empat aturan Karpathy mencegah pola kegagalan yang ia lihat pada Januari 2026: asumsi diam-diam, rekayasa berlebihan, kerusakan yang tidak relevan, dan standar keberhasilan yang lemah. Ini adalah dasar, jangan lewatkan.

Delapan aturan baru yang saya tambahkan mencegah pola kegagalan baru yang muncul setelah Mei 2026: siklus Agent tanpa batasan anggaran, tugas multi-langkah tanpa checkpoint, pengujian yang tampaknya dilakukan tetapi sebenarnya tidak menguji logika kunci, serta masalah menyamarkan kegagalan diam-diam sebagai keberhasilan diam-diam. Ini adalah patch inkremental.

Tentu, efeknya bervariasi tergantung individu. Jika Anda tidak menjalankan pipeline multi-langkah, aturan 10 tidak terlalu penting bagi Anda. Jika kode base Anda hanya memiliki satu gaya seragam yang sudah ditegakkan oleh lint, aturan 11 bersifat redundan. Setelah membaca 12 aturan ini, pertahankan hanya aturan-aturan yang benar-benar sesuai dengan kesalahan yang pernah Anda buat, dan hapus sisanya.

Versi CLAUDE.md dengan 6 aturan yang disesuaikan untuk pola kegagalan nyata, lebih unggul daripada versi dengan 12 aturan yang 6 di antaranya tak pernah Anda gunakan.

Penutup

Tweet Karpathy pada Januari 2026 pada dasarnya adalah keluhan. Forrest Chang mengubahnya menjadi 4 aturan. Akhirnya, 120.000 pengembang memberi bintang pada hasil ini. Dan sebagian besar dari mereka, hingga hari ini, tetap hanya menggunakan keempat aturan tersebut.

Model telah berkembang, dan ekosistem juga berubah. Agent multi-langkah, pemicu rantai hook, pemuatan skill, kolaborasi multi-repo—semua ini belum ada ketika Karpathy menulis tweet tersebut. Empat aturan lama tidak menyelesaikan masalah-masalah ini. Mereka tidak salah, tetapi tidak lengkap.

Menambahkan 8 aturan baru. 6 minggu, mencakup pengujian 30 repositori. Tingkat kesalahan turun dari 41% menjadi 3%.

Simpan artikel ini malam ini, tempel 12 aturan ini ke dalam CLAUDE.md Anda. Jika ini membantu Anda menghemat satu minggu perjalanan Claude, silakan bagikan.