ai-workspace-standardsを探索する

ai-workspace-standardsリポジトリの構造と核心概念を学びます。4レベルレイヤー構造（L0→L1→L2→L3）、バリアント（variant）の概念、主要ファイル（AGENTS.md、CLAUDE.md、GEMINI.md）の役割、そして共通コントラクトを理解します。

ai-workspace-standardsとは

定義

ai-workspace-standardsは、Claude CodeやAntigravity CLIのようなAIコーディングツールを活用して複数のAIエージェントが協力するプロジェクトを作るときに必要なオープンソース標準テンプレートです。GitHubで無料公開されており、誰でもコピーして自分のプロジェクトに適用できます。

• GitHubリポジトリ: github.com/5throck/ai-workspace-standards
• ライセンス: オープンソース（誰でも自由に使用・修正・配布可能）
• 対応プラットフォーム: Claude Code、Antigravity CLI（両プラットフォームとも同じ構造を使用）

なぜ標準が必要なのか？

プロジェクトごとにAIエージェントの定義方法や管理方法が異なると、さまざまな問題が発生します。標準テンプレートが必要な理由は次のとおりです。

• 一貫性 — すべてのプロジェクトが同じ構造に従えば、新しいプロジェクトに加わったチームメンバーも即座に理解できます。ファイルの場所、エージェントの定義方式、ルールがすべて同じだからです。
• 再利用性 — 一度作ったエージェントやスキルを別のプロジェクトでもそのまま使えます。似た作業をいちいちゼロから定義する必要がありません。
• 協業 — 複数人で一緒に作業するとき、共通の「言語」と「ルール」があればコミュニケーションエラーが減り、効率よく協力できます。
• 品質保証 — 自動検証スクリプト（audit、validate）が標準構造をもとに動作するため、ルール違反を早期に発見できます。

初心者向けの例え：組織図と業務マニュアルのテンプレート

ai-workspace-standardsを理解するには会社に例えるのが良いでしょう。会社を設立するには組織図（誰がどんな役割を担うか）と業務マニュアル（各自がどう働くべきか）が必要です。ai-workspace-standardsはまさにこの組織図と業務マニュアルのテンプレートです。このテンプレートをコピーして自分の会社（プロジェクト）に合わせて修正すれば、最初から完全な組織体系を整えられます。

ディレクトリ構造

ai-workspace-standardsリポジトリは規則的なディレクトリ構造を持っています。各フォルダが明確な役割を担っているため、構造を見るだけでプロジェクトがどう構成されているのか一目で把握できます。

最上位ディレクトリの概要

memory/ フォルダ

最上位にはmemory/フォルダもあります。このフォルダはAIセッションの記録、議事録、作業ログなどを保存する場所です。PMエージェントが各セッションの進捗と意思決定の記録をmemory/YYYY-MM-DD.mdファイルとして残します。こうすることで、前回のセッションで何をしたのかを次のセッションでも把握できます。

ルートファイル群

最上位ディレクトリにはフォルダ以外にも重要なファイルがあります。AGENTS.md（エージェントレジストリ）、CLAUDE.md（Claude Code用の指示）、GEMINI.md（Antigravity CLI用の指示）、CHANGELOG.md（変更履歴）が、いずれもプロジェクトのルートに置かれています。これらのファイルは本章の「主要ファイル」セクションで詳しく扱います。

主要ファイル

ai-workspace-standardsの主要ファイルはプロジェクトのルートに位置し、それぞれ明確な役割を果たします。このセクションでは最も重要な5つのファイルを説明します。

AGENTS.md — エージェントレジストリ

AGENTS.mdは、プロジェクトに属するすべてのAIエージェントの定義、役割、Tier、ディスパッチトリガーを登録する「公式名簿」です。このファイルを開くと表形式ですべてのエージェントが並んでおり、各エージェントの詳細定義ファイル（agents/pm.md、agents/research.mdなど）へのリンクが付いています。

AGENTS.mdには次の情報が含まれます。

• エージェントロスター — 全エージェントの名前、ファイルの場所、Tier（優先度）、役割
• PM Gatewayワークフロー — PMがどうエージェントを派遣するかのルール
• ディスパッチトリガー — どんな状況でどのエージェントを呼び出すべきか
• 実行計画テンプレート — 作業を計画するときに使う標準形式

初心者向けの例え：AGENTS.mdは会社の「社員名簿」です。社員名簿には各社員の名前、職級（Tier）、担当業務が書かれています。同様にAGENTS.mdには各AIエージェントの名前、等級、役割が明確に定義されています。

CLAUDE.md — Claude Code用の行動指針

CLAUDE.mdは、Claude Code（AnthropicのAIコーディングツール）がプロジェクト内で動作するときに従うべき行動指針です。Claudeがどんなエージェント役割を担えるか、どんなツールを使ってよいか、どんなルールを守るべきかが詳しく記述されています。

CLAUDE.mdの核心内容は次のとおりです。

• エージェントディスパッチルール — PMがどんな状況でどのエージェントを送るか
• 3-Tier戦略 — High/Medium/Lowモデルをいつ使うか
• ゲートプロトコル — ユーザーの承認が必要な段階と自動進行する段階
• ツール使用権限 — 各エージェントが使えるツールの範囲

初心者向けの例え：CLAUDE.mdはClaudeに渡す「業務指示書」です。「こんな仕事が入ったらこの担当者に回せ」「この段階では必ず管理者の承認を得よ」と書かれたマニュアルのようなものです。

GEMINI.md — Antigravity CLI用の行動指針

GEMINI.mdはAntigravity CLI（GoogleのAIコーディングツール）用の行動指針です。内容と構造はCLAUDE.mdと同じ役割を果たし、違うのはClaude Codeの代わりにAntigravity CLIを使うときに適用されるという点だけです。

なぜ2つのファイルが別々に存在するのでしょうか。Claude CodeとAntigravity CLIはそれぞれ別の会社が作ったツールであるため、モデル名、ツール呼び出し方式、システムプロンプト形式が異なります。しかしエージェント構造、ワークフロー、ゲートルールはまったく同じです。したがってCLAUDE.mdとGEMINI.mdは「同じルール、別のツール設定」と理解すればよいのです。

CHANGELOG.md — 変更履歴の記録

CHANGELOG.mdはプロジェクトのすべての変更を時系列で記録するファイルです。新しいエージェントが追加されたり、スキルが修正されたり、ルールが変わったりするたびにここに記録されます。バージョン管理システム（Git）のコミットログと違い、CHANGELOGは人が読める形で変更内容を要約します。

context.md（docs/ フォルダ内）— L2/L3プロジェクトの高度な設定

docs/context.mdは、L2 variantテンプレートおよびL3プロジェクトにのみ存在する高度な設定ファイルです。ワークスペースルート（L0）にはなく、L0のSSOTはAGENTS.mdです。主な内容は次のとおりです。

• L0 → L1 → L2 → L3レイヤー構造の具体的な定義
• エージェントファイルのfrontmatter仕様
• ライフサイクル管理手順
• ガバナンス文書の構造

このファイルは「システム設定」に近いため、初心者のうちは中身を完全に理解していなくても大丈夫です。プロジェクトを運営しながら徐々に深く参照するようになります。

主要ファイルの比較

4レベルレイヤー構造

ai-workspace-standardsの最も重要な設計原則の一つが4レベルレイヤー構造です。ワークスペースの資源が元ソース（L0）を出発点として、共通インフラ（L1）、variantテンプレート（L2）、実際のプロジェクト（L3）へと伝わっていく階層構造です。

L0 Source (Workspace Root) — 元ソース

L0 Sourceはワークスペースのルートディレクトリそのものです。すべてのエージェント、スキル、スクリプトが書かれる唯一の編集場所であり、変更が他のすべてのレイヤーへ伝わる出発点です。

• 共通エージェント — PMエージェントなど全プロジェクトが使う基本エージェント
• 共通スキル — どこでも再利用できる基本スキル
• コアスクリプト — audit.ts、validate-templates.tsなどの核となる自動化ツール
• AGENTS.md — グローバルなエージェントレジストリ

L1 (Common Template) — 共通インフラ層

L1はtemplates/common/にある共通インフラ層です。L0 Sourceから配布された内容をもとに、すべてのバリアントが共有するテンプレートを提供します。プラットフォーム別設定と標準ディレクトリ構造が含まれます。

• .claude/ ディレクトリ — Claude Code用の設定、コマンド、スキル
• .gemini/ ディレクトリ — Antigravity CLI用の設定、コマンド、スキル
• プラットフォーム別エージェント設定（CLAUDE.md、GEMINI.md）
• 共通エージェントテンプレート、共通スキル、スクリプト
• propagation-map.json — L0→L1配布ルールの定義

参考：L1は直接編集しません。L0 Sourceからbun run propagate:applyを通じて変更が自動的に配布されます。

L2 (Variant Template) — バリアントテンプレート層

L2はtemplates/co-*/にあるバリアントテンプレート層です。各バリアント（co-deck、co-consultなど）はL1をベースに独自のエージェント、スキル、設定を追加したテンプレートです。

• バリアント専用エージェント（例：co-deckのimage-curator、pdf-export）
• バリアント専用スキル（例：co-deckのhtml-build、storyline）
• バリアント設定（variant.json、PMエージェントのYAMLオーバーライド）
• L1共通テンプレートの継承（variant.jsonのinherits_common: "templates/common"）

現在11個のバリアントテンプレートが存在します：co-abap、co-consult、co-deck、co-design、co-develop、co-export、co-game、co-hr、co-news、co-security、co-work。

L3 (Project) — 実プロジェクト層

L3はProjects/*/にある実プロジェクト層です。L2 variantテンプレートをもとにスキャフォールディング（scaffolding）された個別プロジェクトです。各プロジェクトは独立して運営され、ローカルでのカスタマイズが可能です。

• docs/context.md — プロジェクトの高度な設定（プロジェクト生成後は不変）
• プロジェクト専用のエージェント、スキル、スクリプト
• variant.json — L2からコピーされたメタデータ
• 実際の作業成果物が生まれる空間

配布経路とレイヤー構造

このシステムでは2つの方向を区別することが重要です。

• 配布経路（L0 → L1 → L2）: 元ソース（L0）の変更がpropagate:applyを通じてL1共通テンプレートへ、さらに各L2バリアントテンプレートへと伝わる方向です。これがコードが流れる方向です。
• レイヤー構造（L1 → L2 → L3）: 各レイヤーが上位レイヤーのテンプレートを土台に構築される静的な階層関係です。L3プロジェクトはL2バリアントテンプレートからスキャフォールドされ、L2はL1共通テンプレートを継承します。

L2 → L3: 実際にプロジェクトを作る

上のダイアグラムの「スキャフォールド」矢印は、実際にはワークスペースルートでスクリプトを1つ実行することです。new-project.tsスクリプトが選択したL2バリアントテンプレート（templates/co-*/）を読み込み、Projects/<project-name>/以下に実際に動作するL3プロジェクトを生成します。

bun scripts/new-project.ts "my-project" --variant co-consult

このコマンドを実行すると、スクリプトが次の処理を自動的に行います。

• templates/co-consult/（L2）のエージェント、スキル、設定をProjects/my-project/へコピー
• templates/common/（L1）の共通インフラも一緒に適用
• variant.jsonをプロジェクトルートに配置し、プロジェクト名で更新
• docs/context.mdなどプロジェクト固有の設定ファイルを生成

--variantには、co-consultやco-deckを含む現在存在する11個のバリアントのうち1つを指定できます。第6章・第7章の実習で使うco-consult、co-deckの例は、別のリポジトリをクローンするのではなく、公開リポジトリai-workspace-standardsの中のtemplates/co-consult/、templates/co-deck/（L2）を上記のコマンドで直接スキャフォールドした結果物です。

上書きルール

下位レイヤーは上位レイヤーの設定を上書きできる一方、逆方向には影響を与えません。これはオブジェクト指向プログラミングのクラス継承と同じ原理です。

• L3で設定したルールは、L2、L1、L0のルールより優先されます。
• L2で設定したルールは、L1、L0のルールより優先されます（ただしL3で上書きされていない場合）。
• L1で設定したルールは、L0のルールより優先されます（ただしL2、L3で上書きされていない場合）。
• L0のルールは、どこでも上書きされなければ全レイヤーに適用されます。

バリアント（variant）の概念

バリアントとは何か？

バリアント（variant）は、ai-workspace-standardsのL0 + L1テンプレートをベースに、特定の用途に合わせてカスタマイズしたテンプレートです。先ほどの4レベルレイヤー構造で説明したL2がまさにバリアントテンプレートに該当し、L3はそのL2テンプレートをスキャフォールドして作った実プロジェクトです。

すべてのバリアントは同じ「骨格」（L0 + L1）を共有しますが、それぞれの目的に応じて異なるエージェント、スキル、設定を追加します。同じ自動車プラットフォームからセダン、SUV、スポーツカーなど多彩な派生モデルが作られるのと似ています。

バリアントの例

現在のai-workspace-standardsエコシステムには、次のようなバリアントがあります。

• co-consult — AIコンサルティング実習用バリアント。企業分析、戦略立案、報告書作成を自動化するエージェントチームを提供します。本ハンドブックの第6章で実習します。
• co-deck — プレゼンテーション自動化用バリアント。リサーチ → ストーリーライン → デザイン → HTMLビルド → PDF出力までの全パイプラインを自動化します。11段階のワークフローを提供します。

variant.json — バリアントのメタデータ

各バリアントはvariant.jsonファイルを通じて自らのメタデータを定義します。このファイルには次の情報が含まれます。

• 名前 — バリアントの識別子（例：「co-deck」「co-consult」）
• バージョン — バリアントの現在のバージョン（例：「1.0.0」）
• ステータス — draft、beta、stableなど現在の開発段階
• 依存関係 — 上位レベル（L0、L1）に対する依存関係
• 説明 — バリアントの用途と特徴

{
  "name": "co-deck",
  "description": "プレゼンテーション・講義資料制作バリアント",
  "variant_type": "lecture",
  "status": "beta",
  "version": "0.2.0",
  "inherits_common": "templates/common",
  "agents": [
    { "name": "pm",              "file": "agents/pm.md" },
    { "name": "research",         "file": "agents/research.md" },
    { "name": "storyline",       "file": "agents/storyline.md" },
    { "name": "html-build",      "file": "agents/html-build.md" }
  ]
}

variant.jsonは、バリアントをインストール・管理するときに参照される「身分証」のような役割を果たします。このファイルがあるおかげで、システムはどのバリアントなのか、どのバージョンなのか、どんな依存関係があるのかを把握できます。

バリアントのライフサイクル

バリアントは次のようなライフサイクルをたどります。

• draft — 初期開発段階。基本構造だけを備えた状態
• beta — テスト段階。主要機能は実装済みだが安定性の検証が必要
• stable — 安定段階。実際の使用に適している
• deprecated — 使用中止。もうメンテナンスされない

このライフサイクルはdocs/VERSION_MANIFEST.mdで中央管理されます。新しいバリアントを作るとdraftから始まり、十分なテストを経てstableへ昇格します。

バリアントから新規プロジェクトを作る

第6章・第7章の実習では時間を節約するため、あらかじめ作られたサンプルプロジェクト（co-consult、co-deck）をcloneして使います。しかし実際の日々の業務ではcloneをしません — ワークスペースルートからコマンド1行で、L2バリアントテンプレートからまったく新しいL3プロジェクトをスキャフォールディング（scaffolding）します。

bun scripts/new-project.ts "my-market-report" --variant co-consult

このコマンドはProjects/my-market-report/を独立した新しいGitリポジトリとして生成し、co-consultのエージェント・スキル・設定をコピーしたうえで、このプロジェクトだけの目標を書き込めるよう空のdocs/context.md骨格をレンダリングします。全構文は次のとおりです。

bun scripts/new-project.ts "<プロジェクト名>" --variant <variant> [--platform claude|antigravity|both] [--version X.Y.Z] [--country <CODE>]

• <プロジェクト名> — 必須。Projects/以下のフォルダ名になります。
• --variant <variant> — 必須。どのL2テンプレートからスキャフォールドするかを指定します（co-consult、co-deck、co-developなど）。
• --platform — 任意。どのプラットフォーム設定（.claude/、.gemini/）をコピーするか制限します。デフォルトはbothです。
• --version — 任意。元バリアントの現在バージョンの代わりに、特定のテンプレートバージョンを固定して使用します。
• --country <CODE> — 任意。韓国向けプロジェクトなら--country KRを指定してください。国プロファイルがk-dart・k-law・k-kosisのような韓国専用スキルとKR APIキー設定をプロジェクトに一緒に入れてくれます（詳細は別冊Dを参照）。

共通コントラクト

コントラクトとは何か？

コントラクト（Contract）は、エージェント、スキル、スクリプトがすべて守るべき共通ルールです。プログラミングにおける「インターフェース（Interface）」や「プロトコル（Protocol）」と同じ概念で、すべての参加者が同じ形式とルールに従うよう強制します。

初心者向けの例え：コントラクトは「共通言語」です。多言語話者が会議するとき、皆が同じ言語（例：英語）を使うと約束すれば円滑に意思疎通できます。同様に、すべてのエージェントが同じコントラクトに従えば、衝突なく協力できます。

ガバナンスコントラクト — どこに定義されているのか？

ガバナンスコントラクト（共通ルール）は単一のJSONファイルではなく、ワークスペースの核心的なガバナンス文書群に分散して定義されています。

• CONSTITUTION.md — ワークスペース全体のマスター共有標準。ガバナンスルール、PRワークフロー、マルチエージェントアーキテクチャの原則など
• AGENTS.md — L0（ワークスペースルート）のSSOT。エージェントレジストリ、PM Gatewayワークフロー、スキルロスターなど
• docs/context.md（L2/L3プロジェクト専用）— 各バリアントおよびプロジェクトの高度な設定。プロジェクトタイプ、ステータス、アーキテクチャ、主要ファイルなど

これらの文書は、エージェント、スキル、スクリプトがすべて守るべき共通ルールを定義します。プログラミングにおける「インターフェース（Interface）」や「プロトコル（Protocol）」と同じ概念で、すべての参加者が同じ形式とルールに従うよう強制します。

コントラクトの3つの役割

ガバナンスコントラクトは次の3つのコアな役割を果たします。

• 一貫性の保証 — すべてのプロジェクトが同じ形式を使うため、あるプロジェクトのファイルを別のプロジェクトでも即座に理解できます。エージェントファイルがどこにあるか、どのフィールドが必須かが分かります。
• 互換性の維持 — 新しいバリアントを作るとき、コントラクトに従うだけで既存ツール（audit、validate）と自動的に互換になります。別途の設定や変換過程は不要です。
• 自動検証が可能 — bun scripts/audit.tsなどのスクリプトがファイルを自動検査し、ルール違反を検知できます。人が一つひとつ確認する必要がありません。

コントラクトの適用手順

新しいエージェントやスキルを作るとき、コントラクトを適用する過程は次のとおりです。