Panduan Lengkap Izin Claude Code | settings.json, Hooks, dan Allowlist Dijelaskan

Claude Code memiliki kemampuan operasi file dan eksekusi perintah yang sangat powerful. Izin (permissions) adalah cara untuk mengontrol kekuatan tersebut dengan aman. Mari keluar dari kondisi “asal jalan” dan rancang Claude Code yang bekerja persis seperti yang Anda inginkan.

Artikel ini menjelaskan secara mendalam, dengan kode yang berfungsi, semua pengaturan di .claude/settings.json, pola implementasi Hooks, dan desain izin per lingkungan.

Gambaran Umum Izin

Izin Claude Code dikontrol pada 3 level.

Level	Kunci	Perilaku
Izinkan	`allow`	Dieksekusi otomatis tanpa dialog konfirmasi
Tanya	`ask`	Memerlukan persetujuan pengguna setiap kali
Tolak	`deny`	Tidak dapat dieksekusi sama sekali (diblokir dengan error)

Pengaturan secara resmi dikelola lewat settings.json. Gunakan ~/.claude/settings.json untuk pengaturan user, .claude/settings.json untuk pengaturan proyek yang dibagikan tim, dan .claude/settings.local.json untuk override pribadi. ~/.claude.json masih bisa menyimpan state seperti MCP, tetapi aturan izin sebaiknya dibahas sebagai konfigurasi settings.json.

Prioritas (tertinggi lebih dulu):
Managed settings
    > Argumen command-line
        > Local .claude/settings.local.json
            > Project .claude/settings.json
                > User ~/.claude/settings.json

Permission rules digabung antar scope dan dievaluasi dalam urutan deny -> ask -> allow

Struktur Dasar settings.json

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)"
    ]
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": []
  }
}

Nama Tool dan Sintaks Pola

Izin ditulis dalam format “NamaTool(pola argumen)”.

Daftar Tool Utama

Nama Tool	Deskripsi
`Read`	Membaca file
`Write`	Membuat file baru
`Edit`	Perubahan parsial pada file yang ada
`Bash`	Eksekusi perintah shell
`Glob`	Pencarian pola file
`Grep`	Pencarian konten
`WebFetch`	Mengambil URL
`Agent`	Meluncurkan sub-agent

Sintaks Pola

"Read(**)"          // Izinkan membaca semua file
"Read(src/**)"      // Izinkan hanya di bawah src/
"Read(*.md)"        // Izinkan hanya file .md
"Bash(npm run *)"   // Izinkan hanya perintah yang dimulai dengan npm run
"Bash(git *)"       // Izinkan semua perintah git
"Bash(rm -rf *)"    // Tolak rm -rf

** cocok dengan semua path termasuk direktori; * cocok dengan satu segmen.

Pola Praktis

Pola 1: Pengembangan Solo (relatif permisif)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm *)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git add*)",
      "Bash(node *)",
      "Bash(echo *)",
      "Bash(cat *)",
      "Bash(ls *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(rm -rf ~*)",
      "Bash(git push --force *main*)",
      "Bash(git push --force *master*)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(rm *)"
    ]
  }
}

Pola 2: Pengembangan Tim (berorientasi keamanan)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(npm run typecheck)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git branch*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git push -f*)",
      "Bash(git reset --hard*)",
      "Bash(git rebase *main*)",
      "Bash(git rebase *master*)",
      "Bash(DROP *)",
      "Bash(TRUNCATE *)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(git add*)",
      "Bash(npm install*)",
      "Bash(*deploy*)"
    ]
  }
}

Pola 3: Lingkungan Produksi (hanya baca)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git show*)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(ps *)",
      "Bash(df *)",
      "Bash(top *)"
    ],
    "deny": [
      "Write(**)",
      "Edit(**)",
      "Bash(git push*)",
      "Bash(git commit*)",
      "Bash(git reset*)",
      "Bash(rm *)",
      "Bash(mv *)",
      "Bash(*deploy*)",
      "Bash(*restart*)",
      "Bash(*kill *)"
    ],
    "ask": []
  }
}

Untuk worktree atau repo yang dekat dengan produksi, jadikan konfigurasi ini sebagai .claude/settings.json aktif dan mulai dengan claude --permission-mode plan atau dontAsk yang sudah disetujui. Ini lebih sesuai dengan model resmi scope dan permission mode daripada mengganti file settings alternatif lewat environment variable.

Pola 4: Hanya Pembuatan Konten (pola yang digunakan di situs ini)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Write(site/src/content/**)",
      "Write(content/**)",
      "Edit(site/src/content/**)",
      "Edit(content/**)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(node scripts/*)",
      "Bash(QIITA_TOKEN=* node scripts/qiita-publish.mjs)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Edit(.env*)",
      "Read(.env*)"
    ],
    "ask": [
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(bash scripts/deploy.sh*)"
    ]
  }
}

Kuncinya adalah membatasi penulisan ke direktori tertentu seperti dengan Write(site/src/content/**).

Hooks: Menjalankan Proses Sebelum dan Sesudah Izin

Hooks adalah mekanisme yang secara otomatis menjalankan perintah sebelum dan sesudah eksekusi tool. Dapat digunakan untuk pemeriksaan keamanan dan pemformatan otomatis.

PreToolUse: Hook Sebelum Eksekusi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git add*)",
        "hooks": [{
          "type": "command",
          "command": "git diff --cached --name-only | grep -E '^\\.env' && echo '🚨 Penambahan .env terdeteksi!' && exit 1 || exit 0"
        }]
      },
      {
        "matcher": "Bash(git commit*)",
        "hooks": [{
          "type": "command",
          "command": "node scripts/secret-scan.mjs"
        }]
      },
      {
        "matcher": "Bash(rm*)",
        "hooks": [{
          "type": "command",
          "command": "echo '⚠️ Perintah hapus terdeteksi. Akan dieksekusi dalam 5 detik. Ctrl+C untuk membatalkan.' && sleep 5"
        }]
      }
    ]
  }
}

Jika perintah hook mengembalikan kode keluar 1, eksekusi tool diblokir. Ini adalah poin terpenting.

PostToolUse: Hook Setelah Eksekusi

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "npx tsc --noEmit 2>&1 | head -20 || true"
        }]
      },
      {
        "matcher": "Bash(git commit*)",
        "hooks": [{
          "type": "command",
          "command": "git log --oneline -3"
        }]
      }
    ]
  }
}

PostToolUse digunakan untuk pemeriksaan pasca-eksekusi dan efek samping — misalnya, menjalankan pengecekan tipe secara otomatis setelah mengedit file atau menampilkan 3 entri log terbaru setelah commit.

Koleksi Resep Hooks Praktis

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(npm install*)",
        "hooks": [{
          "type": "command",
          "command": "echo '📦 Menambahkan paket. Harap periksa package.json.'"
        }]
      },
      {
        "matcher": "Bash(*deploy*)",
        "hooks": [{
          "type": "command",
          "command": "read -p '🚀 Akan melakukan deploy. Lanjutkan? [y/N] ' ans && [ \"$ans\" = 'y' ] || exit 1"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)|Edit(*.ts)",
        "hooks": [{
          "type": "command",
          "command": "npx eslint --fix $CLAUDE_TOOL_INPUT_FILE_PATH 2>/dev/null || true"
        }]
      }
    ]
  }
}

Mode Izin: Level Izin Saat Peluncuran

Anda juga dapat menentukan mode saat meluncurkan perintah claude.

# Mode normal (mengikuti settings.json)
claude

# Otomatis menyetujui semua operasi (berbahaya! hanya untuk lingkungan terpercaya)
claude --dangerously-skip-permissions

# Lewati hanya operasi tertentu
claude --allowedTools "Read,Grep,Glob"

# Mode non-interaktif (digunakan di CI/CD)
claude -p "Jalankan tes dan laporkan hasilnya" --dangerously-skip-permissions

--dangerously-skip-permissions hanya boleh digunakan untuk otomatisasi CI/CD atau skrip otomatisasi yang sepenuhnya dipahami, dan dihindari dalam penggunaan interaktif sehari-hari.

2026: Permission budget aman dan review tim

Di sini permission budget bukan nama fitur resmi. Artinya adalah batas operasi yang Anda izinkan berjalan otomatis pada minggu pertama penggunaan nyata. Per 1 Juni 2026, dokumentasi resmi menjelaskan bahwa permission rules dievaluasi dalam urutan deny -> ask -> allow. Hook PreToolUse dapat menambah pemeriksaan runtime, tetapi output hook tidak mengganti deny atau ask yang sudah cocok. Jadi budget pertama harus mengutamakan rollback, bukan kecepatan.

Budget awal yang aman sengaja kecil. Di allow, taruh hanya baca dan verifikasi: Read, Glob, Grep, git status, git diff, git log, npm run lint, dan npm run test. Di ask, taruh operasi yang mengubah niat: Edit, Write, git add, git commit, git push, npm install, dan deploy. Di deny, taruh yang irreversible atau sensitif: .env, secrets/**, rm -rf, git reset --hard, git push --force, curl | bash, wget | sh, dan command database produksi. bypassPermissions hanya cocok di container, VM, atau devcontainer yang bisa dibuang.

Dalam tim, review .claude/settings.json seperti kode aplikasi. Setiap PR perlu menjawab tiga pertanyaan: apakah semua allow aman jika dijalankan berulang, apakah setiap ask benar-benar checkpoint niat manusia, dan apakah deny mencakup secrets, force push, penghapusan, serta operasi produksi? Pada organisasi terkelola, admin dapat memakai server-managed settings untuk mengatur disableBypassPermissionsMode dan disableAutoMode ke "disable", lalu memakai allowManagedPermissionRulesOnly untuk menolak aturan lokal atau proyek.

Contoh kegagalan berbahaya adalah memberi allow luas pada Bash(git *) atau Bash(node *), lalu mengira Read(.env*) cukup untuk melindungi secrets. Dokumentasi resmi menyatakan deny Read dan Edit berlaku pada tool file Claude Code dan command file yang dikenali, tetapi tidak menghentikan subprocess arbitrer seperti script Node atau Python yang membuka file langsung. Untuk melindungi secrets, hindari Bash yang terlalu luas dan kombinasikan rules dengan sandbox, izin OS, serta check PreToolUse.

Tentukan pemulihan sebelum insiden. Jika edit tidak diinginkan masuk, buka /permissions untuk melihat rule aktif dan sumbernya, lalu periksa git diff. Rollback dengan git restore -p agar hunk yang benar tetap tersimpan. Untuk file untracked, jalankan git clean -n sebelum menghapus. Jika secret mungkin terbaca atau masuk transcript, memperbaiki .claude/settings.json saja tidak cukup; rotasi token.

Untuk menjadikan artikel ini policy repo, mulai dari permission budget loop dan permission audit checklist. Jika perlu template dan materi belajar siap pakai, bandingkan produk Claude Code. Untuk rollout tim, review izin, dan onboarding aman, konsultasi lebih masuk akal daripada menebak aturan sendiri.

Prioritas dan Override File Konfigurasi

Ketika beberapa file konfigurasi ada:

~/.claude/settings.json     ← User (dibagikan di semua proyek)
.claude/settings.json       ← Project (dikelola git)
.claude/settings.local.json ← Local (pribadi, gitignore)
managed-settings.json       ← Managed (policy organisasi, prioritas tertinggi)

Permission rules digabung, dan deny selalu dievaluasi sebelum allow

Tulis pengaturan tambahan pribadi di .claude/settings.local.json dan tambahkan ke gitignore. Untuk mencegah daftar deny tim di-override oleh pengaturan pribadi, desain yang aman adalah hanya menulis aturan deny di settings.json.

# Tambahkan ke .gitignore
.claude/settings.local.json

5 Jebakan Umum

1. Salah menggunakan pola wildcard

// ❌ Ini hanya cocok dengan perintah tunggal "git"
"Bash(git)"

// ✅ Juga cocok dengan git diikuti argumen
"Bash(git *)"
"Bash(git*)"  // Juga berfungsi tanpa spasi, tapi * eksplisit lebih aman

2. Lupa bahwa deny memiliki prioritas di atas ask

// Dengan konfigurasi ini, Bash(rm -rf /tmp/test) ditangkap oleh deny dan diblokir
// Tidak pernah mencapai ask
{
  "deny": ["Bash(rm -rf*)"],
  "ask": ["Bash(rm*)"]  // ← rm -rf ditangani oleh deny
}

3. Tidak memperhatikan kode keluar hook

# Jika perintah hook PreToolUse selalu mengembalikan exit 0,
# kegagalan pemindaian tidak akan memblokir eksekusi

# ❌ Tetap lolos meski ada error
"command": "node scan.mjs"

# ✅ Kontrol kode keluar secara eksplisit
"command": "node scan.mjs || exit 1"

4. Secara tidak sengaja menambahkan settings.json ke .gitignore

Beberapa tim secara tidak sengaja menambahkan settings.json—yang ingin mereka bagikan—ke .gitignore. Pendekatan yang benar adalah konfigurasi proyek di bawah git, hanya settings.local.json di gitignore.

5. Lupa beralih konfigurasi produksi secara manual

# ❌ Bekerja di produksi dengan pengaturan sehari-hari

# ✅ Mulai dengan plan mode dan pastikan .claude/settings.json worktree aman untuk produksi
claude --permission-mode plan

Mendaftarkan alias membuatnya lebih sulit dilupakan:

# ~/.bashrc or ~/.zshrc
alias claude-prod='claude --permission-mode plan'

Men-debug Konfigurasi

Ketika tidak jelas “mengapa perintah ini diblokir”:

# Periksa pengaturan saat ini
claude --print-settings 2>/dev/null || cat .claude/settings.json

# Periksa aturan mana yang cocok (mode verbose)
claude --verbose -p "Jalankan git push"

Ringkasan: Praktik Terbaik untuk Desain Izin

1. Mulai dengan deny
   → Daftarkan perintah yang tidak boleh pernah dieksekusi
   → rm -rf, git push --force, DROP TABLE wajib ada

2. Kemudian konfigurasikan ask
   → Operasi tulis dan deploy yang memerlukan konfirmasi

3. Allow untuk selebihnya
   → Operasi baca dan CI: allow semua untuk efisiensi

4. Otomatiskan keamanan dengan Hooks
   → Pemindaian pre-commit, pengecekan tipe otomatis setelah edit

5. Siapkan file konfigurasi spesifik lingkungan
   → settings.json (pengembangan), settings.production.json (produksi)

Dengan pengaturan izin yang tepat, Anda akan berhenti menekan tombol persetujuan secara mekanis dan dapat fokus hanya pada operasi yang benar-benar perlu ditinjau. Meluangkan 30 menit untuk desain awal akan membuat ratusan jam kerja mendatang menjadi lebih aman.