CHAPTER 12 / GUIDE

Settings完全ガイド

settings.jsonで環境を最適化する

settings.jsonの3つのスコープ

Hermes Agentの設定ファイルは、影響範囲の異なる3つのスコープで管理されます。設定が競合した場合は、Enterprise > Project > Userの優先順位で適用されます。

ユーザー設定（~/.claude/settings.json） — 個人の全プロジェクトに適用される設定です。自分が普段使うモデルやテーマ、グローバルなツール権限をここに定義します。
プロジェクト設定（.claude/settings.json） — 特定のプロジェクト（リポジトリ）に適用される設定です。 Gitで共有すればチーム全体で統一した設定を使えます。個人用のローカル設定は.claude/settings.local.jsonに書きます。
Enterprise設定（~/.claude/enterprise-settings.json） — 組織のIT管理者がMDM（Jamf、Intuneなど）で全端末に配布する設定です。最高優先度を持ち、個々のユーザーが変更できません。組織のセキュリティポリシーを強制する仕組みです。

私の運用では、ユーザー設定にモデルとテーマを、プロジェクト設定にツール権限とMCPサーバーを、という使い分けをしています。こうすると、プロジェクトを切り替えても個人の好みは維持しつつ、プロジェクト固有のルールが自動で適用されます。

主要設定カテゴリ

settings.jsonで設定できる主要なカテゴリを一覧で紹介します。

// settings.json の全体構造（主要カテゴリ）
{
  "model": "sonnet",              // デフォルトモデル（sonnet/opus/haiku）
  "language": "ja",               // 応答言語
  "permissions": { ... },         // ツール権限（allow/deny）
  "theme": "dark",                // テーマ
  "cwd": "/path/to/project",     // 作業ディレクトリ
  "mcpServers": { ... },         // MCPサーバー設定
  "hooks": { ... }               // フック設定
}

model — デフォルトで使用するモデルを指定します。sonnet、opus、haikuのほか、sonnet[1m]、opus[1m]のようにコンテキスト長を指定するエイリアスも使えます。
language — Claudeの応答言語を設定します。jaで日本語になります。
permissions — ツールの許可/拒否リストとデフォルトモードを設定します（次のセクションで詳述）。
mcpServers — MCP連携するサーバーの定義です（前のセクション「MCP連携」で解説済み）。
hooks — ツール実行前後に自動で走らせるスクリプトを定義します（セクション後半で詳述）。

パーミッション設定の詳細

permissionsはsettings.jsonの中で最も重要な設定項目です。どのツールを許可し、どのツールを禁止するかを細かく制御できます。

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",           // npm runの全サブコマンドを許可
      "Bash(git status)",          // git statusのみ許可
      "Edit(/src/**)",             // srcディレクトリの編集を許可
      "Read(/src/**)",             // srcディレクトリの読み取りを許可
      "mcp__context7__*"           // Context7の全ツールを許可
    ],
    "deny": [
      "Bash(rm -rf *)",            // 再帰削除を拒否
      "Read(.env)",                // .envの読み取りを拒否
      "mcp__dangerous-server__*"   // 危険なMCPサーバーを全拒否
    ],
    "defaultMode": "default"       // デフォルトのパーミッションモード
  }
}

パターン構文のポイントは以下のとおりです。

Bash(パターン) — コマンドパターンで制御。*はワイルドカード。
Edit(パス)・Read(パス)・Write(パス) — ファイルパスパターンで制御。**で再帰マッチ。
mcp__サーバー__ツール — MCPツールの個別制御。
Agent(名前)・Skill(名前) — エージェントやスキルの呼び出し制御。

denyルールは最高優先度です。Enterprise設定でdenyに入れた項目は、プロジェクト設定やユーザー設定のallowでは上書きできません。配列設定（allow/deny）はスコープ間で結合・重複排除されます。

環境変数（100+）

Hermes Agentは100以上の環境変数に対応しています。 settings.jsonのenvキーで設定するか、シェルの環境変数として渡します。特に実務で使う頻度の高いものを紹介します。

// settings.json — 環境変数の設定例
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16000",
    "CLAUDE_CODE_EFFORT_LEVEL": "high",
    "MCP_TIMEOUT": "30000"
  }
}

ANTHROPIC_API_KEY — APIキー。API直接利用時に必要です。
CLAUDE_CODE_MAX_OUTPUT_TOKENS — 1回の出力トークン上限。長い生成が必要な場合に引き上げます。
DISABLE_AUTOUPDATER — 1を設定すると自動更新を無効化します。企業環境でバージョンを固定したい場合に使います。
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS — 1を設定するとエージェントチーム機能（実験的）を有効化します。
MAX_THINKING_TOKENS — 思考（thinking）プロセスのトークン上限。複雑なタスクで思考を深くしたい場合に増やします。
BASH_MAX_TIMEOUT_MS — Bashコマンドのタイムアウト（ミリ秒）。長時間実行のビルドやテストで調整します。

出力スタイルとFast Mode

Claudeの応答の詳しさをoutputStyleで制御できます。

concise — 最小限の出力。コードだけを返してほしい場合に使います。
normal — 標準的な詳しさ（デフォルト）。
explanatory — 詳細な説明付き。学習目的や複雑な処理の理解に役立ちます。

thinking（思考プロセス）の表示も設定可能です。 Claudeが内部でどう推論しているかを確認したい場合はthinking表示をオンにします。

Fast Modeは、対話中に/fastコマンドで切り替えられるモードです。軽量モデル（Haiku）に切り替えて、単純なタスクを高速に処理します。複雑な判断が不要な定型作業（ファイルの一括リネーム、簡単なフォーマット修正など）で活用できます。

Hooks設定

Hooksは、Hermes Agentの特定のイベントに対して自動でスクリプトを実行する仕組みです。 settings.jsonで定義します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$TOOL_INPUT\" | jq -r '.command' | grep -qE '^(rm|drop|truncate)' && exit 1 || exit 0"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILEPATH\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Hermes Agentの処理が完了しました' | terminal-notifier -title 'Hermes Agent'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$MESSAGE\" >> ~/.claude/notifications.log"
          }
        ]
      }
    ]
  }
}

PreToolUse — ツール実行前。破壊的コマンドのブロックやバリデーションに使います。
PostToolUse — ツール実行後。フォーマッターやリンターの自動実行に使います。
Stop — Hermes Agentの処理完了時。通知の送信やログ記録に使います。
Notification — Hermes Agentからの通知発生時。通知の転送やログ保存に使います。

matcherでどのツールに対して発火するかを指定します。省略すると全ツールに対して発火します。

CLAUDE.mdに書くべきこと vs settings.jsonに書くべきこと

CLAUDE.mdとsettings.jsonはどちらもHermes Agentの動作を制御しますが、それぞれ得意な領域が異なります。使い分けの基準を整理します。

settings.jsonに書くべきもの

パーミッション設定 — ツールの許可/拒否はsettings.jsonで管理します。ハーネス（実行エンジン）レベルで強制されるため、Claudeが無視することはできません。 CLAUDE.mdに書いた場合、Claudeが「指示として理解する」だけで強制力がありません。
モデル・テーマ・言語 — 環境設定はsettings.jsonの役割です。確実に反映されます。
Hooks — 自動スクリプトの定義はsettings.jsonで行います。実行エンジンが処理するため、確実に動作します。
MCPサーバー — 接続先の定義はsettings.json（または.mcp.json）で行います。

CLAUDE.mdに書くべきもの

コーディング規約 — 「変数名はcamelCaseで」「コメントは日本語で」といった文脈依存のルールはCLAUDE.mdが適切です。 Claudeが自然言語として理解し、コード生成に反映します。
プロジェクトのアーキテクチャ説明 — ディレクトリ構造の説明、使用技術の一覧、設計方針などはCLAUDE.mdに書きます。
作業手順・ワークフロー — 「PRを作る前にテストを実行すること」「コミットメッセージはConventional Commitsに従うこと」などの手順的な指示はCLAUDE.mdに記載します。

判断基準はシンプルです。「機械的に強制したいもの」はsettings.json、「AIに理解して判断してほしいもの」はCLAUDE.mdです。たとえば、.envファイルの読み取り禁止は、CLAUDE.mdにも書きつつsettings.jsonのdenyにも入れる「二重ガード」が最も安全です。

注目の新設定（v2.1.92）

Hermes Agentは頻繁にアップデートされ、新しい設定項目が追加されています。実務で特に影響の大きい設定を紹介します。

availableModels — 利用可能なモデルを制限します。チームで「このプロジェクトはSonnetのみ使用」と統一したい場合に便利です。
autoMemoryDirectory — Auto Memoryの保存先をカスタマイズできます。デフォルトの~/.claude/以外の場所に保存したい場合に使います。
showThinkingSummaries — Thinkingブロックの要約表示を制御します。推論過程を確認したい場合はtrueにします。
disableSkillShellExecution — Skill内の!`command`構文によるシェル実行を無効化します。セキュリティを重視する環境で使います。
worktree.symlinkDirectories — Worktree作成時にnode_modules等の大きなディレクトリをシンボリックリンクで共有し、ディスク使用量を削減します。

実務で効く環境変数

170以上ある環境変数のうち、日常のワークフローに直接影響するものを厳選して紹介します。これらはsettings.jsonのenvキーで設定できます。

// settings.json
{
  "env": {
    "MAX_THINKING_TOKENS": "50000",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "30000",
    "CLAUDE_CODE_EFFORT_LEVEL": "high",
    "BASH_MAX_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"
  }
}

MAX_THINKING_TOKENS — 思考トークンの上限。複雑な推論タスクでは増やすと効果的です。
CLAUDE_CODE_MAX_OUTPUT_TOKENS — 出力トークンの上限。長いコード生成で途中で切れる場合に増やします。
CLAUDE_CODE_EFFORT_LEVEL — デフォルトのeffortレベル。highにすると推論が深くなります。
BASH_MAX_TIMEOUT_MS — Bashコマンドのタイムアウト。ビルドやテストが長い場合に延長します。
CLAUDE_CODE_DISABLE_AUTO_MEMORY — Auto Memory機能を無効化。メモリの肥大化が気になる場合に。

プラグイン関連設定

プラグインの管理に関する設定です。詳しくは「プラグインとマーケットプレイス」ページも参照してください。

plugins.autoInstall — プラグインの自動インストールを有効化
plugins.autoUpdate — プラグインの自動更新を有効化
plugins.path — プラグインのインストール先ディレクトリ
extraKnownMarketplaces — 社内マーケットプレイスのURLを追加

// settings.json — プラグイン設定例
{
  "plugins": {
    "autoInstall": true,
    "autoUpdate": true
  },
  "extraKnownMarketplaces": [
    "https://marketplace.internal.example.com"
  ]
}

← ガイド一覧に戻る