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 plugins/ai-teams/capabilities/architecture
Quality MCP read-only repository inspection と固定 quality-profile execution plugins/ai-teams/mcp
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
Human documentation Product intent、accepted architecture、policy、user guidance、generated reference docs/en と公式 docs/ja translation

責務 model

Documentation  → intent, policy, accepted architecture
GitHub Issues  → decisions, rationale, agreement history, mutable project state
Tests/gates    → mechanically enforceable invariants
Code/config    → actual behavior and reconstructable facts
Plugin docs    → machine-facing execution contracts and 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 を保持する
  • missing evidence は success ではなく unknown
  • mutable work state は既存 tracker と Git/GitHub object に置く
  • repository change は Issue-linked isolated worktree と Pull Request を使う
  • 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 が所有し、Plugin はそれらの runtime fallback を提供しない

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