AI Orchestra

Claude Code用のマルチエージェントオーケストレーションシステム

設計思想

AI Orchestra は AI コーディングの実行基盤を 3 つの層で組み立て、さらに「変更しても壊れない」ための整合性層を加えた 4 層で捉える。

層	役割	AI Orchestra での実体
Prompt	何を指示するか	facets（policies / instructions / output-contracts）から合成する Skill・Rule
Context	何を踏まえるか	CLAUDE.md / AGENTS.md テンプレート、config の階層上書き、.claude/context/ のセッション間共有
Harness	どう実行するか	hooks、agent-routing（30 エージェント）、packages 配布、外部 CLI（Codex / Antigravity）協調
Coherence（CoDD）	変更が入っても整合を保つ	packages/codd：各ドキュメントの codd: フロントマターで依存を宣言し、scan で依存グラフ構築・validate で不整合検出

最初の 3 層が「一度うまく動かす」ための基盤であるのに対し、CoDD（Coherence-Driven Development / 整合性駆動開発） は「要件や設計が変わったとき、波及先の成果物まで整合を保つ」ことを扱うレイヤー。AI Orchestra ではこれを独立パッケージ packages/codd（essential プリセット）として配布レールに載せ、導入先プロジェクトが生成するドキュメントまで整合性管理の対象にする。

CoDD の中核は次の 3 点:

• 依存グラフ構築 — ドキュメント先頭の codd: ブロックが依存を宣言し、scan がグラフ（.claude/codd/graph.jsonl）を組み立てる。
• 変更影響分析 — 上流を変更したとき、どの下流に波及するかをグラフから辿る（Phase 1 はドリフト検出として素朴に、信頼度スコアによる本格分析は Phase 2）。
• 整合性維持 — validate がリンク切れ・重複・循環・孤立・ドリフトを検出し、追従漏れをガードレールとして可視化する。

本節は CoDD の提唱記事 の概念を、AI Orchestra の用語（facet / hook / packages/codd・scan/validate）に合わせて再構成したもので、原文の転載ではない。実装の詳細は 整合性レイヤー設計 と 要件: 整合性ガードレール を参照。

コード⇔ドキュメントのトレーサビリティ（opt-in）

既定では scan の対象はドキュメントのみだが、.claude/config/codd/codd.yaml の code_scope.include（既定: 空 = 無効）にソースファイルの glob を追加すると、ファイル先頭の 1 行注釈からも依存を宣言できる。

# .claude/config/codd/codd.yaml
code_scope:
  include:
    - "packages/core/**/*.py"

"""
codd:implements design:codd-coherence-layer
codd:node_id code:my-module
"""

// 系言語（TS/JS/Go/Java/Rust/C 系。.mjs / .cjs を含む）はファイル先頭の連続する行コメントに同じ記法で書ける。コード注釈由来のリンクは既定 inline_confidence: 0.7（doc frontmatter の既定 1.0 より低い信頼度）として扱われ、codd impact の下流影響スコアに比例して弱く反映される。詳細は 整合性レイヤー設計 §4.3.1 を参照。

アーキテクチャ

Claude Code (Orchestrator)
    │
    ├── Codex CLI            # `cli-tools.yaml` の設定に応じて利用（役割は config-driven）
    ├── Antigravity CLI (agy) # `cli-tools.yaml` の設定に応じて利用（役割は config-driven）
    │
    ├── $AI_ORCHESTRA_DIR/packages/
    │   ├── core/                     # 共通ユーティリティ
    │   ├── audit/                    # 監査ログ・KPI・ダッシュボード
    │   ├── codex-suggestions/        # Codex 相談提案
    │   ├── codex-harness/            # Codex CLI 向け repo-local ハーネス（hooks/rules/schemas + 非対話 run/review）
    │   ├── antigravity-suggestions/  # Antigravity リサーチ提案
    │   ├── quality-gates/      # 品質ゲート
    │   ├── codd/              # ドキュメント整合性レイヤー（scan/validate）
    │   ├── docker-runtime/    # ハーネス共通 Docker/broker ライフサイクル
    │   ├── skill-evolution/   # スキル自己改善ループ（二軸テレメトリ + オフライン反復）
    │   └── git-workflow/     # Git/GitHub ワークフロー
    │
    └── 30 Specialized Agents
        ├── Planning: planner, researcher, requirements
        ├── Design: architect, api-designer, data-modeler, auth-designer, spec-writer
        ├── Implementation: frontend-dev, backend-*-dev, ai-*, debugger, tester
        └── Review: code-reviewer, security-reviewer, performance-reviewer, ...

仕組み

• Hooks: $AI_ORCHESTRA_DIR 環境変数で直接参照（シンボリックリンク不要）
• Agents/Config: SessionStart hook (sync-orchestra.py) で $AI_ORCHESTRA_DIR から .claude/ に差分コピー
• Skills/Rules: facets/ の composition 定義から facet build で SKILL.md / ルール .md を自動生成
• CLI Scripts: $AI_ORCHESTRA_DIR/packages/{pkg}/scripts/ を直接実行

$AI_ORCHESTRA_DIR は「配布元リポジトリへのポインタ」であり、hook は起動のたびにこのパスを直接実行する。
通常は ~/.claude/settings.json の env.AI_ORCHESTRA_DIR がメインディレクトリ（安定版 main）を指す。

hook の起動に使う Python は env.AI_ORCHESTRA_PYTHON で決まる（orchex init / setup / install / enable が現在のインタプリタを自動設定する）。hook コマンドは "${AI_ORCHESTRA_PYTHON:-python3}" "$AI_ORCHESTRA_DIR/..." の形で登録されるため、hook 起動シェルの PATH 解決に依存しない。別の Python を使いたい場合はこの環境変数を書き換える（削除すると従来どおり PATH の python3 にフォールバックする）。

設定値の妥当性は、init / setup / install / enable のたびに実際にそのインタプリタを起動して 確認する（起動でき、requires-python を満たし、import yaml できるか。pyyaml を見るのは、これを top-level で import する hook があり、欠損時に hook が黙って素通り（fail-open）するため）。起動 できない値（venv の削除、消えたバージョン付きパス、PATH 解決はできるが古すぎる system python3、 pyyaml 未導入など）は、警告のうえ自動修復される。逆に、起動できる値は利用者の明示指定として 尊重し上書きしない。

この確認は、コマンドを実行したシェルの一時的な import 経路を引き継がない（PYTHONPATH / PYTHONHOME と、-c 実行時に載る cwd を外して起動する）。PYTHONPATH=... orchex init のような 実行で成立した import yaml を根拠にしてしまうと、通常の環境から起動された hook では同じ import が 失敗し、上記の fail-open を呼び戻すためである。user site-packages は無効化しない（実際の hook 起動 時には有効なため）。

自動設定の対象は「消えても AI_ORCHESTRA_DIR は生き残る場所の Python」を除いたものに限る。 worktree やプロジェクト直下の venv、一時ディレクトリの Python、および AI_ORCHESTRA_DIR の外に 置いた venv（~/.venvs/... など）の Python は、その venv を消した時点で全プロジェクトの hook が 起動不能になる（同じ変数で起動する SessionStart 同期も止まるため自動修復も効かない）。そうした Python から実行した場合は、venv の基底インタプリタ（起動でき、pyyaml を持つ場合のみ）を代わりに 設定し、それも使えなければ警告のみを出して env.AI_ORCHESTRA_PYTHON を設定しない。未設定なら hook は従来どおり PATH の python3 で起動される。固定したい場合は安定した Python のパスを手動で 設定する。

ただし pip / pipx / uv tool で orchex 自体を venv へ入れた場合は例外で、その venv の Python を 設定する。AI_ORCHESTRA_DIR も同じ venv の中を指すため、venv が消えればどちらにせよ hook は動かず、 固定をやめても失うものがない（むしろ pyyaml を確実に持つ唯一の Python を手放すことになる）。

既存導入プロジェクトへの適用: orchex init --project . を 1 度実行すれば、hook コマンドの表記 移行（旧 python3 直参照 → 現行表記）と env.AI_ORCHESTRA_PYTHON の設定が同時に行われる。 表記移行は SessionStart 同期にも載っているが、そこには依存しない。移行前の hook は PATH の python3 で起動されるため、その python3 が壊れている環境では sync hook 自身が起動できず、 同期経由の移行が永久に走らないためである。init を単独の入口として成立させている。

なお SessionStart 同期は env.AI_ORCHESTRA_PYTHON を書かない。sync hook 自身が PATH の python3 で起動されうるため、そこで観測したインタプリタを固定すると誤った値を恒久化して しまうためである。

hook 起動の確認とロールバック

hook が動いていない疑いがあるときは次の順で確認する。

1. ~/.claude/settings.json の env.AI_ORCHESTRA_PYTHON の値を控え、そのパスを直接実行して起動するか確かめる（<控えた値> -V。この変数は Claude Code の設定側にあり、対話シェルには export されていない）
2. Claude Code を新規セッションで起動し、SessionStart の sync-orchestra hook が実行されるか確認する
3. PATH の python3 へのフォールバックを試す場合は、~/.claude/settings.json から env.AI_ORCHESTRA_PYTHON のキーごと削除して新規セッションを開く（シェル側での unset では変わらない）

ロールバックの正規手順は ~/.claude/settings.json の env.AI_ORCHESTRA_PYTHON を削除するか、 正しいインタプリタのパスへ書き換えることである。hook コマンドは "${AI_ORCHESTRA_PYTHON:-python3}" 形式なので、キーを削除するだけで PATH の python3 起動に戻せる。settings.local.json を触る 必要はなく、同期で巻き戻されることもない（ただし削除しただけだと、次に init / setup / install / enable を実行したときに未設定として再度自動設定される。PATH 解決を恒久的に 選ぶなら、キーを消さず値を python3 と明示しておく）。

${VAR:-default} の展開自体が効かない環境に当たった場合に限り、次の応急処置で hook コマンドを 旧表記へ戻せる。settings.local.json は JSON なので、hook コマンド中の引用符は \" の形で保存 されている。置換パターンもそのエスケープ形に合わせる（合わせないと 1 件も一致せず、sed は黙って 成功する）。

# hook コマンドのインタプリタ参照を PATH の python3 直参照へ戻す
sed -i '' 's/\\"${AI_ORCHESTRA_PYTHON:-python3}\\" /python3 /g' .claude/settings.local.json

# JSON として壊れていないか確認する
python3 -m json.tool .claude/settings.local.json > /dev/null

ただしこれは恒久的なロールバックではない。旧表記へ戻すと sync hook が動くようになり、次の SessionStart 同期（および init / install / enable）が表記を現行形式へ書き戻すため、状態が セッションごとに揺れる。応急処置のあとは必ず上記の env.AI_ORCHESTRA_PYTHON 側で決着させること。

開発・検証フロー（メンテナ向け）

feature 開発は git worktree add で別ディレクトリに切り出す。メインディレクトリは 常に main 固定で、ここではブランチを切り替えない。

# feature ブランチを worktree で作成
git worktree add ../ai-orchestra-feat-X -b feature/X origin/main

検証時は AI_ORCHESTRA_DIR と OCHE_ROOT の 2 変数を同時にインライン上書きして起動する。
この起動セッションだけ feature 版の hooks/skills/agents で動き、ウィンドウを閉じれば次回起動から安定版（main）に自動復帰する。

# 検証用プロジェクトのディレクトリで実行
OCHE_ROOT=~/ghq/.../ai-orchestra-feat-X \
AI_ORCHESTRA_DIR=~/ghq/.../ai-orchestra-feat-X claude

注意: AI_ORCHESTRA_DIR（hooks/sync が参照）と OCHE_ROOT（手動 orche コマンド）は独立して解決される。片方だけ上書きすると orche sync 実行時に安定版から sync され検証環境が汚染される。2 変数は必ず同時に指定すること。
2 変数の同時指定を 1 コマンドに集約する orche-validate <worktree> wrapper の追加を推奨する。

検証後、PR を main へ squash merge して worktree を削除する:

gh pr create --base main --title "feat: X"
# squash merge 後
git worktree remove ../ai-orchestra-feat-X

---

セットアップ

1. インストール

# uv（推奨）
uv tool install orchex

# pip
pip install orchex

# pipx
pipx install orchex

2. プロジェクトへのセットアップ

# チームメンバー向け: 最低限のパッケージを一括インストール
orchex setup essential --project /path/to/project

# 管理者・開発者向け: 全パッケージを一括インストール
orchex setup all --project /path/to/project

# 事前確認（dry-run）
orchex setup essential --project /path/to/project --dry-run

プリセットは presets.json で定義されています:

• essential — core, agent-routing, audit, quality-gates, codd
• all — 全パッケージ

テンプレートのプレースホルダーについて: 配布される CLAUDE.md / AGENTS.md には <YOUR_PROJECT_NAME> などの <YOUR_...> 形式のプレースホルダーが含まれています。セットアップ後にプロジェクト固有の内容に書き換えてください。 AGENTS.md は codex-suggestions パッケージがインストール済みの場合のみ配布されます（Codex CLI と Antigravity CLI が共用。antigravity.md セクションを合成）。

2b. 個別インストール

# 個別にパッケージをインストールする場合
orchex install core --project /path/to/project

orchex が内部で以下を実行:

1. ~/.claude/settings.json に env.AI_ORCHESTRA_DIR と env.AI_ORCHESTRA_PYTHON（hook 起動用インタプリタ）を設定（恒久設定に耐える Python が見つからない場合は env.AI_ORCHESTRA_PYTHON を設定せず、警告のうえ PATH の python3 へフォールバックする）
2. .claude/orchestra.json にパッケージ情報を記録
3. .claude/settings.local.json に hooks を登録（$AI_ORCHESTRA_DIR/packages/... 参照）
4. sync-orchestra.py の SessionStart hook を登録（初回のみ）
5. agents/rules の初回同期を実行（skills は facet build で .claude/skills/ に直接生成）

セットアップ完了条件

以下をすべて満たしたらセットアップ完了です:

• ~/.claude/settings.json に env.AI_ORCHESTRA_DIR が設定されている
• env.AI_ORCHESTRA_PYTHON が設定されている、または 適格な Python がない旨の警告が出たうえで未設定のまま（PATH の python3 へのフォールバック）になっている
• .claude/settings.local.json に AI Orchestra の hooks が登録されている
• .claude/orchestra.json が存在し、インストール済みパッケージが記録されている
• Claude Code 次回起動時に SessionStart hook が走り .claude/ 配下へ差分同期される

3. 管理コマンド

# バージョン確認
orchex --version

全ログの役割・参照先は docs/reference/logging.md を参照。

4. パッケージ管理コマンド

# プロジェクト初期化（setup/install は未初期化なら自動実行するが、明示的な実行も可能）
orchex init --project .

# プリセットで一括セットアップ
orchex setup essential --project .
orchex setup all --project .

# パッケージ一覧
orchex list

# プロジェクトでの導入状況
orchex status --project .

# インストール / アンインストール
orchex install <package> --project .
orchex uninstall <package> --project .

# 一時的な有効化 / 無効化（hooks の登録/解除のみ）
orchex enable <package> --project .
orchex disable <package> --project .

# パッケージ内スクリプトの一覧表示
orchex scripts
orchex scripts --package audit

# CLAUDE.md / AGENTS.md テンプレート管理
orchex context build
orchex context check
orchex context sync --project /path/to/project
orchex context sync --project /path/to/project --force

# 注意: AGENTS.md は codex-suggestions パッケージがインストール済みの場合のみ配布されます
#       （Codex CLI / Antigravity CLI 共用。codex.md + antigravity.md のセクション合成）
# 注意: 旧 .gemini/GEMINI.md（生成物のみ）は context sync 時に自動削除されます

# パッケージ内スクリプトの実行（-- 以降はスクリプトにパススルー）
orchex run audit dashboard
orchex run audit log-viewer --project /path/to/project -- --last 10

# codex-harness: .codex/ へ hash 保護付き配布 + 非対話 run / read-only レビュー
orchex install codex-harness --project /path/to/project
orchex run codex-harness codex_run -- "<task>"
orchex run codex-harness codex_review -- --base main
# 設計資料: docs/design/codex-cli-harness.md
#
# AI_ORCHESTRA_PYTHON: codex-harness の hook を PATH 上の python3 に依存せず、
#   指定した interpreter で実行したい場合に設定する（値は python 実行ファイルの絶対パス。
#   例: venv の bin/python）。codex_run.py / codex_review.py 経由（`orchex run codex-harness ...`）
#   では自動で子プロセスの環境に注入される。対話 TUI や直接の `codex exec` 呼び出しでは
#   この自動注入が効かないため、必要なら自分で export する。未設定時は従来どおり
#   PATH 上の python3 が使われる（no-op、既存動作を変えない）。
export AI_ORCHESTRA_PYTHON=/path/to/venv/bin/python

# dry-run（変更内容を表示のみ）
orchex setup essential --project . --dry-run
orchex install <package> --project . --dry-run

5. ファセット管理コマンド

スキル・ルールをファセット（Policy / Output Contract / Instruction）から自動生成・管理する。配下ディレクトリの役割は facets/README.md、仕組み全体は Facet システム解説 を参照。

# 全 composition をビルド（SKILL.md / ルール .md を生成）
orchex facet build --project .

# 単一 composition をビルド
orchex facet build --name review --project .

# 外部 CLI 向けに生成（.agents/skills/ に出力。Codex CLI / Antigravity CLI(agy) 共用）
orchex facet build --target codex --project .

# 生成済みファイルから instruction をソースに書き戻す（チューニング反映）
orchex facet extract --name review --project .

# 全件書き戻し
orchex facet extract --project .

運用フロー:

facets/policies/*.md         ← 共有ルール（1箇所修正 → 全スキル・ルールに反映）
facets/output-contracts/*.md ← 共有出力形式
facets/instructions/*.md     ← スキル・ルール固有の手順
facets/knowledge/*.md        ← スキルに同梱する参考資料
facets/scripts/*             ← スキルに同梱するスクリプト
facets/compositions/**/*.yaml ← 組み立て定義（skills/ と rules/ に分類）

    ↓ facet build

.claude/skills/{name}/SKILL.md       ← 生成物（Claude Code 用）
.claude/skills/{name}/references/    ← 知識ファイル（knowledge から配布）
.claude/skills/{name}/scripts/       ← スクリプト（scripts から配布）
.claude/rules/{name}.md              ← 生成物（Claude Code 用）
.agents/skills/{name}/SKILL.md       ← 生成物（Codex CLI / Antigravity CLI 共用）

チューニング後の反映:

/config-tune 等で SKILL.md を直接編集
    ↓
orchex facet extract --name {name}   ← instruction をソースに書き戻し
    ↓
次回 facet build で変更が保持される

SessionStart 時に facet build が自動実行されるため、通常は手動ビルド不要。

自動管理されるファイル

• .gitignore — orchex install 時に AI Orchestra 用ブロックを追加（.claude/docs/, .claude/logs/, .claude/state/ 等）

開発者向け: ソースからのインストール

git clone https://github.com/yoshihiko555/ai-orchestra.git
cd ai-orchestra
uv tool install -e .

---

使い方

エージェント一覧

カテゴリ	エージェント
コア	planner researcher requirements
設計	architect api-designer data-modeler auth-designer spec-writer
実装	frontend-dev backend-python-dev backend-go-dev
AI/ML	ai-architect ai-dev prompt-engineer rag-engineer
テスト・デバッグ	debugger tester
レビュー（実装）	code-reviewer security-reviewer performance-reviewer adversarial-reviewer
レビュー（設計）	spec-reviewer architecture-reviewer ux-reviewer
ドキュメント	docs-writer
ユーティリティ	general-purpose specialized-mcp-builder support-executive-summary-generator testing-reality-checker

エージェントの呼び出し

Task(subagent_type="planner", prompt="このタスクを分解して")
Task(subagent_type="code-reviewer", prompt="このコードをレビューして")

スキル一覧

スキル	用途
/review	コード・セキュリティ・設計レビュー（スマート選定 + 並列実行）
/startproject	マルチエージェント協調で新規開発を開始
/issue-create	GitHub Issue の作成と計画策定
/issue-fix	Issue ベースの計画→実装→テスト→レビューフロー
/codex-system	cli-tools.yaml に基づく Codex 利用ガイド（config-driven）
/antigravity-system	Antigravity CLI（agy）でのリサーチ・マルチモーダル処理
/preflight	実装計画の策定
/design	設計テンプレート
/design-tracker	設計記録
/task-state	Plans.md の作成・更新
/release-readiness	マージ前の最終チェック
/tdd	テスト駆動開発ワークフロー
/code-comments	コード・テスト・コミットログ・コードコメントの書き分け
/code-naming	識別子（変数・関数・クラス等）の命名
/explain-visually	計画・差分・PR/Issue を図解 HTML にして説明

レビュースキル

/review              # スマート選定（変更内容に応じて 2-3 名を自動選定）
/review all          # 全 7 レビュアー並列実行
/review code         # コードレビューのみ
/review security     # セキュリティレビューのみ
/review impl         # 実装系（code + security + performance + adversarial）
/review design       # 設計系（spec + architecture）

---

構成

ai-orchestra/
├── facets/           # ファセットプロンプティング基盤（スキル・ルールの部品化）
│   ├── policies/          # 共有 Policy（dialog-rules, cli-language, code-quality, factual-writing）
│   ├── output-contracts/  # 共有 Output Contract（tiered-review, compare-report, deep-dive-report）
│   ├── instructions/      # スキル・ルール固有の instruction
│   ├── knowledge/         # スキルに同梱する参考資料（references/ に配布）
│   ├── scripts/           # スキルに同梱するユーティリティスクリプト（scripts/ に配布）
│   └── compositions/      # 組み立て定義 YAML（facet build で SKILL.md / ルール .md を生成）
│       ├── skills/        # スキル系 composition
│       └── rules/         # ルール系 composition
├── packages/         # パッケージ（hooks・scripts・agents・config）— 詳細は packages/README.md
│   ├── core/              # 共通基盤ライブラリ + hooks
│   ├── agent-routing/     # 30 エージェント定義 + ルーティング hooks
│   ├── audit/             # 監査ログ・KPI・ダッシュボード
│   ├── codex-suggestions/ # Codex 相談提案 hooks
│   ├── codex-harness/     # Codex CLI 向け repo-local ハーネス（hooks/rules/schemas + 非対話 run/review スクリプト）
│   ├── antigravity-suggestions/ # Antigravity リサーチ提案 hooks
│   ├── quality-gates/     # 品質ゲート hooks
│   ├── docker-runtime/    # ハーネス共通 Docker/broker ライフサイクル
│   ├── skill-evolution/  # スキル自己改善ループ（テレメトリ hooks + オフライン CLI）
│   └── git-workflow/    # Git/GitHub ワークフロー（Issue・PR・開発フロー）
├── scripts/          # 管理CLI（エントリポイント + lib/ 共有ライブラリ）
├── templates/        # テンプレート（エージェント・スキル・プロジェクト）
├── tests/            # Python 単体テスト
├── docs/             # 公開ドキュメント（guides / reference / design / adr）
├── taskfiles/        # Task CLI 用タスク定義
└── Taskfile.yml      # メインタスクファイル

---

更新フロー

# PyPI からの更新
uv tool upgrade orchex

# 開発版の更新（ソースインストール時）
cd ai-orchestra && git pull

変更内容	操作
全般	uv tool upgrade orchex（PyPI 経由）
Hook スクリプト修正	アップグレード後、即反映
Skills/Agents/Rules 修正	アップグレード後、次回 Claude Code 起動時に自動同期
新フックイベント追加	アップグレード + orchex install 再実行

リリース手順（メンテナ向け）

ブランチは main 一本。stage を経由しない（ADR-022）。

# 1. リリース用 worktree を作成
git worktree add ../ai-orchestra-release -b release/vX.Y.Z origin/main

# 2. CHANGELOG.md の Unreleased を vX.Y.Z セクションへフラッシュしてコミット
#    （../ai-orchestra-release 内で編集）

# 3. リリース PR を作成して squash merge
task release VERSION=vX.Y.Z

# 4. マージ確認 → main を pull → タグ push → GitHub Actions が Release 生成
task release:complete VERSION=vX.Y.Z