💡 6月15日の課金分離まで22日。 自動の使用 (
claude -p、 GitHub Actions、 SDK) は別の月次の枠に分離、 公式の値段で消費。 Migration Playbook Edition 2 ($19) で、 Path A / B' / D の判定の手引きと cache の費用の計算の経路を articulate。
settings.jsonとは
📕 5月22日発売の Claim-Verify Handbook。 完了の主張が届くが実態の道具の呼び出しが0件の事例を130件の corpus で整理。 試し読み (約16,000字、 章1の全件) で章の構造と15件の本文の事例の articulate を読める。
Claude Codeの挙動を制御するJSON設定ファイル。パーミッション、フック、環境変数などをここで定義する。GUIではなくファイル直編集が基本。
ファイルの配置場所と優先順位
settings.jsonは3つの階層がある。下に行くほど優先度が高い。
| ファイル | スコープ | 用途 |
|---|---|---|
~/.claude/settings.json |
全プロジェクト共通（ユーザーレベル） | どのプロジェクトでも適用したい設定 |
.claude/settings.json |
プロジェクト単位 | チームで共有する設定（git管理対象） |
.claude/settings.local.json |
プロジェクト単位（ローカル） | 個人設定の上書き（gitignore推奨） |
優先順位: local > project > user
同じキーが複数ファイルにある場合、より局所的なファイルが勝つ。たとえばユーザーレベルでrm -rfをdenyしていても、プロジェクトのlocalでallowしていればそちらが適用される。
permissions — 許可と拒否
パーミッションはClaude Codeがツールを実行する際の承認ルールを決める。
defaultMode
{
"permissions": {
"defaultMode": "default"
}
}
| 値 | 挙動 |
|---|---|
"default" |
未登録のコマンドは都度確認を求める |
"dontAsk" |
全コマンドを自動承認（フックは引き続き実行される） |
"bypassPermissions" |
フックも含めて全てスキップ（非推奨） |
"bypassPermissions"はフックによる安全機構まで無効化する。自律運用するなら"dontAsk" + フックの組み合わせが正解。
allow — 自動承認リスト
{
"permissions": {
"allow": [
"Bash(git status:*)",
"Bash(npm test:*)",
"Read(*)",
"Edit(*)",
"Glob(*)",
"Grep(*)"
]
}
}
パターン構文:
-
Tool(pattern)— ツール名と引数パターンの組み合わせ -
*— ワイルドカード（何にでもマッチ） -
:— コマンドと引数の区切り -
Bash(git:*)—gitで始まるコマンド全般 -
Bash(*)— 全Bashコマンド（危険。フックと併用すること）
deny — 常時拒否リスト
{
"permissions": {
"deny": [
"Bash(rm -rf:*)",
"Bash(git push --force:*)",
"Bash(sudo:*)"
]
}
}
注意: allowもdenyも、cd /path && git pushのような複合コマンドにはマッチしない（既知の制限）。確実にブロックしたい場合はフックを使う。
hooks — ツール実行の前後に処理を差し込む
フックはsettings.jsonの中で最も強力な機能。ツール実行の前後にシェルスクリプトを挟み、ブロック・承認・入力の書き換えなどができる。
基本構造
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/destructive-guard.sh"
}
]
}
]
}
}
フックイベント一覧
| イベント | タイミング | 主な用途 |
|---|---|---|
PreToolUse |
ツール実行前 | 危険コマンドのブロック、自動承認 |
PostToolUse |
ツール実行後 | 構文チェック、出力検証 |
Stop |
セッション停止時 | ログ記録、通知送信 |
Notification |
通知表示時 | カスタムアラート |
PermissionRequest |
パーミッション確認時 | 自動承認・自動拒否 |
UserPromptSubmit |
ユーザー入力確定時 | プロンプト検証 |
PreCompact |
コンテキスト圧縮前 | 状態の保存 |
SessionStart |
セッション開始時 | 初期化処理 |
SessionEnd |
セッション終了時 | クリーンアップ |
matcher — どのツールに適用するか
| matcher値 | 対象 |
|---|---|
"Bash" |
Bashツールのみ |
"Edit|Write" |
EditまたはWriteツール |
"Read" |
Readツールのみ |
"" (空文字) |
全ツール |
exit codeの意味
| コード | 意味 |
|---|---|
| 0 | 許可（意見なし） |
| 2 | ブロック — ツール呼び出しをキャンセル |
| その他 | エラー（許可として扱われる） |
ブロックはexit 2のみ。exit 1はエラーとして扱われ、ブロックにならない。ここを間違えるとフックが素通りする。
env — 環境変数
{
"env": {
"NODE_ENV": "development",
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Claude Codeのセッション内で使える環境変数を設定する。実験的機能のフラグや、フックスクリプト内で参照する値の受け渡しに使える。
mcpServers — MCP接続先
MCPサーバーの設定は~/.claude/.mcp.jsonに書く（settings.jsonとは別ファイル）。
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "@my/mcp-server"],
"env": {
"API_KEY": "xxx"
}
}
}
}
その他の設定項目
| キー | 型 | 説明 |
|---|---|---|
cleanupPeriodDays |
number | セッションデータの保持日数 |
language |
string | UIの表示言語（例: "日本語"） |
statusLine |
object | ステータスバーのカスタムコマンド |
skipDangerousModePermissionPrompt |
boolean |
dontAskモード設定時の確認ダイアログをスキップ |
実践例: 安全な自律運用のための推奨設定
{
"permissions": {
"defaultMode": "dontAsk",
"allow": [
"Bash(*)", "Read(*)", "Edit(*)",
"Write(*)", "Glob(*)", "Grep(*)"
],
"deny": [
"Bash(rm -rf /*:*)",
"Bash(sudo:*)"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/destructive-guard.sh" },
{ "type": "command", "command": "~/.claude/hooks/branch-guard.sh" },
{ "type": "command", "command": "~/.claude/hooks/secret-guard.sh" }
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/syntax-check.sh" }
]
}
]
}
}
ポイント:
-
dontAskで承認ダイアログを消しつつ、フックで危険操作をブロック -
destructive-guardがrm -rf ~やgit reset --hardを止める -
branch-guardがmain/masterへの直pushを防ぐ -
secret-guardが.envやAPIキーの漏洩を検知 -
syntax-checkがファイル編集後に構文エラーを自動検出
この構成はnpx cc-safe-setupで一括インストールできる。
よくあるミス3選
1. denyだけで安心する
denyはパターンマッチの制約がある。cd /tmp && rm -rf ~のような複合コマンドはdenyをすり抜ける。確実にブロックしたい操作はフックで実装する。
2. settings.local.jsonの存在を忘れる
「設定したはずなのに効かない」場合、.claude/settings.local.jsonが上書きしていないか確認する。localファイルの優先度が最も高い。チームで共有するproject設定を個人のlocalが潰すケースは多い。
3. フックのexit codeを間違える
ブロックはexit 2だけ。exit 1はエラー扱いで、ブロックにならない。フックを書いたら必ずテストする:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf ~"}}' \
| bash ~/.claude/hooks/destructive-guard.sh
echo $? # 2が返ればOK
まとめ
settings.jsonはClaude Codeの挙動を根本から制御する設定ファイル。パーミッションで大枠を決め、フックで細かい安全策を実装する。3階層の優先順位を理解し、denyの限界を知った上でフックを併用するのが実践的な運用方法になる。
📘 hookの実践パターンはZenn Book（¥800）
🔍 今の設定に問題がないか30秒でチェック: npx cc-health-check
📚 settings.json の沈黙の上書きの事故と防衛の整理
本記事の settings.json の運用の延長で、 v2.1.143 で利用者が明示で書いた規則が沈黙で別の動作に上書きされた事故 (起票 #58513 / #58514 / #58515 / #58916) が発生しています。 「設定で保護した」 と信じていた利用者の側で、 設定の通りの動作が実行されなかった事例で、 通常の settings.json の文書では検出が困難な構造の系統。
5/22 発売の Claude Code Claim-Verify Handbook で、 同型の主張と実態の乖離の事例を 130 件 (本文 15 件 + 付録 D 115 件) に整理した試し読み (無料、 約 9,900 字、 JP) を公開済。 v2.1.143 の事故を含む 4 月から 5 月の運用の事故の総括は、 Postmortems (Gumroad、 ¥4,350) に納めています (試し読み Gist - Incident #1: Cache TTL silent regression)。
購入の検討の判断の助け (Should I buy the Claim-Verify Handbook?) の対話型の道具で、 無料の hook の解説で十分の場合の判定の経路も articulate しています。
継続の更新の経路 (関連の資源)
settings.json の設定の項目は Claude Code の release のたびに追加と変更が累積する。 v2.1.143 では沈黙の上書きの問題があり、 利用者の側の継続的な点検が必要。 月単位の継続の更新の経路として CC Safety Lab Founder Membership (Ko-fi、 ¥500/月) を運営している。 月次で incident roundup と新しい hook と settings.json の regression alert を配信。 6月15日の claude -p の課金の分離 (Pro 20米ドル、 Max 5x 100米ドル、 Max 20x 200米ドル) の前の準備の点検表も含む。
-
CC Safety Lab Founder Membership (Ko-fi、 ¥500/月)
過去の事故の事例の整理
実機の Claude Codeのsettings.jsonの設定 の事例の整理は Claude Code Incident Postmortems (Gumroad、 ¥4,350) に集約。 10件の事故の事例、 settings.json の上書きの事例を含む。 防衛の手順を解説。 - Claude Code Incident Postmortems (Gumroad、 ¥4,350)