AI-DLC Workflow V2のAudit Trail: 記録して、振り返る
「で、結局あのステージでなんて答えたんだっけ？」。エージェントとの長いセッションが終わると、判断の記憶は驚くほど早く薄れます。V2の監査ログは82イベントを自動記録し、「記録して終わり」にしない仕組みを持っています。見ていきましょう。シリーズ第21回。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 21AI-DLC Workflow V2のAudit Trail: 記録して、振り返る This article
1. はじめに
この記事はAI-DLC Workflow V2（以降V2）シリーズの第21回です。第20回 ではHooksの仕組みを扱いました。
今回のゴールは、V2の監査ログ（Audit Trail）の存在意義、構造の概要、そして活用方法を理解することです。ワークフローの中で何が起きたかを記録し、後から参照できる仕組みがどのように設計されているか、見ていきます。
2. なぜ監査ログが必要か
では、そもそもなぜ監査ログが必要なのか。ユースケースから考えてみましょう。
後から振り返りたい。 ワークフローが完了した後に「あの判断、いつ・どの根拠でしたんだっけ？」と振り返りたい場面は頻繁にあります。特にステージ数が多いワークフローでは、個々の判断を記憶だけに頼るのは難しいです。
チームメンバーに共有したい。 同期的にセッションに参加していなかったメンバーが、後から経緯を追えることは重要です。非同期レビューや不在メンバーへの引き継ぎには、構造化された記録が必要になります。
判断の経緯を追跡したい。 要件から設計、実装へと至る判断の連鎖を、後から追跡できること。これはトレーサビリティと呼ばれる性質で、規制環境やチーム開発では特に価値があります。
ここで重要なのは、AIエージェントとの開発では判断の経緯がセッション境界で消えやすいという点です。人間同士の会議ならば議事録を書きますが、エージェントとのやり取りはセッションが終われば文脈が失われます。V2の監査ログは、この問題に対する構造的な解決策です。
3. 監査ログの置き場所と形式
では、監査ログが実際にどこに、どのような形で保存されるかを見ていきましょう。
保存場所
監査ログはインテント（ワークフローの1回の実行単位）ごとに、以下のディレクトリに保存されます。
1
aidlc/spaces/<space>/intents/<YYMMDD>-<label>/audit/ファイル形式
audit/ディレクトリの中にはクローン別のシャードファイル（分割ファイル）が置かれます。ファイル名は<host>-<clone>.mdの形式です（例: 5ce91e7703f5-990d3cfa446f.md）。前半がホスト識別子、後半がgit cloneした各リポジトリコピーごとに自動生成されるクローン識別子です。各クローンは自分のシャードにのみ書き込みます。この設計により、複数人で同時に作業してもgitのマージコンフリクトが起きません。
たとえばConstructionフェーズでサブチームに分かれ、AさんとBさんがそれぞれ別のユニットを並列に実装しているとします。Aさんの作業は
a1b2c3d4e5f6-aaa111bbb222.mdに、Bさんの作業はx9y8z7w6v5u4-ccc333ddd444.mdに記録されます。書き込み先のファイルが物理的に異なるため、同時にpushしても互いの記録が衝突することはありません。途中でドライバー（作業担当者）が交代する場合も同様です。AさんがIdeationを進め、ConstructionからBさんに引き継ぐケースでは、Bさんのクローンで作業を再開した時点から新しいシャードに記録が追記されます。全体の時系列はタイムスタンプで再構成できるため、誰がいつ担当したかもログから追えます。
追記専用
監査ログは追記専用（append-only）です。既存エントリの変更や削除は禁止されています。これにより、記録の完全性が保証されます。
イベントのフォーマット
各エントリは以下のフィールドを含む構造化された形式で記録されます。
- Timestamp — ISO 8601形式のタイムスタンプ
- Event — 82種類のイベントタイプの1つ
- Stage — 関連するステージ名（イベントによっては省略）
- Details — イベント固有のデータ（判断内容、成果物のパスなど）
時系列の再構成
ワークフロー全体の時系列を見たい場合は、
audit/*.mdをglobで集め、タイムスタンプでマージソートすることで再構成できます。4. 82イベント・21カテゴリの全体像
次に、監査ログに記録されるイベントの全体像を見ていきましょう。
概要
V2の監査ログは82種類のイベントを21のカテゴリに分類しています。命名規則は
SUBJECT_PAST_VERBで、「何が起きたか」に答える形になっています。例えばWORKFLOW_STARTEDは「ワークフローが開始された」、GATE_APPROVEDは「ゲートが承認された」という意味です。代表的な4カテゴリ
特に中心的な4つのカテゴリを紹介します。
Workflow Lifecycle（4イベント）
ワークフロー全体の開始・完了・中断・再開を記録します。
| イベント | 記録されるタイミング |
|---|---|
WORKFLOW_STARTED | ワークフロー開始時 |
WORKFLOW_COMPLETED | 全ステージ完了時 |
WORKFLOW_PARKED | ワークフローを中断して後日再開に回した時 |
WORKFLOW_UNPARKED | 中断したワークフローを明示的に再開した時 |
Stage Lifecycle（6イベント）
各ステージの状態遷移を記録します。
| イベント | 記録されるタイミング |
|---|---|
STAGE_STARTED | ステージの作業が開始された時 |
STAGE_COMPLETED | ステージが承認されて完了した時 |
STAGE_AWAITING_APPROVAL | 承認ゲートが開いた時 |
STAGE_REVISING | ユーザーがゲートで差し戻しを要求した時 |
STAGE_SKIPPED | ステージがスキップされた時 |
STAGE_JUMPED | ジャンプ操作でステージに到達した時 |
Interaction（7イベント）
人間とエージェントのやり取りを記録します。
| イベント | 記録されるタイミング |
|---|---|
DECISION_RECORDED | 構造化された質問を提示した時 |
GATE_APPROVED | 承認ゲートで人間が承認した時 |
GATE_REJECTED | 承認ゲートで人間が差し戻した時 |
QUESTION_ANSWERED | 非ゲートの質問に人間が回答した時 |
SUMMARY_CONFIRMATION_RECORDED | 統合サマリーの確認を記録した時 |
REVIEW_REQUESTED | レビューアーエージェントを呼び出した時 |
REVIEW_COMPLETED | レビューアーの判定が返った時 |
Artifact（3イベント）
成果物のライフサイクルを記録します。
| イベント | 記録されるタイミング |
|---|---|
ARTIFACT_CREATED | 新しい成果物が作成された時 |
ARTIFACT_UPDATED | 既存の成果物が更新された時 |
ARTIFACT_REUSED | バックワードジャンプで成果物の再利用を決定した時 |
全21カテゴリ一覧
82イベントの全カテゴリを一覧で示します。上で紹介した4カテゴリを含め、全体像はこのとおりです。
| カテゴリ | イベント数 | 何を記録するか |
|---|---|---|
| Workflow Lifecycle | 4 | ワークフローの開始・完了・中断・再開 |
| Phase Lifecycle | 4 | フェーズの開始・完了・検証・スキップ |
| Stage Lifecycle | 6 | ステージの状態遷移 |
| Session | 5 | セッションの開始・再開・コンパクション・終了・人間の存在確認 |
| Initialization | 3 | ワークスペースの初期化処理 |
| Navigation | 7 | スコープ・深度・テスト戦略・レビュークラスの変更、スコープ検出、リコンポーズ |
| Interaction | 7 | 人間とエージェントのやり取り（質問・承認・レビュー） |
| Unit Lifecycle | 4 | ユニット（作業単位）の開始・一時停止・再開・完了 |
| Artifact | 3 | 成果物の作成・更新・再利用 |
| Subagent | 1 | サブエージェントの完了 |
| Reviewer Enforcement | 2 | レビューアーの読み取り範囲違反のブロック |
| Plan Approval | 1 | コード生成プランの未承認状態でのブロック |
| Utility | 1 | ヘルスチェック（--doctor） |
| Error/Recovery | 2 | エラー記録とリカバリ |
| Construction Bolt | 4 | Bolt（実装バッチ）の開始・完了・失敗・自律モード設定 |
| Worktree | 7 | Bolt用ワークツリーの作成・マージ・破棄と状態フォーク |
| Practices | 4 | チームプラクティスの発見・承認・オーバーライド |
| Merge Dispatch | 3 | マージ戦略の判定依頼・応答・フォールバック |
| Sensors | 5 | 品質センサーの発火・合格・不合格 |
| Learning Loop | 3 | 学習ループ（ルール学習・センサー提案） |
| Swarm | 6 | 並列実行（Swarm）のバッチ管理 |
各イベントのフィールド定義や発火条件を詳しく知りたい場合は、記事末尾のReferencesからたどれます。
5. 監査ログの活用方法
記録されたログをどう使うか、見ていきましょう。V2には監査ログを活用する2つのスキルが用意されています。
replay
/aidlc-replayで呼び出せるスキルです。ワークフローの監査ログと成果物から、読みやすい物語（ナラティブ）を生成します。何が決まり、どの順序で、なぜそうなったかを、ターミナルに表示します。用途は非同期レビューや、セッションに参加していなかったメンバーへの共有です。ここで重要なのは、replayは読み取り専用であるということです。ファイルへの書き込みは一切行わず、ワークフローの状態も変更しません。
outcomes-pack
/aidlc-outcomes-packで呼び出せるスキルです。ワークフロー完了後に、チームへの引き継ぎ文書（OUTCOMES.md）を生成します。何が作られ、どう動かし、どう続けるかをまとめたドキュメントです。こちらもワークフローの状態（ステージポインタや承認状態）は一切変更しません。出力として
OUTCOMES.mdをワークスペースルートに書き込みますが、ワークフローの進行には影響を与えない設計です。つまり、監査ログは記録して終わりではなく、replayやoutcomes-packを通じてチームの共有資産として活用できます。
6. まとめ
この記事ではV2の監査ログの全体像を見てきました。
- 監査ログはワークフローの透明性と追跡可能性を支える記録層です。追記専用・クローン別シャードという設計で、並列作業でもコンフリクトなく記録が蓄積されます
- 82イベント・21カテゴリの体系的な分類により、ワークフローのあらゆる側面が構造化された形で残ります
- 記録して終わりではなく、replayで物語として読み返し、outcomes-packでチームに引き継ぐことができます
全82イベントの詳細な定義と遷移条件については、以下のReferencesを参照してください。
References
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 21AI-DLC Workflow V2のAudit Trail: 記録して、振り返る 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