AI-DLC Workflow V2の異常時の対処: ログ・調査・回避・Issue報告の進め方
ワークフローが進まない、コマンドがエラーになる、なんだか挙動がおかしい。AI-DLC Workflow V2（以降V2）を使っていると、こうした場面に出会うことがあります。慌てて試行錯誤する前に、ログの取り方、調査の仕方、環境変数での一時回避、Issueの書き方を順番に押さえておきましょう。自分で切り分けて、必要なら開発側が解析・再現できる形で報告するところまでの流れを見ていきましょう。シリーズ第31回。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 31AI-DLC Workflow V2の異常時の対処: ログ・調査・回避・Issue報告の進め方 This article
1. はじめに
この記事は、シリーズの第31回です。異常が起きたときの対処がテーマです。
今回のゴールは、V2で異常に遭遇したときに、次の4つへ自力で着手できるようになることです。
- ログを取る
- 原因を調査して切り分ける
- 環境変数で一時的に回避する
- 不具合をIssueとして報告する
この記事では、異常を次の3種類に分けて考えます。
| 種類 | 例 |
|---|---|
| 進行不良 | 承認ゲートが開かない、ステージが先に進まない |
| コマンド・ツールのエラー | コマンドが失敗する、フックが動かない |
| 期待と違う挙動 | 承認したはずの内容をもう一度聞かれる、チェックが想定外に働く |
内容は、公式ガイドの 15-troubleshooting.md 、10-state-and-audit.md 、12-cli-commands.md を参照しています。個別のエラーメッセージを網羅するものではなく、代表的な見方と手順に絞っています。細かい症状は公式ガイドのトラブルシューティングの章で引いてください。
なお、この記事に出てくるコマンドには2種類あります。
/aidlc で始まるもの（例: /aidlc --doctor、/aidlc --status）は、AI-DLCとの会話（チャット）の中で入力するスラッシュコマンドです。aidlc で始まるもの（例: aidlc engine audit history）は、ターミナルで実行するコマンドです。全体の流れは次の図のとおりです。
2. ログの取り方
では、まず異常時に見るべき情報の在りかから見ていきましょう。V2は、誰が何をしたかを記録として残しています。どこを見るかが分かれば、調査の出発点がそろいます。
2.1 見る場所は3つあります
| 見る場所 | 何が分かるか | コマンド・ファイル | どこで使うか |
|---|---|---|---|
| 監査ログ | いつ何が起きたかの時系列 | aidlc engine audit history | ターミナルで実行 |
| 状態ファイル | 今どのステージにいるか | aidlc-state.md | エディタ等で開いて見る |
| ステータス表示 | 進捗と、誰の待ちかの要約 | /aidlc --status | チャット内で入力 |
監査ログ（audit trail）は、承認や質問への回答、ステージの開始と完了などの出来事を残した記録です。
aidlc engine audit history で、時系列のJSONとして読めます。--stage \<slug\> を付けると、特定のステージだけに絞れます。古い順に並び、順序が確定できない行には unordered: true が付きます。このコマンドはファイルを変更せず、ロックも取りません。状態ファイル
aidlc-state.md には、各ステージの状態がチェックボックスで入っています。[ ] は未着手、[-] は実行中、[?] は承認待ち、[R] は修正中、[x] は完了、[S] はスキップです。[?] のまま止まっているなら承認待ち、という具合に、止まっている理由の見当がつきます。/aidlc --status は、状態ファイルを読んで要約を表示します。承認待ちの場合は、いつから待っているかも出ます。何も変更しない読み取り専用のコマンドなので、迷ったら最初に実行して構いません。2.2 診断情報を取得・保存する
状況を保存して共有したいときは、
/aidlc --doctor と /aidlc --doctor --export を使います。どちらもチャット内で入力するスラッシュコマンドです。1
2
/aidlc --doctor
/aidlc --doctor --export/aidlc --doctor は、フックの配線、状態ファイルとログの整合性、ステージの定義などをまとめて点検する健全性チェックです。ワークフローに問題があるときは、「Workflow diagnosis」という節で、進まない原因の候補も出してくれます。/aidlc --doctor --export は、点検をやり直したうえで、共有用の診断レポートを書き出します。出力先はプロジェクトの aidlc/diagnostics/ が既定で、--output \<dir\> で変えられます。システムに tar があれば、日時付きの .tar.gz にまとめられます。このレポートは、作業成果物を含みません。ワークスペースのソース、状態やログの生ファイル、成果物の本文などは入らず、ホームディレクトリやプロジェクトのパスは置き換えられ、秘密らしき値は伏せられます。そのため、第三者に見せる前提で作られています。ただし、渡す前に中身を一度確認しておくと、意図しない情報の混入を防げます。
3. 調査の仕方
続いて、集めた情報から原因を絞り込む手順を見ていきましょう。
3.1 基本の切り分け順序
情報の性質に沿って、次の順序で進めます。
/aidlc --doctorで、設定、フック、環境の健全性を確認する- 指摘があれば、その内容に沿って直す
- 指摘がなければ、
/aidlc --statusとaidlc-state.mdで現在位置を確認する aidlc engine audit historyで、止まる直前に何が起きたかをたどる
doctorは、読み取り中心の点検です。まず環境側の問題を除外してから、ワークフロー固有の問題に進むことで、調査の範囲を狭められます。
調査の途中で、AIが「このようにすれば直ります」と対処を提案してくることがあります。ただ、そのとおりにしても直らないことがよくあります。V2のワークフローはエンジンが決まった手順で進めており、AIを説得しても通らない場面があるためです。AIの提案を試す前に、まず公式ガイドの既知の情報（Quick Fix Tableなど）や、ここまでのログ・状態の確認結果と照らし合わせてください。
3.2 Quick Fix Tableの引き方
公式ガイドのトラブルシューティングの章には、先頭に「Quick Fix Table」があります。症状の列と、対処の列が対になった表です。引き方は次のとおりです。
- 自分の症状に近い行を探す（例: 「No audit entries appearing」「Stuck at approval gate」「Context compacted mid-session」）
- その行の対処を試す。リンクが付いている行は、章内の詳しい説明に進む
- 見つからなければ、
/aidlc --doctor --exportの診断レポートを共有する、という行が最後の手段として載っている
たとえば、承認ゲートで止まっているときは、返答を入力するか、
/aidlc --stage \<target\> で別のステージへ移る、と書かれています。長い会話が要約されて記憶の一部が失われるコンパクションの後は、/aidlc を実行すれば、保存済みの位置から再開できます。簡単な復旧方法として、新しいチャットのセッションを開始し、そこで
/aidlc --resume を実行する方法もあります。新しいセッションは保存済みの状態と成果物を読み込み、止まっていた位置から続けます（/aidlc --resume の代わりに、/aidlc だけでも同じように再開します）。会話が長くなって挙動が重いときや、セッションがおかしくなったときに試せます。3.3 3種の異常ごとの確認観点
| 異常の種類 | まず見る場所 | 確認する観点 |
|---|---|---|
| 進行不良（フックは動くが先へ進まない） | /aidlc --doctor の「Workflow diagnosis」、/aidlc --status、aidlc-state.md | フックは動いているのにエンジンが次へ進むのを拒んでいないか。未解決の承認ゲート、ランタイムグラフの古さや欠落、承認の報告が繰り返し拒否されていないか |
| 進行不良（止まっている） | /aidlc --status、aidlc-state.md | [?] や [R] で止まっていないか。承認の返答が記録されているか。/aidlc --doctor の「Workflow diagnosis」に未解決のゲートが出ていないか |
| コマンド・ツールのエラー | /aidlc --doctor | フックが動いているか。ランタイムが見つかるか。エラーが記録されていれば、監査ログの ERROR_LOGGED を確認する |
| 期待と違う挙動 | /aidlc --status、aidlc engine audit history | 設定（Guard Policyなど）が意図した値か。承認後にファイルが変わっていないか |
進行不良では、未解決の承認ゲートが、公式ガイドで「進まない」原因の代表例として挙げられています（
--doctor --export のレポートでも、最初に挙がる原因です）。承認の返答を入力したのに進まないときは、フックが動いていないために返答が記録されていない可能性があります。この場合、/aidlc --doctor がその理由を示します。一方で、フックは動いているのにエンジンが次へ進むのを拒むこともあります。V2のエンジンは決まった条件がそろうまで次へ進めないため、条件を満たしていないと、承認を報告しても進みません。
/aidlc --doctor の「Workflow diagnosis」は、未解決のゲート、古い・欠けたランタイムグラフ、承認の報告が繰り返し拒否される状態など、「先へ進まない」原因を一覧で示します。まずここを確認してください。期待と違う挙動の例として、承認済みの計画をもう一度聞かれるケースがあります。公式ガイドによると、承認は計画の内容、対象、ステージの試行に結びついています。計画の内容が変わったり、前のステージに戻ったりすると、再び聞かれます。「何が変わったか」は、質問文に書かれます。
4. 環境変数での回避方法
調査しても原因が取り除けないとき、チェックを一時的に無効にして先へ進みたい場面があります。そのための環境変数が用意されています。
4.1 回避用の環境変数
次の表は、公式ガイドとオンボーディング文書に載っている、回避用の環境変数の一覧です。多くは
1 を設定して有効にします。| 環境変数 | 止める対象 |
|---|---|
AIDLC_DISABLE_PLAN_APPROVAL_GUARD | コード計画の承認の確認 |
AIDLC_DISABLE_REVIEW_FREEZE_HOOK | 承認済みの成果物の編集を止めるレビュー凍結チェック |
AIDLC_DISABLE_REVIEWER_SCOPE_HOOK | レビュアーが読める範囲の制限 |
AIDLC_DISABLE_SUMMARY_CONFIRMATION | 要約の確認 |
AIDLC_SKIP_SUMMARY_CONFIRMATION_GUARD | 要約確認のチェック（主にテスト用の迂回） |
AIDLC_SKIP_HUMAN_PRESENCE_GUARD | 承認が人の返答によるものかの確認（人の在席確認） |
AIDLC_SKIP_ARTIFACT_GUARD | ステージ出力のチェック |
AIDLC_SKIP_REVISION_BACKSTOP | 修正再入のバックストップ（安全網） |
AIDLC_DISABLE_ENSEMBLE_EVIDENCE | パイプライン引き継ぎのチェック |
AIDLC_DISABLE_SENSORS | センサー（自動チェック） |
AIDLC_DISABLE_LEARNINGS | 学びの記録 |
AIDLC_DISABLE_COLLABORATORS | ステージの協働エージェント（オフにするとリード単独で実行。レビュアーは影響を受けません） |
AIDLC_SKIP_REVIEWER_GATE_GUARD | レビュアー関連のゲート開始チェック（主にテスト用の迂回） |
AIDLC_DISABLE_USAGE_TRACKING | トークン使用量とコストの記録（Claude Code向けの記録機能で、チェックではありません） |
AIDLC_SKIP_SOURCE_FRESHNESS | ソース変更の鮮度チェック（緊急用の切り替え） |
主な回避用の環境変数を、公式ガイドとオンボーディング文書で確認できたものから挙げています。これで全部というわけではないので、必要な変数は公式ガイドで確認してください。
4.2 これは一時回避です
環境変数での回避は、あくまで一時的な逃げ道です。チェックを止めるということは、そのチェックが守っていたものを一時的に手放すことでもあります。たとえば、人の在席確認は、承認が本当に人の返答によるものだと保証する仕組みです。公式ガイドは、無人運転のように返答する人がいない場面のために、この変数を用意しています。
使うときは、次の点を守ってください。
- 原因を調べるための一時的な措置として使い、直ったら元に戻す
- 本来は、公式ガイドの手順で原因を直す
- 何を止めたかを、後でIssueに書けるよう記録しておく
回避策を含めて、提案された対処を鵜呑みにして自動で実行するのは避け、何を止めるのかを理解してから使ってください。
4.3 aidlc config との使い分け
チェックの切り替えには、環境変数のほかに、設定コマンドもあります。表の
\<key\>・\<変数名\>・\<on|off\> には、次に説明する値を入れます。| 目的 | 使うもの | どこで使うか |
|---|---|---|
| 今のワークフロー1件だけ切り替える | /aidlc config set \<key\> \<on|off\>（例: /aidlc config set guard.review-freeze off） | チャット内で入力 |
| プロジェクトや自分の環境で記録しておく | aidlc config flags --bypass \<変数名\> --local --yes | ターミナルで実行 |
| 元に戻す | aidlc config flags --clear-bypass \<変数名\> --yes | ターミナルで実行 |
| 設定値を確認する | /aidlc config get \<key\>、/aidlc config list | チャット内で入力 |
\<on|off\> は、on（有効）か off（無効）のどちらかです。\<key\> と \<変数名\> は、同じチェックを別の呼び方で指しています。\<key\> は /aidlc config set で使う名前、\<変数名\> は 4.1 の表に挙げた環境変数名（AIDLC_DISABLE_* / AIDLC_SKIP_*）です。主な対応は次のとおりです。| チェック | \<key\>（config set 用） | \<変数名\>（環境変数・bypass 用） |
|---|---|---|
| 計画承認 | plan-approval | AIDLC_DISABLE_PLAN_APPROVAL_GUARD |
| レビュー凍結 | guard.review-freeze | AIDLC_DISABLE_REVIEW_FREEZE_HOOK |
| レビュアーの読み取り範囲 | guard.reviewer-scope | AIDLC_DISABLE_REVIEWER_SCOPE_HOOK |
| 要約の確認 | summary-confirmation | AIDLC_DISABLE_SUMMARY_CONFIRMATION |
| センサー | sensors | AIDLC_DISABLE_SENSORS |
| 学びの記録 | learnings | AIDLC_DISABLE_LEARNINGS |
| 協働エージェント | collaborators | AIDLC_DISABLE_COLLABORATORS |
今その設定がどうなっているかは、
/aidlc config get \<key\>（1件）や /aidlc config list（一覧）で確認できます。使えるkeyの全部と各値の意味は、公式ガイドの設定の章（13-customization.md、aidlc-workflows（GitHub） ）に載っています。迷ったら、まず /aidlc config list で今の値を見て、変えたいチェックの \<key\> と \<変数名\> を上の表（または4.1）で確認してください。aidlc config flags --bypass は、環境変数と同じ切り替えを設定ファイルに記録します。--local は自分のチェックアウトだけ、--project はプロジェクトで共有する記録になります。実際の環境変数は、記録した設定より優先されます。使い分けは次のとおりです。
- その場で試したい一時回避なら、環境変数
- ワークフロー1件に限って変えたいなら、
/aidlc config set - 長く効かせたい、または共有したいなら、
aidlc config flags --bypass
どの方法でも、
/aidlc --status や /aidlc config get で、今どのチェックが止まっているかを確認できます。切り替えたままにして忘れることがないよう、直ったら戻す癖を付けておきましょう。4.4 環境変数は「どこで」設定するか（CLI / IDE）
環境変数は、設定したうえでV2を動かすプロセス（CLIやIDE）を起動すると効きます。すでに起動しているプロセスには後から効かないので、設定したら起動し直してください。
CLI（Claude Code や Kiro CLI） は、環境変数を設定したシェルから起動すれば効きます。
Mac / Linux の例:
1
AIDLC_DISABLE_PLAN_APPROVAL_GUARD=1 kiro-cli chatWindows PowerShell の例:
1
$env:AIDLC_DISABLE_PLAN_APPROVAL_GUARD = "1"; kiro-cli chat（上の
kiro-cli chat を、使っているCLIの起動コマンドに置き換えてください。）IDE（Kiro IDE など） では、環境変数を見た状態でIDEのプロセスが起動している必要があります。アイコンやランチャーから起動すると、ターミナルで設定した環境変数を引き継がないことがあります。その場合は、OSのユーザー環境変数として設定してからIDEを起動し直すか、環境変数を設定したターミナルからIDEを起動してください。
IDEでは、環境変数よりも 4.3 の設定コマンド（チャット内の
/aidlc config set \<key\> \<on\|off\>、またはターミナルの aidlc config flags --bypass）のほうが扱いやすい場面もあります。5. 不具合報告（Issue）
最後に、自力で直せなかった問題を報告するところを見ていきましょう。第三者が障害の解析、再現の確認、改修を進められる情報がそろっていると、やり取りの往復を減らせます。
5.1 まずはプロジェクトのIssueテンプレートに従う
このプロジェクトのGitHubリポジトリには、不具合報告用のIssueテンプレート（Bug Report）が用意されています。Issueを新規作成すると表示されるので、その項目を埋めることを第一にしてください。テンプレートには、次の項目があります。
- Description（概要）
- Steps to Reproduce（再現手順）
- Expected Behavior（期待した結果）
- Actual Behavior（実際の結果）
- AI-DLC Version（v2 または v1）、Release / Commit（リリース番号またはコミットハッシュ）
- AI-DLC Phase（どのフェーズで起きたか）
- Harness（使っているハーネス。複数選択可）
- AI Model（使っていたモデル）
- Environment（OSやハーネスのバージョンなど）
- Additional Context（スクリーンショットやログ出力など、その他の情報）
5.2 各項目に何を書くか
テンプレートの項目に沿って、第三者が障害の解析・再現・改修を進められる情報を書きます。テンプレートに専用の欄がないもの（ログや診断バンドル、自分の調査結果）は、Additional Context にまとめて添えてください。
| 項目 | 書く内容 |
|---|---|
| Description（概要） | 何が起きたかを一文で |
| Steps to Reproduce（再現手順） | 何をどの順で実行したか。コマンドや入力をそのまま書く |
| Expected Behavior（期待した結果） | 本来どうなるはずだったか |
| Actual Behavior（実際の結果） | 実際に何が起きたか。エラー文はそのまま貼る |
| AI-DLC Version / Release / Commit | 使っているV2のバージョン、リリース番号またはコミットハッシュ |
| AI-DLC Phase | どのフェーズ（Ideation / Inception / Construction など）で起きたか |
| Harness / AI Model / Environment | 使っているハーネス、AIモデル、OSやハーネスのバージョン |
| Additional Context | 関連ログ（aidlc engine audit history の該当部分。秘密情報は伏せる）、/aidlc --doctor --export の診断バンドル（.tar.gz）、自分の調査結果 |
特に重要になるのが「自分の調査結果」です。第3章の手順で、doctorの結果、
/aidlc --status の表示、監査ログで確認したことを書いておくと、読む側が同じ調査をやり直さずに済みます。環境変数で回避した場合は、どの変数を使ったか、それで進んだかどうかも書いてください。回避で進んだという事実は、どのチェックが関わっているかを絞る手がかりになります。診断バンドルは、作業成果物を含まない形で作られますが、添付する前に、含まれる内容に問題がないかを一度見ておいてください。
5.3 日本語で相談したいとき
GitHubのIssueでは、基本的に英語でのやり取りになります。英語での報告に敷居を感じる場合は、AWS Builder CenterのAI-DLC Japanスペース に日本語で投稿していただければ、日本語でサポートします。こちらもあわせてご活用ください。
6. まとめ
この記事では、V2で異常が起きたときの対処を、トピック別に見てきました。異常に気づいたら、次の4つを順に進めます。
- ログを取る:
/aidlc --status、aidlc-state.md、aidlc engine audit history、/aidlc --doctor、/aidlc --doctor --export - 調査する: doctorで環境を確かめ、状態とログで何が起きたかをたどり、Quick Fix Tableで症状から引く
- 回避する: 環境変数や
aidlc configで一時的にチェックを止め、直ったら戻す - 報告する: Issueテンプレートに沿って、再現手順、ログ、診断バンドル、自分の調査結果を添える
調査の成果は、そのまま報告の材料になります。途中の調査メモを残しておくと、第三者が同じ調査をやり直さずに済みます。
困ったときは、まず
/aidlc --doctor から始めてみてください。Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 31AI-DLC Workflow V2の異常時の対処: ログ・調査・回避・Issue報告の進め方 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