Claude CodeのautoModeに独自ルールを追加する方法と/auto-mode-setup

「Teach auto mode about your environment?」というダイアログは、auto modeが何度かブロックしてもautoMode.environmentが空のままのときに出ます。/auto-mode-setupを実行すれば、プロジェクトと直近のセッションから環境の説明を下書きしてくれます。

独自ルールを手で足すなら、Claude Codeのauto mode設定は、autoMode.environment・allow・soft_deny・hard_denyという4つの配列でできています。それぞれに文字列"$defaults"を含めるだけで、組み込みルールを保ったまま自分のルールを足せます。逆に"$defaults"を書き忘れると、その配列の組み込みルールごと丸ごと失われます。

v2.1.283以降は、ターミナルとVS Codeの対話セッションがプランを問わずauto modeで始まります。それより前のバージョンで既定になるのはPro・Max・Teamだけでした。既定で使う人が増えたぶん、組み込みルールを壊さずに足す書き方の重みも増しています。この記事では、$defaultsの書き方と設定を置く場所、/auto-mode-setupと/permissionsのAuto modeタブでの編集、設定後の確認コマンドを扱います。数値と出力は、v2.1.285で実際に確認したものです。

組み込みルールはどれくらい入っているか

書き足す前に、土台になる組み込みルールの規模を知っておくと、"$defaults"を落としたときの被害が想像しやすくなります。claude auto-mode defaultsの出力を数えると、v2.1.285では次のとおりでした。

hard_denyが1件しかない点は見落としやすいところです。無条件ブロックは、データ持ち出しを止める1本の規則に集約されています。各ルールはGit Destructiveのように、ラベルで始まる自然文です。このラベルは、拒否されたときの画面表示ともつながります(後述)。

autoMode設定はどこに書けば読まれるか

autoMode設定が読まれる場所は3か所だけです。ユーザー設定(~/.claude/settings.json)・組織の管理設定・--settingsフラグまたはAgent SDK経由のインラインJSONです。プロジェクト直下の.claude/settings.jsonや.claude/settings.local.jsonに書いても分類器には渡りません。

プロジェクト設定が除外されているのは、リポジトリにコミットされたファイルやビルドステップが勝手に許可ルールを注入する経路を塞ぐためです。v2.1.207より前は.claude/settings.local.jsonもautoModeの読み取り対象でしたが、このバージョンで外れました。そこに書いていたautoModeブロックは~/.claude/settings.jsonへ移します。

除外は手元でも確かめられます。空のホームディレクトリと、soft_denyを1件書いたプロジェクト設定だけを用意してclaude auto-mode configを実行すると、件数は組み込みのままでした。

{"autoMode":{"soft_deny":["Never modify files under infra/terraform/prod/"]}}

claude auto-mode config | jq -c '{allow:(.allow|length),soft_deny:(.soft_deny|length)}'

出力は{"allow":17,"soft_deny":70}でした。上のJSONをプロジェクトの.claude/settings.jsonに置いたので、書いた1件が反映されていれば71件になるはずです。反映されないのは仕様どおりで、エラーも警告も出ません。「書いたのに効かない」ときは、まず置き場所を確認します。

複数スコープに同じ配列を書いた場合、内容は結合されます。開発者は個人の項目を足せますが、管理設定が配った項目を削除することはできません。

$defaultsの有無で何が変わるか

$defaultsは、組み込みルールをその位置にそのまま展開する予約文字列です。配列の中に"$defaults"を1つ入れれば、その前後に書いた項目が組み込みルールに追加されます。リリースのたびに更新される組み込みルールも、そのまま引き継がれます。

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/acme-corp and all repos under it"
    ],
    "allow": [
      "$defaults",
      "Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"
    ],
    "soft_deny": [
      "$defaults",
      "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"
    ],
    "hard_deny": [
      "$defaults",
      "Never send repository contents to third-party code-review APIs"
    ]
  }
}

4つの配列は独立に評価されます。environmentだけ書いても、他の3つは組み込みのまま残ります。問題は、配列を書くのに"$defaults"を入れ忘れたときです。同じsoft_denyの1行を、$defaultsありとなしで書き分けて件数を比べました。

消える69件には、force push・curl | bash・本番デプロイ・auto modeのバイパスに関する規則が含まれます。hard_denyを独自ルールだけで置き換えれば、無条件ブロックのデータ流出防止ルールが消えます。どちらも、エラーなしで静かに起きます。

優先順位は、hard_deny→soft_deny→allow→ユーザーの明示的な意図の順です。分類器の判定そのものはClaude Codeのauto mode分類器は何を止めているかに詳しくあります。

意図して組み込みルールを総入れ替えしたい場合だけは、"$defaults"を省いて構いません。その代わりclaude auto-mode defaultsで中身を先に確認し、自分のパイプラインとリスク許容度に照らして1つずつ検討してから書き直します。

environmentの三層スロットで「社内」を教える

autoMode.environmentは許可・拒否のルールではなく、分類器が「社内」と「社外」を見分けるための文脈です。ここに書いていない送信先は、正規の操作でも分類器から見て潜在的な持ち出し先として扱われます。エントリは正規表現やツールパターンではなく自然文で、新しく入った同僚に説明するつもりで書きます。

claude auto-mode defaultsのenvironmentは、v2.1.285で21項目あり、3種類に分かれます。

Sensitivity slotsは、具体的な対象を名指しした時点でヒューリスティックから切り替わります。名指しした対象だけに、その保護ルールが適用されます。Trust slotsはリポジトリ関連2項目(Trusted repo・Source control)を除き、明示的に書かない限りすべてNone configuredのままです。

Contextの中でも、リポジトリの公開範囲には癖があります。分類器は、リモートのホスト名とリポジトリ名から公開と読み取れない限り、非公開のリポジトリとして扱います。公開範囲を伝える根拠は、分類器が読める場所になければなりません。会話の前半で可視性チェックを分類器が読んでいた場合も、公開扱いの根拠になります。Claude Code自身が送る分類器リクエストでは、読まれるのはあなたの発言とClaudeが実行するコマンドで、コマンドの出力は含まれません。あなた自身が「このリポジトリは公開です」と書くのが確実で、gh repo viewの出力だけでは届きません。

コンテナやVM内で動かす場合は、Host containmentスロット(v2.1.257以降)に、許可するホストと、クラウドのメタデータエンドポイントに届かせるかどうかを書きます。使うクラウドプロジェクトやクラスタと、どのIDで使うかも書きます。このIDを名指しするまで、ホスト自身の認証情報を取りに行くリクエストはブロックされます。

一度に全部埋める必要はありません。最初はソース管理の組織と主要な社内サービスだけを足すと、自分のリポジトリへのpushのような、最も多い誤検知が解消します。

pushやPR作成の前に人の確認を挟む

auto modeは既定で、作業中のリポジトリのどのブランチへのpushもPR作成も許可します。productionやrelease、gh-pagesのようにデプロイ先だと分かる名前のブランチだけは既定の対象外で、分類器が個別に安全性を判定します。force pushや、CI・デプロイパイプラインを通した先で機密情報が漏れる変更は、対象ブランチによらず引き続きブロックされます。

pushやPR作成そのものに人の確認を必ず挟みたい場合は、境界の固さに応じて3つの手段から選びます。

permissions.askはautoModeとは別の設定ブロックで、分類器より手前の段階で評価されます。

{
  "permissions": {
    "ask": [
      "Bash(git push *)",
      "Bash(gh pr create *)"
    ]
  }
}

このルールはgit pushやgh pr createで始まるコマンドにだけ一致します。git -C <dir> pushやgit -c <key>=<value> pushのように書き方を変えたpushは一致しません。コマンド全文を検査したい場合はPreToolUseフックを使います。

/auto-mode-setupと/permissionsのAuto modeタブで書く

設定ファイルを直接編集しなくても、autoMode設定を組み立てる手段が2つあります。/auto-mode-setupは、プロジェクトと直近のセッションからautoMode.environmentのたたき台を作るコマンドです。

読む対象は、プロジェクトのCLAUDE.md・README・設定ファイル・gitのリモートです。既存のautoModeとpermissions.allow、直近のセッションでClaudeが実行したコマンドのホスト名・バケット名・コマンド名も読みます。ユーザーのメッセージは読みません。

実行すると、既存のautoModeがある場合は、environmentリストに追加するか置き換えるかを最初に聞かれます(書いたルールはどちらでも残ります)。スキャンの前には「このプロジェクトの使い方」も聞かれます。

任意のスキャンが2つあり、実行前にどちらを回すか確認されます。1つはシェル履歴の各コマンドの先頭単語、もう1つはホームディレクトリ配下のリポジトリのリモートのホスト名とリポジトリ名です。

ドラフトは全体を承諾するか破棄するかの二択で、1項目だけ直したいときは承諾後に~/.claude/settings.jsonを編集します。書き込み時の"$defaults"の扱いは配列ごとに違います。

• environmentは"$defaults"なしで書かれます。組み込みの項目がドラフトに展開済みだからです
• allow・soft_deny・hard_denyは、項目を足した配列に"$defaults"が添えられます。既存のallowが"$defaults"なしなら添えられません
• 保存後は、autoモードが無視するBash(*)のような許可ルールや、破壊的コマンドを自動承認するpermissions.allowのルールを削除するかどうかも聞かれます

/auto-mode-setupの提供条件は次のとおりです。

• Pro・Max・Teamプランとv2.1.228以降が必要
• ネイティブWindowsではv2.1.233以降が必要
• Claude Code on the webでは実行できません
• フィーチャーフラグの取得を止めたセッションでも実行できません

もう1つの手段は/permissionsダイアログのAuto modeタブです(v2.1.246以降、auto modeが使えるセッションでのみ表示)。allow・soft_deny・hard_deny・environmentの各セクションでは、その区分に組み込みルールが効いているかどうかを確認できます。区分に最初の1件を足すと"$defaults"が自動で挿入されます。

組み込みルールの切り替えもここでできます。"$defaults"を自分のリストから外す操作に相当するため、自分のルールが最低1件ないと切れません。管理設定や--settingsフラグ由来のエントリは読み取り専用で、それ以外の変更はすべて~/.claude/settings.jsonに保存されます。

environmentはドキュメント全体をエディタで編集する形式です。未設定の状態から開くと、組み込みを置き換えてよいかを先に聞かれ、そのあと組み込みの全文が入った状態で開きます。保存するとenvironment配列がその文書に置き換わるので、組み込みを残したいなら"$defaults"の行を含めたままにします。

/permissions全体の使い方はClaude Codeの/permissionsコマンドにまとめています。各操作の詳しい手順はClaude CodeのAuto modeルールを編集するに整理しました。

「Teach auto mode about your environment?」と出たらどうするか

このダイアログは、auto modeが何度かブロックしてもautoMode.environmentが空のままのとき、ターンの終わりに出ます。/auto-mode-setupの実行を勧めるもので、受け入れると下書きが作られます。下書きを承諾すると~/.claude/settings.jsonに書き込まれ、あとでclaude auto-mode configで反映結果を確かめられます。

出さないだけなら、ダイアログで「Don't show again」を選びます。コマンドも使わないなら、skillOverridesに"auto-mode-setup": "off"を書きます。disableBundledSkillsではコマンドは消えません。

設定後に効いているかを確認する4つのコマンド

autoMode設定を保存したら、実際に反映されているかを目で確認します。設定ファイルを直接読み返すよりも、分類器が使う最終形をコマンドで出力する方が確実です。

configは、設定がある配列は自分の設定、無い配列は組み込みを表示します。件数を見るならjqで数えるのが手軽です。

claude auto-mode config | jq -c '{allow:(.allow|length),soft_deny:(.soft_deny|length),hard_deny:(.hard_deny|length),environment:(.environment|length)}'

soft_denyに"$defaults"ありで1件足すと、次の出力でした。

{"allow":17,"soft_deny":71,"hard_deny":1,"environment":21}

"$defaults"なしならsoft_denyが1になります。件数が組み込みより減っていたら、"$defaults"の書き忘れを疑います。

claude auto-mode resetを実行すると、消える内容を先に表示します。試した設定では「soft_deny (1 entry)」と出て、確認後にファイルの中身が{}になり、configの件数が組み込みに戻りました。critiqueはモデルを呼ぶため、ここでは実行していません。

claude auto-mode defaultsに--labelを渡すと、ルール名の先頭一致で1件だけをjqなしで読めます(v2.1.208以降)。大文字小文字は区別されません。一致しない配列は空のリストで返ります。claude auto-mode resetは管理設定や--settingsフラグ由来のautoMode設定までは削除しないため、組織のルールはリセット後も残ります。

拒否されたときにどのルールを直すか

ブロックされたとき、画面にはbash denied by auto mode · [Data Exfiltration] · /permissionsのように、角括弧でルール名が出ます。この名前が、そのまま--labelの検索語になります。

claude auto-mode defaults --label 'Data Exfil'のように前置きだけを渡せば、hard_denyの1件に絞れます。全文を読めば、ルールが何を守り、どこで例外になるかが分かるため、闇雲にallowを足す前の確認に向きます。

拒否された操作は/permissionsの「Recently denied」タブに記録され、rで再試行を指示できます。直し方は、その操作が何に届こうとしたかで分かれます。

ツール呼び出しがRan 3 shell commandsのようにまとめて表示されているときは、Ctrl+Oで会話記録を開くと展開できます。画面上の拒否通知やRecently deniedのタブは、コマンドやURLそのものを省く表示です。入力の正確な中身を機械的に集めたいときは、PermissionDeniedフックを使います。

よくあるつまずき

environmentを書いても、allow・soft_deny・hard_denyは緩みません。environmentは分類器の文脈情報で、ルールそのものではないためです。信頼する接続先を教えても、破壊的な操作を許可したことにはならず、そこは別途allowか明示的な意図表明が必要です。

組織のhard_denyは、allowルールを足しても上書きできません。hard_denyは無条件ブロックで、ユーザーの意図もallowの例外も効きません。開発者が個人設定に足したallowが上書きできるのは組織のsoft_denyだけで、hard_denyには届きません。組織側で確実に禁止したい操作は、permissions.denyを管理設定に置く方が確実です。

disableAutoModeは、autoModeの4配列とは役割が違います。前者はauto mode自体をShift+Tabの切り替え候補から外す設定で、後者はauto modeが有効な前提で分類器のルールを調整する設定です。auto modeを完全に使わせたくない場合は前者を管理設定に置きます。

classifyAllShellは、4配列のどれにも書けません。autoModeブロック直下の独立したブール値キーで、$defaultsを含む配列とは別枠です。既定では、Bash(npm test)のような狭い許可ルールは分類器より先に解決されます。一時停止されるのはBash(*)のような広い許可ルールだけで、そのルールで通っていたコマンドは分類器の判定に回ります。trueにすると、auto mode中のBash・PowerShell許可ルールがすべて一時停止し、重要なパスの削除を除くシェルコマンドを分類器が評価します。その分、遅延が増え、シェルコマンドごとに分類器の呼び出しが1回加わります。詳しくはClaude Codeのclassify all shell設定にあります。

プロジェクトの.claude/settings.jsonに書いた設定が効かないときは、置き場所が原因です。前述のとおりautoMode設定はユーザー設定・管理設定・--settingsフラグからしか読まれません。設定ファイルの階層とスコープの全体像はClaude Code settings.json完全ガイドで扱っています。既定でブロックされる操作の一覧はClaude Code auto modeブロック一覧にまとめてあります。

まとめ

autoModeの設定は、~/.claude/settings.jsonか管理設定に置き、配列ごとに"$defaults"を残すのが前提です。総入れ替えは、claude auto-mode defaultsで組み込みの中身を読んでから判断します。