Architecture 概要

English | 日本語

AI Teams は Product Development operating model、focused Skill、bounded MCP tool、任意の integration component を提供する Codex Plugin です。既存 system の coordination layer であり、 source control、planning、CI、review、deployment、provider authentication を置き換えません。

この文書は現在受理されている system を現在形で説明します。この documentation architecture の理由と合意履歴は Decision Issue #670 が正本です。

diagram policy と、C4 を complementary な behavioral view と併用する判断は Decision Issue #682 に記録します。

Current C4 Context view

この view は、AI Teams が human、execution host、system of record、optional control plane、effect provider に対してどこに位置するか、という一つの問いへ答えます。

flowchart LR
    human["Human operator<br/>intent と privileged authority を所有"]
    codex["Codex<br/>execution host と workspace tools"]
    ai["AI Teams<br/>product-development coordination system"]
    github["GitHub<br/>Issues、Git、PR、CI、Releases"]
    control["External Control<br/>trusted wake-up と runtime orchestration"]
    providers["External providers<br/>authorized review、communication、deployment primitives"]

    human -->|"work を依頼し authority を供給"| codex
    codex -->|"load して実行"| ai
    control -->|"isolated work を開始し bounded state を交換"| ai
    ai -->|"decision と delivery evidence を記録"| github
    ai -->|"authorized primitive を一つ選択"| providers

arrow は関係を示し、無制限な authority を示しません。GitHub と各 provider は自身の authentication と effect permission を保持します。

主要 component

Component 責務 Canonical implementation contract
AI Teams core Skill Goal refinement、Bet selection、team shape、evidence interpretation、replanning Core Skill
Focused Skill Plugin diagnosis、product design、release management plugins/ai-teams/skills/*
Architecture capability provider resolution、bounded operation gate、任意の非 authoritative repository understanding plugins/ai-teams/capabilities/architecture
Quality MCP read-only repository inspection と固定 quality-profile execution plugins/ai-teams/mcp
Bounded specialist tasks 任意の Control Lite がタスク所有権と実行記録を管理し、Codex が一度の読み取り専用調査を実行・停止。判断への影響は provider の Decision が確定 専門タスク契約
Bounded Control MCP client 外部 Qoo257/ai-teams-control への planning/status/action transport。queued execution と runtime orchestration は外部 Control が所有 plugins/ai-teams/mcp
Repository delivery system Git branch/worktree、GitHub Issue/PR、isolated self-hosted validation Delivery architecture
Linear planning adapter 組織・チームを固定した Initiative・Project・Issue 操作と外部識別子の receipt。認証と正本は Linear が所有 Linear contract
Jira・Confluence adapter テナント・Project を固定した Jira フィールド・ワークフロー操作を再取得と receipt で確認。独立した Confluence 読取はページの出典を保持し計画状態を保存しない Jira contract
Human documentation Product intent、accepted architecture、policy、user guidance、generated reference docs/en と公式 docs/ja translation
評価の証拠 利用先を明示した family ごとの fixture・選択した baseline・immutable history。production routing と source hash inventory から分離 評価資料の方針

責務 model

これは documentation authority の第二定義ではなく navigation summary です。詳細な allocation と promotion rule はSpecification governanceが所有します。

Specification → current accepted behavior と durable invariant
GitHub Issues → active change、decision、rationale、mutable project state
Tests/gates   → enforceable evidence
Code/config   → implementation と reconstructable fact
Plugin docs   → machine-facing execution contract と task routing

Human architecture は operational detail を複製せず machine contract へ link します。AI 向け instruction file は最小の canonical contract へ route し、human overview を再記述しません。

System invariant

  • specialist を起動しても一人の coordinator が Goal、Bet、acceptance、authority、learning に accountable
  • external system は自身の authentication と effect authority を保持する
  • 任意の Graft repository graph は disposable な retrieval state に留まり、exact source と policy contract が正本であり続ける
  • missing evidence は success ではなく unknown
  • mutable work state は既存 tracker と Git/GitHub object に置く
  • code、configuration、packaging、security、CI、test の変更は Issue-linked isolated worktree と Pull Request を使う。 repository policy は narrow docs-only L1 に限り、新規 Issue なしの branch / PR を許可できる
  • merge candidate は successful exact-head hosted validation でのみ受理し、missing/unsuccessful result は acceptance を block する
  • delivery は implementation を証明するが product outcome は証明しない
  • scheduler、queue、persistence、recovery、worker lifecycle、GUI、provider-integration runtime は 外部 Qoo257/ai-teams-control が自身のサービスについて所有する。明示的な Control Lite コマンドは 登録されたローカル調整のみを担い、常駐サービスを起動せず、外部 Control の不調時に暗黙の代替にもならない

主要 sequence/boundary は execution、delivery、 trust boundaryを参照してください。

GitHub の live portfolio は work-item-search-projection が所有します。既存の差分取得・キャッシュから Issue graph を組み立て、現在の未完了一覧と完了済み依存先を読み直します。不足情報を明示し、推薦やキャッシュから実行権限を与えません。新しいスケジューラーや正本バックログは追加しません。

Linear・Jira も受理済みの planning adapter を通じて同じ graph と結果生成処理を使います。明示的な状態分類と元の説明内のメタデータで正本の識別情報を維持し、再開可能なページを一時保存し、完全な一覧の検証後に正規化した項目と共通索引を一括で確定します。Goal・チーム・コンポーネントごとの比較には既存の件数制限付き選択処理を使います。本文はキャッシュし、認証情報は保存しません。外部サービスの取得失敗から GitHub へ切り替えません。