Claude Code運用ベストプラクティス上級編：Hooks・Subagents・コンテキスト管理の実践テクニック11選【2026年版】¶

対象読者
Claude Codeを日常的に使っているが、より効率的な運用を目指す中級〜上級者
この記事で得られること
公式Best Practicesから厳選した「目から鱗」の運用テクニック11選
想定読了時間
約15分

はじめに：基本Tipsの先にあるもの¶

「テスト/期待出力を渡して自己検証させる」「Plan Modeで探索→計画→実装を分ける」「プロンプトに具体的なコンテキストを入れる」——これらは広く知られた基本Tipsです。

本記事では、公式Best Practicesから、運用設計として"仕組みで縛る"部分に焦点を当て、中級者から上級者への壁を突破する実践的ノウハウを解説します。

1. Hooksは"強制"、CLAUDE.mdは"助言"¶

核心ポイント

絶対に例外なくやらせたいならHook、判断が要るガイダンスならCLAUDE.md

Hooksの特徴¶

Claude Codeのワークフロー中の特定タイミングでスクリプトを自動実行
「Claude に覚えていてもらう」のではなく、決定論的（deterministic）に制御
毎回必ず起きることを保証

具体的な使い分け¶

要件	推奨手段	理由
ファイル保存後に自動lint	Hook (PostToolUse)	例外なく毎回実行したい
機密ファイルへの書き込みブロック	Hook (PreToolUse)	セキュリティは妥協できない
コード規約の遵守	CLAUDE.md	状況に応じた判断が必要
APIの命名規則	CLAUDE.md	例外パターンがある

実装例：機密ファイルへの書き込みをブロック¶

公式仕様に準拠

Hooksの入力はstdinでJSONが渡される形式です。decision/reasonを返す方式は非推奨（deprecated）のため、exit code 2でブロックする方式を使用します。

まず、ブロック用スクリプトを作成：

#!/bin/bash
# ./scripts/block-sensitive-writes.sh
set -euo pipefail

INPUT="$(cat)"
TOOL="$(echo "$INPUT" | jq -r '.tool // empty')"
FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')"

# 機密拡張子への書き込みをブロック
if [[ "$TOOL" =~ ^(Write|Edit)$ ]] && echo "$FILE_PATH" | grep -qE '\.(env|key|pem)$'; then
  echo "Blocked: sensitive file write is not allowed: $FILE_PATH" >&2
  exit 2  # exit code 2 = ブロック
fi

exit 0

次に、settings.jsonでHookを設定：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "./scripts/block-sensitive-writes.sh" }
        ]
      }
    ]
  }
}

なぜ目から鱗か：LLM運用で「プロンプトで縛る」発想から一段上に行き、ガードレールを"システム側"に寄せる設計になっています。

2. Subagentsは"別コンテキスト窓"で動く¶

核心ポイント

調査・検証・レビューを別コンテキストに分離し、汚染とバイアスを抑える

Subagentsの特徴¶

.claude/agents/に定義したサブエージェントへタスクを委任でき、各サブエージェントは独自のコンテキスト窓・利用ツール・指示を持ちます。

スラッシュコマンドとの違い¶

機能	スラッシュコマンド	サブエージェント
呼び出し方	明示的（`/command`）	タスク委任
コンテキスト	共有	独立
用途	反復ワークフロー	分業・探索・検証

効果的な使いどころ¶

調査：本体コンテキストを汚さずコードベース探索
検証：実装後に別エージェントで正当性確認
レビュー：本体の会話バイアスを避ける

なぜ目から鱗か：「コンテキストが資源」という前提で、"探索を別窓に追い出す"のは強力です。単なる並列化ではなく、汚染（failed approachesの蓄積）を構造的に防ぐ発想です。

→ 詳細：Claude Code Subagent完全ガイド

3. Skillsは"文脈で自動発火"するドメイン知識¶

核心ポイント

明示呼び出しではなく、文脈（context）トリガーで動く

Skillsの位置づけ¶

機能	特徴
CLAUDE.md	常時ロードの全体ルール
Slash commands	明示実行する反復ワークフロー
Skills	自動適用されるドメイン知識
Subagents	分離された委任タスク

実装例：API設計ルールをSkill化¶

公式仕様

Skillsは単発の.mdファイルではなく、skills/<skill-name>/SKILL.md のディレクトリ構造が基本です。YAML frontmatterで自動適用の条件を制御できます。

ディレクトリ構成：

.claude/
  skills/
    api-conventions/
      SKILL.md          # メインのスキル定義（必須）
      examples.md       # 期待する出力例（任意）
      reference.md      # 詳細ガイド（任意）

SKILL.md：

---
name: api-conventions
description: API設計・エンドポイント設計時の規約。API/endpoint/REST/スキーマ設計の文脈で適用。
---
When writing API endpoints:
- Use RESTful naming conventions (plural nouns: users, orders)
- Use kebab-case for multi-word paths (user-profiles)
- Include version in URL path (/v1/users)
- Return consistent formats:
  - Success: { "data": {...}, "meta": {...} }
  - Error: { "error": { "code": "...", "message": "..." } }

## Additional resources
- examples.md: 期待する出力例
- reference.md: 詳細な設計方針（必要時に参照）

手動専用Skill（誤爆防止）¶

デプロイなど危険な操作は disable-model-invocation: true で手動専用にできます：

---
name: deploy
description: 本番デプロイ手順
disable-model-invocation: true
context: fork
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Commands vs Skills

旧来の .claude/commands/*.md（スラッシュコマンド）もありますが、同名の場合はSkillが優先されます。CommandsはSkillsに統合されつつあります。

なぜ目から鱗か：「プロンプトを毎回書く」のをやめて、暗黙知を"自動適用される知識層"として実装する発想です。

4. CLAUDE.mdは"短くないと逆効果"¶

重要な原則

1行ごとに「これを消すとClaudeがミスるか？」を問う。ミスらないなら削る。

肥大化の問題¶

CLAUDE.mdが長くなりすぎると、指示が無視される確率が上がります。

削除判断のフレームワーク¶

1. この指示を消すと、Claudeがミスするか？
   → Yes: 残す
   → No: 削る

2. この情報は他の場所（README、Skills）で提供できるか？
   → Yes: 移動して削る
   → No: 残す

3. この指示は常に必要か、特定の文脈だけか？
   → 常に: CLAUDE.mdに残す
   → 特定文脈: Skillsに移動

配置戦略¶

配置場所	用途
`~/.claude/CLAUDE.md`	全セッション共通の個人設定
プロジェクトルート	チーム共有のルール
親ディレクトリ	モノレポでの共通設定
子ディレクトリ	必要時に取り込む特殊ルール

なぜ目から鱗か：「書けば効く」ではなく、"短さが性能要件"として扱っています。

5. "承認疲れ"対策：AllowlistとSandbox¶

承認の罠

承認が多すぎると、人は結局レビューせずにクリックし始める（＝安全性が下がる）

2つの対策アプローチ¶

アプローチ	効果
許可Allowlist	安全なコマンドを許可して中断を減らす
OSレベルのサンドボックス	ファイル/ネットワーク境界を定義して自由度を上げる

Allowlistの設定例¶

{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Read",
      "Glob",
      "Grep"
    ]
  }
}

機密ファイルをdenyで不可視化（Hookより堅い）¶

deny → ask → allow の評価順

permissionsは deny が最優先で評価されます。機密ファイルを deny に設定すると、Claudeから「見えない」状態にできます（Hookでブロックするより堅い）。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Bash(git diff:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl:*)"
    ]
  }
}

`--dangerously-skip-permissions`の正しい使い方¶

適切な場面	不適切な場面
lint修正の自動化	インターネット接続環境
ボイラープレート生成	機密データがある環境
閉じたワークフロー	汎用的な開発作業

重要

--dangerously-skip-permissionsはインターネットなしの隔離環境で使うべきです。

エンタープライズ向け：危険モードを組織で禁止する

組織のセキュリティポリシーとして --dangerously-skip-permissions 自体を使用禁止にしたい場合、disableBypassPermissionsMode: true を設定できます。

{
  "disableBypassPermissionsMode": true
}

→ 詳細：Claude Code自動承認ガイド

6. "失敗を2回繰り返したら /clear"（筆者運用ルール）¶

核心ルール

同じ論点で2回以上修正しているなら、/clearしてやり直す方が速い

公式と本記事ルールの区別

公式Best Practicesは「頻繁に/clearを使う」「コンテキストの汚染が性能を落とす」と説明していますが、"2回"という閾値は明示していません。本記事の「2回失敗したら」は実運用から導出したルールとして提示します。

なぜリセットが有効か¶

セッション内に失敗アプローチが蓄積すると、コンテキストが汚れます。

失敗パターンの蓄積
    ↓
Claudeが過去の失敗を参照
    ↓
同じ方向に引きずられる
    ↓
さらなる失敗

実践フロー¶

1回目の失敗
    ↓
原因を分析、修正を依頼
    ↓
2回目の失敗（同じ論点）
    ↓
★ /clear を実行 ★
    ↓
学びを織り込んだ「より良い最初のプロンプト」でやり直し

なぜ目から鱗か："粘れば良くなる"ではなく、セッションは汚染される前提で運用します。

7. /compactは「要約の指示」を与えられる¶

機能

コンテキスト上限が近づくと自動で履歴を圧縮し、重要なコードや意思決定を保つ

手動制御のパワー¶

# API変更にフォーカスして圧縮
/compact API変更にフォーカスして

# テスト関連の履歴を保持して圧縮
/compact テスト実装の詳細は保持して

# エラー解決の経緯を残して圧縮
/compact エラーの原因と解決策は詳細に残して

なぜ目から鱗か：「要約される」ではなく、要約の"方針"をこちらが指定して、残す情報の圧縮最適化ができるのが運用上かなり効きます。

8. チェックポイントは会話/コードを独立に巻き戻せる¶

柔軟なロールバック

会話だけ戻す・コードだけ戻す・両方戻す、を選べる

チェックポイントの特徴¶

特徴	詳細
自動作成	Claudeの各アクションで自動的に作成
セッション跨ぎ	セッションを跨いで持続
独立ロールバック	会話とコードを独立に戻せる

活用パターン¶

パターン1: 会話だけ戻す（コードは維持）
→ 実装は良いが、説明をやり直したい時

パターン2: コードだけ戻す（会話は維持）
→ 議論は有益だが、実装は別アプローチにしたい時

パターン3: 両方戻す
→ 完全にやり直したい時

制限事項

外部プロセスの変更は追跡しない
gitの代替ではない

なぜ目から鱗か："LLMに慎重な計画を強要する"より、試行錯誤をシステム機能で安全にする方向に設計されています。

→ 詳細：Claude Code 2.0 チェックポイントパターン

9. 仕様策定と実装はセッションを分離する¶

核心ポイント

仕様はインタビューで作らせ、実装は新セッションでやる

推奨フロー¶

graph LR
    A[セッション1: 仕様策定] --> B[SPEC.md]
    B --> C[セッション2: 実装]

    style A fill:#e1f5fe
    style B fill:#fff9c4
    style C fill:#e8f5e9

セッション1: 仕様策定¶

プロンプト例：
「この機能について、AskUserQuestionツールを使って
私にインタビューしながら仕様を固めてください。
最終的にSPEC.mdとして出力してください。」

セッション2: 実装¶

プロンプト例：
「SPEC.mdに基づいて実装してください。
仕様の解釈に迷う点があれば質問してください。」

なぜ目から鱗か：「同一セッションで全部やる」より、Spec → Buildをコンテキスト単位で分割して品質と速度を両立させます。

→ 関連：AskUserQuestionツールガイド

10. 並列セッションはバイアス回避にも効く¶

Writer/Reviewerパターン

新しいコンテキストはレビューに有利——直前に自分で書いたコードに引きずられない

並列セッションの価値¶

目的	効果
スピードアップ	複数タスクの同時進行
品質向上	バイアスの分離

Writer/Reviewerパターン¶

セッションA（Writer）: コードを実装
    ↓
コードを共有
    ↓
セッションB（Reviewer）: 実装をレビュー
→ Writerの思考バイアスから解放された視点でレビュー

テスト分離パターン¶

セッションA: テストを書く
    ↓
テストをコミット
    ↓
セッションB: テストを通すコードを書く
→ テストを書いたバイアスなしに実装

実務テク：git worktreeで物理的に分離¶

衝突事故の予防

並列セッションで同一ファイルを同時に編集すると衝突事故が起きます。公式はgit worktreeで物理的に分離する運用を推奨しています。

# 別ディレクトリにworktreeを作成
git worktree add ../project-review feature-branch

# セッションAはメインディレクトリで作業
# セッションBはworktreeディレクトリで作業

なぜ目から鱗か：人間のペアプロに近いが、より厳密に"バイアスの分離"をコンテキストで実現しています。

11. Fan-outは「少数でチューニング→全体展開」¶

スケール手順

2〜3ファイルでプロンプトをチューニングしてから全体展開

大規模移行のフロー¶

graph TD
    A[タスクリスト生成] --> B[2-3ファイルで試行]
    B --> C{成功?}
    C -->|No| D[プロンプト調整]
    D --> B
    C -->|Yes| E[全体スケール]

    style B fill:#fff9c4
    style E fill:#e8f5e9

実装例¶

# Step 1: タスクリスト生成
claude -p "migration/対象ファイル一覧を生成" > tasks.txt

# Step 2: 少数ファイルでテスト
head -3 tasks.txt | while read file; do
  claude -p "このファイルをPython 3.11対応に" "$file"
done

# Step 3: 結果確認・プロンプト調整
# (問題があれば修正)

# Step 4: 全体スケール（権限制限付き）
cat tasks.txt | while read file; do
  claude -p "このファイルをPython 3.11対応に" \
    --allowedTools "Read,Edit,Grep" \
    --output-format json \
    "$file"
done

無人実行のベストプラクティス¶

設定	理由
`--allowedTools`	権限を絞って予期しない操作を防ぐ
`--output-format json`	機械処理可能な出力
`--output-format stream-json`	リアルタイムモニタリング

なぜ目から鱗か：LLM運用を「職人芸」ではなく、バッチ処理の工程（試作→調整→量産）として定義しています。

まとめ：運用設計の発想転換¶

従来の発想	上級者の発想
プロンプトで縛る	Hooksでシステム的に制御
1セッションで完結	コンテキストを資源として分離
粘り強く修正	2回失敗したらリセット
長いCLAUDE.mdで網羅	短さが性能要件
承認を都度判断	Allowlist+Sandboxで効率化
職人的なプロンプト	Fan-outでスケール

これらの「仕組みで縛る」アプローチを取り入れることで、Claude Codeの運用効率は大きく向上します。

付録：公式仕様に準拠したテンプレート集¶

付録1：Subagents定義テンプレート（frontmatter + skills注入）

Subagentsは独自のsystem promptを中心に動くため、本体の会話バイアスから分離されます。

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
skills:
  - api-conventions
  - error-handling-patterns
---
You are a senior code reviewer. Focus on code quality, security, and best practices.
Provide specific, actionable feedback.

ポイント：

tools: 使用可能なツールを制限
model: 使用するモデルを指定
skills: 事前に注入するSkillsを指定

付録2：CLAUDE.mdのCompact Instructions（圧縮方針の標準化）

/compactの方針をCLAUDE.mdに記載しておくと、自動圧縮時にも一貫した方針が適用されます。

## Compact Instructions

When summarizing this conversation:
- Preserve all API changes and their rationale
- Keep error messages and their solutions
- Maintain the list of modified files
- Summarize exploration attempts briefly

付録3：並列セッション管理（/rename → /resume）

セッションに名前を付けて後から再開できます：

# セッションに名前を付ける
/rename feature-auth-implementation

# 別のターミナルで新しいセッションを開始
claude

# 後で名前付きセッションを再開
/resume feature-auth-implementation

Claude Code運用ベストプラクティス上級編：Hooks・Subagents・コンテキスト管理の実践テクニック11選【2026年版】¶

はじめに：基本Tipsの先にあるもの¶

1. Hooksは"強制"、CLAUDE.mdは"助言"¶

Hooksの特徴¶

具体的な使い分け¶

実装例：機密ファイルへの書き込みをブロック¶

2. Subagentsは"別コンテキスト窓"で動く¶

Subagentsの特徴¶

スラッシュコマンドとの違い¶

効果的な使いどころ¶

3. Skillsは"文脈で自動発火"するドメイン知識¶

Skillsの位置づけ¶

実装例：API設計ルールをSkill化¶

手動専用Skill（誤爆防止）¶

4. CLAUDE.mdは"短くないと逆効果"¶

肥大化の問題¶

削除判断のフレームワーク¶

配置戦略¶

5. "承認疲れ"対策：AllowlistとSandbox¶

2つの対策アプローチ¶

Allowlistの設定例¶

機密ファイルをdenyで不可視化（Hookより堅い）¶

--dangerously-skip-permissionsの正しい使い方¶

6. "失敗を2回繰り返したら /clear"（筆者運用ルール）¶

なぜリセットが有効か¶

実践フロー¶

7. /compactは「要約の指示」を与えられる¶

手動制御のパワー¶

8. チェックポイントは会話/コードを独立に巻き戻せる¶

チェックポイントの特徴¶

活用パターン¶

9. 仕様策定と実装はセッションを分離する¶

推奨フロー¶

セッション1: 仕様策定¶

セッション2: 実装¶

10. 並列セッションはバイアス回避にも効く¶

並列セッションの価値¶

Writer/Reviewerパターン¶

テスト分離パターン¶

実務テク：git worktreeで物理的に分離¶

11. Fan-outは「少数でチューニング→全体展開」¶

大規模移行のフロー¶

実装例¶

無人実行のベストプラクティス¶

まとめ：運用設計の発想転換¶

付録：公式仕様に準拠したテンプレート集¶

関連記事¶

その他の関連記事¶

`--dangerously-skip-permissions`の正しい使い方¶