Claude Code の hooks・サブエージェント入門

Anthropicが提供する「Claude Code」は、単なるチャット型のAIアシスタントではありません。ターミナルに常駐し、ファイル操作、コマンド実行、そして自律的なサブエージェントの起動を行うことができる、エージェント型の開発支援ツールです。

特に、実務において開発生産性を劇的に向上させるのが「hooks（フック）」と「サブエージェント（Sub-agents）」の機能です。本記事では、Anthropicの公式ドキュメントおよび仕様に基づき、これらの高度な機能をどのように設定・運用すべきか、IT実務担当者の視点で解説します。

コードを書かない人の始め方と、任せていい仕事の線引きを、動画にまとめています↓↓

Claude Codeのコア機能：hooksとサブエージェントの概要

エージェント型CLIとしてのClaude Code

Claude Codeは、ターミナルで動くCLIを中心に、IDEの拡張（VS Code・JetBrains）、デスクトップアプリ、ブラウザ（claude.ai/code）でも使える開発支援ツールです（公式の概要）。従来のAIツールと決定的に異なるのは、「コードを書くだけ」ではなく「コードを実行し、エラーを読み取り、修正して再試行する」というループを自律的に行える点にあります。

なぜhooksが実務の自動化に不可欠なのか

hooks（フック）とは、特定のイベントが発生した際に、あらかじめ定義しておいたスクリプトや処理を自動的に実行させる仕組みです。例えば、Claude Codeがコードを修正した直後に自動でテストを走らせ、テストが失敗した場合は自動で再修正を試みさせるといったワークフローが構築可能です。これにより、人間が「テストを叩く」という手間を省き、AIが「完遂」まで責任を持つ環境が整います。

サブエージェントによる並列タスク処理の利点

大規模なリファクタリングや複雑な機能追加を行う際、Claude Codeは親エージェントがタスクを分割し、複数の「サブエージェント」を生成して並行処理を行うことができます。これにより、依存関係の少ないモジュールの同時修正などが可能になり、完了までの時間を大幅に短縮できます。

このようなAIによる自律的なワークフローの構築は、バックオフィス業務の自動化にも通ずる考え方です。例えば、Excelと紙の限界を突破する「Google Workspace × AppSheet」業務DX完全ガイドで解説しているような、手作業をデジタルへ移行し、プロセスを自動化する思想は、エンジニアリングにおけるClaude Code活用とも深く共鳴します。

実践：hooks（フック）の設定方法と活用事例

設定ファイルの構造（settings.json）

hooks は、Claude Code の設定ファイル settings.json に書きます。プロジェクトのメンバーで共有するなら .claude/settings.json（リポジトリに入れられる）、自分だけに効かせるなら .claude/settings.local.json、すべてのプロジェクトに効かせるなら ~/.claude/settings.json です（公式の Hooks reference。2026年9月30日に確認）。サブエージェントは settings.json ではなく、.claude/agents/ に置く Markdown のファイルで定義します（後述）。

基本的な構成例は以下の通りです。ファイルを編集した後に lint を走らせ、git commit の前にテストを走らせて、失敗したらコミットを止める例です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run lint 1>&2 || exit 2" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git commit *)",
            "command": "npm test 1>&2 || exit 2"
          }
        ]
      }
    ]
  }
}

PostToolUse はツールが実行された後なので編集は止まりませんが、終了コード 2 で終わると、エラーの出力が Claude に渡り、Claude が直しにいけます。PreToolUse を終了コード 2 で終えると、そのツールの実行（ここではコミット）が止まります。if は許可の規則と同じ書き方で、Bash のうち git commit のときだけ動かす指定です（Hooks reference）。ただし if での絞り込みは確実ではないため、必ず止めたい操作は、後述の権限の設定で拒否します。

サポートされるイベントの種類

Claude Codeが標準で認識するフックイベントには、主に以下のものがあります。

• PreToolUse: ツール（ファイルの編集、コマンドの実行など）を使う直前に実行。終了コード 2 で終わると、そのツールの実行を止められる。
• PostToolUse: ツールの実行が成功した直後に実行。lint やテストでの結果の検証に向く。
• PostToolUseFailure: ツールの実行が失敗した後に実行。
• Stop・SubagentStop: Claude（またはサブエージェント）が応答を終えたときに実行。
• このほか SessionStart・UserPromptSubmit・Notification・PreCompact などがあり、一覧は公式の Hooks referenceにあります。

【実例】Gitコミット前の自動Lint & テスト実行

実務で最も有用なのが、Claudeが生成したコードに対して強制的にCI的な検証をかけるフックです。
例えば、Claudeに「この関数をリファクタリングして」と依頼した際、ファイルを編集するたびに PostToolUse フックで eslint を、コミットの前に PreToolUse フックで jest を自動実行するように設定しておけば、開発者の手元に届くコードは常に一定の品質が担保された状態になります。

これは、経理業務におけるデータの整合性を自動で担保する仕組みに似ています。楽楽精算×freee会計の「CSV手作業」を滅ぼす。経理の完全自動化とアーキテクチャで見られるような、「人間が介在せずに整合性をチェックする」プロセスこそが、AI時代の標準的なアーキテクチャと言えるでしょう。

サブエージェントの自律性を制御する

タスク分割のメカニズム

Claude Codeのサブエージェント機能は、複雑な指示を受けた際に真価を発揮します。
例えば「認証機能を実装し、それに対応するドキュメントを作成し、テストケースを100%網羅して」という指示を与えた場合、親エージェントは以下のサブエージェントを生成することがあります。

1. 認証ロジック実装エージェント
2. テストコード生成・実行エージェント
3. ドキュメント（Markdown）記述エージェント

自律実行の制限とセキュリティ設定

自律的なエージェントは便利である一方、無限にトークンを消費したり、意図しない破壊的なコマンドを実行したりするリスクがあります。実務上は、以下の制御が推奨されます。

• 実行の確認: Claude Code は既定の権限モードでは、読み取りだけのコマンドを除き、シェルのコマンドを実行する前に許可を求めます。settings.json の permissions の ask（毎回確認する）や deny（拒否する）に、Bash(git push *) のような規則を入れておけます。確認を省く --dangerously-skip-permissions は使わないようにします（公式の Permissions）。
• 予算上限: API（従量課金）で使う場合、非対話モード（claude -p）では --max-budget-usd で API への支出の上限（ドル）を決められます。サブエージェントの分も含まれます（公式の CLI reference）。定額のプランで使う場合は、請求額ではなく、プランの使用量の上限が減っていきます。

特にエンタープライズ環境では、SaaSの管理と同様に「誰が、どの権限で、何を実行したか」のガバナンスが重要です。SaaS増えすぎ問題と退職者のアカウント削除漏れを防ぐ。Entra ID・Okta・ジョーシスを活用した自動化アーキテクチャのように、AIエージェントのアクセス権限も中央集権的なID管理の元に置く検討が必要です。

比較検証：Claude Code vs 他社AIツール

開発現場で利用される主要なAIツールと、Claude Codeの立ち位置を比較表にまとめました。

※料金・仕様は2026年9月30日に各社の公式ページ（Claude のプランと料金 / GitHub Copilot のプラン / Cursor の料金プラン、hooks は Claude Code・GitHub Copilot・Cursor のドキュメント）で確認したものです。最新情報は各社の公式ページをご確認ください。

導入時によくあるエラーとトラブルシューティング

1. hooksの実行エラー（権限・パス問題）

settings.json の hooks に記述したコマンドが command not found になるケースが多発します。これは、Claude Codeが実行されるシェルの環境変数が、ユーザーのログインシェルと微妙に異なる場合に発生します。

• 解決策: 実行コマンドを ./node_modules/.bin/eslint のように相対パスで書くか、絶対パスを指定する。プロジェクトの中のスクリプトは、公式の例のように "$CLAUDE_PROJECT_DIR"/.claude/hooks/check.sh と、プロジェクトのルートを指す環境変数を使って書くと確実です。パスが間違っているとフックは動かず、多くのイベントでは処理がそのまま進むので、最初の実行で警告が出ていないか確かめます。
• 権限: 実行するスクリプト（.sh等）に実行権限（chmod +x）が付与されているか確認する。

2. サブエージェントの無限ループ回避

サブエージェントがエラーを修正しようとして、別のエラーを誘発し、それをまた修正しにいくというループに陥ることがあります。

• 解決策: サブエージェントの定義の maxTurns（手数の上限）や、非対話モード（claude -p）の --max-turns で、試行の回数に上限を設ける（Subagents・CLI reference）。

3. ネットワーク環境（プロキシ・ファイアウォール）の対応

企業の社内ネットワークでは、AnthropicのAPIエンドポイントへの通信が遮断されることがあります。
環境変数 HTTPS_PROXY の設定が正しく反映されているか確認してください。

まとめ：自律型開発環境への移行ステップ

Claude Codeのhooksとサブエージェントを使いこなすことは、単に「AIにコードを書かせる」段階から「AIに開発プロセスを運用させる」段階へのシフトを意味します。

1. まずは、プロジェクトの .claude/settings.json に、簡単な PostToolUse フック（npm test等）を書くところから始める。
2. サブエージェントの挙動を観察し、並列処理が可能なタスク（リファクタリングとテスト生成など）を意識的に切り出す。
3. MCP（Model Context Protocol）サーバーを活用し、Slack通知やGitHub Issueとの連携など、フックから外部サービスを叩く仕組みを構築する。

開発環境の自動化は、ビジネスプロセス全体の自動化と本質的に同じです。エンジニアリング以外の領域でも、データの流れをスムーズにし、手作業を排除する取り組みは加速しています。自社の基盤を見直す際は、こうしたAIの自律性をどう組み込むかを常に念頭に置いてください。

Claude Code の hooks やサブエージェントを組織展開するフェーズでは、実行権限のスコープを最小化し、どのコマンドを誰に許可し、実行ログをどう記録・監査するかの設計が情シスとの合意事項になります。自社の体制に合ったエージェント運用ルールの整備や導入設計は Claude Code 導入支援 でご相談いただけます。