AI-DLC Workflow V2のHooks: 見えないところで品質を守る仕組み
コード生成を頼んだのに「まず計画を確認させてください」と返される。承認ゲートを飛ばそうとしたら拒否される。AI-DLC Workflow V2を使っていると、エージェントが自分自身にブレーキをかける場面に出会います。これは17個のフックによる品質保証の仕組みです。シリーズ第20回。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 20AI-DLC Workflow V2のHooks: 見えないところで品質を守る仕組み This article
1. はじめに
この記事はV2シリーズの第20回です。前回の記事ではAI-DLC Workflow V2（以降V2）の「one core, many harnesses」アーキテクチャの設計思想を扱いました。
今回のゴールは、V2に組み込まれた17個のフックについて「何を守っているか」を概要レベルで理解することです。各フックの実装詳細やカスタマイズ方法には踏み込みません。ユーザーとして「なぜ止められたのか」「裏で何が起きているのか」を把握できる状態を目指します。
2. フックとは何か
フックとは、ワークフロー実行中に特定のタイミングで自動的に発火し、品質やプロセスの整合性を守る仕組みです。ユーザーが明示的に呼び出すものではなく、エンジンがツール呼び出しやセッション境界で自動的に起動します。
ユーザーから見た体験
フックの存在をユーザーが意識するのは、たいてい「何かを拒否された」時です。
- コード生成プランの承認前に開発エージェントを起動しようとしたら拒否された
- レビュー完了後に成果物を編集しようとしたら書き込みがブロックされた
- レビューアエージェントが他のユニットのファイルを読もうとしたら拒否された
- ワークフローが未完了なのにターンが終了しそうになると引き止められた
これらはバグではなく、フックが設計通りに動作した結果です。
V2のフック構成
V2には17個のフックが同梱されています。この記事ではカスタムフックの作成方法やハーネスごとの差異は対象外とし、標準で組み込まれた17個の役割に焦点を当てます。
3. フックの分類
17個のフックをカテゴリ別に見ていきましょう。機能の性質に応じて6つに分類できます。
3.1 セッション管理（3個）
セッションのライフサイクルを記録し、ワークフローの文脈を維持するフックです。
| フック名 | 何を守っているか |
|---|---|
aidlc-session-start | セッション開始・再開時にワークフローの文脈を注入し、再開やコンパクション後も状態が失われないことを保証する |
aidlc-session-end | セッション終了を監査ログに記録し、ワークフローの観測可能性を確保する |
aidlc-record-human-turn | プロンプト送信ごとに人間の存在を記録し、承認ゲートが人間不在のまま通過されないことを保証する |
ここで重要なのは、
aidlc-record-human-turnの役割です。V2の承認ゲートは「人間がそこにいること」を前提として設計されています。このフックが各プロンプトでHUMAN_TURNイベントを記録することで、ゲート承認時に「直近の人間の操作があったか」を検証できます。3.2 ワークフロー継続制御（2個）
ワークフローが途中で止まったり、状態が同期から外れたりしないよう制御するフックです。
| フック名 | 何を守っているか |
|---|---|
aidlc-continue-workflow | ワークフローが未完了のままターンが終了することを防ぎ、転送ループを強制する |
aidlc-sync-workflow-state | ステージ遷移を検出して状態ファイルの現在ステージを同期し、状態の乖離を防ぐ |
aidlc-continue-workflowはStop hookと呼ばれる種類のフックで、エージェントのターン終了時に発火します。ワークフローが進行中なのに作業が止まりそうな場合、このフックが「まだ終わっていません」と引き止めます。3.3 品質ガード（4個）
ワークフローの正しい順序やスコープを強制するフックです。ユーザーが「拒否された」と感じる場面の多くは、このカテゴリに属します。
| フック名 | 何を守っているか |
|---|---|
aidlc-state-transition-guard | ステートマシンへの直接呼び出しを拒否し、オーケストレータ経由の正規パスを強制する |
aidlc-plan-approval-guard | コード生成計画の承認前に開発エージェントが起動されることを拒否し、計画→承認→生成の順序を保証する |
aidlc-review-freeze | レビュー完了後に成果物ファイルへの書き込みを拒否し、レビュー結果の無効化を防ぐ |
aidlc-reviewer-scope | レビューアエージェントが担当外ユニットのファイルを読むことを拒否し、レビュースコープの独立性を保証する |
言い換えれば、このカテゴリはV2の「プロセスの正しさ」を物理的に強制する仕組みです。ドキュメントに「この順序で進めてください」と書くだけでなく、違反した瞬間にツール呼び出しを拒否することで、ルールの形骸化を防いでいます。
3.4 監査・記録（3個）
ワークフロー中のイベントを監査ログに記録するフックです。品質を「守る」というより「記録する」ことで、トレーサビリティを確保します。
| フック名 | 何を守っているか |
|---|---|
aidlc-write-audit-log | 成果物ファイルの作成・更新を自動記録し、いつ何が書かれたかの追跡を保証する |
aidlc-log-subagent | サブエージェントの完了を記録し、誰が何をしたかの帰属追跡を保証する |
aidlc-fold-usage | ツール呼び出しごとのトークン使用量を永続的な台帳に集約し、コスト観測を可能にする（Claude Code専用） |
3.5 構造維持（3個）
ワークフローの内部構造（ステージグラフ、ルール配信、状態の整合性）を維持するフックです。
| フック名 | 何を守っているか |
|---|---|
aidlc-rebuild-stage-graph | ステージ遷移後にランタイムグラフを再コンパイルし、グラフと実行状態の整合性を保証する |
aidlc-validate-state | コンテキストのコンパクション前に状態構造を検証し、圧縮後に壊れた状態で再開されることを防ぐ |
aidlc-deliver-stage-rules | コンダクタからサブエージェントへの境界でステージルールを決定論的に配信し、ルールの欠落を防ぐ |
つまり、このカテゴリはV2のエンジン自身の「健全性」を守っています。ステージが変わればグラフを更新し、コンパクションが起きれば状態を検証し、エージェントが交代すればルールを渡す。ユーザーには見えませんが、ワークフローの安定稼働を支える基盤です。
3.6 検証・表示（2個）
成果物の品質検証と進捗表示を担うフックです。
| フック名 | 何を守っているか |
|---|---|
aidlc-run-sensors | ファイル書き込み時にステージセンサーを自動発火し、成果物が検証基準を満たしているか即時チェックする |
aidlc-statusline | ターミナルのステータスエリアにワークフローの進捗を表示し、現在位置の可視化を提供する |
aidlc-run-sensorsは前回のセンサー記事で扱った仕組みの「発射台」にあたります。センサーマニフェストのmatchesパターンにファイルパスが一致した時、このフックがセンサーを起動します。4. ユーザーが遭遇する代表的な場面
概念を理解したところで、実際のワークフローでフックに遭遇する場面を見ていきましょう。
場面1: コード生成計画をスキップしようとした
Code Generationステージでは、Step 2で計画を作成し、Step 3で人間が承認し、Step 4で開発エージェントがコードを生成するという順序が定められています。
もし何らかの理由でStep 2-3をスキップして開発エージェントを直接起動しようとすると、
aidlc-plan-approval-guardが発火してツール呼び出しを拒否します。画面には「プランが未承認です」という旨のメッセージが表示されます。これは安全装置です。計画なしにコードを生成すると、手戻りのコストが大きくなります。フックがこの順序を物理的に保証しているため、「うっかり飛ばす」ことがありません。
場面2: レビュー完了後に成果物を編集しようとした
レビューアエージェントが成果物を検証し、READY（承認可能）の判定を出した後に、その成果物ファイルを再度編集しようとすると
aidlc-review-freezeが書き込みを拒否します。これは「レビュー結果の無効化」を防ぐための仕組みです。レビュー後に内容が変わったら、そのレビュー結果はもう有効ではありません。再編集が必要な場合は、改めてレビューを通す必要があります。
場面3: レビューアが隣のユニットを覗こうとした
Per-unitレビュー（ユニット単位のレビュー）では、レビューアエージェントは担当ユニットの
construction/<unit>/配下のファイルだけを読むことができます。他のユニットのファイルにアクセスしようとすると、aidlc-reviewer-scopeがファイル読み取りを拒否します。これにより、レビューアは自分の担当範囲だけを見て判定するため、レビューの独立性が保たれます。隣のユニットのコードに引きずられて判断が歪むことを構造的に防いでいます。
場面4: ワークフローの途中でターンが終了しそうになった
ワークフローが進行中（ステージが未完了）なのにエージェントのターンが終わりそうになると、
aidlc-continue-workflowが「まだ完了していません」とブロックします。これが転送ループ（forwarding loop）の強制です。ユーザーが意図的にワークフローを中断したい場合は
/aidlc --parkで明示的に中断を宣言できますが、暗黙的に放棄されることはこのフックが防いでいます。5. フックのアーキテクチャ概観
ここで、フックがいつ発火するかの大枠を整理しましょう。深入りはしませんが、「なぜ特定の操作が止められるのか」を理解する手がかりになります。
発火タイミング
フックの発火タイミングは大きく3つに分類できます。
| 発火タイミング | 意味 | 典型的な用途 |
|---|---|---|
| PreToolUse | ツール実行の直前に割り込む | 操作を「拒否」できる（書き込みブロック、読み取り制限） |
| PostToolUse | ツール実行の直後に反応する | 実行結果を「記録」する（監査ログ、グラフ更新） |
| セッション境界 | セッションの開始・終了・コンパクション・プロンプト送信・ターン終了時 | 状態の注入・検証・継続制御 |
ここで重要なのは、PreToolUseのフックだけが「拒否」の能力を持っている点です。品質ガードカテゴリの4つのフックがいずれもPreToolUseで動作するのはこのためです。ツールが実行される前に割り込むことで、不正な操作を未然に防ぎます。
PostToolUseのフックは操作を拒否しません。ツールが実行された後に「何が起きたか」を記録し、必要に応じてエンジンの内部状態を更新します。
セッション境界のフックは、ワークフロー全体のライフサイクルに関わります。セッション開始時に文脈を注入し、コンパクション前に状態を検証し、ターン終了時に継続を強制します。
17個のフック一覧（発火タイミング別）
| フック名 | カテゴリ | 発火タイミング | 何を守るか |
|---|---|---|---|
aidlc-state-transition-guard | 品質ガード | PreToolUse | ステートマシンへの直接呼び出しを拒否 |
aidlc-plan-approval-guard | 品質ガード | PreToolUse | 未承認プランでの開発エージェント起動を拒否 |
aidlc-review-freeze | 品質ガード | PreToolUse | レビュー完了後の成果物書き込みを拒否 |
aidlc-reviewer-scope | 品質ガード | PreToolUse | レビューアの担当外ファイル読み取りを拒否 |
aidlc-deliver-stage-rules | 構造維持 | PreToolUse | サブエージェントへのルール配信（入力を書き換える） |
aidlc-fold-usage | 監査・記録 | PreToolUse + PostToolUse | トークン使用量を台帳に集約 |
aidlc-write-audit-log | 監査・記録 | PostToolUse | 成果物の作成・更新を監査ログに記録 |
aidlc-rebuild-stage-graph | 構造維持 | PostToolUse | 遷移後にランタイムグラフを再コンパイル |
aidlc-run-sensors | 検証・表示 | PostToolUse | ファイル書き込み時にセンサーを発火 |
aidlc-sync-workflow-state | ワークフロー継続制御 | PostToolUse | 状態ファイルの同期 |
aidlc-log-subagent | 監査・記録 | SubagentStop | サブエージェント完了を記録 |
aidlc-session-start | セッション管理 | SessionStart | ワークフロー文脈の注入 |
aidlc-session-end | セッション管理 | SessionEnd | セッション終了の記録 |
aidlc-validate-state | 構造維持 | PreCompact | コンパクション前の状態検証 |
aidlc-record-human-turn | セッション管理 | UserPromptSubmit + PostToolUse | 人間の存在記録 |
aidlc-continue-workflow | ワークフロー継続制御 | Stop | ターン終了の阻止 |
aidlc-statusline | 検証・表示 | StatusLine（独立メカニズム） | ステータスエリアに進捗を表示 |
設計の意図
この分類から読み取れるのは、大枠としてV2のフックが「防御」「記録」「維持」の3つの役割で構成されているということです。
- 防御: 不正な操作を事前に拒否する（主にPreToolUse）
- 記録: 何が起きたかを忠実に記録する（主にPostToolUse）
- 維持: ワークフロー全体の一貫性を維持する（セッション境界 + 一部PreToolUse）
実際には
aidlc-deliver-stage-rulesのようにPreToolUseで構造維持を担うフックや、aidlc-fold-usageのように両タイミングで動作するフックもあり、役割と発火タイミングは完全に一対一ではありません。しかしこの3つの役割が協調することで、ユーザーが意識しなくてもワークフローの品質が保たれます。6. まとめ
ここまで、V2に組み込まれた17個のフックの全体像を見てきました。
フックは6つのカテゴリに分かれ、それぞれが異なるタイミングで発火します。品質ガードは操作の前に割り込んで拒否し、監査フックは操作の後に記録し、セッション管理フックはワークフローの文脈を維持します。一部のフックは複数のタイミングで動作しますが、大枠としてこの「防御・記録・維持」の3つの役割が協調しています。
ユーザーとして覚えておくべきことはシンプルです。ワークフロー中に何かを「止められた」時、それはフックが設計通りに機能している証拠です。計画なしにコードを生成しない、レビュー後に成果物を上書きしない、レビューアが担当外を見ない。これらのルールが「お願い」ではなく「強制」として実装されているのがV2のフックシステムです。
17個のフックが協調して動くことで、ユーザーは「正しいプロセスを守ること」に認知コストを使わなくて済みます。ルールを覚えて自分で注意する代わりに、エンジンが自動で守ってくれる。これがV2のフックが実現している品質保証の形です。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 20AI-DLC Workflow V2のHooks: 見えないところで品質を守る仕組み This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article