Claude Code
Best Practices

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "./.claude/hooks/block-rm.sh" }]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{ "type": "command", "command": "npm run lint --fix $CLAUDE_FILE_PATH" }]
    }],
    "Notification": [{
      "hooks": [{ "type": "command", "command": "notify-send '$CLAUDE_MESSAGE'" }]
    }],
    "Stop": [{
      "hooks": [{ "type": "command", "command": "./scripts/post-session.sh" }]
    }],
    "SubagentStop": [{
      "hooks": [{ "type": "command", "command": "./scripts/aggregate-subagent.sh" }]
    }]
  },
  "routines": [
    { "schedule": "0 9 * * 1", "task": "毎週月曜朝: PRサマリーを作成しSlackへ通知" },
    { "schedule": "0 8 * * *", "task": "毎朝: 未マージPRのコードレビューを自動実行" }
  ],
  "model": "claude-sonnet-4-6",
  "permissionMode": "default"
}

Claude Codeは複数のCLAUDE.mdを積み重ねてロードする。

~/.claude/CLAUDE.md      # 個人グローバルルール
/project/CLAUDE.md        # プロジェクト全体
/project/src/CLAUDE.md    # src/配下の特殊ルール
/project/CLAUDE.local.md  # 個人ローカル (gitignore)

深い階層のCLAUDE.mdは親を上書きではなく追記として機能する。サブパッケージごとに異なるコーディング規約を持つモノレポで特に有効。

// .claude/hooks/block-rm.sh (PreToolUse)
#!/bin/bash
CMD="$CLAUDE_TOOL_INPUT"
if echo "$CMD" | grep -qE 'rm\s+-rf|DROP TABLE|DELETE FROM'; then
  echo '{"decision":"block","reason":"危険なコマンドをブロックしました"}'
  exit 0
fi
echo '{"decision":"approve"}'

// PostToolUse: updatedToolOutput で結果を置換 (v2.1.141+)
{
  "hookSpecificOutput": {
    "updatedToolOutput": "[lint済み出力をここに]"
  },
  "terminalSequence": "]9;PostToolUse完了"
}

アシスタントの応答テキストをユーザーへ表示する前に変形・フィルタできるHook。機密情報の自動マスクやフォーマット統一に使う。

// .claude/settings.json
{
  "hooks": {
    "MessageDisplay": [{
      "hooks": [{ "type": "command", "command": "./.claude/hooks/filter-output.sh" }]
    }]
  }
}

hookSpecificOutput.updatedMessage で変換後テキストを返す。空文字を返すとメッセージを非表示にできる。

Stop Hookが連続8回ブロックし続ける場合、警告付きでターンが自動終了する。以前は無限ループになり得た。

• 上限変更: CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=N
• Stop Hookで強制ブロックするパターンを使っている場合は挙動変化に注意

Hook JSON出力にterminalSequenceフィールドが追加。コンテナやCI等ターミナルを持たない環境でも、デスクトップ通知・ウィンドウタイトル変更・ベル音をHookから発火できる。

{
  "terminalSequence": "]9;Task completed",
  "hookSpecificOutput": { "updatedToolOutput": "..." }
}

最大の生産性向上は3〜5セッションを並列でそれぞれのgit worktreeで動かすこと。

# worktreeの作成
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

# 大規模バッチ変更のプロンプト例
"Migrate all sync IO to async.
Launch 10 parallel agents with worktree isolation.
Each agent tests its changes end-to-end, then opens a PR."

ベストプラクティス: 1サブエージェント1専門領域。単純タスクにはHaiku、複雑な分析にはSonnet。独立した作業は並列実行。

claude agents内でCtrl+Tでセッションをピン留めすると、アイドル時も生き続ける。

• ピン留めセッションはClaude Codeアップデート時にインプレースで自動再起動
• メモリ逼迫時は非ピンのセッションから先に解放される
• 長時間タスクや常駐エージェントに最適

CLAUDE.mdが手順書のように膨らんできたら、その手順はSkillに切り出すサイン。Subagentsはコンテキスト分離が目的で「失敗したアプローチの蓄積汚染」を構造的に防ぐ。

成功の評価基準ルーブリックを定義すると、独立したコンテキストの別グレーダーが評価して再実行させるループ。

• グレーダーはエージェントの推論から独立した別コンテキストウィンドウで評価（バイアスなし）
• 不合格部分を特定してエージェントが再実行、基準を満たすかイテレーション予算切れまで繰り返す
• Webhookで完了通知を受け取れる

リードエージェントがタスクを分解し、独自モデル・プロンプト・ツールを持つ最大20人のスペシャリストに委任。

• Claude Consoleで各サブエージェントの動作・出力を詳細確認可
• Netflix等のエンタープライズで既に採用
• API: managed-agents-2026-04-01 betaヘッダーで利用可

核心的示唆: 3機能（Dreaming / Outcomes / Multiagent）は独立していない。OutcomesはイベントHistoryが必要。Multiagent OrchestraionはSubagentStopフックと組み合わせて使うと最も強力。