サブエージェント・フック・スラッシュコマンド：AIコーディングツールでよく使われる拡張概念

約14分developer-tools
#サブエージェント#フック#スラッシュコマンド#AIコーディングツール#用語集
※ 編集方針：以下の業務状況および人物は、用語の理解を助けるための架空のシナリオです。実際の著者の経験や特定の企業で起きた出来事を再現したものではありません。
社내ログイン画面のセッション切れバグを、AIコーディングツールを使って追跡する架空の夜間作業を考えてみましょう。
その日1日、AIコーディングツールを使いながら、見慣れない言葉に何度も遭遇しました。最初に目にとまったのは「サブエージェント」でした。

AIコーディングツールに「サブエージェントを実行中」と表示される理由

セッションバグの原因になりそうなファイルは1つや2つではありませんでした。「このプロジェクト全体からセッション関連のロジックをすべて探し出して、原因を特定して」と指示したところ、画面にこのような行が表示されました。
bash
1$ claude "세션 끊김 버그 원인 찾아줘"
2Launching subagent: code-reviewer (Explore)...
3Launching subagent: file-search (Explore)...
自分が制御できない何かが勝手に動いているのではないかと思い、一瞬躊躇しました。
調べてみると、心配する必要はありませんでした。新しいAIが独立して現れたわけではなく、現在会話しているそのエージェント自身が「この部分はユーザーが直接確認せず、専属のアシスタントに任せます」と宣言しているに過ぎないのです。会社に例えるなら、上司がすべてを自分で処理するのではなく、「この部分はレビューチームに回します」と言うようなものです。
メインエージェントが2つのサブエージェントにタスクを分割して委任する構造を描いたツリー図
メインエージェントが下位タスクをサブエージェントに委任し、結果だけを受け取る構造
実際、この恩恵を受けました。サブエージェントを使わずにメインの会話だけで何百ものファイルをすべて開いていたら、無関係な内容まで会話のメモリに蓄積され、本当に重要な文脈が後回しになっていたでしょう。
代わりに「コードレビューチーム」と「ファイル探索チーム」を別々に稼働させ、それぞれ結果だけを持ち帰るようにしました。メインの会話を散らかすことなく、3つのファイルに散らばっていた原因を特定することができました。
原因を特定してコードを修正し、コミットしようとした瞬間、今度はAIではなくシステム自体が作業を妨げました。

コミットしようとした時にAIツールが突然ブロックしてきた時の、pre-commitフックの正体

text
1[SECRET DETECTED] .env.local: AWS_SECRET_ACCESS_KEY 패턴 감지
2.husky/pre-commit 실행됨, 커밋이 차단되었습니다.
シナリオ内の担当者は、シークレットキーをコミットするように指示した覚えはありませんでした。そのため、AIが誤動作して、存在しないものを存在すると言い張っているのだと思いました。
画面をもう一度見ると、答えはすでにログに出力されていました。.husky/pre-commitという名前でした。デバッグ中に一時的に .env.local に実際のAWSキーを入れていたことを忘れていたのですが、 これを検出したのはAIではなく、チームの管理者が以前に「コミットする直前には必ずこのチェックを実行せよ」と設定しておいたフックでした。AIはそのルールに従っただけです。
暗い部屋、ノートPCの画面に「COMMAND BLOCKED」の警告が表示され、キーボードの上で手が止まった瞬間を描いたイラスト
コミットの試行からフックの実行、ブロックまでの手順を時系列で並べたタイムライン図
「コミット直前」というタイミングであらかじめ設定されたフックが自動的に実行されます
玄関のドアに「出かける前にガスの元栓を確認」という貼り紙をしておけば、ドアを開けるたびに自動的に目に入るのと同じです。特定の行動の直前に自動的に実行されるよう、あらかじめ仕組まれた装置です。
このフックがなければ、そのキーはそのままリモートリポジトリにアップロードされていたでしょう。後から気づいたとしても、すでに履歴に残ってしまい、キーを丸ごと破棄して再発行する羽目になっていたはずです。人間が毎回記憶する代わりに判断自体を自動化しておいたおかげで、1つのミスが大事故に発展するのを防げました。
シークレットキーを再発行したときには、すでに午前0時を過ぎていました。コミットメッセージまで書かなければならないと思うと、すっかり疲れ果ててしまいました。

毎回コミットコンベンションを説明するのに疲れたなら、スラッシュコマンドが代わりに覚えてくれます

隣にいた同僚が「ただ /commit とだけ入力すればいいよ」と教えてくれました。
bash
1> /commit
2→ diff 분석 중...
3→ fix(auth): 세션 만료 시 자동 로그아웃 처리
4→ Committed: a1b2c3d
最初は、よく使うコマンドを省略して呼び出すショートカットキーのようなものだと思っていました。
毎回ルールを説明する方式と、コマンド1つにルールを保存しておく方式を並べて比較した図
毎回繰り返し説明する代わりに、チームのルールをコマンド1つにあらかじめ保存しておく構造
後で分かったことですが、さらに重要な役割がありました。このチームには、コミットメッセージに定められたルール（タイプ、スコープ、韓国語での説明）がありました。そのルールを毎回プロンプトで長く説明する必要がなくなったのです。チームのルールが /commit コマンド1つにあらかじめ組み込まれていたからです。
食堂で「いつもの」と注文すれば、メニューを見なくてもお互いに何を頼んでいるか正確に伝わるのと同じです。担当者個人が使うショートカットキーではなく、チーム全体が同じルールで作業できるようにするための仕組みだったという点が重要です。
チームに合流したばかりで、コンベンションのドキュメントをまだ読み切れていない状態でした。しかし、/commit と入力しただけで、チームのルールに沿ったコミットメッセージがそのまま生成されました。オンボーディングドキュメントを精読する代わりに、コマンド1つがそのドキュメントの役割を果たしてくれたわけです。
その日1日、サブエージェントもフックもスラッシュコマンドも、すべて「自分が知らないうちに何かが勝手に動いている」という感覚を与えました。
しかし、3つとも深く探ってみれば、その本質は同じでした。AIが勝手に振る舞っているのではなく、開発者自身であれチームであれ、誰かがあらかじめ決めておいたルールと役割の中で動いていたに過ぎないのです。
日付の変わった時計と閉じられたノートPC、湯気の立つマグカップが置かれた静かな部屋を描いたイラスト

よくある質問

サブエージェントを複数呼び出すと、余計に時間がかかりますか？

直感とは異なり、むしろ速くなるケースが多いです。複数のアシスタントが同時にそれぞれの担当ファイルを探るため、1つのAIが順番にすべて開いて確認するよりも全体の作業時間を短縮できます。ただし、アシスタントの数が多すぎると結果の集約に時間がかかるようになるため、やみくもに多く呼び出せばよいというわけではありません。

フックはユーザーがオフにできますか？

はい、ほとんどのツールでは設定ファイルでフックのオン・オフを切り替えることができます。ただし、今回のようにシークレットキーの流出を防ぐフックなど、安全性に直結するものはチームレベルで強制されていることが多く、個人が勝手にオフにすると、事故を防ぐ最後の砦を自ら取り払うことになりかねません。

スラッシュコマンドは誰でも作成できますか？

はい、プロジェクトごとに独自のコマンドを定義できます。チームで繰り返される手順（コミットルール、コードレビューのチェックリスト、デプロイ前の確認事項など）がある場合は、スラッシュコマンドを作成しておくことをお勧めします。新しく合流した人にドキュメントを読ませる代わりに、コマンド1つでその手順を実行させることができます。

AIコーディングツール用語集シリーズの第1弾です。次回は、AIが「権限を要求します」と表示したときに実際に起きていることについて取り上げます。権限プロンプト、サンドボックス、チェックポイント、ワークツリー隔離、コンテキスト枯渇について順に解説します。

参考・根拠

Anthropic Claude Code CLI reference

関連記事

パーミッションプロンプト・Sandbox・Checkpoint：AIエージェントの実行境界を理解する

AIコーディングツールを使う中で直面するパーミッションプロンプト、サンドボックス、チェックポイントなど5つの用語を、仮想の業務シナリオを通じてわかりやすく解説します。

Kill Switch・Backoff・Runtime：実行を停止し復旧するための基本機能

AIコーディングツールを使っていると遭遇する、キルスイッチ、バックオフ、リポジトリなどの5つの用語を、仮想の業務シナリオを通じてわかりやすく解説します。

Drift・環境変数・PATH：マシンごとに開発環境が異なる理由

AIコーディングツールを使用する中で直面する、ドリフト、ウォーターマーク、環境変数などの5つの用語を、仮想的な業務シナリオを通して解説します。