第5章

ai-workspace-standards 紹介

第7章で見る「開発ツール + variant」モデルを実際に実装したリポジトリがai-workspace-standardsである。本章では、このリポジトリが正確には何であり、どのようなファイルで構成され、どのようなプロジェクトテンプレートを提供するのかを順を追って紹介する。

出典: ai-workspace-standards (GitHub), ADR-0031 L1–L2 Fork Model, CONSTITUTION.md §0 SSOT Architecture

この章で扱うこと
  • ai-workspace-standardsとは何か、なぜ「ワークスペースルート」としてクローンすべきなのか
  • リポジトリ全体のディレクトリ構造と、セッションが実際にどの順序でファイルを読み込み実行するか(ランタイムフロー)
  • CONSTITUTION.md、CLAUDE.md、GEMINI.md、AGENTS.md、4つの中核ファイルの役割
  • templates/配下にある11種のvariantがそれぞれどのドメイン向けなのか
  • セッション開始チェックリストとnew-project.tsのスキャフォールディングフローの概念図

リポジトリとは何か

ai-workspace-standardsは自らを「Vibe CodingとHarness Engineeringのためのマルチエージェントチーム運用方式」と紹介している。複数のAIコーディングツール(Claude Code/App、Antigravity CLI/Desktopなど)にわたって、同一の動作・ワークフロー・品質基準を適用するためのリポジトリである。

このリポジトリの使い方は少し独特だ。通常のライブラリのように1つのプロジェクトに従属させるのではなく、リポジトリ自体をワークスペースのルートとしてクローンして使う。WindowsではC:\git、macOS/Linuxでは~/gitのような場所がその例である。こうしておくことで、その配下に新規作成するすべてのプロジェクトが、ワークスペースの共有ルールを自動的に継承する。

ai-workspace-standardsは「完成したプロジェクト」ではなく「プロジェクトの作り方」を配布するリポジトリである。 — ワークスペースルートとしてクローンする理由

全体アーキテクチャを俯瞰する

以降の節で4つの中核ファイル、variant、L0→L1→L2を1つずつ掘り下げる前に、これらの要素が実際にリポジトリのどこにどのような名前で配置されているかをまず全体として把握しておくと、方向を見失わずに済む。ワークスペースルートをクローンすると、次のような最上位構造が得られる。

C:\git\  (ワークスペースルート = L0)
├── CONSTITUTION.md          ← §2: 何を守るべきか (マスター標準、L0原本)
├── CLAUDE.md                ← §2: Claude Code/Appでどう実行するか
├── GEMINI.md                ← §2: Antigravity CLI/Desktopでどう実行するか
├── AGENTS.md                ← §2: 誰がその作業を行うか (エージェントロスター、L0原本)
├── agents/                  ← §5: pm.mdなどエージェント定義の原本 (L0、ここでのみ編集)
│   └── pm.md
├── .claude/                 ← §2: Claude専用のコマンド・スキル (/sync、create-variantなど)
├── .gemini/                 ← §2: Antigravity専用のコマンド・スキル (同名で実装が異なる)
├── .agents/                 ← §2: ツール非依存のコマンド・スキル (AGENTS.md標準対応ツール向け)
├── scripts/                 ← §4·§5: new-project.ts、propagate-to-templates.tsなどの運用スクリプト
├── templates/                (L1 + 公式L2)
│   ├── common/              ← §5: L1 — L0のスナップショット、variant作成時の出発点
│   │   └── agents/pm.md     ← extends: ../../../agents/pm.md (L0参照 + ワークスペース専用セクションを除去)
│   ├── co-develop/          ← §3: L2公式variant (ソフトウェア開発、6段階)
│   ├── co-design/           ← §3: L2公式variant (UI/UX、5段階)
│   ├── co-work/             ← §3: L2公式variant (協業/ドキュメント、6段階)
│   ├── co-security/         ← §3: L2公式variant (レッドチーム、6段階)
│   ├── co-consult/          ← §3: L2公式variant (コンサルティング、7段階)
│   ├── co-deck/   [beta]    ← §3: L2公式variant (講義/プレゼン、11段階)
│   ├── co-game/             ← §3: L2公式variant (ゲーム開発)
│   ├── co-export/ [beta]    ← §3: L2公式variant (輸出入貿易コンサルティング)
│   ├── co-hr/     [beta]    ← §3: L2公式variant (人事・労務コンプライアンス)
│   ├── co-news/   [beta]    ← §3: L2公式variant (金融ジャーナリズム)
│   ├── co-abap/             ← §3: L2公式variant (SAP ABAP開発)
├── Projects/                 (L3 — new-project.tsでスキャフォールディングされた稼働中のプロジェクト作業ディレクトリ)
│   └── <my-project>/
│       ├── docs/context.md  ← §4: このプロジェクトの設定文書 (variantの空の骨格を埋めたもの)
│       ├── agents/          ← variantから継承し、このプロジェクト専用として進化を続ける
│       └── (独立したgitリポジトリ — ワークスペースルートとは別)
└── memory/
    └── YYYY-MM-DD.md            ← §4: セッション間で引き継がれるコンテキスト記録

このツリーで注目すべきは、4つの層が実際のディレクトリ構造としてそのまま現れている点である。ルート直下(CONSTITUTION.md・CLAUDE.md・GEMINI.md・AGENTS.md・agents/・scripts/)がL0であり、templates/common/がL1、templates/co-*/がL2、開発者が日常的に作業する実際のプロジェクト作業ディレクトリであるProjects/*/がL3である。つまり「L0→L1→L2→L3」は抽象的な概念図ではなく、クローンしたフォルダでlsを一度打つだけで見える物理的な配置なのである。

この構造の上で実際に作業が進行する順序(ランタイムフロー)は次のとおりである。

  1. セッション開始。 エージェントはCONSTITUTION.md → 現在のプロジェクトのdocs/context.md（プロジェクト設定） → AGENTS.md（エージェントロスター） → memory/YYYY-MM-DD.mdの順に読み込む(§4で扱う)。
  2. ツール別の実行規則を適用。 Claude Code/AppであればCLAUDE.mdと.claude/が、Antigravity系であればGEMINI.mdと.gemini/が詳細な実行方式を定める。
  3. 新規プロジェクトが必要な場合。 scripts/new-project.tsがtemplates/co-<variant>/(L2)の構成全体をProjects/<name>/に複製し、L3のプロジェクト作業ディレクトリを作成する。このときtemplates/co-<variant>/自体は、一世代前にtemplates/common/(L1)からスナップショットを受け取って作られた状態だった。
  4. 運用中にL0が変更された場合。 scripts/propagate-to-templates.tsが/syncパイプラインの一部として、L0の変更をL1(templates/common/)に自動的かつ継続的に発行する。すでに生まれたL2やL3には自動的には伝播しない。これが第8章で扱う「フォーク」原則である。
一言で言えば: L0は「ルート直下」、L1は「templates/common/」、L2は「templates/co-*/」、L3は「Projects/*/、実際のプロジェクト作業ディレクトリ」 — この4つの座標さえ覚えておけば、以降の節のすべての説明を実際のフォルダ位置に対応させながら追うことができる。

4つの中核ファイル

ワークスペースルートには、すべてのプロジェクトが共通して参照する4つの中核ファイルがある。

CONSTITUTION.mdはマスター共有標準であり、セッション開始時に最初に読むべき文書である。ワークスペース全体のガバナンスルール、PRワークフロー、マルチエージェントアーキテクチャの原則がここに定義されている。CLAUDE.mdはClaude Code/Appでの具体的な動作方式(フック、スラッシュコマンド、エージェントディスパッチ規則)を、GEMINI.mdはAntigravity CLI/Desktopでの同等の動作を定義する。AGENTS.mdはワークスペース全体で利用可能なエージェント群の正本目録(ロスター)としての役割を果たす。このファイル名は、第2章で紹介したClaude Codeをはじめとする30以上のツールが共通して読み込む開放型AGENTS.md標準と同じである。ただしこのリポジトリでは、「エージェントレジストリ兼オーケストレーションリファレンス」というより具体的な役割まで兼ねている。ファイルの冒頭に「このファイルはAIツールへの指示文ではなく、人間が定義した複数の役割の登録簿である」と明記されているほどだ。

この4つのファイルの関係を一文でまとめると、CONSTITUTION.mdが「何を守るべきか」を定義し、CLAUDE.md/GEMINI.mdは「それを各プラットフォームでどう実行するか」を、AGENTS.mdは「誰がその作業を行うか」を定義している。

AGENTS.mdのエージェント項目は次のようなフィールドで構成される。具体的な作成ガイドとツール別の実装マッピングは第8章§3 AGENTS.md深掘りで扱う。

フィールド意味必須例
## Agent: {名前}エージェント識別子必須## Agent: reviewer
役割このエージェントが何をするか必須「テキストファイルの誤字脱字をレビューする」
入力どのような入力を受け取るか推奨「レビュー対象のテキストファイルパス」
出力どのような出力を出すか推奨「誤字脱字・不備・改善点のリスト」
権限ファイルアクセス範囲推奨「読み取り専用」/「書き込み許可 — 指定ファイルのみ」
handoff_to完了後に引き継ぐ対象任意handoff_to: reviewer

具体的な規則を1つ例にとって、この関係をたどってみよう。「PRのタイトルと本文は必ず英語で書く」という規則があるとすると、この規則自体はCONSTITUTION.mdに一度だけ記載される。CLAUDE.mdはこの規則をClaude Codeでどのように強制するかを定義する。例えば、/syncコマンドの言語ゲート(language-guard.ts)がコミット前にこの規則を自動的にチェックするよう明示する形だ。GEMINI.mdは同じ規則をAntigravity側のパイプラインで強制する方法を定義する。そして、この検査を実際に実行するのが「誰」なのか、すなわちどのエージェントがこのゲートを担当するのかはAGENTS.mdのロスターに登録されている。1つの規則が4つのファイルにそれぞれ異なる角度で現れるわけだ。これは重複ではなく、「何を・どのように・誰が」という3つの問いに対するそれぞれ異なる答えである。

4つのファイルの下には、実行可能な資産を格納するフォルダがある。コマンド・スキルは3か所に分かれており、.claude/はClaude Code/App専用、.gemini/はAntigravity CLI/Desktop専用、そして.agents/はどれか1つのツールに縛られないツール非依存(engine-agnostic)のコマンド・スキルを格納する。例えば/sync・/meetingのようなスラッシュコマンドやcreate-variant・audit-workspaceのようなスキルは3つのフォルダすべてに同じ名前で存在するが、それぞれ自プラットフォームのツール規則(Claude CodeのAgentツール構文、Antigravityのサブエージェント方式など)に合わせて実装が少しずつ異なる。AGENTS.md標準に対応する外部ツール(Codex、Cursorなど)がこのリポジトリを開くと、.agents/フォルダを参照することになる。

templatesと11種のvariant

templates/ディレクトリは、バージョン管理されたプロジェクトテンプレート「variant」の集合である。各バリアント(variant)は特定のドメイン向けの完結したマルチエージェントチーム構成を持つ。PM、専門エージェント群、段階的なガバナンスパイプラインがここに含まれる。リポジトリが提供するバリアント(variant)は次のとおりである。

co-developソフトウェア開発向け。PM・Architect・Designer・Code Writer・Test Runner・Security Monitorで構成される6段階のガバナンスパイプライン。
co-designUI/UX向け。Design Lead・UX Researcher・Visual Designer・Prototype Engineerなどによる5段階の反復ワークフロー。
co-work一般的な協業/ドキュメント作業向け。Analyst・Technical Writer・Content Writerなどによる6段階の非同期ワークフロー。
co-securityレッドチーム/ペネトレーションテスト向け。Red Team Lead・Pentester・Threat Modelerなどによる6段階のパイプライン。
co-consult戦略コンサルティング向け。PM(Engagement Leader)が指揮する7段階(Phase 0〜6)のワークフロー。Strategy Analyst・Change Management Partner・Industry Expert・SMEなど10名の専門エージェントで構成される。市場分析 → 組織診断 → 相互検証(Phase 1.5) → 提案承認ゲート(Phase 2) → 実務ソリューション設計 → 納品 → PR/引き渡しまで、コンサルティングプロジェクトの全工程を扱う。
co-deck beta講義・プレゼン資料制作向け。PMが指揮する11段階(Stage 0〜11)のパイプライン。Research → Source Verifier(信頼性検証) → Storyline → Design → Image Curation + Diagram Generation(並列) → HTML Build → Layout Measure → PDF Exportまで、リサーチから印刷用PDF出力までの全工程を自動化する。5種のテーマ(outline、pitch、pitch-enhanced、vertical、zen)と5種のスタイル(premium-dark、classic、minimal、visual-heavy、academic)をサポートする。
co-gameHTML5 Canvasゲーム開発向け。
co-export beta輸出入貿易コンサルティング向け。PMと8名の専門エージェント — HS Classification Specialist、FTA Origin Analyst、Customs Duty Drawback Specialist、Export Control Compliance Specialist、Trade Documentation Specialist、Logistics Coordinator、Foreign Regulatory Intelligence Analyst、Market Entry Strategist。
co-hr beta人事・労務関係向け。対象管轄の労働法コンプライアンス(国プロフィル対応)に加え、HRM/HRD、組織設計、変革マネジメントコンサルティングを扱う。
co-news beta上場企業を対象とする経済・金融ジャーナリズム向け。PM(編集長)と6名の専門エージェント — Financial Analyst、Legal Researcher、Fact-Checker、Reporter、Style Editor、Visual Editor。国プロフィルメカニズム(docs/countries/)により規制当局の財務開示情報と商法リサーチを統合し、ファクトチェック済みの記事を作成する — KRプロフィル適用時は韓国上場企業の開示情報(DART)など国スコープのデータを使用する。
co-abapSAP ABAP開発向け。

各バリアント(variant)はgitタグtemplate-vX.Y.Zでバージョン管理され、bun scripts/validate-templates.tsがエージェントfrontmatterの完全性、必須セクション、AGENTS.mdロスターとの整合性、.claude/・.gemini/間のプラットフォームパリティなど、構造的な規定遵守を検査する。

templates/という名前が示すとおり、このリポジトリが配布するものは結局のところボイラープレート(boilerplate)である。プロジェクトごとに毎回一から書き直す必要があったPMの役割定義、ガバナンスパイプライン、プラットフォーム別のコマンド・スキル配線をあらかじめ備えた出発点である。ただし「コピーして各自で勝手に直す」ありふれたボイラープレートとは異なり、このリポジトリはその出発点がどこから来て、どのように更新されるかまで階層構造として明示する。それが次節のL0 → L1 → L2 → L3である。

このボイラープレートがあらかじめ備えているものの1つがエージェントの役割別モデル割り当てである。variant内の各エージェント定義ファイル(agents/*.md)はfrontmatterにtierフィールドを持ち、この値はプラットフォーム別(claude/gemini/antigravity/gemini-cli)にhigh/medium/lowのいずれかを指定する。判断が重い役割(PM・Architect)にはhigh、実際の実装を担当する役割(code-writer・docs-writer)にはmedium、定型化された反復作業(automation-engineerなど)にはlowを割り当てる形だ。実際のmodelフィールドは通常inheritのまま残されるが、これは各プラットフォームが配布時点でこのtier値を自プラットフォームのモデルエイリアス(opus/sonnet/haiku)に変換して割り当てるためである。つまりボイラープレートを複製した瞬間、新しいプロジェクトは「誰がどのコストのモデルで働くか」まですでに決まった状態で始まる。

このティアリングがないと実際にどのような問題が生じるか。すべてのエージェントを画一的に最高性能モデル(high)に割り当てると、automation-engineerのように定型化されたスクリプト実行のみを繰り返す役割にも毎回不必要に高コストな推論コストがかかり、チーム全体の運用コストが無意味に膨らむ。逆に、すべてを最低コストモデル(low)に統一すると、PMのように複数のエージェントの成果物を総合して判断すべき役割が浅い推論しかできず、誤った調整判断を下すことが頻発する。ティアリングは「この役割が実際にどれだけ深い推論を必要とするか」に合わせて、コストと品質のバランスを役割単位であらかじめ整えておく仕組みである。

このモデルコストティア(high/medium/low)は、第8章で扱うL0 → L1 → L2 → L3の4層(ファイルがどこから来て、どのように流れるかについての階層)と、名前の「層」という感覚が同じだけで、互いに異なる概念である。一方は「エージェントにどのモデルを割り当てるか」であり、もう一方は「ファイルの原本がどこにあるか」である。

セッション開始チェックリストとスキャフォールディング

CONSTITUTION.mdは、すべてのセッション開始時に従うべき順序を定義する。まずgit config core.hooksPath .githooksでgitフックのパスを設定し、CONSTITUTION.md自体を読んだ後、作業中のプロジェクトのdocs/context.md（プロジェクト設定文書）を読む。続いてAGENTS.md（エージェントロスター）で利用可能なエージェントを確認し、memory/YYYY-MM-DD.mdに前回セッションの文脈が残っているかを点検した上で、docs/context.mdが指定するスキルを読み込む。

新規プロジェクトを作成する流れは概念的には単純である。bun scripts/new-project.tsスクリプトにプロジェクト名と希望するバリアント(variant)を指定して実行すると、そのバリアント(variant)の構成全体が複製され、完全に独立したgitリポジトリになる。このリポジトリはワークスペースルートとは分離されているが、生まれた時点からCONSTITUTION.mdの共有標準を継承した状態で始まる。チームはその中で、プロジェクト固有のdocs/context.mdとプロジェクトレベルのCLAUDE.md/GEMINI.mdオーバーライドを埋めながらチームを発展させていく。

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

このコマンドの完全な構文と全オプション(--platform、--version)は第6章§1・プロジェクトスキャフォールディングコマンドで実際に実習する。

L0 ワークスペースルート C:\git\ new-project.ts templates/co-consult/ L2テンプレート複製 AGENTS.md · CONSTITUTION.md · agents/ を含む 独立git初期化 Projects/my-project/ 独立リポジトリ

ここでCONSTITUTION.mdとcontext.mdの関係を明確にしておく必要がある。両方とも「セッション開始チェックリスト」で読む文書だが、SSOTの階層が異なる。CONSTITUTION.mdはL0(ワークスペースルート)にただ1つだけ存在し、すべてのプロジェクトが共有するルールを定義する。ガバナンス、PRワークフロー、マルチエージェントの原則がここに含まれる。一方、context.mdはL3(個別プロジェクト)ごとに別々に存在し、そのプロジェクト固有の目標・ドメイン知識・現在の進捗状況を格納するプロジェクト専用の設定文書である。CONSTITUTION.mdが上から強制されて埋められるファイルではなく、各プロジェクトチームが自ら書き進めていくファイルである点が異なる。だからチェックリストにも順序がある。CONSTITUTION.mdで「何を守るべきか(共通)」をまず確認した後、context.mdで「今このプロジェクトが何をしているか(個別)」を確認する。

ところで、templates/<variant>/docs/context.mdのように、variantの中にも同じ名前のファイルがある。これはL3プロジェクトのcontext.mdと名前だけが同じで役割は異なる。variant内のcontext.mdはまだ埋められていない空の骨格(プレースホルダー)であり、new-project.tsが実行される瞬間、他のL2→L3ファイルと同様に一度だけ複製される。複製された後は、原本(バリアント(variant)のcontext.md)との連結が完全に切れ、そのプロジェクトチームが実際の内容で埋めていく独立した文書になる。そのため、以降にバリアント(variant)のcontext.mdの骨格が変わっても、すでにスキャフォールディングされたプロジェクトのcontext.mdには自動的には反映されない。

ワークスペースルートのファイル(CONSTITUTION.md、CLAUDE.mdなど)と、スキャフォールディングされた個別プロジェクトのファイルは、それぞれ別のgitリポジトリに属する。両者を同じ作業の中で一緒に修正しないことが、このリポジトリの基本原則である。