Claude Code 上級テクニック完全ガイド【2026年最新】｜Hooks・サブエージェント・CI/CD自動化からコスト最適化まで

目次

1. Hooks：6つのライフサイクルイベントで開発を自動化
2. カスタムサブエージェント：専門AIチームを構築する
3. Skills：動的コンテキスト注入とフォーク実行
4. Git Worktrees：並列開発で生産性を5倍にする
5. Headless Mode：CI/CDパイプラインとの完全統合
6. CLAUDE.md設計術：モノレポからエンタープライズまで
7. コンテキストウィンドウ完全攻略
8. Chrome連携：ビルド→テスト→検証の自動ループ
9. DevContainer：安全な自律実行環境
10. Permissions：三層評価とエンタープライズ管理
11. Plugin Marketplace：エコシステムの活用
12. 知られていないショートカットと環境変数
13. まとめ：上級者への12のチェックリスト

Hooks：6つのライフサイクルイベントで開発を自動化

Hooksは、Claude Codeの中で最も強力でありながら十分に活用されていない機能のひとつです。Claude Codeのライフサイクルの各ポイントに自動処理を差し込むことで、コードフォーマット、セキュリティチェック、テスト実行、通知送信などを完全に自動化できます。設定は .claude/settings.json に記述し、プロジェクト単位・ユーザー単位のどちらでも適用可能です。

Hookイベントの一覧

Claude Codeは以下のライフサイクルイベントをサポートしています。それぞれのイベントが発火するタイミングと主な用途を理解することが、Hook設計の第一歩です。

Hookの3つのタイプ

Hookには実行方式の異なる3つのタイプがあります。用途に応じて使い分けることで、決定論的な処理からAI判断を伴う高度な検証まで対応できます。

1. Command Hook（type: “command”）

シェルスクリプトを実行する最も基本的なタイプです。決定論的な処理に最適で、フォーマッタの実行、ファイルのコピー、ログの記録など、結果が予測可能な操作に使います。標準入力でツールの入出力をJSON形式で受け取り、標準出力でClaude Codeに結果を返します。

2. Prompt Hook（type: “prompt”）

LLM（Haiku）を使って、yes/noの判断を行うタイプです。「このコードは品質基準を満たしているか」「ユーザーの要求は完全に達成されたか」といった、人間的な判断が必要な場面で威力を発揮します。Haikuモデルで実行されるため、コストを抑えつつ知的な判断を自動化できます。

3. Agent Hook（type: “agent”）

マルチターンのサブエージェントを起動して検証を行う最も高度なタイプです。ファイルを読み込み、テストを実行し、その結果を分析するといった複数ステップの検証処理を自動化できます。

実践的なHook設定例

ここからは、すぐに使える実践的なHook設定を6つ紹介します。すべて .claude/settings.json に記述してください。

例1：ファイル編集のたびにPrettierで自動フォーマット（PostToolUse）

Claude Codeがファイルを編集・作成するたびに、Prettierが自動で走ります。AIが生成するコードのインデント崩れやフォーマット不統一を完全に排除できます。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null; exit 0"
      }]
    }]
  }
}

matcher に "Edit|Write" を指定することで、EditツールとWriteツールの実行後にのみ発火します。末尾の exit 0 は、Prettierが対応していないファイル形式でエラーになってもHook全体を失敗させないための安全策です。

例2：APIキーのハードコードをブロックするセキュリティゲート（PreToolUse）

OpenAI（sk-）、AWS（AKIA）、GitHub（ghp_）のAPIキーパターンを検出し、コードに書き込まれる前にブロックします。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'INPUT=$(cat); CONTENT=$(echo \"$INPUT\" | jq -r \".tool_input.new_string // .tool_input.content // empty\"); if echo \"$CONTENT\" | grep -qE \"(sk-[a-zA-Z0-9]{20,}|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36})\"; then echo \"{\\\"decision\\\": \\\"block\\\", \\\"reason\\\": \\\"APIキーのハードコードを検出しました\\\"}\"; else echo \"{\\\"decision\\\": \\\"approve\\\"}\"; fi'"
      }]
    }]
  }
}

PreToolUseフックが {"decision": "block"} を返すと、そのツール実行はキャンセルされます。Claude Codeは reason の内容を読み取り、別のアプローチ（環境変数の使用など）を自動で提案します。

例3：コンテキスト圧縮後にプロジェクトルールを再注入（SessionStart）

長時間のセッションでコンテキストウィンドウが圧縮（compaction）されると、序盤に伝えた指示が失われることがあります。このHookは、圧縮後に重要なルールを自動で再注入します。

{
  "hooks": {
    "SessionStart": [{
      "matcher": "compact",
      "hooks": [{
        "type": "command",
        "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current branch: '$(git branch --show-current)'. Last commit: '$(git log --oneline -1)''"
      }]
    }]
  }
}

matcher に "compact" を指定することで、セッション開始時ではなくcompaction後にのみ発火します。Gitのブランチ名や最終コミット情報を動的に取得して注入している点がポイントです。

例4：LLMによる完了検証（Stop）

Claude Codeが応答を完了するたびに、Haikuモデルが「ユーザーの要求は本当に満たされたか」を検証します。ファイルの作成漏れ、TODOコメントの放置、テストの未実行などを自動で検出できます。

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "Review the conversation. Did the user's request get fully completed? Check: all files created, tests passing, no TODO comments left.",
        "timeout": 30
      }]
    }]
  }
}

Prompt Hookが問題を検出した場合、Claude Codeは自動的に作業を再開して未完了部分を補完します。timeout を設定することで、検証が長引きすぎることを防ぎます。

例5：macOSデスクトップ通知（Notification）

Claude Codeがユーザーの対応を必要とする場面（確認待ち、エラー発生など）で、macOSのネイティブ通知を表示します。別の作業をしながらClaude Codeを走らせるときに便利です。

{
  "hooks": {
    "Notification": [{
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude Codeの対応が必要です\" with title \"Claude Code\"'"
      }]
    }]
  }
}

例6：全Bashコマンドの監査ログ（PostToolUse）

Claude Codeが実行したすべてのシェルコマンドをタイムスタンプ付きでログファイルに記録します。チーム開発やセキュリティ監査で、AIが何を実行したかを追跡できます。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'jq -r \".tool_input.command\" <<< \"$(cat)\" | while read cmd; do echo \"$(date +%Y-%m-%dT%H:%M:%S) $cmd\" >> \"$CLAUDE_PROJECT_DIR\"/.claude/command-audit.log; done; exit 0'"
      }]
    }]
  }
}

環境変数 $CLAUDE_PROJECT_DIR はClaude Codeが自動で設定するプロジェクトルートのパスです。ログは .claude/command-audit.log に蓄積され、いつでも確認できます。

HookのJSON解析エラーを防ぐ

Hookを設定したのにJSON解析エラーが発生する場合、シェルプロファイル（~/.zshrc や ~/.bashrc）が原因であることが多いです。プロファイルに無条件の echo 文があると、その出力がHookの標準出力に混入し、JSONパースに失敗します。以下のように、対話モードの場合のみ出力するよう修正してください。

# 修正前（問題あり）
echo "Shell ready"

# 修正後（対話モードでのみ出力）
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

Hook設計のベストプラクティス

「Block-at-Submit, not Block-at-Write」戦略：PreToolUseでEdit/Writeをブロックするのは避けてください。AIが計画の途中で何度もブロックされると、全体の作業効率が大幅に低下します。代わりに、git commitのタイミングでBashツールのPreToolUseフックを使い、テスト通過を示すマーカーファイルの存在を確認する方式が推奨されます。書き込み時ではなく、コミット時にゲートを設けることで、AIの思考フローを妨げずにコード品質を担保できます。

カスタムサブエージェント：専門AIチームを構築する

Claude Codeのサブエージェント機能を使えば、コードレビュー専門、セキュリティ監査専門、テスト設計専門など、役割特化型のAIエージェントを定義し、メインのClaude Codeセッションから呼び出せます。サブエージェントは .claude/agents/ ディレクトリにMarkdownファイルとして配置します。

サブエージェント定義ファイルの書き方

以下は、コードレビュー専門のサブエージェント定義例です。.claude/agents/code-reviewer.md として保存します。

---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
maxTurns: 50
memory: user
skills:
  - api-conventions
---

You are a senior code reviewer specializing in TypeScript.
Analyze code changes and provide structured feedback.
Focus on: security vulnerabilities, performance issues, type safety.

YAMLフロントマターの各フィールドが、サブエージェントの振る舞いを細かく制御します。

主要フィールドの解説

model（モデル選択）

サブエージェントに使用するモデルを指定します。ルーティンなタスク（フォーマットチェック、定型的なレビュー）には sonnet や haiku を割り当て、重要な判断が必要なタスク（アーキテクチャレビュー、セキュリティ監査）には opus を割り当てるのが効果的です。モデルを使い分けることで、コストを最適化しつつ品質を維持できます。

memory（永続メモリ）

サブエージェントがセッションをまたいで知識を蓄積できるメモリ機能です。3つのスコープから選択します。

例えば、コードレビューエージェントに memory: project を設定すると、過去のレビューで学んだプロジェクト固有のパターンやコーディング規約をチーム全体で共有できます。

tools（利用可能ツールの制限）

サブエージェントが使えるツールを明示的に制限します。セキュリティ監査エージェントにはRead/Grep/Globのみ（書き込み不可）、デプロイエージェントにはBashのみ、といった制御が可能です。最小権限の原則に従い、必要なツールだけを許可してください。

skills（スキルの読み込み）

サブエージェントに特定のスキルを読み込ませます。後述するSkills機能と組み合わせることで、ドメイン知識を持った専門エージェントを構築できます。

CLIから一時的なサブエージェントを定義する

ファイルを作成せずに、コマンドラインから直接サブエージェントを定義することも可能です。一時的な用途や試行錯誤の段階で便利です。

claude --agents '{
  "security-auditor": {
    "description": "Security vulnerability scanner",
    "prompt": "You are a security auditor. Check for OWASP Top 10.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "haiku"
  }
}'

この方法で定義されたサブエージェントは、そのセッション限りで消滅します。有用だと判明したら、.claude/agents/ に正式なファイルとして保存しましょう。

Master-Cloneアーキテクチャパターン

サブエージェントの設計パターンとして、役割ごとに異なるエージェントを作る方法と、同じ知識を持つクローンを複数生成する方法があります。後者は Master-Cloneパターン と呼ばれ、実践的な場面で特に効果的です。

このパターンでは、すべてのコンテキストを CLAUDE.md に集約し、Task(...) でクローンを生成します。各クローンは新しいコンテキストウィンドウを持ちますが、同じ CLAUDE.md の知識を共有します。異なるエージェントの性格やプロンプトを管理するより、単一の CLAUDE.md を充実させる方がシンプルで保守性も高くなります。

サブエージェント vs Agent Teamsの比較

Claude Codeには、サブエージェントの他にAgent Teams（複数エージェントの協調実行）という仕組みもあります。それぞれの特性を理解して使い分けてください。

サブエージェントは「上司が部下に仕事を振る」モデルで、親エージェントがすべてを統制します。Agent Teamsは「同僚同士が連携する」モデルで、各エージェントが自律的にタスクリストを確認しながら協調します。小規模なタスクにはサブエージェント、大規模な並列作業にはAgent Teamsが適しています。

Skills：動的コンテキスト注入とフォーク実行

Skillsは、Claude Codeに対してドメイン知識を最もトークン効率よく提供する仕組みです。CLAUDE.md がセッション開始時に常にロードされるのに対し、Skillsはスラッシュコマンドや自動トリガーで呼び出されたときだけコンテキストに注入されます。この「オンデマンド読み込み」により、普段のセッションではコンテキストウィンドウを消費せず、必要な場面でのみ専門知識を活用できます。

Skills、Hooks、Pluginsの関係

3つの拡張機能の役割を整理しましょう。Skills はナレッジ（知識）の提供に特化しています。Hooks はオートメーション（自動処理）に特化しています。そして Plugins は、SkillsとHooksの両方をパッケージ化して配布可能にしたものです。

SKILL.mdの書き方

Skillsは .claude/skills/ ディレクトリにMarkdownファイルとして配置します。YAMLフロントマターでメタデータを定義し、本文にプロンプトと動的コンテキストを記述します。

---
name: pr-summary
description: Pull Requestの要約を生成
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PRコンテキスト
- PRの差分: !`gh pr diff`
- PRのコメント: !`gh pr view --comments`
- 関連Issue: !`gh pr view --json body -q '.body'`

## タスク
上記のPR情報を分析し、以下の形式で要約を生成してください：
1. 変更の概要（3行以内）
2. 主な変更ファイルと理由
3. レビュー時の注意点

動的コンテキスト注入（!`command` 構文）

Skillsの最も強力な機能が、!`command` 構文による動的コンテキスト注入です。この構文で記述されたシェルコマンドは、Skillの内容がClaudeに送信される前に実行され、その出力結果がプロンプトに埋め込まれます。

つまり、以下のような動的な情報をSkill起動時にリアルタイムで取得してClaudeに渡せます。

• !`gh pr diff` ：実行時点のPR差分を注入
• !`git log --oneline -5` ：直近5件のコミット履歴を注入
• !`cat package.json | jq '.dependencies'` ：現在の依存関係一覧を注入
• !`wc -l src/**/*.ts | tail -1` ：TypeScriptファイルの総行数を注入

静的なプロンプトでは実現できない、プロジェクトの「今の状態」を正確に反映したコンテキストを構築できます。

context: fork による隔離実行

Skillのフロントマターに context: fork を指定すると、そのSkillは独立したサブエージェントとして実行されます。メインセッションのコンテキストウィンドウは消費されません。

これは、大量のコードを分析するスキルや、長時間の処理を伴うスキルで特に有効です。メインセッションが軽量に保たれるため、その後の作業にも余裕が生まれます。フォーク実行されたSkillの結果は、処理完了後にメインセッションへ要約として返されます。

disable-model-invocation: true

フロントマターに disable-model-invocation: true を追加すると、Claude Codeが自律的にそのSkillを呼び出すことを禁止できます。ユーザーがスラッシュコマンドで明示的に起動した場合のみ実行されます。

これは、デプロイスキルやメッセージ送信スキルなど、意図しない実行が問題になる操作に必須の設定です。安全性を担保しつつ、ワンコマンドで複雑な手順を実行できる利便性を両立します。

“ultrathink” キーワード

Skillの本文のどこかに ultrathink というキーワードを含めると、そのSkill実行時に拡張思考モード（Extended Thinking）が有効になります。複雑なアーキテクチャ分析や、多数のファイルにまたがるリファクタリング計画など、深い思考が必要なスキルで活用してください。

実践的なSkill活用例

1. コードベース可視化スキル

プロジェクトのディレクトリ構造、依存関係、モジュール間の関連をインタラクティブなHTMLファイルとして生成します。新しくプロジェクトに参加したメンバーのオンボーディングに有効です。

2. データベーススキーマ分析スキル

マイグレーションファイルやORMの定義からスキーマを読み取り、テーブル間のリレーション、インデックスの最適性、正規化の状態を分析します。

3. 依存関係アップデートチェッカー

!`npm outdated --json` で現在の依存関係の状態を動的に取得し、セキュリティアップデートの有無、破壊的変更の影響範囲、推奨アップデート手順を提案します。

4. テストカバレッジレポーター

!`npx jest --coverage --json` でカバレッジデータを取得し、カバレッジが低いモジュールの特定、テスト追加の優先順位付け、具体的なテストケースの提案を行います。

Skillsエコシステム

コミュニティによって37以上のSkillが公開されており、PR要約、コードレビュー、ドキュメント生成など、汎用的なタスクをカバーしています。Claude Code Skill Factory を使えば、プロジェクト固有のSkillを一括生成することも可能です。

また、--add-dir オプションで追加したディレクトリに含まれるSkillは自動的にロードされます。チーム共通のSkillリポジトリを用意し、各メンバーが --add-dir で参照する運用が効果的です。

Skillsの設計原則：1つのSkillは1つの目的に集中させてください。「何でもできるSkill」は、コンテキストが膨らむだけで精度が下がります。小さく単機能なSkillを組み合わせる方が、結果の品質もトークン効率も高くなります。

Git Worktrees：並列開発で生産性を5倍にする

Git worktreeは、パワーユーザーの間でも最も過小評価されている機能の一つです。単一のGitリポジトリから複数の作業ディレクトリを作成し、それぞれで独立したClaude Codeセッションを走らせることで、開発速度を劇的に向上させることができます。

Git Worktreeとは何か

通常、Gitリポジトリは1つのワーキングディレクトリしか持てません。ブランチを切り替えるにはgit checkoutが必要で、その度にファイル状態が書き換わります。Git worktreeはこの制約を取り払い、同一リポジトリから複数の独立した作業ディレクトリを生成します。各worktreeは独自のブランチ、ファイル状態を持ち、完全に独立したClaude Codeセッションを実行できます。

セットアップ

まず、メインリポジトリから各機能用のworktreeを作成します。

# 機能Aのworktreeを作成
git worktree add ../myproject-feature-a feature/auth-system

# 機能Bのworktreeを作成
git worktree add ../myproject-feature-b feature/payment-api

# 機能Cのworktreeを作成
git worktree add ../myproject-feature-c feature/dashboard-ui

これにより、ファイルシステム上に3つの独立したディレクトリが生まれます。それぞれが異なるブランチをチェックアウトした状態になっていますが、.gitオブジェクトはメインリポジトリと共有されるため、ディスク消費は最小限に抑えられます。

並列開発パターン

3つのターミナルを開き、それぞれでClaude Codeを起動します。

# ターミナル1：認証システムの実装
cd ../myproject-feature-a && claude

# ターミナル2：決済APIの実装
cd ../myproject-feature-b && claude

# ターミナル3：ダッシュボードUIの実装
cd ../myproject-feature-c && claude

各Claude Codeインスタンスが得る恩恵は以下の通りです。

• 独立したコンテキストウィンドウ：他の機能の情報でコンテキストが汚染されない
• 機能固有のメモリ：アーキテクチャ上の判断が各セッション内に隔離される
• 独立したテスト実行：各worktreeで個別にテストを走らせられる
• ファイル競合の回避：異なるファイルに書き込むため、マージコンフリクトが発生しにくい

Writer/Reviewerパラレルパターン

同一機能に対して2つのClaude Codeセッションを使い分ける手法もあります。

• セッションA（Writer）：機能を実装する。コードを書き、テストを通し、動作確認を行う
• セッションB（Reviewer）：完全に新鮮なコンテキストでレビューを行う。実装の経緯を知らないため、客観的な品質チェックが可能

人間のレビューでも同じことが言えますが、自分が書いたコードを自分でレビューすると「自己バイアス」が働きます。Writer/Reviewerパターンは、セッションを分離することでこのバイアスを構造的に排除します。

マージワークフロー

機能の実装が完了したら、メインリポジトリに戻ってマージし、不要になったworktreeを削除します。

# 機能Aが完了した場合
cd ../myproject
git merge feature/auth-system
git worktree remove ../myproject-feature-a

注意点

Git worktreeは万能ではありません。以下の点に留意してください。

• 密結合コードの並列変更は危険：同じファイルやモジュールを複数のworktreeで同時に変更すると、マージコンフリクトの解決コストが時間の節約を上回る場合がある
• コードベースの異なる領域を触る機能に最適：フロントエンド、バックエンド、インフラなど、明確に分離された領域での並列開発で最大の効果を発揮する
• ディスクスペースの消費：各worktreeはファイルのコピーを保持する。ただし.gitオブジェクトは共有されるため、リポジトリの完全コピーに比べれば消費は少ない

参考：Shipping faster with Claude Code and Git Worktrees – incident.io

Headless Mode：CI/CDパイプラインとの完全統合

Claude Codeの真価は対話的な利用だけにとどまりません。Headless Modeを使えば、CI/CDパイプラインやスクリプトからプログラマティックにClaude Codeを呼び出し、コードレビュー、テスト生成、セキュリティ監査などを完全に自動化できます。

基本的なHeadless利用

-pフラグを使うと、Claude Codeを非対話モードで実行できます。対話的なプロンプトは表示されず、結果を標準出力に返して終了します。

# シンプルなタスク実行
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

# JSON形式で出力
claude -p "Summarize this project" --output-format json

# JSONスキーマによるバリデーション付き出力
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

# トークンをリアルタイムにストリーミング
claude -p "Write a poem" --output-format stream-json

--output-format jsonは構造化データを受け取りたい場合に、--json-schemaは出力形式を厳密に制御したい場合に使用します。stream-jsonはトークン単位のストリーミングが必要なリアルタイム処理向けです。

GitHub Actionsとの統合

公式のClaude Code GitHub Actionが提供されています。セットアップはClaude Codeのターミナルから/install-github-appコマンドを実行するだけです。これによりGitHubリポジトリとClaude Codeが接続され、PR作成やコメントベースの自動処理が可能になります。

実践的なCI/CDパターン

パターン1：コミットメッセージの自動生成

ステージングされた変更を分析し、適切なコミットメッセージを自動生成してコミットします。--allowedToolsでgit関連のコマンドのみに権限を制限している点に注目してください。

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

パターン2：セキュリティ特化型PRレビュー

PRの差分をパイプで渡し、セキュリティエンジニアの視点でレビューさせます。SQLインジェクション、XSS、ハードコードされたシークレット、安全でないデシリアライゼーションなど、具体的な脆弱性カテゴリを指定することで精度が上がります。

gh pr diff "$PR_NUMBER" | claude -p \
  "You are a security engineer. Review this diff for vulnerabilities including: SQL injection, XSS, hardcoded secrets, insecure deserialization." \
  --output-format json \
  --allowedTools "Read,Grep,Glob"

パターン3：GitHub Actionsワークフロー

CIパイプラインにClaude Codeを組み込む具体的なワークフロー定義例を示します。

- name: AI Code Review
  run: |
    gh pr diff ${{ github.event.pull_request.number }} | \
    claude -p "Review this PR for bugs, security issues, and style violations" \
    --output-format json \
    --allowedTools "Read,Grep,Glob"

パターン4：PRやIssueでの@claudeメンション

GitHub Appをインストール済みの場合、PRコメントやIssueで@claudeとメンションするだけで、自動的な分析、実装、PR作成が行われます。人間のチームメンバーに話しかけるのと同じ感覚でClaude Codeを起動できるため、開発者体験が極めて自然になります。

セッション継続

CIの複数ステップにまたがって同一セッションを維持したい場合、セッションIDを使って継続できます。

# レビューを開始し、セッションIDを取得
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')

# 次のCIステップで同じセッションを継続
claude -p "Continue that review" --resume "$session_id"

これにより、前のステップで蓄積されたコンテキスト（ファイル構造の理解、発見した問題点など）を引き継ぎながら、後続の処理を実行できます。

セキュリティ上の注意

• ネットワーク制限がデフォルトでは存在しない：GitHub Copilotとは異なり、Claude Codeはネットワークアクセスに制限をかけない。CI環境では特に注意が必要
• APIキーはGitHub Secretsで管理：ワークフローファイルにAPIキーを直接記述しないこと
• –allowedToolsで権限を最小化：CI環境では必要なツールのみを許可し、意図しないファイル変更やコマンド実行を防ぐ

参考：Claude Code Headless Mode Documentation、Claude Code GitHub Actions Documentation

CLAUDE.md設計術：モノレポからエンタープライズまで

CLAUDE.mdはClaude Codeの「設定ファイル」であると同時に、AIとの「契約書」でもあります。適切に設計すれば、セッションごとのブレを排除し、チーム全体で一貫した開発品質を維持できます。設計が甘ければ、毎セッションのトークンを無駄に消費し続けることになります。

4階層のヒエラルキー

CLAUDE.mdは4つのレベルで配置でき、それぞれ異なるスコープと読み込みタイミングを持ちます。

モノレポアーキテクチャ

モノレポでは、ルートのCLAUDE.mdに全体ルールを置き、各パッケージに固有ルールを配置します。

myrepo/
├── CLAUDE.md                    # リポジトリ全体：TypeScript strict, pnpm, テストポリシー
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md            # Reactの規約、コンポーネントパターン
│   ├── backend/
│   │   └── CLAUDE.md            # Expressのパターン、DBアクセスルール
│   └── shared/
│       └── CLAUDE.md            # 共有型定義、ユーティリティパターン
└── infrastructure/
    └── CLAUDE.md                # Terraformの規約、AWSパターン

ここで重要なのは、サブディレクトリのCLAUDE.mdは遅延読み込みされる点です。Claude Codeがそのディレクトリ内のファイルを読み取ったときに初めてコンテキストに取り込まれます。フロントエンド開発中にバックエンドのルールでコンテキストが汚染されることはありません。

何を書くべきか（優先順位順）

1. エンジニアリング原則とフォルダ構造：プロジェクトの「なぜ」を伝える
2. ビルド・テスト・デプロイコマンド：正確な実行手順
3. やってほしくないこと（除外ルール）：Claudeが暴走しがちな領域を明示的に制限する
4. ファイル命名規約とパターン：一貫性を保つための規約
5. モジュール間の依存関係：どのモジュールがどのモジュールに依存するか

何を書くべきでないか

• 汎用的なアドバイス：「きれいなコードを書け」のような指示はトークンの無駄。Claudeは元々きれいなコードを書く
• コードスニペット：時間とともに陳腐化する。代わりにfile:line形式の参照を使う
• @メンションによるドキュメント全文の取り込み：必要になったときにClaudeが自分で読めばよい。常にコンテキストに載せる必要はない

「広告スペース」の原則

CLAUDE.mdを希少な広告スペースとして扱え。全ての行が、全てのセッションでトークンを消費する。そのトークンコストを正当化できないなら、削除せよ。目標は500行以下だ。

これはCLAUDE.md設計における最も重要な原則です。プロジェクトが成長するにつれて、CLAUDE.mdも肥大化しがちですが、定期的に棚卸しを行い、不要になったルールを削除することが不可欠です。

ライブ設定更新

CLAUDE.mdは静的なファイルではありません。セッション中にClaudeが新しいパターンを発見した場合、その場でCLAUDE.mdを更新させることができます。一部のチームでは、~/.claude/projects/ディレクトリの履歴データを分析してエラーパターンを特定し、その知見に基づいてCLAUDE.mdを改善するプラクティスを採用しています。

エンタープライズ向けmanaged-settings.json

IT管理者は、ユーザーが上書きできない管理設定をデプロイできます。これにより、組織全体で一貫したセキュリティポリシーやツール制限を強制することが可能です。

参考：Claude Code Memory Documentation

コンテキストウィンドウ完全攻略

Claude Codeのパフォーマンスは、コンテキストウィンドウの管理品質に直結します。200Kトークンという広大な空間も、無計画に使えばすぐに枯渇します。ここでは、コンテキストウィンドウの内部動作を理解し、最大限に活用するための戦略を解説します。

トークンバジェットの現実

200Kトークンの全てが自由に使えるわけではありません。実際の内訳を正確に把握しておく必要があります。

新規セッションを開始した時点で既に約20Kトークンが消費されます。これはシステムプロンプト、CLAUDE.mdの内容、有効なSkillsの定義などで占められます。CLAUDE.mdの肥大化が直接的にセッションの有効容量を圧迫する理由がここにあります。

StatusLine計算の罠

Claude Codeが表示するremaining_percentageには、Autocompactバッファ（16.5%）が含まれています。つまり、表示上の残り割合と実際に使える容量には乖離があります。

freeUntilCompact = max(0, remaining_percentage - 16.5)

例えば、残り25%と表示されていても、実際に圧縮が発動するまでに使えるのは8.5%しかありません。残り20%で「まだ余裕がある」と思い込むのは危険です。

圧縮タイミングのオーバーライド

デフォルトの圧縮トリガーが早すぎる、または遅すぎる場合は、環境変数で調整できます。

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90

値を大きくするとコンテキストをより長く保持しますが、圧縮が発動したときの情報損失量も大きくなります。逆に小さくすると頻繁に圧縮されますが、各回の損失は小さくなります。プロジェクトの性質に応じて調整してください。

3段階のコンテキスト戦略

コンテキストが逼迫した際の対処法は、状況に応じて3段階に分かれます。

レベル1：シンプルなリスタート

/clearでコンテキストをリセットし、直後に/catchupを実行します。/catchupはgitで変更されたファイルを自動的に読み込み、直前の作業状態をある程度復元してくれます。

レベル2：Document & Clear

複雑なタスクの途中でコンテキストが不足した場合、まずClaudeに現在の進捗をマークダウンファイルにダンプさせます。その後、新しいセッションを開始し、ダンプしたファイルを読み込ませて作業を継続します。圧縮による情報損失を自分でコントロールできます。

レベル3：拡張コンテキスト

sonnet[1m]を使うと100万トークンのコンテキストウィンドウが利用可能になります。大規模なコードベースの一括分析や、巨大なログファイルの解析など、通常の200Kでは足りない場面で有効です。

主要コマンド一覧

/compactコマンドには引数としてフォーカスエリアを指定できます。例えば/compact authentication logicと指定すると、認証ロジックに関する情報を優先的に保持しつつ、それ以外を圧縮します。漫然と圧縮するより遥かに品質が高くなります。

アンチパターン：Kitchen Sinkセッション

1つのセッションで無関係な複数タスクを処理するのは、コンテキスト管理における最大のアンチパターンです。タスク間で/clearを挟むだけで、トークン消費量を50-70%削減できます。

「バグ修正」「新機能追加」「リファクタリング」を同一セッションで行うと、それぞれのタスクに関する情報が混在し、Claudeの判断精度が低下します。さらに、不要な情報がコンテキストを圧迫し、本来必要な情報が圧縮で失われるリスクも高まります。タスクの切れ目で/clearを習慣化してください。

サブエージェント委任によるコンテキスト保護

Claude Codeは最大7つの並列サブエージェントを起動できます。各サブエージェントは独自のコンテキストウィンドウを持つため、メインセッションのコンテキストを消費しません。

以下の処理はサブエージェントに委任すべきです。

• 大量のファイル読み取り：コードベース全体のスキャンなど
• 広範なコード検索：grepやglobによるパターン検索
• Webフェッチ：ドキュメントやAPIリファレンスの取得

これらの操作をメインセッションで直接行うと、読み取ったファイルの内容がそのままコンテキストに蓄積されます。サブエージェントに委任すれば、結果のサマリーだけがメインセッションに返され、コンテキストの消費を大幅に抑制できます。

参考：Claude Code Best Practices Documentation

Chrome連携：ビルド→テスト→検証の自動ループ

Claude Codeは、Chrome拡張機能「Claude in Chrome」（ベータ版）と連携することで、ターミナルを離れることなくブラウザ操作を自動化できます。コードを書き、ブラウザで検証し、問題があれば即座に修正する。このループが完全に自動化されます。

Chrome連携でできること

Claude in Chrome拡張機能を導入すると、Claude Codeから以下の操作が可能になります。

• ページナビゲーション：指定URLを開き、ボタンクリック、フォーム入力を自動実行
• コンソールログの読み取り：ブラウザのconsole.logやエラーをリアルタイムで監視
• ネットワークリクエストの監視：APIコールの成功・失敗を検証
• ブラウザ操作のGIF記録：インタラクションの様子をGIFとしてキャプチャ
• ビルド→テスト→検証ループ：ターミナルから一切離れずに完結

自動ループのワークフロー

Chrome連携の真価は、開発サイクル全体を自動化できる点にあります。以下のフローがClaude Codeの単一セッション内で実行されます。

1. Claude Codeがコードを記述・編集する
2. Claude CodeがChrome拡張機能にlocalhost:3000を開くよう指示する
3. Chrome拡張機能がUIの表示・動作を検証する
4. コンソールにエラーが検出された場合、Claude Codeが自動的にコードを修正する
5. 全テストがパスするまでループを繰り返す

セットアップ手順

セットアップは非常にシンプルです。

1. Chrome Web Storeから「Claude in Chrome」拡張機能をインストールする
2. Google ChromeおよびMicrosoft Edgeに対応している
3. Claude Codeが拡張機能を自動検出するため、追加設定は不要

実践的なユースケース

フロントエンド開発では、Reactコンポーネントを記述した後、ブラウザで即座に描画結果を確認し、視覚的な問題を自動修正できます。例えば「ボタンの色がデザインと異なる」といった問題も、ブラウザ上のレンダリング結果からClaude Codeが検知して修正します。

E2Eテストでは、ブラウザ操作を通じたユーザーフローのテストを自動化できます。フォーム入力、ボタンクリック、ページ遷移といった一連の操作をClaude Codeが実行し、期待通りの結果が得られるかを検証します。

デバッグでは、ブラウザのコンソールエラーを読み取り、原因を特定して自動修正します。手動でDevToolsを開いてエラーを確認する手間が完全に不要になります。

スクリーンショットによるドキュメント作成では、UIの各状態をキャプチャしてドキュメント用の素材として保存できます。

現時点での制限事項

Chrome連携はベータ機能であり、以下の制限がある点に注意が必要です。

• ベータ版のため、動作が不安定な場合がある
• 複雑なドラッグ＆ドロップ操作はまだサポートされていない
• 認証フローを含む操作は慎重な取り扱いが必要

参考：Anthropic – Chrome Integration

DevContainer：安全な自律実行環境

Claude Codeの生産性を最大化するには、全ての操作を自動承認する「完全自律モード」が理想的です。しかし、ホストマシン上で全権限を与えるのは明らかに危険です。この矛盾を解決するのがDevContainerによる「Dangerboxing」パターンです。

なぜDevContainerが必要か

Claude Codeはマシン上であらゆるコマンドを実行できます。最大限の生産性を引き出すためには完全な自律権を与えたいところですが、ホストシステム上での完全自律は以下のリスクを伴います。

• 重要なシステムファイルの誤削除
• 意図しないネットワークアクセス
• 認証情報の漏洩
• 他プロジェクトへの干渉

Dangerboxingという発想

Dangerboxingとは、Dockerコンテナ内でClaude CodeをbypassPermissionsモードで実行するアプローチです。セキュリティ境界をパーミッションシステムではなく、コンテナそのものに委ねます。コンテナ内では何をしても良い。なぜなら、コンテナの外には影響が及ばないからです。

Anthropic公式DevContainer設定

Anthropicが提供する公式のdevcontainer設定は以下の通りです。

{
  "name": "Claude Code Dev",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {}
  },
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code"
}

この設定でUbuntuベースのコンテナにNode.jsとClaude Codeがインストールされます。VS CodeのDev Containers拡張機能やdevcontainer CLIから利用できます。

Trail of Bits セキュリティ強化版DevContainer

セキュリティ企業Trail of Bitsが公開しているDevContainerは、さらに強固なセキュリティ制約を実装しています。

• デフォルト拒否ネットワークポリシー：SSHとDNSのみ許可
• アウトバウンドファイアウォール：ホワイトリストに登録されたドメインのみ接続可能
• ホストファイルシステムへのアクセス不可：完全に隔離された環境
• コンテナ内での完全自律：bypassPermissionsを安全に有効化

セキュリティ比較

リモート開発ワークフロー

DevContainerはリモート開発とも相性が良いです。SSHでリモートのdevserverに接続し、devcontainer CLIでコンテナを起動してtmuxセッション内で作業します。Neovimと組み合わせれば、リモートコンテナ上で動作しているにもかかわらず、ネイティブに近い開発体験が得られます。

参考：Anthropic – DevContainer、Trail of Bits – Claude Code DevContainer

Permissions：三層評価とエンタープライズ管理

Claude Codeのパーミッションシステムは、単純な許可・拒否ではなく、三層の評価順序を持つ高度な仕組みです。この仕組みを正しく理解することで、セキュリティを維持しながら開発効率を最大化できます。

三層評価の順序

パーミッションルールは以下の優先順位で評価されます。

1. Deny（拒否）ルール：他のルールに関係なく、マッチしたら即座にブロック。最も高い優先度を持つ
2. Allow（許可）ルール：マッチした場合に自動承認
3. Ask（確認）ルール：ユーザーに承認プロンプトを表示する。デフォルトの動作

重要なのは、Denyルールが常に最優先される点です。Allowルールで許可されていても、Denyルールにマッチすれば拒否されます。

パーミッションモード

Shift+Tabを押すたびに、Normal → Accept Edits → Plan Modeとモードが切り替わります。状況に応じてモードを使い分けることで、セキュリティと効率のバランスを調整できます。

高度なパーミッションルール構文

設定ファイル（.claude/settings.json等）でツールごとに細かいルールを定義できます。

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Read",
      "Edit(/src/**/*.ts)",
      "WebFetch(domain:example.com)",
      "mcp__github__*"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Read(.env*)"
    ]
  }
}

この例では、npm run系コマンドとgit commitは自動許可、/src配下のTypeScriptファイル編集は自動許可、一方でrm -rfやgit push --force、.envファイルの読み取りは完全にブロックしています。

パスパターンの種類（gitignore仕様）

重要な落とし穴：/Users/alice/fileは絶対パスではありません。これは設定ファイルからの相対パスとして解釈されます。ファイルシステムの絶対パスを指定するには、//Users/alice/fileとスラッシュを2つ重ねる必要があります。この仕様を知らないと、意図しないファイルが許可・拒否の対象になる可能性があります。

ワイルドカードの落とし穴

*の前のスペースの有無で挙動が変わります。Bash(ls *)はls -laにマッチしますが、lsofにはマッチしません。一方、Bash(ls*)はスペースなしのため、lsで始まる全てのコマンド（lsofを含む）にマッチします。

エンタープライズ管理設定

企業のIT部門は、ユーザーが上書きできないマネージド設定をデプロイできます。

• macOS：/Library/Application Support/ClaudeCode/managed-settings.json
• Linux：/etc/claude-code/managed-settings.json

エンタープライズ専用の設定項目として以下が利用できます。

• disableBypassPermissionsMode：bypassPermissionsモードの無効化
• allowManagedPermissionRulesOnly：管理者定義のルールのみ許可
• allowManagedHooksOnly：管理者定義のHooksのみ許可
• strictKnownMarketplaces：既知のマーケットプレイスのみ許可
• allowedMcpServers / deniedMcpServers：MCPサーバーのホワイトリスト・ブラックリスト

これらの設定により、組織全体で一貫したセキュリティポリシーを適用しつつ、開発者の生産性を確保できます。

参考：Anthropic – Permissions

Plugin Marketplace：エコシステムの活用

Claude Codeは単体でも強力ですが、コミュニティが構築したプラグインエコシステムを活用することで、その能力は飛躍的に拡張されます。2026年2月現在、Claude Codeのエコシステムは急速に成長しています。

Everything-Claude-Code（48K+ Stars）

コミュニティ最大のプラグインであるEverything-Claude-Codeは、Claude Codeの機能を大幅に拡張する統合パッケージです。

• 12の専門サブエージェント：タスク別に最適化されたエージェント群
• 30以上のスキル：再利用可能な動的コンテキスト注入
• 31以上のスラッシュコマンド：頻出ワークフローのショートカット
• 多言語ルールシステム：言語ごとに最適化されたルール

特筆すべきコマンドを以下に紹介します。

• /learn：セッション中にパターンを抽出し、学習する
• /evolve：学習したインスティンクト（直感）をスキルにクラスタリングする
• /instinct-status：学習済みインスティンクトを信頼度スコア付きで表示する
• /multi-plan：タスクを複数エージェントに分解して実行する
• /skill-create --instincts：継続学習型インスティンクトを生成する

マーケットプレイスの追加とプラグインのインストール

/plugin marketplace add <github-url>
/plugin install plugin-name@marketplace-name

GitHubリポジトリをマーケットプレイスとして登録し、そこからプラグインをインストールする仕組みです。

Claude Codeエコシステムの現状（2026年2月時点）

エコシステムの規模は以下の通りです。

• 57のプロダクション対応スラッシュコマンド：15のワークフロー、42のツール
• 37以上のコミュニティスキル
• 12以上のHookコレクション
• 注目リポジトリ：wshobson/commands、qdhenry/Claude-Command-Suite
• キュレーションリスト：GitHubのawesome-claude-code

参考：Anthropic – Plugin Marketplaces、awesome-claude-code

知られていないショートカットと環境変数

Claude Codeには公式ドキュメントでは目立たない位置に記載されているショートカットや環境変数が数多く存在します。これらを知っているかどうかで、日々の操作効率は大きく変わります。

隠れたキーボードショートカット

EscとEsc x2の違いに注目してください。1回のEscは現在の操作を中断するだけでコンテキストは保持されます。2回連続のEscはリワインド機能を呼び出し、直前のチェックポイントまでコンテキストを巻き戻します。誤った方向に進んだ場合の強力なリカバリ手段です。

また、!プレフィックスは非常に便利です。!ls -laのように入力すると、Claude Codeのトークンを一切消費せずにシェルコマンドを直接実行できます。ファイルの確認やgit statusなど、AIの応答が不要な操作に最適です。

パワーユーザー向け環境変数

CLAUDE_AUTOCOMPACT_PCT_OVERRIDEは特に重要です。デフォルトではコンテキストウィンドウの一定割合を超えると自動圧縮が発生しますが、この変数でトリガーを調整できます。長いセッションで頻繁に圧縮が走る場合は、値を上げることで作業の中断を減らせます。

CLAUDE_CODE_MAX_OUTPUT_TOKENSは、Claude Codeの1回の応答に使えるトークン数の上限です。大量のコード生成が必要な場合にデフォルトの32Kでは不足することがあります。その場合はこの値を増やしてください。

デバッグの切り札

Claude Codeの動作を深く理解するためのデバッグ手法も紹介します。

• HTTPS_PROXY / HTTP_PROXY：プロキシを設定することで、Claude Codeが送信する生のプロンプトを傍受・確認できる。どのようなコンテキストがAPIに送信されているかを正確に把握したい場合に有用
• claude –debug：フラグを付けて起動すると、完全な実行詳細が表示される。ツール呼び出しの順序、パーミッション評価の結果、MCP通信の詳細などが確認可能
• /context：リアルタイムでコンテキストの使用量を確認する。どのファイルやツール出力がどれだけのトークンを消費しているかを把握できる

まとめ：上級者への12のチェックリスト

本記事で解説した12のテクニックを、実践チェックリストとしてまとめます。各項目を自分のワークフローに1つずつ導入し、効果を確認してください。

1. Hooks：PreToolUseでセキュリティゲートを実装し、PostToolUseで自動フォーマット・テストを実行する
2. カスタムサブエージェント：専門領域ごとのエージェントを定義し、memory設定でコンテキストを効率化する
3. Skills：動的コンテキスト注入を活用し、context: forkで独立実行環境を構築する
4. Git Worktrees：並列開発で生産性を5倍に引き上げる
5. Headless Mode：CI/CDパイプラインでの自動コードレビュー・修正を実現する
6. CLAUDE.md：モノレポ向けに階層設計を行い、500行以内のルールを徹底する
7. コンテキスト管理：/clear + /catchupを駆使し、Kitchen Sink Sessionsを回避する
8. Chrome連携：ビルド→テスト→検証の自動ループで手動確認を排除する
9. DevContainer：Dangerboxingで安全な自律実行環境を構築する
10. Permissions：三層評価を理解し、パスパターンの正しい書き方（//による絶対パス）を徹底する
11. Plugin Marketplace：コミュニティエコシステムを活用し、定型作業を自動化する
12. ショートカット：Shift+Tab、Esc x2、!コマンドで操作を高速化する

Claude Codeの真価は、デフォルト設定では発揮されません。Hooks、Skills、サブエージェント、DevContainerを組み合わせることで、AIコーディングアシスタントは「自律開発プラットフォーム」に進化します。本記事の12のテクニックを1つずつ試し、自分のワークフローに組み込んでください。

関連記事

• Claude Code 初心者完全ガイド
• Claude Code 実践ワークフロー完全ガイド
• Claude Code Agent Teams完全ガイド
• Claude Code 完全攻略ガイド
• Claude MCP入門

参考文献

1. Anthropic – Claude Code Hooks
2. Anthropic – Custom Subagents
3. Anthropic – Skills
4. Anthropic – Memory
5. Anthropic – Headless Mode
6. Anthropic – GitHub Actions
7. Anthropic – Chrome Integration
8. Anthropic – DevContainer
9. Anthropic – Permissions
10. incident.io – Git Worktrees with Claude Code
11. Trail of Bits – Claude Code DevContainer
12. awesome-claude-code