本記事の位置づけ — 本記事は、
awslabs/aidlc-workflowsリポジトリの規範ルールおよび利用ガイドを素材として、筆者が AI を活用して読み解き、まとめた解釈です。AWS が公式に発表した方法論ではなく、一次資料の翻訳・要約でもありません。シリーズ — 本記事は AIで紐解くAI-DLC v2 シリーズの一部です。
参照した版 — Claude Code 実装を対象に、2026 年 8 月 4 日時点のコミット
c73ee984（AIDLC_VERSION 2.5.37、core/）を参照しています。Claude Code 以外の実装（Kiro CLI／Kiro IDE／Codex CLI／opencode）は対象外で、記述が異なる場合があります。OSS 実装は更新が続いているため、最新の状態は公式リポジトリをご確認ください。
概要
AI-DLC v2 の工程は32ステージ、スコープは9種。連載ではそう書いてきました。これは出荷時点の数で、固定量ではありません。
プラグイン機構は、工程そのものを外から足す仕組みです。新しいステージを持ち込むだけでなく、既存のステージに項目を足すこともできます。非機能設計のステージに「テストハーネスの設計」という手順と成果物を追加する、といった形です。
本記事では、足せるものの種類、既存ステージへの追加がどう混ざるのか、そしてプラグインが1つも無いとき core が変わらないことをどう保証しているのかを読み解きます。
足せるもの
プラグインは plugins/<名前>/ に置きます。宣言ファイルには名前や版が入りますが、何を持ち込むかはディレクトリの構成から発見されます。stages/・scopes/・agents/ など、決められた名前の置き場を見る形です。宣言の列挙を読む仕組みはまだ入っていません。
| 持ち込むもの | 置き場所 | 内容 |
|---|---|---|
| ステージ | stages/ |
新しい工程そのもの |
| 既存ステージへの追加 | contributions/ |
既にある工程に手順と成果物を足す |
| エージェント | agents/ |
新しいペルソナ |
| スコープ | scopes/ |
新しい工程の絞り込み |
| ナレッジ | knowledge/ |
エージェントが参照する方法論 |
| センサー | sensors/ |
保存時に走る決定論的なチェック |
| ツール | tools/ |
センサーの実体など |
出荷時には test-pro という参考実装が1つ付いてきます。テストの網羅性を扱うプラグインで、上記のすべてを使っています。
新しいステージ
プラグインが持ち込むステージは、core のステージと同じ形をしています。フロントマターにフェーズ・主担当・モードを備え、plugin: フィールドで誰の持ち物かを示す点が違います。表示名と番号もフロントマターで宣言でき、core のステージはどちらも宣言していません。
宣言した名前は、コンパイル済みの表示名がまだ無いときに採られます（ふつうは初めてコンパイルされるときです）。番号の扱いはこれと違って、決めるのは常にコンパイラです。宣言した値がグラフにそのまま渡ることはなく、同じフェーズに新しく入るステージどうしの並び順で、依存だけでは順番が決まらないときのタイブレークに使われるだけです。並ぶ相手はプラグインの別を問いません。参考実装にはステージが2本あり、うち構築フェーズのものは 3.85 という番号を宣言しています。ただし読まれるのは小数点以下の 85 だけです。フェーズを決めるのは番号ではなくファイルの置き場所です。既存の 3.1〜3.7 の後ろに入るのも、新しいステージが空き番号の続きを採るからであって、宣言したからではありません。
採番では、同じフェーズに新しく入るステージをひとまとめにし、それらの間の順番の依存（requires_stage）で並べます。依存では決まらない同士だけを宣言値、次いで slug の順に置き、先頭から空き番号を連番で振ります。新しいステージどうしで依存が循環していれば、コンパイルは黙って進むことはなく、失敗します。すでに番号が決まっているステージは、番号も表示名も振り直されません。
宣言値を絶対値として採らないのは、示し合わせていないプラグインどうしを衝突させないためです。同じ「いかにもな番号」を2つのプラグインが書いても、先に入れたほうが番号を占有することにはなりません。
実行条件も core のステージと同じように書けます。参考実装の統合テストのステージは「プラグインが有効で、かつビルドが複数の作業単位にまたがるときに1回だけ」という条件を持ちます。これは全ステージ共通の散文フィールドで、プラグイン固有のものではありません。
これとは別に、機械が読める起動条件のフィールドもあります。参考実装の運用フェーズのステージが「ある成果物の生産者が計画に入っているとき」という形で書いていますが、いまは形が正しいかを検証するだけで、評価そのものは未実装です（後述の「いま足せないもの」）。
既存ステージへの追加
プラグインは、既存ステージの中身に手順や成果物を足せます。合成はインストール先のステージファイルへ直接書き込む形で行われ、書き込んだ内容は再コンパイルをまたいで残ります。
追加を書いたファイルには、どのステージが対象かと、何を足すかが宣言されています。参考実装が非機能設計のステージに足しているものを例に取ると、こうなります。
- 作る成果物を1つ追加（テストハーネスの設計）
- 読む成果物を1つ追加（任意扱い）
- 必須の見出しを1つ追加（「Test Harness Design」）
- 本文の断片を、指定した位置に差し込む
差し込む位置は名前で指定します。参考実装は「手順の最後」を指定していて、複数のプラグインが同じ場所を狙ったときのために順番を表す数値も添えます。
つまり上流の core/ には手を加えず、インストール先で合成した結果が使われます。プラグインを外すときは、合成で足した分を取り除く処理が別に用意されています。
合成の実体
合成を行うのは、セッション開始のたびに走る1本のスクリプトです。同じ内容を二度入れないようになっていて、変更が無ければ何もせず終わります。やっていることは4つあります。
新しいステージをコピーする。 すでに同じ名前があれば上書きしません。
追加を混ぜ込む。 作る成果物・読む成果物・センサー・走るスコープ・必須見出しは、対象ステージの宣言に足し合わせます（重複は取り除かれます）。読む成果物については、必須かどうかも、条件付きかどうかも保たれます。走るスコープを足すと、core の既存ステージが、そのプラグインの持ち込んだスコープでも走るようになります。
本文の断片を差し込む。 内容のハッシュを見て、同じものを二度入れないようにします。バージョンが上がったときの入れ替えにも対応し、複数のプラグインが混ざっても順序が決まります。
グラフを組み直す。 新しいステージが加わったので、エンジンが工程を辿れるように依存グラフを再コンパイルします。これをしないと、足したステージは存在しないのと同じです。
合成の過程で取りこぼしがあれば記録に残り、診断コマンドが表に出します。失敗を握りつぶさない設計です。
ハーネスごとの投影
AI-DLC は5種類の配布物を出しますが、プラグインもそれぞれの形に投影されます（Kiro は CLI と IDE の2つを数えます）。
Claude と Codex にはプラグインの仕組みが元々あるので、その作法に沿った形で出力されます。Kiro はフォルダを置いて明示的に合成を走らせる形です。
プラグインを実行してよいかの検証も、各ハーネスの仕組みに任せています。AI-DLC 独自の検証は設けず、その環境のやり方に従います。
未使用時の不変性
拡張の仕組みを入れると、使わない人にも影響が出がちです。ここはそうならないように作られています。
プラグインが1つも無ければ、core の出力はバイト単位で同一です。ステージのフロントマターに追加されたフィールドは、core のステージがどれも使っていないので、コンパイル結果が変わりません。
さらに、配布物の生成にはずれの検出が組み込まれています。生成し直した結果が既存と1バイトでも違えば失敗します。プラグイン側の投影も同じ検査の対象です。しかもプラグイン側の生成は、core の配布物のディレクトリを一切書き換えません。
インストール側の選択
インストール側にも選択権があります。どのプラグインの内容を利用者に見せるかを選べます。
ここで、core 自身が暗黙のプラグインとして扱われます。名前は aidlc で、選択から外すこともできます。外せば、選んだプラグインが持ち込むコマンドとスコープだけが見える環境になります（ワークスペースを用意する初期化フェーズだけは、選択に関わらず常に残ります）。
「core があって、その周りに拡張がある」のではなく、core も拡張も同じ仕組みで扱われます。
いま足せないもの
参考実装はすべての種類を使っていますが、機構としてはまだ完成していない部分があります。一次資料が「先送り」として明示しているのは、条件式による有効化の評価、依存するステージの指定を足し合わせる仕組み、配布の仕組みや固定版の管理といったあたりです。
拡張点を先に決めて、実装を段階的に埋めていく形になっています。
まとめ
プラグイン機構があるため、「32ステージ」「スコープ9種」は固定量ではありません。連載の数値はいずれも出荷時点のもので、インストール先で増えることがあります。
設計として目を引くのは2点あります。
1つは、既存ステージへ宣言で足すという選び方です。プラグイン側は足したい分だけを書き、合成がそれをインストール先のステージへ混ぜ込みます。上流の core/ を書き換えないので、core の更新とプラグインの更新が衝突しません。
もう1つは、core 自身を暗黙のプラグインとして扱ったことです。特別扱いせず同じ仕組みに乗せているので、「core だけ」も「プラグインだけ」も同じ機構で表現できます。拡張の仕組みを後付けするとき、本体を特別扱いしたまま外側に足すほうが実装は楽ですが、そうしなかった形です。
参照元
| ファイル | 内容 |
|---|---|
plugins/test-pro/.aidlc-plugin/plugin.json |
プラグインの宣言。持ち込める7種類（stages／overlays／agents／scopes／knowledge／sensors／tools）と依存の宣言 |
plugins/test-pro/contributions/construction/nfr-design.md |
既存ステージへの追加の実例。対象ステージ・足す成果物・必須見出し・差し込む断片と位置 |
plugins/test-pro/stages/construction/test-pro-integration.md |
プラグインのステージの実例。小数の番号（3.85）と表示名の宣言、plugin: による所有権、実行条件 |
plugins/test-pro/stages/operation/test-pro-full-suite.md |
機械が読める起動条件（when:）を宣言している唯一の実例。形は検証されるが評価は未実装 |
core/tools/aidlc-stage-schema.ts |
plugin／number／name／when／required_sections を省略可能フィールドとして受けること。number は順序のヒントで、コンパイル後の値はコンパイラが与えること。when は形のみ検証しコンパイル時の評価は別扱い。core のステージはこれらを持たないのでコンパイル結果が変わらない |
core/tools/aidlc-graph.ts |
新しいステージの採番。番号は常にコンパイラが与え、宣言値の絶対値は使わないこと（示し合わせていないプラグインどうしを衝突させないため）。フェーズごとに新規ステージを requires_stage で並べ、決まらない同士を宣言値→slug で置いて連番を振ること（束の単位はフェーズで、プラグインの別は見ない）。循環はコンパイル失敗。既存の行は番号も表示名も振り直さない。コンパイル済みの表示名が無いときに限り宣言値を採ること（門は nameBySlug のヒット有無で、ピン済み判定に使う number とは別） |
core/tools/aidlc-utility.ts |
合成が足し合わせる面の列挙（作る成果物／読む成果物／センサー／走るスコープ／必須見出し）と、プラグインごとの控え。無効化時に足した分だけを剥がす処理 |
scripts/plugin-hooks-template/compose.ts |
セッション開始時に走る合成フック。上書きしないステージのコピー、作る成果物・読む成果物・センサー・走るスコープ・必須見出しの足し合わせ、内容ハッシュによる冪等な断片の差し込みと順序決定、グラフの再コンパイル、取りこぼしの記録 |
scripts/package.ts |
ハーネスごとの投影と、生成し直してのずれ検出 |
関連記事
前の記事: 協働のトポロジー
次の記事: エージェント階層
目次: AIで紐解くAI-DLC v2