AI-DLC Workflows 2.0 とは何か、そしてどう実装されているか
はじめに
AI コーディングエージェントが日々の開発に入り込むにつれ、多くのチームが同じ壁に突き当たります。エージェント向けのワークフローは、バグ修正でも新規開発でも同じ重厚な手順を求めてきます。しかも自動化に慣れるほど、人間の側は AI に全部決めさせる受け身の姿勢に傾き、レビューと監督の質が落ちていく。手順の硬さと人間の関与の薄さが同時に進んでしまう、という問題です。
AWS はこの課題に対して AI-DLC(AI-Driven Development Life Cycle) というメソドロジーを提唱し、2025 年 11 月にその実装を awslabs/aidlc-workflows として OSS 公開しました。2026 年に入ると「AI-DLC Workflows 2.0」として大幅に作り直され、7 月に GA(一般提供)に到達しています。当初は v2 ブランチで開発されていましたが、現在は 2.x がデフォルトブランチ(main)になり、v1 世代は v1 ブランチに残されています。単一のハーネスに依存せず、1 つのコアから複数のハーネス向けの配布物を生成するアーキテクチャです。ここでいう ハーネス(Harness) とは、リポジトリの用語集の定義では「AI-DLC のコアを載せて動かすエージェント CLI / IDE(Claude Code や Kiro など)と、それ向けに生成される配布形態」を指します。
AI-DLC そのものの理念は、AWS 公式ブログの日本語訳記事「AI 駆動開発ライフサイクル:ソフトウェアエンジニアリングの再構築」で次のように説明されています。
AI-DLC は、ソフトウェア開発に対する AI 中心の革新的なアプローチで、2 つの重要な要素を重視しています。AI が実行し人間が監視する:AI は体系的に詳細な作業計画を作成し、積極的に意図のすり合わせとガイダンスを求め、重要な決定は人間に委ねます。ダイナミックなチームコラボレーション:AI がルーティンタスクを処理する一方で、チームはリアルタイムでの問題解決、創造的思考、迅速な意思決定のために、コラボレーションしやすい環境で協力します。
同記事は AI-DLC のフェーズを「開始(Inception)」「構築(Construction)」「運用(Operation)」の 3 つとして紹介していますが、これは 2025 年 8 月時点(v1 世代)の説明です。本記事で扱う 2.x では、これが Initialization / Ideation / Inception / Construction / Operation という 5 フェーズ・33 ステージにさらに細分化されています。同記事が触れている「ボルト(bolts)」(スプリントに代わる短い作業サイクル)や「作業単位(Units of Work)」(エピックに代わる用語)といった AI-DLC 独自の用語体系も、2.x の実装に引き継がれました。
本記事では、AI-DLC というメソドロジーが何を解決しようとしているのか、そして aidlc-workflows がそれを「Harness Engineering」という設計思想でどう実装しているのかを、最新の安定版のコードとドキュメントに沿って解説します。AI-DLC の考え方を詳しく紹介しているのは、AWS DevOps Blog の記事「Open-Sourcing Adaptive Workflows for AI-Driven Development Life Cycle (AI-DLC)」です。
注記:本記事は 2026 年 10 月 24 日時点の最新安定版 2.11.1(2026 年 10 月 20 日リリース)に合わせて更新しました(初版は GA 直後の 2.5 系を元に書いています)。プレビュー版はほぼ毎日出ており、
aidlc update --channel previewで追従できます。安定版を使う場合も、プロジェクトごとにバージョンを固定(pin)したり、aidlc rollbackで前の版に戻したりできます。設計全体をまとめたホワイトペーパー「AI-DLC Workflows 2.0 Specification」とロードマップも公開されています。
GA から何が変わったか
初版を書いた 2.5 系から 2.11.1 までの 3 か月で、使い方に関わる変更がかなり入りました。本文は最新版に合わせて書き直していますが、初版を読んだ方向けに主なものを先にまとめておきます。
- インストールの形が変わりました。以前は Bun を入れてリポジトリの
dist/<harness>/を手でコピーしていましたが、現在はネイティブのaidlcコマンドをインストーラで入れ、aidlc config --harness <name>でプロジェクトに配置します。Bun も Node.js も不要です。 - 対応ハーネスが 5 つから 7 つになりました。Cursor と GitHub Copilot(Copilot CLI と VS Code)が加わっています。
- ステージが 32 から 33 になりました。Inception の Application Design が、部品を洗い出す Domain Design と、Unit 間の契約や外部 API を決める Contract Design に分かれています。
- スコープが 9 から 11 になりました。v1 と同じ流れの
classicと、最軽量のexpressが加わり、各スコープが Guard Policy やセンサーの既定値まで持つようになりました。 - コード生成の前に、計画を人間に見せて承認をもらう Plan Approval がエンジンの仕事になりました。enterprise 以外のスコープでは、各ステージは既定でリードエージェントだけで進みます。
- 学習ループで残した訂正は、次のワークフローを待たず、今のワークフローの次のステージから効くようになりました。
- 監査イベントの種類は 74 から 120 に増えました。
全体像(俯瞰図)
本記事で扱う要素は多岐にわたるため、先に全体を 1 枚の図で示します。左がメソドロジーそのもの、つまり何が実行されるかで、右がそれを各ハーネスに配る仕組み、つまりどう実行されるかです。この記事で主に掘り下げるのは右側、ビルドパイプラインと Kiro CLI との統合になります。

図1: メソドロジーと配布の仕組みの全体像
この図の要素を、記事の中で順番に見ていきます。
AI-DLC がそもそも解決したい課題
AI-DLC の課題認識は次の 3 点です。1 つ目が画一的なワークフロー問題で、バグ修正のような小さな作業にも、新規サービス開発と同じ重厚な手順を強制してしまうこと。2 つ目は深さの調整ができないことで、ちょっとしたユーティリティ関数の実装にもフルスケールのドメインモデリングを要求してしまいます。3 つ目が人間の監督の薄れで、自動化が進むほど人間が何でも AI に決めさせる受け身の姿勢になりがちで、レビューの質が落ちていく点です。
AI-DLC はこれらを、Method Definition Paper の Principle 10("No Hard-Wired, Opinionated SDLC Workflows")に基づいて解決しようとしています。AI 自身が意図(intent)に応じて、どのステージを踏むか、どの深さで実行するかを提案し、各ステージの承認ゲートで人間が判断する、という形です。
aidlc-workflows はこのメソドロジーの実装です。v1 世代は Kiro の Steering Files として実装されていましたが、2.x ではハーネス中立な core/ から複数のハーネス向けに生成する構成に作り直されました。Steering Files は Kiro 向け生成時の 1 つの投影(rules/ → steering/ へのリネーム)という位置づけになっています。
2.x の全体像(14 エージェント・33 ステージ・11 スコープ)
2.x の規模感から押さえます。手元でソースを確認する場合は、デフォルトブランチをそのままクローンしてください。
git clone https://github.com/awslabs/aidlc-workflows.git
2.11.1 は以下の構成です。
| 項目 | 数 |
|---|---|
| フェーズ | 5(Initialization / Ideation / Inception / Construction / Operation) |
| ステージ | 33 |
| エージェント | 14(ドメインエキスパート 11:product / design / delivery / architect / aws-platform / compliance / devsecops / developer / quality / pipeline-deploy / operations + レビュアー 2:architecture-reviewer / product-lead + composer) |
| 適応スコープ | 11(enterprise / feature / mvp / poc / bugfix / refactor / infra / security-patch / classic / workshop / express)+ 自動検出 |
| 深さレベル | 3(Minimal / Standard / Comprehensive) |
| テスト戦略レベル | 3(Minimal / Standard / Comprehensive) |
| 監査イベント種別 | 120 |
README はスコープを「workflow profile」とも呼んでいますが、ファイル名(core/scopes/)やコマンド(/aidlc --scope)では今も scope です。本記事もスコープで統一します。
対応するハーネスは Claude Code、Kiro IDE、Kiro CLI、Codex CLI、Cursor、opencode、GitHub Copilot の 7 つです。ここが 2.x のもっとも大きな特徴で、実際のディレクトリ構成と生成の流れを図にすると設計意図が見えてきます。

図2: core から各ハーネス向けの配布物を生成する 3 層構造
core/ に置かれているのは、メソドロジー本体(33 個のステージ定義、14 個のエージェント定義など)の Markdown + YAML フロントマターと、エンジン本体の TypeScript です。bun scripts/package.ts を実行すると、これが各ハーネス向けにコンパイル・展開されます。生成物はリポジトリにはコミットされず(dist/ と dist-release/ は .gitignore 対象のローカル出力です)、リリースのたびに runtime/<harness>/ として配布アーカイブに入ります。利用者は自分でビルドする必要はありません。docs/reference/01-architecture.md や docs/harness-engineering/09-porting-to-a-new-harness.md にある通り、新しいハーネスを追加する際も core/ は原則として変更せず、harness/<name>/manifest.ts を中心に書くだけで済むように設計されています。
「Harness Engineering」という考え方
aidlc-workflows のリポジトリには docs/harness-engineering/ というガイドがあります。ここでの「Harness Engineering」は、AI-DLC というメソドロジーが個々のハーネス(Claude Code、Kiro、Codex CLI など)でどう振る舞うかを、TypeScript のコードを書かずに、Markdown + YAML の定義ファイルの編集だけで調整することを指しています。
補足:Kiro CLI 2.7.0(2026 年 6 月リリース)で追加された
/goalコマンドは、受入基準を検証してからでないと完了できないループをコマンド単体で提供する機能です(筆者の別記事「ゴールが決まるまで笛は鳴らない ~ Kiro CLI の goal コマンドで「完了」を勝ち取る」で解説)。AI-DLC はこの「自己申告の完了を許さない」という思想をさらに一段上のレイヤーで、33 個のステージそれぞれに承認ゲートとセンサーを埋め込み、かつ人間の承認を必須にするという形で、プロジェクト全体の開発ライフサイクルに適用しています。
リポジトリの docs/harness-engineering/00-overview.md が明確に区別しているのは、次の三者の読者です。
| ガイド | 対象読者 | 変更するもの |
|---|---|---|
| User Guide | AI-DLC を 使って ソフトウェアを作る人 | 何も変更しない(/aidlc を実行し、ゲートで回答し、成果物をレビューするだけ) |
| Harness Engineer Guide | AI-DLC の 振る舞いを自分たちのチーム向けに調整する 人 | フレームワークが読み込む 定義ファイル:ステージ、エージェント、スコープ、ルール、センサー(いずれも Markdown + YAML) |
| Developer Reference | AI-DLC そのもの を変更する人 | その定義ファイルを読み込む コード:オーケストレーター、フック、CLI ツール(TypeScript) |
このガイドの核心は、「ステージを追加する」「エージェントを追加する」「スコープを定義する」といった変更が、すべて TypeScript を書かずに、Markdown ファイルの YAML フロントマターを編集するだけで完結する、という設計方針です。これがどう成立しているのかを、実際のファイルを例に説明します。
ステージは「何をするか」、エージェントは「誰がするか」
core/aidlc-common/stages/inception/domain-design.md を例に取ると、1 つのステージ定義は YAML フロントマターと本文(プロンプト)の組み合わせで表現されています(以下は主要フィールドの抜粋です)。
---
slug: domain-design
phase: inception
execution: CONDITIONAL
condition: Execute when new components or logical building blocks are needed. ...
lead_agent: aidlc-architect-agent
support_agents:
- aidlc-aws-platform-agent
- aidlc-design-agent
mode: inline
summary_confirmation: required
reviewer: aidlc-architecture-reviewer-agent
review_artifact: components
reviewer_max_iterations: 2
review_class: advisory
produces:
- components
- decisions
- traceability
consumes:
- artifact: requirements
required: true
- artifact: architecture
required: false
conditional_on: brownfield
# ...(抜粋。実物には stories / component-inventory / team-practices も続く)
requires_stage:
- requirements-analysis
- refined-mockups
sensors:
- required-sections
- upstream-coverage
- traceability
scopes:
- enterprise
- feature
- mvp
- classic
- workshop
---
# Domain Design
...
## Steps
### Step 1: Load Prior Context
...
## Sensors
...
## Learn
...
Domain Design は、GA 時点の Application Design を分割してできたステージです。コードを書く対象の部品(コンポーネント)を洗い出すところまでを担当し、どうデプロイ単位にまとめるかは後続の Units Generation に任せます。Unit 同士の境界や外部に公開する API の契約は、Units Generation の後にある Contract Design が決めます。
この 1 ファイルには 2 種類の読者がいます。パーサーはフロントマターだけを読み、どの成果物を消費・生成するか、リードエージェントは誰か、どのスコープで実行されるかという依存グラフのノードを組み立てる役割です。実行するエージェントのほうは本文(## Steps / ## Sensors / ## Learn の 3 セクション)だけを読み、実際の作業を進めます。

図3: フロントマターはパーサー、本文はエージェントが読む
この 2 つを 1 ファイルに共存させているのが設計上のポイントです。ドキュメントの docs/harness-engineering/01-anatomy-of-a-stage.md では、これを分離すると「グラフの依存関係」と「実行手順」を並べて見比べられなくなり、レビューしづらくなる、と説明されています。
そして、フロントマターを編集したら、YAML をコンパイルして stage-graph.json を再生成する必要があります。この生成物は手編集禁止です。ステージ定義は、ソースコードと同じ厳密さで管理される定義ファイルという位置づけになっています。
エンジンとコンダクターで「決定」と「実行」を分ける
ステージファイルが「何をするか」を定義していることは分かりましたが、実際に次にどのステージを実行するかを決めているのは誰でしょうか。これは AI-DLC のもう 1 つの重要な設計判断で、docs/reference/17-skill-system.md に「エンジン」と「コンダクター」という 2 つの役割として明記されています。
エンジン(core/tools/aidlc-orchestrate.ts)は、現在のワークフロー状態(aidlc-state.md)とコンパイル済みのステージグラフ(stage-graph.json)を読み、次に何をすべきかを決定論的なコードとして計算し、directive(指示)という JSON を 1 件だけ返します。ルーティングの判断はここで完結し、LLM には一切委ねません。コンダクター(skills/aidlc/SKILL.md)は、エンジンが返した directive を受け取り、それに従ってステージを実際に実行します。エージェントのペルソナを読み込み、質問をし、成果物を作り、承認ゲートで人間に確認する、薄いフォワーディングループです。

図4: エンジンが次を決め、コンダクターが実行するループ
なぜこの 2 つを分離しているのでしょうか。ドキュメントには「ルーティングは決定性が求められる関心事であり、ツール(コード)に持たせるべきで、LLM のプロンプトに持たせてはならない」と明記されています。ルーティングの判断を LLM に任せてしまうと、コンテキストが積み重なった状態で誤った遷移(後述する Kiro の roll-forward バグのようなもの)が起きやすくなります。エンジンをコードとして固定することで、次に何が起きるかを常に再現できるようにしているわけです。GA 以降はこの範囲がさらに広がり、コード生成の前に計画を人間に承認してもらう Plan Approval の質問も、エンジンが計画ファイルのフィンガープリントを持って自分で尋ねるようになりました。チャットが圧縮されたり作業が中断したりしても、同じ計画について二度聞くことはありません。
さらに、このフォワーディングループ自体が止まってしまわないよう、aidlc-continue-workflow.ts という Stop フックが監視しています(GA 時点の名前は aidlc-stop.ts でした)。コンダクターがターンを終えようとするたびに、このフックがエンジンにもう一度問い合わせます。まだ実行すべき directive が残っていればターン終了をブロックし、人間の承認待ちや会話中であれば通過させる、という仕組みです。docs/reference/06-hooks-and-tools.md によると、17 個あるフックのうち 11 個は処理を止めない(non-blocking)フックで、動作フローを変える(flow-altering)ものは次の 6 個です。
| フック | 役割 |
|---|---|
aidlc-continue-workflow.ts |
ターン終了時にエンジンへ問い合わせ、作業が残っていればループを続けさせる |
aidlc-state-transition-guard.ts |
AI-DLC のフックや実行時の記録、監査ログへの直接書き込みを拒否し、状態遷移をエンジン経由に限定する |
aidlc-plan-approval-guard.ts |
計画が承認されるまで、developer エージェントへの委譲やプロジェクトのコードへの書き込みを止める |
aidlc-review-freeze.ts |
レビュー済みの成果物を、承認ゲートの前にこっそり書き換えることを拒否する |
aidlc-reviewer-scope.ts |
レビュアーのサブエージェントが担当外ユニットのファイルを読むことを拒否する |
aidlc-deliver-stage-rules.ts |
サブエージェントへの委譲時に、そのステージに効くルールの原文を確実に渡す |
どれも、コンダクターやエージェントがプロトコルを律儀に守ることを、善意に頼らずコードで強制するためのものです。
承認ゲートと学習ループで人間の訂正がルールになる
AI-DLC が人間中心を掲げる部分の実体は、各ステージの本文にある ## Learn セクションと、それに対応する学習ループです。ステージプロトコルには「ステージ実行中に memory.md という日記を書き続け、承認ゲートの直前にその内容を候補として提示する」と定義されています。これがどう「次から効くルール」になるのかを、docs/guide/09-rules-and-the-learning-loop.md の具体例で説明します。

図5: 人間の訂正が承認ゲートを経てルールになる流れ
ドキュメントに載っている具体例(銀行のプロジェクト)を要約すると、次のような流れです。
- 要件分析ステージで、ステークホルダーが「transaction が重複しないように」とメモに書く
- product エージェントはこれを「データベーストランザクション」と解釈するが、人間が「銀行の決済処理のことだ」と訂正する
- エージェントはこの訂正を
memory.mdの## Interpretationsに 1 行で記録する(ルールはまだ何も作られていない) - ステージ完了時の承認ゲートで、この記録が候補として提示され、人間が「残す」を選ぶ
-
org.mdの既存ルールと矛盾しないかが LLM でチェックされ、問題なければ決定論的なツールがmemory/project.mdに 1 行追記する(監査ログにはRULE_LEARNEDが残る) - ワークフローが次の user-stories ステージに進むと、エンジンはステージを渡す前に
project.mdの中身を読み直すので、訂正は今回のワークフローの次のステージから効く。後日別のワークフロー(例えば/aidlc bugfix)を始めた場合も、最初のステージから効く
6 番目は GA 時点から変わった点です。初版を書いた 2.5 系のドキュメントは「今回のワークフローには反映されず、次回の実行から効く」と説明していました。現在は、エンジンがステージを渡すたびに、選択済みのルールファイルの現在の中身を読み直します。ワークフロー開始時のコンパイルで固定されたまま実行中に変わらないのは、どのファイルを読むかという選択のほうです。新しいルールファイルの追加や新しいセンサーの紐付けは、次にステージグラフをコンパイルするまで反映されません。ドキュメントはこれを「BGP のルーティングテーブルが飛行中のパケットに対して再計算されないのと同じ安定性」とたとえています。残した訂正が実行の残りの間ずっと放置されることはなく、承認済みのゲートが前提にしたルールの組み合わせは崩れない、という両立のさせ方です。
この学習ループがあるおかげで、前節で見た「ステージファイルは手で触らない」という制約と矛盾しません。チームの知見はステージ定義ではなく aidlc/spaces/<space>/memory/ 配下のルールファイルに蓄積されていきます。フレームワーク自体をハーネスごとにカスタマイズせずに、プロジェクトの振る舞いを継続的に洗練させていけるわけです。
なお、AI-DLC が各ステージに埋め込んでいる「センサー」は、いずれもエージェント自身の自己評価ではなく、決定論的なチェックとして実装されています。同梱されているのは required-sections / upstream-coverage / traceability / claim-sources / linter / type-check の 6 つで、traceability(要件から成果物への追跡)と claim-sources(主張の出典)は GA 以降に加わりました。これは /goal コマンドの「検証してからでないと完了できない」という思想と地続きです。同梱の 6 つはすべて advisory で、承認ゲートをブロックせずシグナルを見せるだけです。ゲートが開くと、エージェントはまだ指摘が残っているチェックを人間に伝えます。一方、チームが自分で追加するセンサーは、マニフェストに default_severity: blocking と書くと、通らない限り承認ゲートが開かないようにできます。その場合は Fix findings(直す)か Override blocking sensors(上書きする)を人間が選び、上書きは人間の選択として記録されます。強制力をどこまで持たせるかもチームが決められるわけですが、最終判断を人間の承認ゲートに委ねるという設計思想は変わっていません。
Intent と Space で複数の作業を 1 つのワークスペースに束ねる
前節で学習ループが memory/project.md に書き込むと説明しましたが、この memory/ はどこに、どういう単位で存在しているのでしょうか。実際に手を動かすと分かりますが、実プロジェクトでは 1 つの機能を作っている最中に、無関係な緊急バグが飛んでくる状況が普通に起きます。AI-DLC 2.x はこれを Intent と Space という 2 つの概念で扱います。docs/guide/03-spaces-and-intents.md の説明を要約すると次のとおりです。
Intent(インテント) はライフサイクルの 1 回の実行、つまり 1 つの作業の単位です。/aidlc Build a REST API for inventory management のように作業を説明すると、エージェントはまずその作業向けの計画(スコープ)を提案します。それを確認した時点で Intent が作られ、aidlc/spaces/<space>/intents/<YYMMDD>-<label>/ という専用の記録ディレクトリができます。ここが状態ファイル(aidlc-state.md)、監査ログ(audit/)、各ステージの成果物が溜まっていく場所です。Space(スペース) は 1 つのチームの世界で、その中に方法論(memory/)、ドメイン知識(knowledge/)、コード知識(codekb/)、そして複数の Intent の記録(intents/)が入っています。ほとんどのプロジェクトは default という 1 つの Space しか使いません。

図6: Space に入る memory、knowledge、intents の関係
Intent が進行中の状態で新しい依頼をすると、エンジンは今の Intent の続きか別の作業かを判断します。別の作業らしい場合は、次のように尋ねます。
New request
Work is already in progress on: "Build a REST API for inventory management". You said: "Fix the
timeout on the export endpoint". What should I do?
> 1. Part of the active work
Continue the current workflow
2. Separate new piece of work
Yes, set it up alongside the current one without changing it; you pick its plan next
3. Reshape the active work
Change how the remaining plan is shaped
4. Type something.
5. Chat about this
2 を選ぶと新しい作業の計画を選ぶ段階に進み(この例ではエージェントが bugfix を提案します)、2 つ目の Intent が立ち上がります。進行中の Intent(inventory-rest-api)の状態・記録には一切手を触れません。3 を選んだ場合は、新しい Intent を作らずに、進行中の Intent の残りの計画を組み替えます。AI-DLC が尋ねずに 2 つ目の Intent を作ることはありません。
/aidlc intent で Space 内の Intent 一覧を確認し、/aidlc intent inventory-rest-api のように名前を指定して切り替えます。切り替えた時点で、状態・監査ログ・進行中のステージもすべてその Intent のものに戻るので、複数の作業を同時に進めながら、それぞれの文脈を混ぜずに管理できます。
前節の学習ループが書き込む先(memory/project.md)があるのは、Intent ではなく Space のレイヤーです。つまりチームの学習は個々の Intent の記録には残らず、そのチームが担当するすべての Intent に対して横断的に効きます。「このプロジェクトのコードベースはこういう構造だ」というコード知識(codekb/)も同じく Space レベルで保持され、複数の Intent を通じて再利用されます。
チームを複数持つプロジェクトでは、/aidlc space create payments-team(短縮形は /aidlc space-create payments-team)のように Space 自体の追加も可能です。新しい Space は default の org.md のコピーとフレームワークのフェーズ別ルールを引き継ぎ、team.md と project.md、knowledge/、codekb/ は空の状態からスタートします。他チームの方法論やコード知識と混ざることはなく、それぞれ独立した memory/ を持ちます。
ワークフローをカスタマイズするには、どこをいじればいいか
ここまでで AI-DLC のアーキテクチャの仕組みを見てきました。実際に自分のチーム向けにワークフローを調整したい場合、どのファイルをどう編集すればいいのでしょうか。これは docs/harness-engineering/ ガイドがまさに「Harness Engineer」と呼ぶ読者に向けて書いている内容で、ポイントは、すべての変更が定義ファイルを編集するだけで完結し、TypeScript のコードには触れないという点です。core/ を編集した場合は、リポジトリで bun scripts/package.ts を実行して全ハーネス向けの生成物を作り直します。
主なカスタマイズ項目と、編集対象のファイルを整理すると次のとおりです。
| やりたいこと | 編集する場所 | 補足 |
|---|---|---|
| 既存ステージの手順を変える |
core/aidlc-common/stages/<phase>/<slug>.md の本文(## Steps) |
フロントマターは変えずに、エージェントへの指示文だけを書き換える |
| 新しいステージを追加する | 同ディレクトリに新規 .md を追加し、requires_stage / consumes / produces / scopes を設定 |
追加後は bun scripts/package.ts で全ハーネス分を再生成する。インストール済みの環境で試すだけなら aidlc engine graph compile でそのツリーのグラフだけを再コンパイルできる |
| 新しいエージェント(ペルソナ)を追加する |
core/agents/<name>-agent.md を新規作成 |
ステージ側の lead_agent / support_agents から参照されて初めて使われる |
チーム独自のスコープを追加する(例:hotfix) |
core/scopes/aidlc-<name>.md を新規作成 + 対象ステージの scopes: にタグ追加 |
11 個の既存スコープファイルは変更不要 |
| チームの標準的な決定事項を教える(「常に squash-merge する」等) |
aidlc/spaces/<space>/memory/team.md または project.md
|
コードではなく、ワークフロー実行中に学習ループが書き込む先と同じファイル |
| フェーズ全体に効くルールを追加する | aidlc/spaces/<space>/memory/phases/<phase>.md |
例:Inception フェーズでは必ず 2 つ以上の代替案を検討させる、等 |
| 独自の検証ロジック(センサー)を追加する |
core/sensors/aidlc-<id>.md のマニフェスト + 対象ステージの sensors: に ID 追加 |
実体のチェックスクリプトは core/tools/ に別途実装が必要(ここは唯一コードが絡む)。default_severity: blocking にするとゲートを止められる |
| チームのドメイン知識を追加する |
aidlc/knowledge/<agent>-agent/ 配下に自由形式のファイルを追加 |
フレームワーク側は上書きしない、プロジェクト固有の資料置き場 |
| 自社独自のステージ・エージェント・センサーをパッケージ化して複数プロジェクトに配布する |
plugins/<name>/ を新規作成(独立した git リポジトリとして管理) |
core/ は変更不要。既存ステージへの追加変更も contributions/ で可能(後述) |
| 新しいハーネスを追加する |
harness/<name>/manifest.ts を新規作成 |
core/ は原則変更不要。フックのペイロード差異を吸収するアダプタも必要(後述) |
この表からも分かるように、AI-DLC のカスタマイズ経路は大きく 3 つに分かれます。
1 つ目はチームとしてのカスタマイズで、aidlc/spaces/<space>/memory/ を編集します。core/ には一切触れず、標準インストールのまま、ワークフローの振る舞いだけをプロジェクト固有に調整する経路です。前述の学習ループが自動で書き込む先でもあり、日常的にはこちらのほうが出番が多いはずです。
2 つ目はプラグインとしてのカスタマイズで、plugins/<name>/ を新規作成します。core/ を直接編集せず、新しいステージ・エージェント・スコープ・センサーや、既存ステージへの追加変更(contributions/、既存ステージを書き換えずに ## Steps へプロセス片を差し込む仕組み。2.11.1 ではコアのペルソナへの追記や、ステージの前提条件の追加もできます)を、独立したディレクトリかつ独立した git リポジトリとしてパッケージする方法です。docs/harness-engineering/10-authoring-a-plugin.md に手順が示されており、aidlc-workflows 自身のサンプルプラグイン test-pro(plugins/test-pro/)がリポジトリに同梱されています。作ったプラグインは aidlc plugin validate で検証し、aidlc plugin build で各ハーネス向けに組み立てます。Claude Code / Codex CLI ではホスト側のプラグインストア経由(/plugin marketplace add 等)で配布・インストールでき、2.11.1 からは他チームが作ったプラグインも作者が付けた名前のまま並べて入れられるようになりました。Kiro にはプラグインストアがないため、組み立てたプラグインの .kiro フォルダをプロジェクトにコピーし(.kiro/aidlc-plugins/<name>/ に配置されるので、複数のプラグインが上書きし合いません)、/aidlc plugin sync でコンポーズする運用です。自社固有の業界ルール(コンプライアンス要件を専用ステージとして追加する、など)を、全プロジェクトが必ず読み込む本体ではなく、選んだプロジェクトだけが opt-in する追加パッケージとして配りたい場合、この経路がもっとも fork との衝突リスクが低い選択肢です。
3 つ目はフレームワーク開発者としてのカスタマイズで、core/ を編集します。ステージ・エージェント・スコープ・センサーの定義そのものを変える経路で、リポジトリを fork するか、社内でこのリポジトリをベースにカスタム版を運用する場合の入口です。編集後は必ず bun scripts/package.ts で生成し直し、--check で生成が安定していることを確認します。
はじめて調整に着手するなら、1 つ目(memory/team.md や memory/project.md を手で書く、あるいは学習ループに任せる)から試すのが安全です。自社の複数プロジェクトに配布したい独自のステージやエージェントがある場合は、次に 2 つ目のプラグイン機構を検討する価値があります。既存のステージ・スコープを直接編集する 3 つ目のアプローチは、フレームワークの将来のアップデートとの衝突を招く選択です。docs/harness-engineering/04-scopes.md も、同梱スコープを直接チューニングするとフレームワークの更新時にすり合わせが必要になるので、「11 個の同梱スコープの横に新しいスコープファイルを足すほうがクリーン」と推奨しています。
「どのステージを実行するか」を決めるスコープ
33 個あるステージのうち、実際にどれを実行するかを決めるのが スコープ です。core/scopes/aidlc-feature.md のようなファイルで、スコープの識別情報(深さ、キーワード、説明)と、そのスコープで作業するときの既定値を定義します。各ステージ側のフロントマターに scopes: [feature, ...] と書くことで、そのステージがこのスコープに含まれることを表現します。
# core/scopes/aidlc-feature.md
---
name: feature
depth: Standard
keywords: []
description: Full lifecycle for new features, practical depth
skeleton: on
runner: true
guard_policy: off
sensors: on
learnings: on
summary_confirmation: on
plan_approval: on
---
この「スコープ側に加盟ステージのリストを持たせるのではなく、ステージ側にスコープのタグを付ける」という向きが重要です。新しいステージを追加するときは、そのステージファイルに scopes: を書くだけで済み、11 個のスコープファイルすべてを編集する必要がありません。ビルド時にステージグラフのコンパイラがこれを転置し、scope-grid.json という EXECUTE / SKIP のグリッドを生成します。

図7: ステージの scopes タグを EXECUTE / SKIP のグリッドに転置
これにより、例えばバグ修正スコープ(bugfix)では 33 ステージのうち 9 ステージだけを実行し、市場調査やデプロイパイプライン構築のステージを自動的にスキップします。エンタープライズスコープ(enterprise)は全 33 ステージを通します。画一的なワークフロー問題への対処が、コードの分岐ではなく定義ファイル上のタグの組み合わせとして実現されているわけです。
GA 以降に加わった 2 つのスコープは対照的です。classic は v1 と同じ流れで、Inception と Construction を各ステージの承認付きで進めます。スコープを明示しなかったときの暗黙の既定もこれです。express は要件からデプロイまでを、設計工程とレビュアーなしで進める最軽量のスコープです。
上の YAML にある guard_policy や sensors、learnings、summary_confirmation、plan_approval は、そのスコープで作業するときの儀式の既定値です。Guard Policy は enterprise だけが strict で、それ以外は off になっています。2.11.0 からは、enterprise 以外のスコープでは各ステージがリードエージェントだけで進むようになり、サポートエージェントの参加は /aidlc --collaborators on で作業ごとに戻す形になりました。どの設定を変えても、各ステージの承認ゲートと「人間が実際に発言したか」のチェックはそのまま残ります。
さらに、11 の既成スコープと自動検出に加えて adaptive composer(/aidlc compose)があります。タスクの内容・スキャンレポート・実行中のワークフローを入力として、composer エージェントが既成スコープに縛られないオーダーメイドのステージプランを提案する仕組みで、11 のダイヤルのどれにも合わない仕事への回答という位置づけです(docs/guide/05-scopes-and-depth.md)。提案された計画はその作業だけに使われ、承認ゲートで「Approve and save as scope」を選んだときだけ再利用できるスコープとして保存されます。
新しいハーネスをどう追加するか
新しい CLI ハーネス(例えば将来登場するかもしれない別のエージェント CLI)を追加する手順は docs/harness-engineering/09-porting-to-a-new-harness.md に定められています。要点は次の 5 つです。
-
harness/<name>/manifest.tsを書く。core/のどのディレクトリをどこに配置するか、ルール用ディレクトリの名称変更(例:Kiro ではrules→steering)などを宣言的に記述する。ドキュメントはこれを「宣言的な 8 割」と呼んでいる - フックアダプタを 1 つ書く。各ハーネスのフックのペイロード形式は異なるため、それを共通フォーマットに正規化する薄いアダプタを用意する(コアのフック本体はロジックを分離せず、全ハーネスでバイト単位で共有し続ける)
- 必要な場合のみ
emit.tsを書く。宣言的なマニフェストで表現できない構造的な差異(Codex CLI のconfig.toml生成など)を命令的に処理する。2.11.1 でemit.tsを持つのは Codex CLI、GitHub Copilot、opencode の 3 つ - 許された種類の変換だけを使う(後述)
- テストを通す。
package.ts --checkによる生成の決定性、Bun 版とネイティブ版の両方の配布物の検査、Bun が PATH にない状態でネイティブ版が動くことの検査、実機で取得したペイロードを流すアダプタの契約テスト、そして実機での e2e が関門になる
原則として core/ への変更は不要で、ドキュメントが認めている唯一の例外は --doctor のハーネス別チェック分岐です。これが「one core, many harnesses」という README のキャッチフレーズを裏付けています。GA 以降に Cursor と GitHub Copilot が加わったのも、この手順に沿った追加です。
実際に動かすには
実際に手元で試す場合、README の Quick Start に従うと以下のような流れになります(Claude Code の例)。
# AI-DLC をインストール(macOS / Linux / WSL)
curl -fsSL https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh | sh
# プロジェクトにハーネスを設定
cd /path/to/your-project
aidlc config --harness claude
aidlc doctor
claude
Windows では PowerShell で irm https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.ps1 | iex を実行します。インストーラはネイティブの aidlc コマンドと全ハーネス分のランタイムを入れ、公開されている SHA-256 チェックサムで検証します。ネイティブ版は Bun も Node.js も使いません。自分でファイルを管理したい場合や実行ファイルを入れられない環境向けには、リリースの aidlc-copy-runtime-X.Y.Z.tar.gz から runtime/<harness>/ をコピーする方法も残っていて、Bun が必要なのはこの経路だけです。
Claude Code のセッション内では以下を実行します。
/aidlc --doctor # セットアップの健全性チェック
/aidlc Build a task management API with user authentication # ワークフロー開始
aidlc doctor(チャット内では /aidlc --doctor)は、フックが実際に動いているか、ステージグラフに循環がないか、全スコープがグラフ上で解決できるか、プロジェクトとランタイムのバージョンがずれていないか、などを確かめます。2.11.0 からは、ハーネスがフックを一度も実行していない場合、最初のメッセージの時点でそのツールでの有効化手順(Codex CLI なら /hooks で信頼する、Kiro CLI なら /agent で aidlc を選ぶ、など)を示して止まるようになりました。承認が記録されないまま進んでしまう事故を防ぐためです。
モデルの扱いも GA 時点から変わっています。以前は Bedrock 経由の Claude を前提にした設定が同梱されていましたが、現在の同梱設定は、利用者がすでに選んでいるプロバイダーとモデルをそのまま使います。Amazon Bedrock 用の設定は aidlc config providers で入れられます。推奨モデルは Claude Opus 4.8 です。
ほかのハーネスも --harness の値を変えるだけです。Kiro は 2 系統に分かれていて、Kiro CLI(V2 エンジン、2.6 以上)は kiro、Kiro IDE(1.1.70 以上)と、v3 エンジンを使う Kiro CLI(2.24.1 以上)は kiro-ide を選びます。CLI 版が Agent Config の hooks ブロックでフックを登録するのに対し、IDE 版は .kiro/hooks/*.kiro.hook ファイルという IDE のフック機構を使う、という違いです。既存の kiro プロジェクトは aidlc config --harness kiro-ide で .kiro/ をその場で切り替えられ、aidlc/ はそのまま残ります。Codex CLI(0.145.0 以上)では呼び出しが /aidlc ではなく $aidlc になります。opencode(1.17 以上)は、.opencode/tools/*.ts をカスタムツールとして自動インポートする事情から、エンジン本体を .aidlc/ という別ディレクトリに置く分割レイアウトです。Kiro CLI のガイドには次の注記があります。
AI-DLC on Kiro CLI works best with Claude Opus 4.8, which requires a paid Kiro plan. On weaker models the conductor may skip optional stage steps (reviewer pass, learnings ritual) or rush approval gates.
(Kiro CLI 上での AI-DLC は Claude Opus 4.8 との組み合わせで最も良く機能し、これには有料の Kiro プランが必要です。より軽量なモデルでは、コンダクターがオプションのステージ手順(レビュアーパスや学習の振り返り)を省略したり、承認ゲートを急いでしまう場合があります。)
Kiro CLI 向けに何が用意されているか
統合の仕組みの前に、そもそも Kiro CLI 向けに配布される一式が何なのかを整理します。以下は aidlc config --harness kiro がプロジェクトに配置するファイル(リリースの runtime/kiro/ と同じ中身)です。以降は V2 エンジン向けの kiro ハーネスを前提にしています。

図8: Kiro CLI 向け配布物 .kiro/ と aidlc/ の構成
1. コンダクターと 14 体の委譲先エージェント(.kiro/agents/)
.kiro/agents/aidlc.json が Kiro の Agent Config で、これを chat.defaultAgent に設定すると /aidlc コマンドがそのまま使えます。同じディレクトリには、14 体のエージェントペルソナ(11 のドメインエキスパートに product-lead / architecture-reviewer / composer を加えた core/agents/ からコピーされた Markdown)と、その全 14 体に対応する Kiro ネイティブの agent-v1.json 設定が同梱されています。14 体すべてがサブエージェントとして委譲可能です。
2. コンダクター本体と 41 個のランナースキル(.kiro/skills/)
skills/aidlc/ が /aidlc の本体で、フォワーディングループを実行するコンダクターの実装です。それ以外に、aidlc-domain-design、aidlc-feature、aidlc-bugfix のように、個々のステージや個々のスコープに直接ジャンプできるランナースキルが 41 個(コンダクター本体と合わせて .kiro/skills/ 配下に 42 個)同梱されています。aidlc-intent-capture、aidlc-requirements-analysis、aidlc-contract-design のようなステージ単位のスキルを中心に、aidlc-feature、aidlc-express、aidlc-security-patch のようなスコープ単位のスキル、aidlc-init / aidlc-compose / aidlc-session-cost のようなユーティリティスキルが、/aidlc-<name> という短いコマンドとして使えるように生成されています。これらは core/tools/aidlc-runner-gen.ts が自動生成するもので、手で書かれたものではありません。
3. アダプタ 1 つとコアフック 17 個(.kiro/hooks/)
後述する通り、aidlc-kiro-adapter.ts が Kiro 専用に書かれたアダプタです。それ以外の aidlc-write-audit-log.ts、aidlc-run-sensors.ts、aidlc-continue-workflow.ts などはすべて Claude Code と完全に同じ内容(バイト単位で同一)のフック本体です。GA 時点のコアフックは 13 個でしたが、aidlc-plan-approval-guard.ts(計画の承認前のコード変更を拒否)、aidlc-review-freeze.ts(レビュー済み成果物の書き換えを拒否)、aidlc-deliver-stage-rules.ts(委譲先へのルールの受け渡し)、aidlc-record-human-turn.ts(人間の発言の記録)などが加わって 17 個になり、いくつかは名前も変わりました(aidlc-audit-logger.ts → aidlc-write-audit-log.ts、aidlc-sensor-fire.ts → aidlc-run-sensors.ts など)。
4. 約 95 個の TypeScript ファイル(.kiro/tools/、エンジン本体)
aidlc-orchestrate.ts(次に何をすべきかを決定するエンジン本体)、aidlc-state.ts(状態管理)、aidlc-graph.ts(ステージグラフのコンパイラ)など、フレームワークの実体を成す TypeScript です。GA 時点の 30 個から約 3 倍に増えました。Construction フェーズで複数の developer エージェントを git worktree 上に並列展開する「スワーム」を扱う aidlc-swarm.ts / aidlc-worktree.ts もここにあります。これらもすべてハーネス間で共有される内容で、Kiro 固有の改変は一切入っていません。ネイティブ版では、これらを aidlc コマンドが Bun なしで実行します。
5. メソドロジー本体(.kiro/aidlc-common/ .kiro/scopes/ .kiro/sensors/ .kiro/knowledge/ .kiro/steering/)
33 個のステージ定義ファイル、11 個のスコープ定義ファイル、センサー定義、14 エージェント分のドメイン知識と共有ナレッジ(アーキテクチャパターン、テスト戦略、CI / CD パターンなど)が、そのまま core/ からコピーされています。Kiro 向けのオンボーディング文書は .kiro/steering/aidlc-onboarding.md に置かれ、コンダクターの resources から読み込まれます。
6. Kiro CLI 固有の設定(.kiro/settings/)
{
"chat.defaultAgent": "aidlc"
}
cli.json が持つのは、デフォルトエージェントを aidlc に固定する設定だけです。GA 時点では Opus 4.8 の推論努力度を xhigh にする設定もプロジェクトに入っていましたが、現在は外されました。Kiro アカウントごとに使えるモデルが違い、チームメイトのアカウントにないモデルをプロジェクトで指定するとプロンプトが毎回失敗するためです。モデルと推論努力度は個人の Kiro 設定(~/.kiro/settings/cli.json)に保存され、aidlc config models でプリセット(minimal = low、balanced = medium、thorough = xhigh)を選びます。古い版で作ったプロジェクトを更新すると、プロジェクト側の推論努力度の設定は取り除かれます。
同じディレクトリの mcp.json には、Claude Code と同じ 5 つの MCP サーバー(context7 と AWS 系 4 つ)が、すべて無効の状態で入っています。"disabled": false にしたサーバーと、個人の ~/.kiro/settings/mcp.json に追加したサーバーは、AI-DLC のチャットと 14 体のペルソナから使え、呼び出しのたびに確認を求められます。
7. AGENTS.md と aidlc/(プロジェクトルート)
.kiro/ の外側、プロジェクトルートに配置される 2 つです。AGENTS.md はハーネス共通のオンボーディング文書で、同じプロジェクトに複数のハーネスを入れた場合はこのブロックを共有します。チームがすでに AGENTS.md を持っていれば、その後ろに AI-DLC のブロックが追加されます。aidlc/spaces/default/memory/ はチームのプラクティスや過去の学習内容を保持するワークスペースシェルです。/aidlc --doctor は、この aidlc/spaces/default/memory/ の存在を必須チェックしています。
インストールから起動まで
これだけの量がありますが、ユーザーが実際にやることはシンプルです。
curl -fsSL https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh | sh
cd your-project
aidlc config --harness kiro
aidlc doctor
kiro-cli chat
セッション内で /aidlc --doctor を実行すれば、上記すべて(フックの存在、33 ステージの整合性、11 スコープの解決可能性など)が自動でチェックされます。ネイティブ版の aidlc コマンドを入れられない環境では、aidlc-copy-runtime-X.Y.Z.tar.gz から runtime/kiro/.kiro/ と runtime/kiro/aidlc/ をプロジェクトにコピーし、bun .kiro/tools/aidlc.ts config --from <runtime> --harness kiro を実行します。
「共通ファイルからコンパイルする」の実体
ここまでの説明の通り、aidlc-workflows が配布しているのは「Kiro CLI 用に個別に書かれたファイル一式」ではありません。core/ という共通のソースから、ビルドスクリプトが各ハーネス向けにコンパイル(変換・生成)した結果を配布しています。この変換処理を実際に担っているのが scripts/package.ts で、コメントに明記されているパイプラインは次の 6 段階です(GA 時点は 5 段階で、6 段目が増えました)。

図9: core から Kiro 向け配布物への 6 段階のコンパイル
この 6 段階のうち、特に押さえておきたいポイントが 3 つあります。
1 つ目は、許される変換の種類が限られていることです。core/ の Markdown 本文には {{HARNESS_DIR}}(ハーネスのディレクトリ名。.claude / .kiro / .codex など)、{{INVOKE}}(エンジンの呼び出し方。ネイティブ版では aidlc、Bun 版では bun .kiro/tools/aidlc.ts)、{{TOOL_PREFIX}}、{{TRUSTED_NAMESPACE}} という 4 種類のトークンが埋め込まれていて、これをハーネスごとの値に置き換えるのが変換の中心です。ほかに認められているのは、Kiro 向けの rules/ → steering/ の改名(Kiro は steering という名前でルールを自動読み込みするため)、マニフェストで宣言したフロントマターの追加、ネイティブ版向けにコマンドの許可リストやフックの経路を書き換える処理だけです。ドキュメントは「No blind sed」と書いており、恣意的な文字列置換は禁止されています。core/ にハーネスのパスが直書きされていないかを確かめるテスト(t146-core-hygiene)まで用意されています。
2 つ目は、ステージグラフとランナースキルがコンパイルされた副産物であって、ソースではないことです。core/aidlc-common/stages/*.md の YAML フロントマターを人間が編集した後、ビルド時に stage-graph.json(ステージの依存関係グラフ)と scope-grid.json(どのスコープでどのステージを実行するかの表)がハーネスごとに再コンパイルされます。前節で触れた 41 個のランナースキルも同様で、aidlc-runner-gen.ts がステージ定義・スコープ定義から自動生成します。6 段目では、コンダクターのスキル本文に埋め込まれたステージ表とスコープ表が、コンパイルしたばかりのグラフから更新されます。手書きではありません。
3 つ目は、生成物の扱いです。GA 時点では dist/ をリポジトリにコミットし、package.ts --check がビルド結果とコミット済みの dist/ をバイト単位で比べていました。現在は dist/(Bun で動くコピー版)と dist-release/(ネイティブ版)はどちらもコミットしないローカル出力で、配布物はリリースのたびに作られます。--check はコピー版・ネイティブ版・プラグインの配布物一式を、独立した一時ディレクトリに 2 回生成してバイト単位で比べ、生成が決定的でなければ CI を失敗させます。
この設計の効果を一言でいうと、ステージやエージェントの定義を core/ の 1 箇所で 1 回だけ編集すれば、bun scripts/package.ts を実行するだけで、7 つのハーネス向けの配布物すべてに反映される、ということです。配布物は毎回 core/ から作り直され、人が手で触ることはありません。そのため「Kiro 向けだけ古い定義のままになっている」といった実装の分岐が起きる余地がない仕組みです。
Kiro CLI との統合を掘り下げる
共通のソースからコンパイルされることを説明しましたが、その変換規則自体(harness/kiro/manifest.ts が何を指示しているか)と、コンパイルだけでは埋まらない Kiro 固有の挙動差をどう吸収しているかは、harness/kiro/ の実装に集約されています。ここでは harness/kiro/manifest.ts・harness/kiro/agents/aidlc.json・harness/kiro/hooks/aidlc-kiro-adapter.ts の 3 つに沿って、統合の仕組みを具体的に説明します。
1. Kiro CLI は「エージェント」という単位でフックを持つ
Claude Code にも Kiro にも「フック」という仕組みがあり、ツール呼び出しの前後(PreToolUse / PostToolUse)やセッション開始時などに任意のコマンドを実行できる点は共通です。しかし両者には無視できない違いがあります。Claude Code では、フックは settings.json にプロジェクト単位で登録します。Kiro CLI では、.kiro/agents/aidlc.json という Agent Config ファイルの中の hooks ブロックとして登録します(この JSON は Kiro CLI のエージェントスキーマに準拠しています)。
ネイティブ版で配置される .kiro/agents/aidlc.json では、hooks の中に agentSpawn(セッション開始時)、userPromptSubmit(プロンプト送信時)、preToolUse / postToolUse(ツール呼び出し前後)、stop(応答終了時)の 5 種類のイベントに対して、合計 15 個のフック登録(すべてアダプタ経由)が記述されています(GA 時点は 9 個でした。以下は timeout_ms フィールドを省略した抜粋です)。
"hooks": {
"agentSpawn": [
{ "command": "aidlc engine adapter kiro session-start" }
],
"userPromptSubmit": [
{ "command": "aidlc engine adapter kiro verb-intercept" }
],
"preToolUse": [
{ "matcher": "execute_bash", "command": "aidlc engine adapter kiro state-transition-guard" },
{ "matcher": "execute_bash", "command": "aidlc engine adapter kiro guard-tool-call" },
{ "matcher": "fs_write", "command": "aidlc engine adapter kiro review-freeze" },
{ "matcher": "execute_bash", "command": "aidlc engine adapter kiro review-freeze" },
{ "matcher": "subagent", "command": "aidlc engine adapter kiro deliver-stage-rules" },
{ "matcher": "subagent", "command": "aidlc engine adapter kiro plan-approval-guard" },
{ "matcher": "fs_write", "command": "aidlc engine adapter kiro plan-approval-guard" },
{ "matcher": "execute_bash", "command": "aidlc engine adapter kiro plan-approval-guard" }
],
"postToolUse": [
{ "matcher": "fs_write", "command": "aidlc engine adapter kiro audit-and-sensors" },
{ "matcher": "execute_bash", "command": "aidlc engine adapter kiro rebuild-stage-graph" },
{ "matcher": "todo_list", "command": "aidlc engine adapter kiro sync-workflow-state" },
{ "matcher": "subagent", "command": "aidlc engine adapter kiro log-subagent" }
],
"stop": [
{ "command": "aidlc engine adapter kiro continue-workflow" }
]
}
Bun で動かすコピー版では、各コマンドが bun .kiro/tools/aidlc.ts engine adapter kiro ... になります。中身は同じで、{{INVOKE}} トークンの置き換え先が違うだけです。
つまり Kiro CLI 上での AI-DLC は、Kiro のスキルとして動く汎用エージェントではなく、chat.defaultAgent: "aidlc" として登録された専用の Kiro エージェントとして実装されています。以下の図が、フックイベントとアダプタのサブコマンドの対応です。

図10: フックイベントとアダプタのサブコマンドの対応
この Agent Config には、使えるツールの許可リスト(tools / allowedTools)、execute_bash で事前に許可するコマンド(ネイティブ版では aidlc engine * と aidlc doctor などの読み取り専用コマンドだけ)、書き込み可能なパス(fs_write.allowedPaths)、委譲可能なサブエージェント(subagent.trustedAgents に 14 体)まで、Kiro のネイティブなアクセス制御機構を使って細かく制限が掛けられています。許可リストにないシェルコマンドは実行前に確認を求められ、git push や再帰的な削除も確認を経てから実行されます。Claude Code の settings.json のツール許可リストに相当する仕組みですが、フックと権限がひとつの Agent Config ファイルに集約されている点が Kiro 側の特徴です。
2. アダプタが「ペイロードの翻訳者」として働く
core/hooks/ にある実際のフック本体(aidlc-write-audit-log.ts や aidlc-run-sensors.ts など)は、Claude Code のフックが渡す JSON ペイロードの形式(ClaudeCodeHookInput)を前提に書かれています。これが全ハーネスでバイト単位で共有されるコアのロジックです。
しかし Kiro CLI が実際に渡してくるペイロードは、形式が微妙に異なります。harness/kiro/hooks/aidlc-kiro-adapter.ts の冒頭コメントには、Kiro CLI で実際に観測した 3 つの差異が明記されています。
-
tool_nameは Claude Code の名称(Bash、Write)ではなく Kiro 側の名前で届き、しかも Kiro のランタイムの世代によって変わる(shell/execute_bash、write/fs_write/str_replace/fs_append、subagent/invoke_sub_agent/subagent_<agent>) - 書き込み先のパスがプロジェクトからの相対パスのこともあり、フィールド名も
path、file_path、paths[]、operations[].pathのいずれかで届く -
todo_listの入力がコマンド形式({command: "create", tasks: [...]})で、Claude Code のTaskUpdateのような状態遷移を持たない
aidlc-kiro-adapter.ts はこの差異を吸収する翻訳レイヤーです。Kiro から届いた生のペイロードを Claude Code 互換の形式に正規化し、対応するコアフック(例:aidlc-write-audit-log.ts)をサブプロセスとして呼び出します。図にすると次のような流れです(監査・センサー系の advisory なフローの例。次節の guard-tool-call のように exit 2 でツール呼び出しをブロックする経路もあります)。

図11: アダプタがペイロードを正規化してコアフックを呼ぶ
これにより、コアのフックロジックは Claude Code 向けに書かれたものを 1 文字も変えずに、Kiro CLI でも動かせます。manifest.ts のコメントにも "hooks/ is MIXED: core hook bodies are copied; the one authored aidlc-kiro-adapter.ts stdin shim is a harnessFile" と明記されている通り、コアのフック本体(コピーされるだけ)とアダプタ(Kiro 専用に書かれる)の区別は明確です。
3. 「暴走防止」の仕組みもアダプタの中に実装されている
aidlc-kiro-adapter.ts には、単なるペイロード変換だけでなく、Kiro CLI 特有の弱点を補うための追加ロジックが実装されています。特に重要なのは次の 3 つです。
verb-intercept は roll-forward 対策です。/aidlc --status や /aidlc --doctor、/aidlc intent <name> のような読み取り専用やナビゲーションのコマンドを、コンダクター(LLM)に判断させず、アダプタがエンジン自身の分類器で判定して直接実行し、結果を「ワークフローを進めるな」という指示つきでコンダクターに渡します。コメントには「セッションの文脈が積み重なった状態では、コンダクターが素の next を実行してワークフローを進めてしまう(roll-forward バグ)」ことが実測で確認されており、これを避けるための決定的な迂回路として実装されています。
guard-tool-call は、その後ろに置かれた最終防衛線です。Kiro の userPromptSubmit はコンテキストを差し込めるだけで、処理を止められません。そこで、同じターンに verb-intercept が読み取り専用コマンドを処理済みなのに、コンダクターが進める意図のない素の next を execute_bash で実行しようとした場合、preToolUse で exit 2 を返してツール呼び出しを止めます。Kiro 側の拒否コントラクト(exit 2 と stderr でツール呼び出しを止められる。exit 1 や stdout の JSON では止まらない)を利用した実装です。
もう 1 つは、承認が人間の発言にもとづいているかの確認です。verb-intercept は、人間が実際に入力したターンで HUMAN_TURN という監査イベントを記録します。エンジンは、承認ゲートを表示した後にこのイベントが記録されていなければ承認を受け付けません。Kiro は、ワークフローの指示やサブエージェントの完了通知などを、自分でプロンプトとして差し込むことがあります。アダプタは Kiro 自身のチャット記録(~/.kiro/sessions/ 配下)で、そのメッセージが人の入力か Kiro が作ったものかを見分け、後者は HOST_TURN として記録して人間の発言とは数えません。AI やホストが自分で承認したことにしてしまうのを防ぐための仕組みです。GA 時点では、承認ゲートが開いているのに人間が発言していないターンの execute_bash を止める pretool-block がこの役割を担っていましたが、発言の記録とエンジン側のチェックに置き換わりました。
ほかにも、前述の flow-altering フック(state-transition-guard、plan-approval-guard、review-freeze、deliver-stage-rules、reviewer-scope)はすべてアダプタ経由で Kiro に配線されています。reviewer-scope は少し特殊です。Claude Code ではフックのペイロードに含まれるサブエージェント名(agent_type)で、今動いているのがレビュアーかどうかを判定します。Kiro CLI のペイロードにはこれが無いため、レビュアーエージェント 2 体(architecture-reviewer / product-lead)自身の Agent Config にフックを登録し、登録の場所そのものをアイデンティティの証明にする、という配線になっています。deliver-stage-rules も Kiro では作りが違い、委譲先のエージェント設定の resources に Space のルールファイルが読み込まれているかを委譲前に確かめ、欠けていれば修復方法を示して委譲を止めます。
このように、Kiro CLI との統合は単純なファイルコピーではありません。Kiro Agent Config のフック機構を使って、コアのロジックに手を入れずに、Kiro 固有の制約(ペイロード形式の違い、暴走しやすいポイント、ホストが差し込むプロンプト)を吸収する専用のアダプタを書く、という形で実現されています。これが docs/harness-engineering/09-porting-to-a-new-harness.md で説明されている「Step 2:フックアダプタ」の実体です。
Claude Code と Kiro CLI での挙動の違い
docs/guide/harnesses/kiro-cli.md には、両ハーネスでの挙動の違いが一覧化されています。主要なものは次のとおりです。
| 項目 | Claude Code | Kiro CLI |
|---|---|---|
| 承認ゲートの UI |
AskUserQuestion ウィジェット |
番号付きの選択肢(数字で回答) |
| ステータスライン | 現在のステージ・モデル・コンテキスト残量を表示 | 非対応(/aidlc --status と各ゲートの進捗行で代替) |
| サブエージェント委譲 |
Task ツール |
Kiro の subagent ツール(全 14 ペルソナの設定を同梱し trustedAgents で許可) |
| Construction のスワーム実行 | 並列 Task によるファンアウト |
サブエージェントのファンアウトのみ(AIDLC_USE_SWARM=1 は no-op) |
| セッション監査イベント |
SESSION_STARTED/RESUMED/ENDED 等 |
SESSION_STARTED のみ(Kiro にセッション終了フックが無いため) |
| Stop フックによるループの維持 | 対話でもヘッドレスでも有効 | 対話セッションのみ(--no-interactive では Stop フックのブロックが効かない) |
| ツール許可 |
settings.json のアローリスト |
aidlc.json の toolsSettings(ネイティブ版は aidlc engine * などを事前許可、それ以外は確認) |
| MCP サーバー | 5 つ同梱(context7 + AWS 系 4 つ) |
同じ 5 つを .kiro/settings/mcp.json に無効の状態で同梱 |
同じメソドロジー・同じステート管理・同じ監査ログでありながら、UI とフックの発火タイミングというシェルの部分だけが、ハーネスごとの制約に応じて作り込まれていることが分かります。
まとめ
aidlc-workflows の 2.x は、AI-DLC というメソドロジーの「適応的なワークフロー」という理念を、次の設計判断で実装に落とし込んでいます。

図12: 2.x の 4 つの設計判断
- ステージ・エージェント・スコープをすべて Markdown + YAML の定義ファイルとして表現することで、コードを書かずにワークフローの振る舞いを調整できるようにする
- 定義のおおもとを
core/の 1 箇所に置き、各ハーネスは薄い変換層に留めることで、Claude Code・Kiro・Codex CLI・Cursor・opencode・GitHub Copilot といった複数のハーネスに同じメソドロジーを一貫して展開する - フックのペイロード形式の差異を専用アダプタが吸収することで、コアのフックロジック自体はハーネス間でバイト単位で共有し続ける。Kiro CLI の実装(
aidlc-kiro-adapter.ts)を見ると、単なる形式変換だけでなく、ハーネス固有の弱点(ワークフローの roll-forward、ホストが差し込んだプロンプトを人間の承認と取り違えること)を埋め合わせる追加ロジックまで、このアダプタ層に集約されていることが分かる - 配布物はリリースのたびに
core/から生成し、人が手で触らない。package.ts --checkが生成のぶれを機械的に検出することで、「ハーネス A ではこう動くのにハーネス B では違う」という実装の分岐を防ぐ
GA から 3 か月で、対応ハーネスは 7 つに増え、インストールは aidlc コマンド 1 つになり、動作フローを変えるフックは 3 個から 6 個に増えました。それでも、上の 4 つの設計判断は初版を書いた時点から変わっていません。
なお、本記事の「Harness Engineering」は aidlc-workflows が docs/harness-engineering/ で使っている意味(ハーネスごとの振る舞いを定義ファイルで調整する設計手法)に限定した用語です。この設計思想の全体像に興味を持たれた方は、awslabs/aidlc-workflows をクローンして docs/harness-engineering/ 以下を読んでみてください。
Discussion