Tahap Pengguna, Projek dan Direktori

Fail peringkat projek terletak di akar repositori sebagai ./CLAUDE.md (atau .claude/CLAUDE.md). Oleh sebab fail ini berada dalam repositori, ia diserahkan dan dikongsi melalui kawalan versi.

Itulah yang anda perlukan untuk peraturan yang menjadi sandaran seluruh pasukan: arahan binaan, rangka kerja ujian, konvensyen seni bina, susun atur direktori dan apa-apa sahaja yang diperlukan oleh penyumbang baharu pada hari pertama.

Petua umum: jika klon baharu akan gagal tanpanya, fail itu hendaklah berada dalam CLAUDE.md peringkat projek — bukan dalam fail pengguna peribadi anda.

CLAUDE.md yang diletakkan dalam subfolder adalah terhad kepada direktori: ia hanya digunakan apabila Claude bekerja dalam subpepohon tersebut. Ini mengekalkan peraturan setempat yang khusus dekat dengan kod yang dikawalnya.

Contoh: frontend/CLAUDE.md boleh mengandungi konvensyen React/Tailwind yang tidak sesuai untuk bahagian belakang, manakala services/payments/CLAUDE.md boleh mengandungi peraturan yang hanya penting untuk kod pengebilan.

Fail peringkat direktori masih diserahkan (kerana ia berada dalam repositori), jadi fail tersebut dikongsi — tetapi jangkauannya ialah folder itu, bukan seluruh projek.

Peringkat ini memberikan konteks tambahan, bukannya pilihan yang saling mengecualikan. Apabila anda bekerja dalam subfolder, Claude boleh menggunakan fail pengguna, fail projek dan fail direktori secara bersama.

Anggaplah ia sebagai skop sepusat:

• Pengguna — jangkauan paling luas (setiap projek), khalayak paling kecil (anda sahaja).
• Projek — seluruh repositori, seluruh pasukan.
• Direktori — satu subpepohon, seluruh pasukan.

Jadi, persoalannya bukan hanya "sejauh mana khususnya peraturan ini?" tetapi juga "siapa yang perlu melihatnya — saya atau semua orang?" Khalayak menentukan pengguna berbanding projek; skop menentukan projek berbanding direktori.

Corak anti yang paling biasa ialah meletakkan peraturan yang diperlukan oleh semua orang ke dalam ~/.claude/CLAUDE.md. Peraturan itu berfungsi dengan sempurna untuk anda — jadi jurangnya tidak kelihatan — tetapi kerana fail pengguna tidak pernah dikongsi melalui VCS, rakan sepasukan baharu langsung tidak mengetahuinya.

Gejalanya: Claude mematuhi konvensyen pada mesin anda tetapi mengabaikannya pada mesin rakan sekerja, dan tiada siapa dapat mengetahui sebabnya. Penyelesaiannya sentiasa sama: pindahkan peraturan yang dikongsi ke bawah ke dalam CLAUDE.md peringkat projek (atau peringkat direktori) supaya peraturan tersebut disertakan bersama repositori.

CLAUDE.md tidak semestinya satu fail gergasi. Anda boleh memasukkan fail lain dengan import @path, supaya setiap fail kekal fokus dan mudah dibaca.

Contohnya, fail projek boleh mengimport dokumen piawaian yang dikongsi dan bukannya memasukkan ratusan baris secara sebaris. Ini memudahkan hierarki diselenggara dan membolehkan anda menggunakan semula piawaian yang sama merentas fail.

CLAUDE.md monolitik dimuatkan ke dalam konteks untuk setiap tugasan — walaupun sebahagian besarnya tidak berkaitan — lalu membazirkan token. Corak yang lebih kemas untuk peraturan khusus ialah fail .claude/rules/ dengan frontmatter YAML.

Setiap fail peraturan mengisytiharkan corak paths, dan hanya dimuatkan apabila anda menyunting fail yang sepadan. Ini memberikan ketepatan peringkat direktori sambil menjimatkan konteks, kerana peraturan yang tidak sepadan dengan fail semasa tidak akan dimasukkan.

Anda tidak perlu menyunting fail ini secara manual dalam penyunting luaran. Dalam Claude Code, arahan /memory membuka dan menyunting memori CLAUDE.md, dan perubahan tersebut kekal merentas sesi.

Untuk repositori yang benar-benar baharu, /init menyediakan CLAUDE.md peringkat projek dengan mendokumentasikan pangkalan kod, lalu memberikan titik permulaan yang munasabah untuk anda perhalus kemudian.

Pemilihan fail yang mana untuk ditulis oleh /memory masih kembali kepada keputusan yang sama: peribadi (pengguna) berbanding dikongsi (projek atau direktori).

Pembahagian pengguna berbanding projek ini bukan khusus untuk CLAUDE.md — ia ialah corak Claude Code yang konsisten. Kemahiran dan arahan menggunakan dua skop yang sama:

• Skop projek — .claude/skills/ dan .claude/commands/ dalam repositori dikongsi melalui VCS.
• Skop pengguna — ~/.claude/skills/ adalah peribadi.

Perhatikan bahawa .claude/commands/ ialah bentuk legasi dan .claude/skills/ ialah bentuk semasa, tetapi peraturan skopnya sama: repositori = pasukan, direktori utama = anda. Fahami pembahagian ini sekali dan ia terpakai di mana-mana.

Oleh sebab fail peringkat projek dan peringkat direktori diserahkan kepada kawalan versi, anggap fail tersebut seperti kod awam: jangan sekali-kali letakkan rahsia di dalamnya. Disiplin yang sama terpakai pada .mcp.json berlingkup projek (dikongsi dalam VCS) berbanding ~/.claude.json peribadi.

Untuk token dan kunci, rujuk pemboleh ubah persekitaran — contohnya ${GITHUB_TOKEN} — dan bukannya menampal nilai mentah. Fail yang dikongsi menyatakan pemboleh ubah yang mana untuk digunakan; rahsia sebenar kekal dalam persekitaran, di luar repositori dan di luar CLAUDE.md.

Pilih peringkat dengan menjawab dua soalan — siapa dan di mana:

• Pengguna (~/.claude/CLAUDE.md): peribadi, setiap projek, TIDAK dikongsi melalui VCS — rakan sepasukan baharu tidak akan mengetahuinya. Gunakan untuk pilihan peribadi sahaja.
• Projek (./CLAUDE.md): dikongsi melalui VCS, seluruh pasukan, seluruh repositori. Tempat untuk arahan binaan dan konvensyen yang diperlukan oleh semua orang.
• Direktori (subfolder CLAUDE.md): dikongsi melalui VCS tetapi terhad kepada satu subpepohon.

Pastikan fail ringkas dengan import @path dan muatkan peraturan khusus apabila diperlukan melalui .claude/rules/ dengan frontmatter paths. Jangan sekali-kali serahkan rahsia — rujuk pemboleh ubah persekitaran seperti ${GITHUB_TOKEN}. Perangkap terbesar yang perlu dielakkan ialah meletakkan peraturan pasukan dalam fail pengguna peribadi anda, yang tidak akan dilihat oleh orang lain tanpa mereka sedari.