Catatan editor: Pada Januari 2026, keluhan Andrej Karpathy terhadap Claude dalam menulis kod memperkenalkan satu fail yang kelihatan kecil tetapi sangat penting dalam alur kerja pengaturan AI: CLAUDE.md. Forrest Chang kemudian menghimpunkan masalah-masalah ini menjadi 4 peraturan tingkah laku, cuba mengawal kesilapan biasa Claude semasa pengaturan: andaian senyap, kejuruteraan berlebihan, kerosakan kod yang tidak berkaitan, dan ketiadaan piawaian kejayaan yang jelas.

Namun, beberapa bulan kemudian, skenario penggunaan Claude Code sudah tidak lagi sekadar “meminta model menulis sepotong kod”. Dengan munculnya agen multi-langkah, pemicu rantai hook, pemuatan kemahiran, dan kerjasama pelbagai repositori kod sebagai norma, corak kegagalan baru juga muncul: model kehilangan kawalan semasa tugas panjang, ujian berjaya tetapi tidak mengesahkan logik sebenar, migrasi selesai tetapi melewatkan ralat secara senyap, dan gaya kod yang berbeza dicampurkan secara salah.

Penulis artikel ini menguji 30 repositori kod dalam tempoh 6 minggu dan menambahkan 8 peraturan baru berdasarkan 4 peraturan asal Karpathy, cuba merangkumi masalah baru yang muncul apabila pengaturcaraan AI bergerak dari pelengkapan tunggal kepada kolaborasi berasaskan Agen.

Berikut ialah teks asal:

Pada akhir Januari 2026, Andrej Karpathy menghantar satu siri tweet mengeluh tentang cara Claude menulis kod. Beliau menunjukkan tiga kategori masalah typikal: membuat andaian yang salah tanpa penerangan, memperumitkan secara berlebihan, dan menyebabkan kerosakan yang tidak berkaitan pada kod yang sepatutnya tidak diubah.

Forrest Chang melihat rantai tweet ini, mengumpulkan keluhan tersebut menjadi 4 peraturan tingkah laku, menulisnya ke dalam fail terpisah CLAUDE.md, dan menerbitkannya di GitHub. Projek ini mendapat 5.828 bintang pada hari pertama pelancaran, dikumpul sebanyak 60.000 kali dalam dua minggu, dan kini memiliki 120.000 bintang, menjadikannya repositori kod satu fail dengan pertumbuhan paling pantas pada tahun 2026.

Selepas itu, saya menguji ia menggunakan 30 repositori dalam tempoh 6 minggu.

Empat peraturan ini memang berkesan. Kesilapan yang sebelumnya berlaku sekitar 40% kebarangkalian telah turun kepada kurang daripada 3% dalam tugas-tugas yang sesuai untuk peraturan-peraturan ini berfungsi. Tetapi masalahnya ialah, templat ini asalnya dicipta untuk menyelesaikan kesilapan yang berlaku semasa Claude menulis kod pada bulan Januari.

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

Jadi, saya menambahkan 8 peraturan lagi. Berikut adalah versi lengkap 12 peraturan CLAUDE.md: mengapa setiap peraturan patut ditambahkan, dan di mana templat asli Karpathy akan gagal secara halus di 4 tempat.

Jika anda ingin melangkau penjelasan dan menyalin serta menggunakannya terus, fail lengkap berada di akhir teks.

Mengapa ini penting

Fail CLAUDE.md milik Claude Code ialah fail yang paling diabaikan dalam keseluruhan tumpukan teknologi pengaturcaraan AI. Kebanyakan pembangun biasanya melakukan tiga jenis kesilapan:

Pertama, anggap ia sebagai tong sampah preferensi, masukkan semua kebiasaan anda ke dalamnya, sehingga meledak hingga lebih dari 4000 token, dan tingkat kepatuhan terhadap peraturan turun menjadi 30%.

Kedua, lebih baik tidak menggunakannya sama sekali dan meminta semula setiap kali. Ini akan menyebabkan pembaziran token sebanyak 5 kali ganda dan kurangnya konsistensi antara sesi-sesi yang berbeza.

Ketiga, selepas menyalin satu templat, anda tidak lagi memperhatikannya. Ia mungkin berfungsi selama dua minggu, tetapi seiring perubahan pada kod pangkalan, ia akan menjadi tidak berfungsi tanpa anda sedari.

Dokumen rasmi Anthropic menyatakan dengan jelas: CLAUDE.md pada dasarnya bersifat bersifat cadangan. Claude akan mengikuti sekitar 80% masa. Selepas melebihi 200 baris, kadar kepatuhan akan menurun secara ketara kerana peraturan penting akan ditenggelamkan oleh gangguan.

Templat Karpathy menyelesaikan masalah ini: satu fail, 65 baris, 4 peraturan. Ini adalah piawaian minimum.

Tetapi had atas boleh lebih tinggi lagi. Selepas menambah 8 peraturan berikut, ia tidak hanya merangkumi masalah penulisan kod yang dikeluhkan oleh Karpathy pada Januari 2026, tetapi juga masalah pengaturan Agen yang baru muncul pada Mei 2026—masalah-masalah ini tidak wujud ketika templat asal ditulis.

4 peraturan asal

Jika anda belum melihat repositori Forrest Chang, lihat versi asas ini terlebih dahulu:

Peraturan 1: Fikir terlebih dahulu sebelum mengod.

Jangan membuat andaian secara diam-diam. Nyatakan andaian anda, tunjukkan titik kompromi. Tanyakan terlebih dahulu sebelum menebak. Apabila terdapat penyelesaian yang lebih mudah, nyatakan keberatan secara aktif.

Peraturan 2: Keutamaan kepada yang mudah.
Gunakan kod paling sedikit yang boleh menyelesaikan masalah. Jangan tambah fungsi yang dibayangkan. Jangan reka lapisan abstrak untuk kod sekali pakai. Jika jurutera berpengalaman akan menganggapnya terlalu kompleks, maka permudahkan.

Peraturan 3: Pemodifikasian secara pembedahan.
Hanya ubah bahagian yang perlu diubah. Jangan secara spontan 'mengoptimumkan' kod, komen, atau format bersebelahan. Jangan mentadbir semula perkara yang tidak rosak. Kekalkan gaya yang selari dengan yang sedia ada.

Peraturan 4: Laksanakan dengan berorientasi pada tujuan.
Tentukan standard kejayaan terlebih dahulu, kemudian lakukan iterasi berulang-ulang sehingga pengesahan selesai. Jangan beritahu Claude apa yang perlu dilakukan pada setiap langkah, tetapi beritahu ia seperti apa hasil kejayaan seharusnya, biarkan ia beriterasi sendiri.

Empat peraturan ini dapat menyelesaikan sekitar 40% mod kegagalan yang saya lihat dalam sesi Claude Code tanpa pengawasan. Sebanyak 60% masalah yang tersisa bersembunyi di ruang kosong di bawah ini.

Saya menambahkan 8 peraturan baru, dan mengapa

Setiap peraturan berasal dari satu momen nyata: Empat peraturan asal Karpathy sudah tidak mencukupi. Saya akan menerangkan skenario tersebut terlebih dahulu, kemudian memberikan peraturan yang berkaitan.

Peraturan Karpathy tidak merangkumi perkara ini. Oleh itu, model mula membuat keputusan tentang perkara-perkara yang sepatutnya ditangani oleh kod penentu: sama ada mengulangi panggilan API sekali lagi, bagaimana menghantar mesej, dan bila meningkatkan pemprosesan. Hasilnya, keputusan setiap minggu berbeza-beza. Anda mendapat satu bentuk if-else yang tidak stabil yang dikenakan caj sebanyak 0.003 dolar setiap token.

Pada masa itu, terdapat kod yang memanggil Claude untuk "menentukan sama ada perlu mencuba semula apabila berjumpa dengan 503". Ia berfungsi dengan baik pada awalnya, berterusan selama dua minggu, tetapi kemudian tiba-tiba menjadi tidak stabil kerana model mula menganggap badan permintaan sebagai konteks penilaian. Strategi percubaan semula menjadi rawak kerana prompt itu sendiri adalah rawak.

CLAUDE.md tanpa batasan bajet adalah seperti cek kosong. Setiap kitaran berpotensi kehilangan kawalan dan menjadi penumpahan konteks 50,000 token. Model tidak akan berhenti dengan sendirinya.

Masa itu adalah seperti berikut: sesi penyahpepijatan berlangsung selama 90 minit. Model terus berulang-ulang pada sepotong maklum balas ralat 8KB yang sama dan perlahan-lahan lupa tentang penyelesaian yang telah dicuba sebelumnya. Pada akhirnya, ia mula mencadangkan semula penyelesaian yang sudah saya tolak 40 mesej sebelumnya. Jika terdapat anggaran token, proses ini sepatutnya dihentikan pada minit ke-12.

Apabila dua bahagian dalam repositori kod bertentangan satu sama lain, Claude akan cuba memuaskan kedua-dua belah, hasilnya ialah kod yang tidak koheren.

Pada masa itu, terdapat dua pola penanganan ralat dalam repositori kod: satu menggunakan async/await dengan try/catch eksplisit, dan yang lain menggunakan global error boundary. Kod baru yang ditulis oleh Claude menggunakan kedua-duanya. Akibatnya, penanganan ralat dilakukan dua kali. Saya mengambil masa 30 minit untuk memahami mengapa ralat itu ditelan dua kali.

Pengubahahan "bedah" Karpathy memberitahu Claude untuk tidak mengubah kod bersebelahan. Tetapi ia tidak memberitahu Claude: fahami dahulu kod bersebelahan. Tanpa ini, Claude akan menulis kod baru yang bertentangan dengan kod sedia ada yang berjarak 30 baris.

Pada masa itu, Claude menambahkan fungsi yang sepenuhnya sama bersebelahan dengan fungsi yang sudah ada, kerana ia tidak membaca fungsi asal terlebih dahulu. Kedua-dua fungsi melakukan perkara yang sama. Namun, disebabkan urutan import, fungsi baharu menimpa fungsi lama, sedangkan fungsi lama telah menjadi satu-satunya piawaian sebenar selama 6 bulan.

"Eksekusi berorientasi tujuan" Karpathy mengimplikasikan bahawa ujian boleh dijadikan ukuran kejayaan. Tetapi dalam amalan, Claude akan menjadikan "uji lulus" sebagai satu-satunya tujuan, dan menulis kod yang boleh lulus ujian cetek tetapi merosakkan perkara lain.

Pada masa itu, Claude menulis 12 ujian untuk fungsi pengesahan, dan semuanya lulus. Tetapi logik pengesahan dalam persekitaran pengeluaran rosak. Ujian-ujian itu hanya mengesahkan bahawa fungsi itu "mengembalikan sesuatu", bukan mengesahkan sama ada ia mengembalikan sesuatu yang betul. Fungsi itu lulus ujian kerana ia mengembalikan nilai malar.

Templat Karpathy secara lalai menggunakan interaksi satu kali. Namun, kerja sebenar Claude Code biasanya melibatkan beberapa langkah: merekabentuk melalui 20 fail, membina ciri dalam satu sesi, dan memperbaiki ralat melalui beberapa commit. Tanpa titik semak, kesilapan satu langkah boleh menyebabkan semua kemajuan sebelumnya hilang.

Pada masa itu, tugas rekonstruksi 6 langkah mengalami ralat pada langkah ke-4. Apabila saya sedar, Claude sudah melanjutkan langkah ke-5 dan ke-6 di atas keadaan ralat tersebut. Masa yang diambil untuk menganalisis dan memperbaiki lebih lama daripada melakukan keseluruhan tugas semula. Sekiranya terdapat titik semakan, ralat pada langkah ke-4 boleh dikenal pasti.

Dalam kod base yang sudah mempunyai corak yang matang, Claude suka memperkenalkan gaya penulisan sendiri. Walaupun gayanya lebih baik, memperkenalkan corak kedua sendiri lebih buruk daripada sebarang corak tunggal.

Pada masa itu, Claude memperkenalkan hooks ke dalam kod base React yang berdasarkan class component. Ia berfungsi, tetapi ia merosakkan corak ujian asal kod tersebut kerana ujian-ujian itu bergantung kepada componentDidMount. Akhirnya, ia mengambil separuh hari untuk menghapus dan menulis semula.

Kegagalan paling mahal Claude seringkali adalah yang kelihatan seperti kejayaan. Satu fungsi「berjalan」, tetapi mengembalikan data yang salah; satu migrasi「selesai」, tetapi melewatkan 30 rekod; satu ujian「lulus」, tetapi hanya kerana pernyataan itu sendiri salah.

Pada masa itu, Claude mengatakan bahawa migrasi pangkalan data telah "berjaya selesai". Namun, sebenarnya ia secara senyap melangkau 14% rekod yang mengalami konflik sekatan pemicu. Tindakan melangkau ini dicatatkan dalam log, tetapi tidak dinyatakan secara jelas. 11 hari kemudian, apabila data laporan mula menunjukkan anomali, kami baru menyedari masalah tersebut.

Dalam masa 6 minggu, saya memantau sekumpulan 50 tugas perwakilan yang sama, merangkumi 30 repositori kod, dan menguji tiga konfigurasi.

Kadar kesalahan merujuk kepada: tugas perlu diperbetulkan atau ditulis semula agar sejajar dengan niat asal. Kesalahan yang dihitung termasuk: andaian kesalahan senyap, kelebihan kejuruteraan, gangguan tidak relevan, kegagalan senyap, melanggar perjanjian, kompromi konflik, dan melewatkan titik semakan.

Kepatuhan merujuk kepada kebarangkalian bahawa Claude akan secara eksplisit mengaplikasikan peraturan tersebut apabila peraturan tersebut berlaku.

Keputusan yang benar-benar menarik bukan hanya kerana kadar kesalahan turun dari 41% kepada 3%. Lebih penting lagi, apabila jumlah peraturan diperluaskan dari 4 kepada 12, beban kepatuhan hampir tidak bertambah, kadar kepatuhan hanya berubah dari 78% kepada 76%, tetapi kadar kesalahan turun lagi sebanyak 8 peratus. Peraturan baru yang ditambahkan menangani mod kegagalan yang tidak diliputi oleh 4 peraturan asal, dan mereka tidak bersaing untuk mendapatkan anggaran perhatian yang sama.

Di mana sahaja templat Karpathy akan gagal secara senyap

Walaupun tidak menambah peraturan baru, empat templat peraturan asal juga tidak mencukupi di sekurang-kurangnya 4 tempat.

Pertama, tugas Agent yang berjalan dalam jangka masa panjang.
Peraturan Karpathy terutama berfokus pada ketika Claude sedang menulis kod. Tetapi apa yang berlaku apabila Claude menjalankan pipeline berlangkah banyak? Templat asal tidak mempunyai peraturan bajet, peraturan checkpoint, atau peraturan 'gagal dengan nyaring'. Oleh itu, pipeline akan perlahan-lahan menyimpang.

Kedua, konsistensi pelbagai repositori kod.
“Menyesuaikan gaya yang ada” secara lalai hanya mempunyai satu gaya. Tetapi dalam monorepo yang mempunyai 12 perkhidmatan, Claude mesti memilih gaya mana yang hendak disesuaikan. Peraturan asal tidak memberitahunya bagaimana untuk memilih. Oleh itu, ia sama ada memilih secara rawak atau mencampurkan beberapa gaya secara saksama.

Ketiga, kualiti ujian.
“Melaksanakan berdasarkan sasaran” menganggap “ujian lulus” sebagai kejayaan, tetapi tidak menjelaskan bahawa ujian itu sendiri mesti bermakna. Akibatnya, Claude menulis ujian yang hampir tidak memverifikasi apa-apa, tetapi ujian-ujian ini membuatnya salah sangka bahawa ia sangat yakin.

Keempat, perbezaan antara persekitaran pengeluaran dan peringkat prototaip.
Empat peraturan yang sama boleh mencegah kod pengeluaran daripada kelebihan kejuruteraan, tetapi juga boleh memperlambat pembangunan prototaip. Ini kerana tahap prototaip kadang-kadang memang memerlukan 100 baris kerangka eksploratori untuk mengenal pasti arah terlebih dahulu. Pendekatan "ringkas dahulu" Karpathy mudah terpicu secara berlebihan dalam kod awal.

Oleh itu, 8 peraturan tambahan ini bukan untuk menggantikan 4 peraturan asal Karpathy, tetapi untuk memperbaiki kekosongan mereka: templat asal sesuai dengan skenario penulisan kod yang lebih berfokus pada pengisian automatik pada Januari 2026; tetapi pada Mei 2026, Claude Code telah memasuki persekitaran yang digerakkan oleh Agen, berlangkah banyak dan bekerjasama antara banyak repositori kod, dan kedua-duanya menghadapi masalah yang berbeza.

Apakah kaedah yang tidak berkesan

Sebelum menetapkan 12 peraturan ini, saya juga pernah mencuba beberapa penyelesaian lain.

Masukkan peraturan yang saya lihat di Reddit / X.
Sebahagian besar daripadanya hanya mengulangi semula 4 peraturan asal Karpathy dengan cara yang berbeza, atau merupakan peraturan khusus bidang yang tidak boleh digeneralisasi, seperti "sentiasa gunakan class Tailwind". Semuanya akhirnya dipadamkan.

Lebih daripada 12 peraturan.
Saya hanya menguji sehingga 18 aturan. Selepas 14 aturan, kadar kepatuhan turun dari 76% kepada 52%. Had 200 baris adalah nyata. Selepas melepasi panjang ini, Claude akan bermula mencocokkan pola sebagai "di sini ada peraturan", bukan membaca peraturan satu-satu.

Peraturan yang bergantung pada keberadaan alat tertentu.
Sebagai contoh, "sentiasa gunakan eslint", sekiranya eslint tidak dipasang dalam projek, peraturan ini akan gagal, dan gagal secara senyap. Kemudian saya mengubahnya kepada ungkapan yang tidak bergantung pada alat tertentu, seperti menukar "guna eslint" kepada "ikuti gaya yang telah dikenakan dalam repositori kod".

Contoh dalam CLAUDE.md, bukan peraturan.
Contoh lebih mendominasi konteks berbanding peraturan. Tiga contoh menghabiskan konteks yang hampir setara dengan 10 peraturan, dan Claude mudah mengalami overfitting terhadap contoh. Peraturan adalah abstrak, manakala contoh adalah spesifik. Oleh itu, sepatutnya menggunakan peraturan.

Berhati-hati. Fikirkan dengan teliti. Fokuslah.
Semuanya ini adalah gangguan. Kepatuhan terhadap arahan semacam ini turun ke sekitar 30% kerana ia tidak boleh diuji. Kemudian, saya menggantikannya dengan peraturan perintah yang lebih spesifik, seperti "nyatakan andaian dengan jelas".

Beritahu Claude untuk bertindak seperti "jurutera berpengalaman".
Ini tidak berfungsi. Claude sudah merasa dirinya seperti jurutera berpengalaman. Masalah sebenarnya bukan sama ada ia berfikir begitu, tetapi sama ada ia melaksanakannya begitu. Peraturan imperatif boleh mengurangkan jurang ini, tetapi petunjuk identiti tidak.

Versi lengkap 12 peraturan CLAUDE.md

Versi penuh yang boleh disalin dan dilekatkan secara langsung berikut ini.

Kandungan ini tidak boleh ditunjukkan di luar dokumen Feishu sementara waktu

Simpan sebagai CLAUDE.md di direktori akar repositori. Di bawah 12 peraturan ini, tambahkan peraturan khas projek, seperti teknologi, arahan ujian, corak ralat, dsb. Keseluruhan tidak melebihi 200 baris, kerana selepas itu, tahap kepatuhan terhadap peraturan akan menurun ketara.

Bagaimana untuk memasang

Hanya dua langkah:

1. Tambahkan 4 peraturan asas Karpathy ke dalam CLAUDE.md anda
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Salin peraturan 5–12 dalam teks ini di bawah

Simpan fail di akar repositori. >> di sini sangat penting, fungsinya adalah untuk menambahkan ke CLAUDE.md yang sudah ada, bukan menimpa peraturan khusus projek yang telah anda tulis.

CLAUDE.md bukan senarai harapan, tetapi satu perjanjian tingkah laku untuk menutup corak kegagalan spesifik yang telah anda perhatikan.

Setiap peraturan harus menjawab satu soalan: ia mencegah kesilapan apa?

Empat peraturan Karpathy mencegah corak kegagalan yang dilihatnya pada Januari 2026: andaian senyap, kejuruteraan berlebihan, kehancuran yang tidak berkaitan, dan standard kejayaan yang lemah. Ini adalah asas, jangan langkau.

Oleh kerana saya menambah 8 peraturan baru untuk mencegah corak kegagalan baru yang akan muncul selepas Mei 2026: kitaran Agen tanpa batasan bajet, tugas berbilang langkah tanpa checkpoint, ujian yang kelihatan seperti telah diuji tetapi sebenarnya tidak menguji logik penting, serta masalah mengubah kegagalan senyap menjadi kejayaan senyap. Ini adalah pampasan bertambah.

Tentu, kesan spesifik berbeza-beza mengikut individu. Jika anda tidak menjalankan pipeline berbilang langkah, Peraturan 10 tidak begitu penting untuk anda. Jika kod anda hanya mempunyai satu gaya seragam yang sudah ditegakkan oleh lint, Peraturan 11 adalah berlebihan. Selepas membaca 12 peraturan ini, kekalkan hanya peraturan yang benar-benar berkaitan dengan kesilapan yang pernah anda buat, dan buang yang lain.

Versi CLAUDE.md dengan 6 peraturan yang disesuaikan untuk pola kegagalan sebenar, lebih baik daripada versi dengan 12 peraturan di mana 6 daripadanya anda tidak akan pernah gunakan.

Penutup

Tweet Karpathy pada Januari 2026 pada dasarnya adalah keluhan. Forrest Chang menjadikannya 4 peraturan. Akhirnya, 120,000 pembangun memberi Star pada hasil ini. Dan kebanyakan daripada mereka hari ini masih hanya menggunakan 4 peraturan itu.

Model telah maju, dan ekosistem juga berubah. Agent berlangkah banyak, pemicu rantai hook, pemuatan skill, kerjasama pelbagai repositori kod—semua ini tidak wujud ketika Karpathy menulis tweet itu. Empat peraturan asal tidak menyelesaikan masalah-masalah ini. Ia tidak salah, tetapi tidak lengkap.

Tambah 8 peraturan baru. 6 minggu, meliputi ujian 30 repositori. Kadar ralat turun dari 41% kepada 3%.

Simpan artikel ini malam ini, salin 12 peraturan ini ke dalam CLAUDE.md anda. Jika ia membantu anda mengelakkan seminggu perjalanan yang salah dengan Claude, sila kongsikan.