AI-DLC Workflow V2のPlugin: core/を変えず、現場に合わせてステージとエージェントを足す
「うちのプロジェクト、標準の33ステージにもう1つ足したいんだけど……core/を直接いじっちゃダメなの？」。やってもいいですが、おすすめしません。本体を書き換えた分だけ、フレームワークのアップデートのたびに衝突を抱え込むからです。core/を一切触らずにステージとエージェントを足す方法、プラグインで見ていきましょう。シリーズ第23回。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 23AI-DLC Workflow V2のPlugin: core/を変えず、現場に合わせてステージとエージェントを足す This article
1. はじめに
この記事はAI-DLC Workflow V2（以降V2）シリーズの第23回です。前回の第22回では、ステージのレビュー強度を選ぶ「レビュークラス」を扱いました。今回のテーマはカスタマイズです。具体的には、ステージの追加とエージェントの追加を「プラグイン」という形にまとめる方法を見ていきます。
結論から言えば、プラグインは
core/（フレームワーク本体のソース）を一切編集しません。追加したいものを plugins/<name>/ という独立したディレクトリに束ね、ハーネス（Claude Code や Kiro などの実行環境）が標準で持つプラグインの仕組みを通じて、利用者の環境に組み込みます。そして、すべてのプラグインを無効にすれば、インストールは素の core とバイト単位で同一に戻ります。2. カスタマイズの2つのアプローチ
V2でステージやエージェントを足すと言っても、やり方は一つではありません。では、大きく2つのアプローチを見ていきましょう。
アプローチ1:
core/ を直接編集する。 ステージファイルを
core/aidlc-common/stages/ に、エージェントファイルを core/agents/ に置きます。これはフレームワーク本体そのものを変える行為です。bun scripts/package.ts で全ハーネスの配布ツリーに焼き込まれ、そのインストールでは常に存在します。オン・オフの概念はありません。この方法には課題もあります。本体を書き換えた分だけ、フレームワークのアップデートのたびに衝突を抱え、更新に追従しづらくなります。とくに出荷済みのファイル（標準のステージやエージェント）を書き換えた場合は、アップグレードで上書きされます。
さらに、変更は本体に常時反映されます。そのため、特定のプロジェクトだけに閉じたり、必要なときだけ有効にしたりする使い分けはできません。
アプローチ2: プラグインとして束ねる。
プラグインは、任意（optional）で、作者が所有し、バージョン管理された追加物の束です。自分のリポジトリで公開し、利用者が選んで自分のインストールに「合成（compose、複数のプラグインとcoreを1つに束ねる処理）」します。
全プロジェクトが欲しいわけではない一式に向いています。たとえば、テスト強化パックやコンプライアンスパックのようなドメインパックです。しかも core/ を変えないので、フレームワーク本体のアップデートをそのまま受けられます。追加は自分のプラグイン側に隔離されているからです。
プラグインで足せるものは、新しいステージ、エージェント、スコープ（どんな種類の仕事でどのステージを動かすかの定義）、センサー（成果物に対する自動チェック）、メソッドやルール、ナレッジです。さらに、既存の
core ステージを壊さずに拡張する「貢献（contribution）」という仕組みもあります。ここで大事な言い回しがあります。「プラグインは足す、インストール側が選ぶ」です。プラグインは候補を提供するだけで、どれを有効にするかはインストール側が決めます。
考え方の軸は前回までと同じで、ステージは「何をするか（what）」、エージェントは「誰がやるか（who）」です。なお、AI-DLCチームが出す一次プラグイン（first-party）と、それ以外の第三者プラグイン（third-party）は、構造も仕組みも同一です。違うのは出所、つまりどのリポジトリにあり誰がレビューしたか、それだけです。
3. プラグインの構造とマニフェスト
では、プラグインの中身を見ていきましょう。プラグインは1つのディレクトリであり、同時に1つのgitリポジトリです。
ここで重要なのは、プラグインは
core/ のファイルを一切編集しないという不変条件です。プラグインが持つものは、すべてプラグイン自身のツリーの中にあります。中心にあるのが宣言的なマニフェスト
.aidlc-plugin/plugin.json です。主な項目は次のとおりです。name: プラグイン名。ディレクトリ名と一致させます。core・aidlc・aidlc-*は予約語で使えませんversion: セマンティックバージョニングの版番号description/author: 説明と作者dependencies: 依存する他プラグインaidlc: AI-DLC固有の設定を入れる入れ子ブロック。中のcontributesで、このプラグインが提供するサブツリーを宣言します
そして
core/ と同じ形のサブツリーを持ちます。新しいステージは stages/、エージェントは agents/、スコープは scopes/、センサーは sensors/（実行スクリプトは tools/）、メソドロジー知識は knowledge/、既存ステージへの貢献は contributions/ に置きます。ここで1つ、正確に押さえておきたい点があります。
aidlc.contributes ブロックは設計上は存在しますが、現時点ではパッケージャがディレクトリ名の規約（stages/・sensors/ など）で中身を発見しており、このブロック自体はまだ読まれていません。設計済みで未実装の項目、と理解しておいてください。
4. プラグインでステージ（Stage）を追加する
では、プラグインで新しいステージを足す手順を見ていきましょう。プラグインのステージは、通常のステージファイル（
stages/<phase>/<slug>.md、フェーズがディレクトリで、ファイル名の語幹が slug、つまりステージの識別子）に、2つのルールを加えたものです。- frontmatter（ファイル冒頭のYAML設定）の
plugin:フィールドに、自分のプラグイン名を書く produces:（生成する成果物）は<plugin>-を頭に付けて名前空間化する。たとえばtest-pro-integration-test-resultsのようにします
frontmatter の
scopes: に書いたスコープでだけ、そのステージが有効になります。ここに載せない限り、どのスコープでも動きません（SKIP扱い）。番号についても押さえておきましょう。
number:（表示番号）は表示と並び順のヒントにすぎません。グラフ上の実際の位置は slug ベースの requires_stage（依存の辺）で決まり、絶対値はエンジンが採番します。プラグインは番号の範囲を主張しないので、無関係な2つのプラグインが番号でぶつかることはありません。なお、起動条件を表す
when: は、現時点では解析はされるものの評価はされません。設計済みで未実装なので、実際にどのスコープで動かすかは scopes: で指定してください。5. プラグインでエージェント（Agent）を追加する
続いて、プラグインでエージェントを足す方法を見ていきましょう。エージェントは
agents/<plugin>-<role>-agent.md というファイル1つで定義します。frontmatter の name はファイル名の語幹と一致させ、plugin: に自分のプラグイン名を設定します。合成のあとに自動で発見され、自分のプラグインのステージが lead_agent（主担当）や support_agents（補助）として指名できるようになります。ここで重要なのは、エージェントを「サブエージェントとしてディスパッチする（別エージェントに委任する）」場合の注意です。Kiro や Codex などで、mob・pipeline・subagent といった委任型の進め方をする場合、あるいは承認ゲートを持つステージに
reviewer:（レビュー担当）を置く場合には、ハーネス固有の登録が必要になります。Kiro であれば、agent-v1 形式のJSONと、conductor（進行役）の
trustedAgents への登録です。これが揃っていないと、合成はそのステージを拒否し、drops ログに理由を記録します。言い換えれば、こういうことです。コンダクターが自身のコンテキスト内でペルソナを引き受けて進める inline なら、Markdown のペルソナだけで動きます。しかし委任型では、このハーネス固有の登録が別に必要になります。
知識の置き場所も区別しておきましょう。チーム固有のドメイン知識は、space階層の
aidlc/knowledge/<slug>-agent/ に置きます。ここは起動時は空で、チームが必要になったときに作る領域で、プラグインは配りません。プラグインが配るのは、メソドロジー知識である knowledge/<agent-slug>/ のほうです。6. 既存ステージを壊さず拡張する（貢献 / contribution）
プラグインの強みは、新しいステージやエージェントを足すだけではありません。すでにある標準ステージに、そのファイルを一切書き換えずに、あとから機能を継ぎ足すこともできます。この「既存ステージへの後付けの継ぎ足し」を、AI-DLCでは貢献（contribution）と呼びます。
イメージしやすい例を挙げます。標準の Build and Test（build-and-test）ステージに、新しい確認手順（たとえば分岐カバレッジのチェック）や、新しい成果物（たとえば回帰テストのスイート）を足したいとします。このとき、元のステージファイルには一切触れません。足したい内容だけを別のファイルに書いておき、合成（compose）のときに元のステージへ重ね合わせます。これが貢献です。
その別ファイルは
contributions/<phase>/<slug>.md に置き、frontmatter で次を指定します。target: 拡張したい既存ステージの slugplugin: 自分のプラグイン名adds: 構造的な追加。produces・consumes・sensors・scopes・required_sectionsを集合和（set-union）で足しますfragments: 本文への文章の差し込み。アンカー（after-step:<n>、before-step:<n>、end-of-steps、in:<区画名>など）で位置を指定します
原則は strict-additive、つまり追加のみです。既存フィールドの上書きや削除、既存の手順文の置換はできません。
2つのプラグインが同じステージに貢献しても、構造は集合和で、文章は
(order, plugin) の順で決定的に並べて合成されます。先に書いたほうが勝つ、という上書きにはなりません。ここも正確に押さえておきましょう。次の項目は設計済みで未実装です。
adds.requires_stage は宣言できますが、まだマージされずログに記録されるだけです。required_sections はマージも検証もされますが、機械的な強制まではまだ行われず、宣言的な意図として扱われます。after-questions アンカーは未実装なので、after-step:<n> を使ってください。7. 配布・インストール・選択
作ったプラグインは、どう配って、どう有効にするのでしょうか。ここが core/ 直接編集との一番の違いです。
コマンドの2つのレイヤーを先に区別する
第7章では合成（compose/sync）や選択（select）のコマンドが出てきますが、AI-DLCのプラグイン運用コマンドには2つのレイヤーがあり、書き方が異なります。ここを最初に押さえておくと、以降の手順で迷いません。
- セッション内（ハーネスのチャット内で打つ）:
/aidlc plugin sync、/aidlc plugin list、/aidlc plugin selectのように、スラッシュ付きの/aidlcコマンドとして実行します。/aidlc --doctorもこのレイヤーです。 - ネイティブCLI（シェルで打つ）:
aidlc engine plugin sync、aidlc engine plugin list、aidlc engine plugin selectのように、aidlcのengine名前空間配下で実行します。aidlc plugin syncのようなスラッシュ無しのトップレベル形は存在しないので注意してください（installed-pluginのライフサイクルはengine名前空間に置かれています）。
インストール方法がネイティブの
aidlc コマンド（bun 不要のバイナリ）に一本化された関係で、シェルから叩く場合は必ず aidlc engine plugin ... の形になります。以降、シェルで実行するものは aidlc engine plugin ...、チャット内で確認するものは /aidlc plugin ... と書き分けます。dist を作る（ビルド）
配布の第一歩は、プラグインのソースからハーネスごとの「実プラグイン」を生成することです。これはフレームワーク本体と同じパッケージャで行います。
1
bun scripts/package.tsパッケージャは
plugins/<name>/（.aidlc-plugin/plugin.json を持つディレクトリ）を自動で発見し、ハーネスごとの実プラグインを dist/plugins/<name>/<harness>/ に出力します。出力には、ホストネイティブのマニフェスト（.claude-plugin/・.codex-plugin/・.kiro-plugin/ など）、marketplace.json、合成フック（hooks/aidlc-plugin-compose.ts）、そしてプラグインの中身（ステージ・エージェント・スコープ・センサー・貢献など）が含まれます。出力後は、意図せぬ手編集が入っていないかをドリフトガードで確認できます。
1
bun scripts/package.ts --checkこれで
dist/plugins/<name>/<harness>/ が揃いました。ここからが配置です。dist を作ったあと、どう配置するか
dist/plugins/<name>/<harness>/ ができたら、次はそれをプロジェクトに配置します。ここもハーネスによって手順が分かれます。大きく言えば、Claude Code と Codex CLI はホストのプラグインストアでインストールし、以降の合成は SessionStart フックが自動で走ります。一方 Kiro はストアが無いため、フォルダに配置し、合成は手動で実行します。Claude Code / Codex CLI（ストア経由） は、フォルダにコピーするのではなく、ホストのプラグインコマンドで登録します。emit されたディレクトリを marketplace として追加し、install します。
1
2
3
4
5
6
7
8
9
# Claude Code（セッション内で実行）
/plugin marketplace add <repo-or-path>/dist/plugins/<name>/claude
/plugin install aidlc-<name>@aidlc-plugins
# → 次のセッション開始時に SessionStart フックが自動で合成する
# Codex CLI（gitリポジトリ内で実行）
codex plugin marketplace add <…>/dist/plugins/<name>/codex
codex plugin add aidlc-<name>@aidlc-plugins
# → 一度きりのフックのトラストプロンプトを承認する合成は SessionStart フックが自動で走らせるので、手動での合成コマンドは要りません。これらホストストア経由の導入コマンドは、ハーネス（Claude Code / Codex CLI）がネイティブに持つ仕組みで、AI-DLC側のインストール方式の変更による影響は受けません。
Kiro（ストアなし → フォルダに配置後、合成を明示実行） は、emit されたツリーをプロジェクトにコピーし、合成コマンドを手動で実行します。これが「フォルダに配置する」方式の実体です。合成には、プラグインの場所（
AIDLC_PLUGIN_ROOT）、配置先プロジェクト（AIDLC_PROJECT_DIR）、ハーネスのディレクトリ（AIDLC_HARNESS_DIR）を環境変数で渡します。1
2
3
4
5
6
7
8
9
# PLUGIN_ROOT = emit された Kiro 向けディレクトリ（hooks/compose.ts とプラグイン中身を含む）
# <project> = .kiro を配置してある自分のプロジェクト
PLUGIN_ROOT="$(pwd)/dist/plugins/<name>/kiro"
# 1. プロジェクトにコピー(フォルダに配置)
cp -r "$PLUGIN_ROOT"/. <project>/
# 2. 合成を明示実行（aidlc が PATH にある場合の推奨）
AIDLC_PLUGIN_ROOT="$PLUGIN_ROOT" AIDLC_PROJECT_DIR="./" AIDLC_HARNESS_DIR=.kiro aidlc engine plugin sync合成コマンドが内部で何をしているのかも押さえておくと安心です。
aidlc engine plugin sync（および aidlc-plugin-compose.ts）は、(1) プラグインの新規ファイル（ステージ・エージェント・スコープなど）をコピーし、(2) 貢献（contribution）を既存ステージのソースへマージし、(3) 最後に aidlc-graph compile を実行して stage-graph.json と scope-grid.json を再生成します。orchestrator はこの 2 つのコンパイル済みファイルだけを見てルーティングするため、合成が終わった瞬間からプラグインのステージやスコープがそのまま plan に乗ります。プロース（skill）の編集は要りません。この再コンパイルは合成の一部として自動で走るので、通常はユーザーが手で aidlc-graph compile を叩く必要はありません（合成はステージソースを書き換えるため、後で別の理由で再コンパイルしても貢献は消えず、再合成しても二重には積まれない＝冪等です）。配置と合成が終わったら、
/aidlc plugin list（セッション内）で有効なプラグイン一覧を、/aidlc --doctor（セッション内）で有効プラグイン数やステージ数を確認できます。なお、
harness.json に plugins キーで選択集合がすでにある場合、合成しただけでは自動で有効化されません（ファイルはコピーされますが、無効のままです）。その場合は明示的に選択します（シェルから叩く場合は engine名前空間）。1
aidlc engine plugin select aidlc,<name>そして選択です。ここでも「プラグインは足す、インストール側が選ぶ」が効きます。有効なプラグイン集合は
<harness-dir>/tools/data/harness.json の plugins キーで決まり、シェルからは aidlc engine plugin list で確認、aidlc engine plugin select で変更できます（チャット内なら /aidlc plugin list / /aidlc plugin select）。着脱の性質にも触れておきます。プラグインを無効にすると、そのプラグインが
core ステージに足した貢献も一緒に剥がれます。自分のファイルだけが消えるのではありません。だからこそ、すべてを無効にすれば素の core とバイト単位で同一に戻ります。トラスト（信頼）はホストネイティブです。Claude は管理者が設定する許可リスト（
れてください。
strictKnownMarketplaces、利用者は上書き不可）、Codex は内容ハッシュで固定される一度きりのトラストプロンプトで守られます。Kiro はストアが無く、フォルダへの配置そのものが信頼の判断になります。配置した瞬間にフックが動くため、コードを実行してよいと判断できる出所からだけ入れてください。
エンジンのアップグレード後は再合成を。 ネイティブのaidlc updateやaidlc configはエンジンとグラフのファイルを更新するため、プラグインがcoreステージに足した貢献が一時的に剥がれます。プラグインを使うプロジェクトでは、アップグレードのたびに/aidlc plugin sync（セッション内）またはaidlc engine plugin sync（シェル）で再合成してください。合成は冪等なので、同じ状態が二重積みなく復元されます。状態は/aidlc --doctor（aidlc doctor）が「Composed plugin surface」として報告します。
8. まとめ
この記事では、カスタマイズをプラグインとして束ねる流れを見てきました。
coreは不変: プラグインはcore/を一切編集しない。追加物はすべてプラグイン自身のツリーの中にある- 追加のみ（strict-additive）: 既存フィールドの上書きや削除、手順文の置換はできない。貢献も集合和で重なる
- オフで無効: すべてのプラグインを無効にすれば、インストールは素の
coreとバイト単位で同一に戻る - ホストネイティブ配布: 配布・トラスト・合成はハーネス（Claude Code / Codex / Kiro）の標準の仕組みに乗る
- コマンドは2レイヤー: チャット内は
/aidlc plugin ...、シェルはaidlc engine plugin ...（スラッシュ無しのaidlc plugin ...は無い） - slugが同一性、番号は表示のみ: グラフ上の位置は
requires_stageで決まり、挿入してもcoreの番号は振り直されない
ステージやエージェントをプラグインとして束ねれば、同じ「ステージを足す・エージェントを足す」でも、配布と着脱ができる形で配れます。
core/を直接編集するアプローチが「常時オンの土台変更」なのに対し、プラグインは「任意で着脱できる束」です。どちらを選ぶかは、その追加を自分たちだけで使うのか、配って使い分けたいのかで決めるとよいでしょう。Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 23AI-DLC Workflow V2のPlugin: core/を変えず、現場に合わせてステージとエージェントを足す 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