Cara Menulis CLAUDE.md yang Meningkatkan Output AI

CLAUDE.md adalah berkas berdaya ungkit tertinggi dalam repo berbantuan AI dan yang paling sering disalahgunakan. Ia dimuat ke konteks model secara otomatis di awal setiap sesi, yang berarti dua hal sekaligus: semua yang Anda taruh di dalamnya mengarahkan setiap tugas, dan semua yang Anda taruh di dalamnya memakan konteks pada setiap tugas. Yang terbaik menghormati kedua fakta itu.

Panduan ini membahas apa itu CLAUDE.md, di mana berkasnya berada dan bagaimana keduanya bergabung, apa yang sebenarnya layak masuk, dan mode kegagalannya, yakni kegemukan, yang diam-diam membuatnya lebih buruk. Prinsip yang sama berlaku untuk konvensi AGENTS.md yang sedang muncul yang dibaca tool lain, jadi upayanya tidak khusus Claude.

Untuk apa CLAUDE.md

CLAUDE.md adalah berkas memori: Markdown biasa yang dibaca Claude Code ke konteks saat sebuah sesi dimulai, sebelum Anda mengetik apa pun. Ia adalah tempat menyandikan pengetahuan proyek yang dibutuhkan rekan baru yang cakap pada hari pertama tetapi tidak bisa disimpulkan dari kode saja, seperti cara build dan tes, konvensi mana yang diikuti, dan apa yang tidak boleh disentuh.

Cara paling berguna memikirkannya adalah sebagai prompt tetap, bukan dokumen. Pembingkaian ulang itu menuntun ke pilihan lebih baik:

• Setiap baris bersaing untuk perhatian model, jadi fakta yang tidak mengubah perilaku tidaklah netral; ia mengencerkan fakta yang mengubah.
• Ini instruksi, bukan prosa, jadi tulis secara imperatif dan konkret: jalankan perintah tes yang persis, bukan proyek ini punya suite tes yang komprehensif.
• Ini dibaca setiap sesi, jadi konten usang justru berbahaya; perintah yang salah di CLAUDE.md diikuti dengan percaya diri, setiap kali.

Di mana berkasnya berada dan bagaimana keduanya bergabung

CLAUDE.md bersifat hierarkis. Berkas di akar proyek dibagikan dengan tim lewat repo; berkas di direktori home Anda memegang preferensi pribadi yang berlaku lintas setiap proyek; dan CLAUDE.md di dalam subdirektori diambil ketika agen bekerja di bagian pohon itu. Semuanya berlapis, sehingga aturan global, aturan proyek, dan aturan modul semua sampai ke sesi bersama-sama.

Anda juga bisa menyusun berkas dengan mengimpor yang lain, yang menjaga masing-masing tetap fokus:

# Project: billing-service

## Commands
- Build:          pnpm build
- Test one file:  pnpm vitest run path/to/file.test.ts
- Lint and fix:   pnpm lint --fix

## Conventions
- Money is always integer cents, never floats.
- API handlers live in src/routes and return typed Result objects.
- Never edit generated files under src/db/schema.

## Gotchas
- The test DB must be running: docker compose up -d db

## More detail
@docs/architecture.md

Apa yang sebenarnya layak masuk

CLAUDE.md yang kuat sebagian besar adalah hal-hal yang benar tentang proyek Anda tetapi tak terlihat oleh seseorang yang membaca satu berkas. Dalam praktik itu adalah daftar pendek.

• Perintah: invokasi build, tes, lint, dan run yang persis, termasuk mantra untuk menguji satu berkas, sehingga agen berhenti menebaknya.
• Konvensi: aturan yang tak jelas, seperti uang dalam sen bilangan bulat, error dikembalikan bukan dilempar, atau direktori ini ter-generate, yang diikuti kode tetapi tak pernah dinyatakan.
• Batasan: daftar jangan, seperti berkas yang tak boleh disunting atau perintah yang tak boleh dijalankan, yang mencegah seluruh kategori kesalahan.
• Penunjuk: tautan ke dokumen lebih dalam yang bisa dibuka agen saat membutuhkannya, sehingga detail tinggal satu lompatan alih-alih menggemukkan berkas utama.

Jaga tetap ramping dengan progressive disclosure

Mode kegagalan yang dominan adalah panjang. CLAUDE.md yang tumbuh menjadi manual 500 baris berhenti dibaca dengan saksama, baik oleh model, yang memindai, maupun oleh Anda, yang berhenti merawatnya. Disiplinnya adalah menjaga berkas yang selalu dimuat tetap pendek dan mendorong kedalaman ke berkas yang ditarik agen hanya saat relevan.

Ini adalah gagasan progressive disclosure yang sama yang dipakai skills: tingkat teratas yang ramping dengan penunjuk ke detail. Jika sebuah bagian hanya relevan untuk satu alur kerja, ia layak berada di dokumen yang dirujuk alur kerja itu, atau di sebuah skill, bukan di berkas yang dimuat pada setiap giliran terlepas dari apa yang Anda kerjakan.

Rawat seperti kode

CLAUDE.md hanya sebaik akurasinya, dan akurasi meluruh. Perlakukan berkas sebagai bagian hidup dari basis kode alih-alih langkah setup sekali jalan.

• Commit dan tinjau perubahannya di pull request, karena perubahan pada cara agen berperilaku layak mendapat kecermatan yang sama seperti perubahan pada kode.
• Pangkas terjadwal: ketika sebuah konvensi berubah atau sebuah perintah diganti nama, perbaiki CLAUDE.md di commit yang sama, dan hapus apa pun yang tak bisa Anda jamin.
• Utamakan berkas yang dikurasi manusia ketimbang yang sepenuhnya ter-generate otomatis; versi ter-generate adalah titik awal, tetapi penilaian tentang apa yang penting adalah tugas Anda untuk menambahkannya.

CLAUDE.md yang hebat itu singkat, spesifik, dan benar: sebuah brief padat yang bisa langsung ditindaklanjuti karyawan baru yang tajam, bukan ensiklopedia. Tuliskan perintahnya, konvensi yang tak jelas, dan batasannya; dorong sisanya ke balik penunjuk; dan jaga tetap jujur seiring proyek bergerak. Perbaiki itu dan setiap sesi mulai dari tempat yang lebih baik, sebelum Anda mengetik satu kata pun.