Claude Code の hooks・サブエージェント入門（要公式確認）

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

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

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

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

Claude Codeは、開発者が普段使用しているターミナル上で動作するCLIツールです。従来のAIツールと決定的に異なるのは、「コードを書くだけ」ではなく「コードを実行し、エラーを読み取り、修正して再試行する」というループを自律的に行える点にあります。

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

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

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

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

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

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

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

Claude Codeの挙動をカスタマイズするには、プロジェクトのルートディレクトリに .claudecode.json を作成します（※公式の最新仕様ではファイル名やスキーマが変更される可能性があるため、常に Anthropic公式ドキュメント を参照してください）。

基本的な構成例は以下の通りです。

{
"hooks": {
"pre-fix": "npm run lint",
"post-fix": "npm test",
"on-error": "sh ./scripts/notify-error.sh"
},
"subagents": {
"allowParallel": true,
"maxCount": 3
}
}

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

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

• pre-action: AIがコマンドを実行したりファイルを編集したりする直前に実行。
• post-action: アクション完了直後に実行。結果の検証に最適。
• on-failure: コマンドが失敗したり、テストが通らなかった場合に起動。

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

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

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

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

タスク分割のメカニズム

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

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

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

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

• 実行確認モード: 破壊的なコマンド（rm -rf 等）を実行する前に必ず人間に確認を求める設定（--yesフラグの不使用）。
• 予算上限（Budgeting）: 1セッションあたりの最大トークン消費量を制限する。

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

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

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

※料金・仕様は2025年時点の公式発表に基づきます。最新情報は各社公式ページ（Anthropic / GitHub / Cursor）をご確認ください。

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

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

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

• 解決策: 実行コマンドを ./node_modules/.bin/eslint のように相対パスで書くか、絶対パスを指定する。
• 権限: 実行するスクリプト（.sh等）に実行権限（chmod +x）が付与されているか確認する。

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

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

• 解決策: --max-iterations などのオプションを活用し、1つのタスクにおける試行回数に上限を設ける。

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

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

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

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

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

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