Scope Settings Claude Code: File Mana Menang, Mana Dibagikan
Scope settings Claude Code dari repo nyata: file user, project, local, dan managed, mana yang menang, apa yang dibagikan lewat git, dan cara list digabung.
Oleh Matthews WongDitinjau pada Dicek dengan Claude Code v2.1.301
Poin utama
Claude Code membaca settings dari file user, file project bersama, file project lokal, dan managed policy dari organisasi. Jika dua di antaranya mengatur key yang sama, level yang lebih tinggi menang, tetapi key berbentuk list seperti permissions.allow digabung. Hanya file project bersama yang ditujukan untuk git, jadi scope yang Anda pilih menentukan siapa yang mendapat setting itu.
Setelah pelajaran ini, Anda bisa
- Memilih scope yang tepat untuk sebuah setting: hanya Anda, hanya proyek ini, atau seluruh tim.
- Memprediksi nilai mana yang dipakai Claude Code ketika dua file mengatur key yang sama.
- Memeriksa file settings mana yang benar-benar termuat, dan menjaga file pribadi tetap di luar git.
Ikuti diagramnya langkah demi langkah
Tekan Putar, atau melangkah dengan panah. Setiap langkah juga ditulis di bawah diagram.
Satu key, empat tempat untuk mengaturnya
Key yang diatur di file user sampai ke sesi kecuali level project, local, atau managed mengaturnya lagi; setiap level yang lebih tinggi menimpa level di bawahnya, sedangkan key berbentuk list justru digabung.
Ditinjau pada 17 Oktober 2026 · Claude Code v2.1.301
Tombol: ← → langkah · Home / End · K putar atau jeda
Settings berasal dari hingga empat sumber, digambar dari yang terendah ke tertinggi. Jika satu key muncul di lebih dari satu sumber, sumber tertinggi yang memberi nilainya.
File user Anda mengatur sebuah key untuk semua proyek. Tidak ada level di atasnya yang mengatur key itu, jadi nilainya sampai ke sesi apa adanya.
// ~/.claude/settings.json "model": "A"Tim meng-commit key yang sama di file project bersama. Posisinya di atas file user Anda, jadi nilai tim menggantikan nilai Anda di proyek ini.
// .claude/settings.json (committed) "model": "B"Tebak langkah berikutnya Anda menambahkan key yang sama, bernilai C, ke file project lokal Anda. Nilai mana yang dipakai sesi Anda? (B, nilai tim yang di-commit · C, nilai lokal Anda · Keduanya, digabung)File lokal menang atas file yang di-commit, tetapi hanya untuk Anda. Claude Code menjauhkannya dari git, jadi rekan tim tetap memakai nilai B.
// .claude/settings.local.json (not in git) "model": "C"Jika organisasi Anda mengatur sebuah key di managed settings, nilai itu menang atas ketiga file. Tidak ada file Anda yang bisa menimpanya.
Tebak langkah berikutnya File user dan project masing-masing punya daftar aturan permissions.allow. Apa yang dilakukan Claude Code dengan kedua daftar itu? (Hanya memakai daftar project · Menggabungkan kedua daftar · Hanya memakai daftar user)Key berbentuk list seperti permissions.allow digabung di semua file, bukan ditimpa. Setiap file menambah aturan tanpa menghapus aturan file lain.
permissions.allow // every file contributes entries
Di scope settings Claude Code mana sebuah setting sebaiknya ditaruh?
Claude Code membaca settings dari empat file, dan organisasi juga bisa mengirim managed settings dari konsol claude.ai. Setiap sumber punya scope, yaitu siapa dan proyek mana yang terkena sebuah setting. File user, ~/.claude/settings.json, milik Anda di semua proyek di mesin itu. File project bersama, .claude/settings.json, berlaku untuk semua orang yang bekerja di folder itu, dan di repositori git file ini di-commit agar rekan tim ikut mendapatkannya.
Baca selengkapnya (2)Tutup
File project lokal, .claude/settings.local.json, hanya milik Anda di satu proyek ini. Claude Code menjauhkannya dari git saat membuat file itu: pada penulisan pertama, Claude Code menambahkan satu baris untuk file itu ke global git excludes Anda. Kalau Anda membuat file itu manual, tambahkan sendiri ke .gitignore. Managed settings datang terakhir: kebijakan keamanan dan kepatuhan yang dikirim organisasi Anda, dan tidak bisa dilonggarkan oleh file Anda sendiri.
Jadi pertanyaannya: siapa yang harus mendapat setting ini. Hook atau aturan izin yang dibutuhkan seluruh tim masuk ke file bersama. Preferensi pribadi, atau sesuatu yang masih Anda uji sebelum dibagikan, masuk ke file lokal atau file user. Repo ini mengikuti pembagian itu: .claude/settings.json yang di-commit hanya berisi satu hal yang dibutuhkan semua kontributor, yaitu hook pemeriksaan gambar, dan tidak ada yang bersifat pribadi.
Nilai mana yang menang ketika dua file settings mengatur key yang sama?
Claude Code memakai nilai dari level tertinggi yang mengatur key itu. Urutannya dari yang tertinggi: managed settings, lalu JSON yang diberikan lewat flag --settings untuk satu sesi, lalu file project lokal, lalu file project bersama, lalu file user. Key yang tidak Anda tulis di level lebih tinggi tetap memakai nilai dari level di bawahnya, jadi setiap file hanya perlu berisi key yang diubahnya.
Baca selengkapnya (2)Tutup
Key berbentuk list adalah pengecualian. Jika permissions.allow muncul di lebih dari satu file, Claude Code menggabungkan daftarnya, jadi setiap file bisa menambah entri tanpa menghapus entri file lain. Beberapa key yang berisi daftar model punya aturan sendiri, dan untuk beberapa key yang sensitif secara keamanan, Claude Code menghormati nilai yang lebih ketat dari level bawah, bahkan atas nilai managed. Environment variable sama sekali bukan level dalam tumpukan ini; untuk setiap pasangan variabel dan key, dokumentasi menyebut mana yang berlaku.
Hook berperilaku seperti list juga. Hook dari semua sumber digabung: semua hook yang terdaftar berjalan untuk event yang cocok, apa pun file yang mendefinisikannya. Karena itu hook pribadi di file user Anda berjalan berdampingan dengan hook tim yang di-commit, bukan menggantikannya.
Bagaimana memeriksa file settings Claude Code mana yang termuat?
Jalankan /status di dalam Claude Code. Tab Status punya baris Setting sources yang mendaftar setiap file settings yang dimuat untuk sesi itu, misalnya User settings atau Project local settings. Baris itu memastikan file mana yang dibaca; ia tidak menunjukkan file mana yang memasok tiap key. Untuk entri yang ditolak Claude Code, jalankan claude doctor.
Baca selengkapnya (1)Tutup
Untuk menguji satu lapisan secara terpisah, mulai dengan flag --setting-sources, yang menerima daftar user, project, dan local yang dipisah koma, seperti yang ditampilkan claude --help. File settings adalah JSON yang ketat: komentar atau koma di akhir adalah syntax error, dan dilaporkan sebagai Settings Error saat start berikutnya.
Konfigurasi nyata di balik pelajaran ini
Kutipan dari repositori yang membangun dan men-deploy situs ini, apa adanya.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "node \"${CLAUDE_PROJECT_DIR:-.}/scripts/review-blog-figures.mjs\" --hook 2>/dev/null || true",
"timeout": 30,
"statusMessage": "Checking whether the figures fit"
}
]
}
]
}
}Scope project bersama, seluruhnya. File ini di-commit, jadi setiap kontributor mendapat hook yang sama. File ini bisa sekecil itu karena tidak ada yang bersifat pribadi di sini: persetujuan yang Anda berikan di prompt disimpan ke .claude/settings.local.json yang tidak masuk git, dan preferensi Anda tetap di file user.
Kesalahan yang benar-benar membuang waktu
File lokal buatan manual ikut ter-commit
Claude Code baru menambahkan .claude/settings.local.json ke global git excludes saat pertama kali ia sendiri menulis file itu. Kalau Anda membuat file itu sendiri, belum ada yang mengabaikannya. .gitignore repo ini juga tidak mencantumkannya, jadi perlindungannya adalah pengaturan per mesin. Periksa dengan git check-ignore -v sebelum commit pertama.
Mengira file Anda mengalahkan managed settings
Tidak ada file Anda maupun flag --settings yang menimpa key managed. Kalau sebuah setting tidak mau berubah, jalankan /status dan lihat baris Setting sources untuk sumber managed, lalu tanyakan ke administratornya. Beberapa key pembatas justru sebaliknya: nilai yang lebih ketat dari scope mana pun dihormati.
Menghapus aturan dari satu file tidak menghapusnya
Karena permissions.allow digabung di semua file, aturan allow yang Anda hapus dari file bersama tetap aktif kalau file user atau lokal juga mencantumkannya. Buka setiap file yang mungkin mendefinisikannya. Claude Code juga menggabungkan aturan allow organisasi Anda dengan aturan Anda, kecuali organisasi membatasinya.
Key di file yang salah diabaikan
Beberapa key tidak pernah berlaku dari file project bersama, hanya dari settings user, local, atau managed, kecuali beberapa yang masih bisa dimatikan oleh file repositori. Kalau Claude Code mengabaikan key yang Anda commit, lihat scope key itu di referensi settings. Dan beberapa key hanya dibaca sekali saat sesi dimulai, jadi edit lalu restart.
| Scope | File | Siapa yang menerima | Masuk git? |
|---|---|---|---|
| User | ~/.claude/settings.json | Anda, di semua proyek | Tidak |
| Project bersama | .claude/settings.json | Semua orang di proyek | Ya, commit |
| Project lokal | .claude/settings.local.json | Anda, di proyek ini | Tidak, jauhkan |
| Managed | managed-settings.json, MDM, atau konsol | Semua yang dijangkau organisasi Anda | Bukan file repo |
Lakukan di komputer Anda sendiri
Anda butuh Claude Code dan satu repositori git untuk latihan. Anda akan mengatur aturan di dua scope, memastikan keduanya termuat, lalu melihat file rusak dilaporkan.
Buat file bersama, .claude/settings.json, dengan satu aturan allow. Commit file itu: ini scope yang akan diterima tim Anda.
mkdir -p .claude echo '{ "permissions": { "allow": ["Bash(git status)"] } }' > .claude/settings.json git add .claude/settings.json && git commit -m "Share a project setting"Buat file lokal secara manual dengan aturan allow yang berbeda, lalu tanyakan ke git apakah file itu diabaikan. Kalau perintahnya tidak mencetak apa pun, tambahkan sendiri file itu ke .gitignore.
echo '{ "permissions": { "allow": ["Bash(git diff)"] } }' > .claude/settings.local.json git check-ignore -v .claude/settings.local.json # no output? then: echo ".claude/settings.local.json" >> .gitignoreJalankan Claude Code lalu /status. Di tab Status, cari baris Setting sources: baris itu seharusnya menyebut project settings dan project local settings.
claude > /statusJalankan ulang dengan sebagian sumber saja lalu /status lagi. File lokal seharusnya hilang dari baris Setting sources.
claude --setting-sources user,project > /statusRusak file lokal dengan sengaja memakai koma di akhir, jalankan ulang, lalu baca Settings Error. Setelah itu jalankan claude doctor untuk detailnya. Perbaiki file itu kalau sudah selesai.
echo '{ "permissions": { "allow": ["Bash(git diff)",] } }' > .claude/settings.local.json claude # then, from a shell claude doctor
Tiga pertanyaan sebelum lanjut
Pilih jawaban untuk melihat kenapa benar atau salah. Tidak ada yang disimpan atau dinilai, jadi tebak saja dengan bebas.
Jawab dalam hati, lalu cek
1.Apa yang ditunjukkan baris Setting sources di /status, dan apa yang tidak?Lihat jawabannya
Jawaban:Baris itu mendaftar setiap file settings yang dimuat Claude Code untuk sesi itu, sehingga Anda bisa memastikan sebuah file terbaca. Baris itu tidak menyebut file mana yang memasok tiap key. Untuk entri yang ditolak, jalankan claude doctor.
2.Mengapa settings.local.json buatan manual butuh baris .gitignore sendiri?Lihat jawabannya
Jawaban:Claude Code hanya menambahkan file itu ke global git excludes saat pertama kali ia sendiri menulis file tersebut. File buatan manual belum punya perlindungan itu, dan file lokal yang ter-commit akan membagikan settings pribadi Anda.
3.Hook pribadi rekan tim dan hook tim yang di-commit sama-sama cocok dengan satu event. Apakah salah satunya menggantikan yang lain?Lihat jawabannya
Jawaban:Tidak. Hook digabung: semua hook yang terdaftar berjalan untuk event yang cocok, apa pun sumber yang mendefinisikannya.
Bahasan mendalam terkait di situs ini
Sumber
Sumber primer yang diperiksa pada tanggal riset. Ikuti tautannya untuk versi terbaru.