AWS Builder Center

AI-DLC Workflow V2のHooks: 見えないところで品質を守る仕組み

コード生成を頼んだのに「まず計画を確認させてください」と返される。承認ゲートを飛ばそうとしたら拒否される。AI-DLC Workflow V2を使っていると、エージェントが自分自身にブレーキをかける場面に出会います。これは17個のフックによる品質保証の仕組みです。シリーズ第20回。

Series: AI-DLC Workflow V2の解説 (37 articles)

  1. …
  2. 20
    AI-DLC Workflow V2のHooks: 見えないところで品質を守る仕組み This article
AWS Japan, Developer Specialist SA

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の解説 (37 articles)

  1. …
  2. 20
    AI-DLC Workflow V2のHooks: 見えないところで品質を守る仕組み This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article