概要¶

English | 日本語

AI Teams は、Codex Skill と bounded tool を一つの Plugin として提供します。core Skill は Product Development の accountable lead として、依頼を Goal と Next Bet に整理し、価値があるときだけ specialist work を調整し、project toolchain を通じて届け、証拠から学びます。

明示的に依頼された、または具体的な event に起因する横断 review では、AI Teams は有限な project-health operation を実行し、全 finding の disposition と正本 tracker の完了 readback を確認できます。通常の status と狭い delivery は直接処理し、repository の古さや大きさだけを理由に audit を開始しません。

最初に使う4つの概念¶

基本概念	答える問い
Goal	どの outcome が重要か
Bet	次に試す価値がある一手は何か
Work Item	delivery と acceptance の永続的な単位はどこか
Evidence	何が起き、次に何を変えるべきか

通常の作業はこの4概念で始められます。integration、architecture、delivery mechanism の用語は、判断に影響するときだけ示します。

GitHub、Git、CI、code review、security scanner、planning system を置き換えません。それらの authority と authentication boundary を保ちながら capability を選択・解釈します。

standard setup は AI Teams + GitHub Plugin + Codex native capability です。Linear、Jira、その他の planning system が既に authoritative なら product state をそこに残し、code delivery だけを GitHub へ link します。task ごとに provider stack を再設計するよう user へ求めません。

Linear 利用者は Linear planning adapter で Initiative・Project・Issue の読取と検索、変更案の確認と適用、状態変更、delivery の関連付けを行えます。プロジェクト側で組織・チーム ID とフィールド・状態の対応を定義し、認証は provider が管理します。変更は既定でプレビューとなり、適用には対象操作の権限が別途必要です。古い版は拒否し、結果が不明なら読み直します。Linear が使えなくても GitHub に backlog を作りません。 Linear には版を原子的に照合する更新機能がないため、競合する編集は呼出し側で直列化します。 Linear のバックログ推薦には、後述の portfolio コマンドを使います。

Jira Cloud 利用者は Jira planning adapter で既存 Project の Epic・Issue を読み取り・検索し、変更案の確認、カスタムフィールドの更新、許可されたワークフローの状態変更、関連付け、コメント追加を行えます。プロファイルでテナント・ Project と各フィールド・状態の ID を指定し、未登録のカスタムフィールドと書式付き本文を保持します。変更には別途権限が必要で、対象の版と変更後の再取得結果を確認します。作成やコメント追加の結果が不明な場合は再送せず、Jira 上で確認します。Confluence は空間と版を固定した独立の読取アダプターを使い、ページ内容を計画の正本として保存しません。認証情報は連携プロセスの環境で管理します。 Project の管理設定と Data Center 対応は別の範囲です。Jira のバックログ推薦には、後述の portfolio コマンドを使います。

GitHub Plugin が operation に対して unavailable、unauthorized、unsupported の場合、明示的に観測した standard CLI または登録済み bundled fallback を利用できます。authorized path がなければ bounded handoff を返し、成功の捏造や system of record の黙った置換は行いません。

repository understanding も任意かつ provider-neutral です。固定済みの Graft CLI companion が利用可能な場合、AI Teams は map、context search、caller/dependency、blast radius、freshness のうち一つを有限な条件で実行できます。Graft の出力は検索の手掛かりに限られ、正確な source、 Markdown/JSON contract、Git、test、tracker record が引き続き正本です。Graft がない場合や失敗した場合も native read、Git、rg で通常どおり動作します。通常の task は Graft の install、telemetry、 model/key、hook、agent instruction を設定しません。

Operating model¶

確認済みで他のプロジェクトにも当てはまる AI Teams の不具合・改善候補は、明示的なオプトインにより検証済みの upstream Issue tracker へ報告できます。既定では無効で、Plugin の有効化とは別の利用者所有の許可が必要です。導入先の正本 tracker は変わらず、ソースツリー・会話・振り返りを自動送信しません。送信前にローカルで生成された本文全体を確認してください。完全一致する Issue は再利用し、それ以外の候補や結果不明の場合は自動再試行せず確認に引き継ぎます。同意・前提条件・プレビュー・無効化・復旧手順は upstream 報告の操作説明を参照してください。この機能がプロジェクトの AI Teams を有効化したり、更新をインストールしたりすることはありません。

Team とは、役割ごとに必ず別 agent を置くことではなく、連携する責務と contract です。既定では一人の coordinator が accountable であり、独立した専門性、context の分離、並列作業が quality、latency、evidence を実質的に改善するときだけ specialist work を加えます。これは常設の役割階層でも acceptance evidence でもありません。

stakeholder outcome と現在の証拠を理解する
Goal と依頼された solution を分離する
assumption、unknown、constraint、non-goal を特定する
最小で価値のある Bet を選ぶ
authoritative Work Item と repository workflow を通じて届ける
exact candidate を検証し、outcome evidence を観測する
stop、iterate、revert、または新しい Bet を選ぶ

一人の coordinator が既定です。agent 数は acceptance evidence ではありません。

material work では、production edit の前に Calibrated Delegation を使います。routine な選択は、明示された intent、受け入れ済み preference、既存 design、確立した practice、最も単純で reversible な default の順に解決します。product value、public behavior、authority、高コストで不可逆な outcome を実質的に変える未解決の選択がある場合だけ direction を求めます。 narrow bug fix のように明確で客観的かつ low-risk な作業は直接処理します。会話中の correction が受け入れ済み outcome を変えた場合は、実装を続ける前に以前の readiness decision を無効化します。

外はシンプルに、内側は厳密に¶

通常の interaction は、目指す outcome、次に試す価値がある Bet、起きたこと、次に取れる action から始めます。implementation detail は onboarding の負担にせず、必要なときに progressive disclosure で確認できます。

この簡潔さで safety state を隠すことはありません。必要な approval または action、failed または pending の gate、external effect の uncertainty、authorized path がない事実は、次の判断に影響するとき常に表示します。内側の isolation、exact-candidate validation、readback、 rollback、release control は厳密なままです。

内部用語が現れるとき¶

内部用語	user の判断または action に必要となる開示条件
Standard Profile / provider / system of record	integration または authoritative tracker の選択、認証、復旧が必要なとき
Control	persistent discovery、scheduling、queue/recovery state、worker、Control UI を選ぶとき
Goal Brief / structural reassessment	高コスト、曖昧、または workaround が反復する判断を深く整理するとき
candidate / exact-head validation	exact revision を特定し、pending または failed の merge gate を説明するとき
authority / approval	external、privileged、destructive、または human-owned effect に同意が必要なとき

詳細用語は Goal、Bet、Work Item、Evidence の path を補足します。この path を置き換えたり、必要な action、failed gate、uncertainty を隠したりしません。

永続設定¶

AI Teams は ~/.codex/ai-teams/settings.json の review 済み default と、 .ai-teams/project-policy.json の repository rule を利用できます。project policy は user default より優先され、current explicit instruction はその両方より優先されます。 provider preference の順序、language / interaction default、delivery convention、既存の release-policy overlay を選択できますが、credential、provider availability、absolute project path、work state、external effect の権限は保存しません。file がなければ product default を維持し、malformed または unsafe な file は reject します。

ホストが学習済みの好みを渡す場合は、明示的な指示・プロジェクト方針・ユーザー設定より低く、製品の既定値より高い優先順位で適用します。ユーザー設定でサポートする好みの値だけを受け付け、プロジェクト方針や承認を与えることはできません。設定解決自体はメモリを取得・保存しません。

.codex/ai-teams と .ai-teams には通常のディレクトリを使います。設定への経路にシンボリックリンクがある場合は、JSON ファイルがない壊れたディレクトリリンクも含めて拒否します。復旧時は、確認済みの設定を正規の場所の通常のディレクトリに配置してください。プロジェクトルートの別名は、引き続き同じプロジェクトとして解決します。

たとえば、ユーザー設定には次のように記述できます。

{"schema": "ai-teams-user-settings/v1", "companion_locale": "ja"}

プロジェクト方針では、ドキュメントの言語を選択できます。

{"schema": "ai-teams-project-policy/v1", "documentation_language": "en"}

現在のバックログから次の候補を選ぶ¶

python3 <ai-teams-skill-dir>/scripts/portfolio.py --repo OWNER/REPO で、GitHub から推薦1件と代替候補最大4件を取得できます。graph JSON の手作りは不要です。GitHub CLI の認証中アカウントを使い、Issue と差分同期カーソルはリポジトリ外の既存の再構築可能なキャッシュに保持します。

結果には優先度・緊急度・依存関係・確信度と不足情報が含まれます。低い確信度は比較材料の不足を表し、実装の成功やユーザーへの効果を証明するものではありません。一覧を完全に取得できなければ推薦を返しません。推薦は検討用であり、実行許可にはなりません。実装前には対象 Issue を読み直します。任意の比較項目と graph の100ノード上限は契約に記載しています。

GitHub の索引は、未完了1万件でも件数だけを理由に停止しません。 --goal-ref GOAL、--team TEAM、--component COMPONENT で比較範囲を絞れます。 team と component は Issue の明示的な team:VALUE / component:VALUE ラベルを使います。 1ページの未完了項目は最大50件で、直接の依存先と合わせて比較し、候補は最大5件を返します。続きがあれば truncated と partition.next_cursor に表示されます。同じ絞り込み条件に --cursor CURSOR を加えて次のページを確認してください。推薦はそのページ内の比較結果で、古い情報のページでは推薦を返しません。同期が partition.resume_required を返した場合は、同じコマンドで保存済みの取得位置から再開できます。バックグラウンドでは実行しません。 2,000件の保持上限は完了済み履歴にだけ適用します。

Linear・Jira では、既存のアダプタープロファイルと、未完了・完了に当たる状態名を指定します。

python3 <ai-teams-skill-dir>/scripts/portfolio.py --provider linear \
  --profile linear-project.json --open-state planned --open-state active --closed-state done
python3 <ai-teams-skill-dir>/scripts/portfolio.py --provider jira \
  --profile jira-project.json --open-state planned --open-state active --closed-state done

状態名は例をそのまま使わず、プロファイルに設定した名前に合わせます。フラグを繰り返して全状態を重複なく分類してください。元の Issue 説明から Work Item メタデータと比較項目を読み取ります。Jira は ADF の通常段落・コードブロック内のテキストに対応します。依存先は Linear の UUID、または Jira の ID・キーで指定し、不足する情報は unknown として表示します。認証方法は既存アダプターと同じです。外部トラッカーでは --repo を指定しません。

1回の通信は最大10回です。Linear は最大500件、Jira はプロジェクト確認を含め最大250件を取得します。pending は検証済みページを保存した状態なので、同じコマンドで再開します。全ページを確認してから索引をまとめて更新し、削除・閲覧権限の喪失による一覧からの除外を反映します。

--goal-ref、--team、--component で対象を絞り、返されたページカーソルを --cursor に指定すると索引の続きを読めます。Goal は明示的なメタデータ、チーム・コンポーネントは team:・component: ラベルを使います。Linear の既定チームはネイティブのチームIDです。不明・対象範囲外の依存先は着手可能とみなしません。最大100ノードを比較して候補を5件まで返し、鮮度と途中ページかどうかを表示します。

キャッシュには正規化した項目と本文を保存しますが、認証情報は保存しません。旧形式の識別情報のみのキャッシュで cache_conflict が返った場合は、そのキャッシュだけを削除して再取得してください。プロファイル変更・走査開始から24時間の経過後も再構築します。取得や保存に失敗しても、確定済みの索引と成功時点は保持します。GitHub へ自動で切り替えません。詳細は外部 portfolio 契約を参照してください。

後続の作業で得られる証拠を戻す¶

残りの受入証拠が別の作業中に自然に得られる Issue では、遅延受入チェックを任意登録できます。たとえばビルド対象パスの修正なら、無関係な push で Pages チェックが出ないことと、文書変更の push でビルドが成功することを待てます。 AI Teams はチェック完了の観測時に少数の登録を照合し、許可された証拠を元の Issue へ戻します。一部の証拠だけでは未完了を維持し、すべての受入条件と通常の完了判定を満たす必要があります。

登録先は元の Issue で、有効期限と取消しを設定できます。初版は GitHub の正確なコミット変更パスと app/name によるチェック識別に対応し、不在の判定には事前に定めた観測期間を使います。任意コードの hook や常駐 polling は追加しません。 AI Teams 外の作業は、明示的な project-health 棚卸しでの照合が必要な場合があります。証拠の書込み、受入条件の更新、Issue のクローズは別々の権限です。

登録と入力形式は遅延受入チェックの契約を参照してください。

進捗と判断待ちをまとめて確認する¶

AI Teams に「進捗と、私の判断が必要なものを見せて」と伝えます。GitHub プロジェクトの現在の Goal・Bet・観測予定・判断待ちを確認し、推奨回答、その影響、待機する作業と継続する作業を示します。Goal・Bet への明示的なリンクがない Issue は未関連付けの作業として表示し、関係を推測しません。判断待ちが空でもバックログが空とは限りません。ジョブの参照先が未設定の場合は、ジョブの状態を「取得できない」として扱います。

インストール済みのコマンドは次のとおりです。

python3 <ai-teams-skill-dir>/scripts/decision_inbox.py --repo OWNER/REPO status

status を decisions、goals、bets、evidence、jobs に替えると対象を絞れます。必要なら --jobs-database <既存のControl-Liteストア> を指定します。参照は読み取り専用です。回答するときは、対象の判断と選んだ回答を AI Teams に伝えます。AI は現在の記録と表示時の revision を確認し、既存の権限の範囲で回答を記録します。CLI はまず書き込まずに回答案を作ります。

python3 <ai-teams-skill-dir>/scripts/decision_inbox.py --repo OWNER/REPO answer \
  --issue NUMBER --revision '表示された正確なREVISION' \
  --answer '提示された選択肢' --rationale '選択の理由'

権限を持つエージェントは --apply --authority-basis <正確な権限の参照> を加えて保存できます。withdraw と expire は同じ識別情報と理由を使い、回答を指定しません。古い状態への回答は最新の判断を確認してからやり直します。回答してもデプロイ権限の付与やジョブの再開は行いません。対象範囲のない旧形式の判断は、この操作の前に明示的な移行が必要と表示します。スキーマ、取得上限、復旧方法は Decision Inbox 契約を参照してください。

複数リポジトリを一つの Goal で追跡する¶

所有者が明示的に承認した Project Workspace は、最大 20 個の正確なリポジトリ名を許可リストに持ち、一つの Goal と任意の Bet に Work Item、PR、deployment を関連付けます。正本のリビジョンを参照し、別のバックログは作りません。選択済みの範囲内で読む際のリポジトリ確認は繰り返し不要ですが、書き込みには対象操作の権限が引き続き必要です。

プロバイダー操作前の範囲確認は、インストール済み Skill の scripts/project_state.py workspace-check、完全なリポジトリ別スナップショットの集約は workspace-status を使います。どちらも標準入力の上限付き JSON を受け取り、自身ではプロバイダー操作を行いません。認証済み観測情報は host/provider が供給し、このコマンドは自動取得やデプロイを行いません。リポジトリの欠落や期待リビジョンの不一致は拒否し、古い観測情報は古いまま表示します。依存関係・デプロイ順序は参考情報であり、PR のマージやデプロイ成功を Bet の成果とは判定しません。

入力項目、識別規則、上限、再構築方法は Workspace 契約を参照してください。既存の単一リポジトリ用コマンドは移行せず利用できます。