新規variantの作成 vs 既存プロジェクトをバリアント(variant)へ昇格させる

第6章§2では、co-retailという新規バリアント(variant)を最初からスキャフォールディングする過程を実習した。しかし、ai-workspace-standardsにはこれとは性質の異なるもう一つの経路がある。すでに問題なく動いており、テンプレートにするつもりなど全くなく始めたプロジェクトを、後になって正式なバリアント(variant)へと「昇格」させる経路である。本章では、この二つの経路が概念的にどう異なるのか、そしてどのような状況でどちらを選ぶべきかを扱う。

出典: ai-workspace-standards (GitHub)

二つの経路の違い

新しいバリアント(variant)をワークスペースに追加する方法は一つではない。ai-workspace-standardsは二つの異なる出発点を認めている。一つは「まだどのプロジェクトも存在しない状態から、最初からテンプレートになることを念頭に置いて設計する」経路である。もう一つは「元々テンプレートにするつもりなど全くなく始めたプロジェクトが、時間が経つにつれて複数のチームが手作業でコピーして使うほど実証された後になって、テンプレートへと昇格する」経路である。

この二つの違いは、単に「コマンドが違う」というレベルの話ではない。前者は設計が先で使用が後であり、後者は使用（そして検証）が先でテンプレート化が後である。ワークスペースがこの両方の経路をサポートしている理由は、新しいドメインのエージェントチームを作る実際の状況が、この二つの形のいずれかに収束するためである。

最初から作る経路

グリーンフィールドの状態から始まるこの経路は、二つの段階に分かれる。まずcreate-variantスキルとbun scripts/create-l3-scaffold.ts <variant-name> --domain <type> [--country <CODE>]により、Projects/<variant-name>/配下に独立した「Phase Aプロトタイプ」を作る。この段階は、ワークスペースのドキュメントで「L1-L2 Fork Model」と呼ばれる構造の一部であり、まだ正式なtemplates/に属していないため、自由に実験し方向を変えることができる。第11章の実習（D-1）で作るco-retailプロトタイプは、まさにこのPhase A段階に該当する。この実習は第6章§2の実習（D-1）を参照する。

プロトタイプが十分に成熟すると、promote-variantスキルを通じて「Phase B昇格」を経て、正式なtemplates/co-<name>/となる。つまり、最初から作る経路も結局は昇格の段階を通過する。ただし、そのプロトタイプ自体が最初からテンプレートになることを前提に設計されている点が、次節の経路と区別される点である。

スキャフォールディングコマンドはオプションの--countryフラグも受け付ける（例: --country KR）。カントリープロファイル機構は、DART照会や法令検索のように特定国のデータ体系にアクセスするスキルを国コードでスコーピングし、k-dart・k-law・k-kosisといったKR共通スキルを--country KRプロジェクトにだけ注入する。KOSIS_API_KEYのような認証情報も国スコープの資産として分類され、該当プロジェクトにのみ配布される。設計の根拠はワークスペース文書のADR-0057とADR-0058に、実際のプロファイル定義は各プロジェクトのdocs/countries/KR.mdに文書化されている。

既存プロジェクトを昇格させる経路

二つ目の経路は出発点そのものが異なる。あるチームが特定のドメインの課題を解決するためにプロジェクトを一つ作ったが、そのプロジェクトは他のテンプレートを原型にもしておらず、そもそも再利用を念頭に置いてもいなかった。ところが時間が経つにつれ、そのプロジェクトの構成があまりにうまく機能しているため、社内の他のチームがファイルを手作業でコピーして似たようなものを作り始める。このような「すでに実証されているが、テンプレートとして生まれたわけではない」プロジェクトを正式なバリアント(variant)へと転換することが、昇格の目的である。

この経路も結局は同じpromote-variantスキルとbun scripts/l3-to-variant-pipeline.ts --l3-path=Projects/<name> --name=co-<name> --type=<type> --description="<説明>"パイプラインを使用するという点で、最初から作る経路のPhase Bとメカニズムは同じである。--descriptionと、オプションフラグの--version（デフォルト0.1.0）、--status（デフォルトbeta）は、昇格結果のtemplates/<name>/variant.jsonに直接書き込まれる。昇格前にはPROMOTION_CHECKLIST.mdの条件（bun run agent:verify、bun scripts/validate-skills.ts、bun scripts/audit.tsの合格可否など）をすべて満たさなければならないというゲートがある。パイプライン実行後は、variant.jsonのinherits_commonバージョンの確認、共通ファイルと重複する部分を取り除く「reconcile」段階、そして.claude/・.gemini/・.agents/の3プラットフォーム（Claude/Gemini/Antigravity）間のプラットフォームパリティ検証が続く。このパイプラインが自動で処理できないドメイン固有のディレクトリ（例: workflows/、regulations/など）は、_ORIGIN.mdが指定した通りに手動で移す必要がある。

「reconcile」と「_ORIGIN.mdによる手動移管」が実際に何をするのか、具体例で見てみよう。財務チームが作ったProjects/budget-review/を昇格させるとすると、このプロジェクトには二種類のファイルが混在している。①PM定義やセッションチェックリストのようにtemplates/common/にすでに存在する共通ファイルをそのままコピーしてきたもの、②regulations/フォルダ内の社内会計規程文書のように、このプロジェクト固有の資産。reconcile段階は①に該当するファイルを「コピー」から「共通ファイルを継承する参照」へと戻し、後でtemplates/common/が更新された際にこのvariantも一緒に最新化されるようにする。一方②はパイプラインがその存在自体を知る手立てがないため、元のプロジェクトに残された_ORIGIN.mdの「Manual Phase B Steps」リストに「regulations/フォルダを新規バリアント(variant)へ手動でコピーすること」のように明記しておき、昇格担当者がチェックリストを見ながら一つずつ手作業で移す。

どちらの経路をいつ選ぶか

結局のところ、選択の基準は一つに要約される。参考にできる先例が全くない新しいドメインであれば、最初から設計する経路が自然である。逆に、組織内にすでに一度以上検証され、皆が真似して使っているプロジェクトがあるなら、その実証済みの成果を尊重して昇格経路で正式化する方がより安全で効率的である。両方の経路とも最終的には同じtemplates/co-<name>/という形に収束するという点で、これは「どの山に登るか」の問題であって、「別の山に到着するか」の問題ではない。