331 lines
21 KiB
Markdown
331 lines
21 KiB
Markdown
---
|
||
description: worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が concrete Ticket 群の実装・外部レビュー・修正・完了準備を管理する orchestration フロー
|
||
model_invokation: true
|
||
user_invocable: true
|
||
requires: []
|
||
---
|
||
# Multi-agent Worktree Workflow
|
||
|
||
yoi を yoi で開発する際の、worktree + coder Pod + 外部 reviewer Pod + orchestrator Pod の標準フロー。これは **最上位 Pod が細かい code review を抱えず、下位 orchestrator が実装と外部レビューの loop を完了状態まで運ぶためのフロー** である。
|
||
|
||
worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依頼の Ticket 化は `$user/ticket-intake-workflow`、Ticket の next action 分類は `$user/ticket-orchestrator-routing`、実装前の planning/requirements sync は compatibility canonical id `$user/ticket-preflight-workflow` に分ける。
|
||
|
||
この Workflow は、対象 ticket が implementation-ready であることを前提にする。implementation-ready は full implementation plan ではなく、recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions に基づいて coder が bounded investigation を進め、reviewer が判断できる状態を指す。設計境界・仕様・authority boundary が未同期の場合は、worktree 作成や coder Pod 起動の前に planning/requirements sync 互換入口として `ticket-preflight-workflow` を通す。
|
||
|
||
## 目的
|
||
|
||
- 実装差分を ticket ごとの child worktree に隔離する。
|
||
- coder Pod に narrow write scope を渡して実装させる。
|
||
- reviewer Pod を coder の子ではなく **同じ orchestrator 配下の sibling** として立て、外部レビューを行わせる。
|
||
- orchestrator は coder / reviewer のやり取り、修正 loop、validation、merge-ready dossier 作成に責任を持つ。
|
||
- 最上位 orchestrator は、コードを直接理解し切ることではなく、委譲した intent / 要件 / invariant に沿って下位 orchestrator が完了まで運んだかを acceptance する。
|
||
|
||
## Pod coordination model
|
||
|
||
基本形は以下。
|
||
|
||
```text
|
||
最上位 orchestrator Pod
|
||
- 人間との会話相手
|
||
- intent / 要件 / invariant / escalation 条件を定義
|
||
- 複数の作業群を並列管理
|
||
- final merge / ticket close / main workspace validation を行う
|
||
- 原則として line-by-line code review を主業務にしない
|
||
|
||
下位 orchestrator Pod（area / concrete-ticket-set coordinator）
|
||
- 連続した複数 concrete Ticket または大きめの concrete Ticket を完了状態まで運ぶ
|
||
- worktree / branch / coder / reviewer / validation / 修正 loop を管理する
|
||
- coder と reviewer を sibling として扱う
|
||
- 親には merge-ready dossier と残論点だけを返す
|
||
|
||
coder Pod
|
||
- 指定 worktree / branch に実装する
|
||
- ticket 外判断や設計衝突は orchestrator に戻す
|
||
- reviewer に直接反論・修正依頼を完結させず、orchestrator に報告する
|
||
|
||
reviewer Pod
|
||
- 原則 read-only
|
||
- ticket / intent packet / diff / validation 結果を読む
|
||
- 実際のコード変更が概念的に何を変えたかを説明する
|
||
- intent / 要件 / invariant に反する blocker を分類して返す
|
||
```
|
||
|
||
一段だけで足りる小さい concrete Ticket では、最上位 orchestrator が直接 coder / reviewer sibling を扱ってよい。複数 concrete Ticket や設計境界をまたぐ作業では、最上位の下に下位 orchestrator を挟む。
|
||
|
||
この Pod coordination model は runtime delegation の形であり、Ticket hierarchy を作る根拠ではない。複数 Ticket を扱う場合も各 Ticket は concrete work item として独立に実装・レビュー・検証・close できる必要がある。broad effort の進捗コンテナとして umbrella Ticket、parent/child Ticket、sub-ticket、part-of、contains などを作らない。中期的な目的や戦略は Objective context に置き、typed Ticket relations が利用可能な場合も dependency / related / blocking / replacement などの非階層メタデータに限る。
|
||
|
||
明示的な queue review や routing kick の中で、独立した queued Ticket が複数あり coder/reviewer capacity が残っているなら、最初の Ticket の完了を待つことを default にしない。Orchestrator は各 Ticket の relation metadata、OrchestrationPlan records、Ticket thread、workspace/worktree dirty state、visible Pods、既存 branch、conflict notes を確認し、blocking relation や `do_not_parallelize` がなく、write surface が disjoint または conflict risk が小さく機械的に処理できるものを、別 worktree・別 branch・別 narrow write scope で並列開始する。これは background scheduler や queue drain loop ではなく、人間が queued にした Ticket だけを、その場の明示的な acceptance 判断で `queued -> inprogress` に進める運用である。
|
||
|
||
## 開始条件
|
||
|
||
以下が揃っている時に使う。
|
||
|
||
- 対象 concrete Ticket または concrete Ticket 群が決まっている。
|
||
- Ticket lifecycle を使う場合、対象はすでに `inprogress` であるか、worktree 作成・Pod spawn・coder routing の前に Orchestrator が個別に `queued -> inprogress` acceptance を記録できる `queued` Ticket に限る。unqueued Ticket は capacity 埋めの対象にしない。
|
||
- ticket の背景・意図・制約・受け入れ条件から、実装調査と局所 tactic 選択を coder に委ねても product / API / UX / authority / design-boundary decision を silently 固定しないと判断できる。
|
||
- worktree 作成と git 書き込み操作について、人間の許可がある。
|
||
- merge target workspace の unrelated dirty changes を把握している。
|
||
- 下位 orchestrator に渡す binding decisions / invariants、implementation latitude、escalation conditions を短く書ける。
|
||
- 設計境界・仕様・authority boundary に不確定要素があり、bounded project-context checks 後も concrete missing decision / information が残る場合、planning/requirements sync 互換入口 `ticket-preflight-workflow` の結果が ticket thread に記録されている。
|
||
|
||
product / API / UX / authority / design-boundary 方針が複数自然に導ける場合、ticket 自体の再定義が必要な場合、または protocol / scope / permission / history persistence に触れる作業で bounded project-context checks 後も concrete missing decision / information が残る場合は、実装委譲前に planning/requirements sync 互換入口 `ticket-preflight-workflow` を通し、必要なら人間へ戻す。scope / Pod / permission / persistence のような authority-adjacent domain は reviewer focus と context lookup の signal であり、intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions が明確なら coder に委ねてよい。実装ファイルの探索、既存コード読解、局所的な構成選択のような bounded implementation uncertainty も同様に coder に委ねてよい。
|
||
|
||
## Intent packet
|
||
|
||
階層化すると人間の意図が劣化しやすい。下位 orchestrator や coder / reviewer へは、自然文の依頼だけでなく intent packet を渡す。
|
||
|
||
標準形:
|
||
|
||
```text
|
||
Intent:
|
||
- 何を実現するか。
|
||
|
||
Binding decisions / invariants:
|
||
- 人間/Orchestrator/Ticket に記録済みで coder / reviewer が従うべき decision。
|
||
- 壊してはいけない設計境界、authority boundary、明示制約。
|
||
- 残してはいけない旧概念や互換層。
|
||
|
||
Requirements / acceptance criteria:
|
||
- 完了時に満たすべき observable な要件と reviewer が判断できる基準。
|
||
|
||
Implementation latitude:
|
||
- Coder が調査しながら選んでよい local tactic / file-local organization / bounded uncertainty。
|
||
|
||
Escalate if:
|
||
- 親へ戻すべき判断条件。特に product / API / UX / authority boundary / explicit design constraint を変える必要が出た場合。
|
||
|
||
Validation:
|
||
- 実行すべき format / build / test / doctor。
|
||
|
||
Reviewer focus:
|
||
- reviewer が確認すべき critical risks。
|
||
```
|
||
|
||
reviewer には coder の実装方針ではなく、この intent packet と diff を中心に読ませる。reviewer は recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / explicit escalation conditions に照らして判断し、不記録の preferred tactic を基準にしない。
|
||
|
||
## orchestrator の責務
|
||
|
||
下位 orchestrator を挟まない場合は、以下を最上位 orchestrator が行う。下位 orchestrator を挟む場合は、最上位は intent packet を渡し、以下の実務を下位に委譲する。
|
||
|
||
1. 状態確認
|
||
- `git status --short --branch`
|
||
- 対象 ticket / ticket 群
|
||
- relation metadata / OrchestrationPlan records / do_not_parallelize / conflict or dependency notes
|
||
- visible Pods、既存 worktree/branch、coder/reviewer follow-up capacity
|
||
- 関連 TODO / docs / 既存 worktree
|
||
- planning sync が必要な ticket では、互換入口 `ticket-preflight-workflow` の分類・要件同期・critical risks
|
||
|
||
2. worktree 作成
|
||
- 対象 Ticket が `queued` なら、この step の前に typed Ticket backend/tool path で `queued -> inprogress` を記録する。これより前に branch 作成、worktree 作成、Pod spawn、実装調査依頼などの implementation side effect を行わない。
|
||
- Orchestrator が dedicated orchestration worktree で動く場合でも、implementation worktree は Orchestrator cwd ではなく recorded original workspace root の `.worktree` 配下に作る。
|
||
- merge-completion は recorded merge target workspace で行い、Orchestrator cwd を merge target とみなさない。
|
||
- `$user/worktree-workflow` に従い `<original-workspace-root>/.worktree/<task-name>` を作る。
|
||
- `.yoi` 自体は除外しない。tracked project records は child worktree に存在してよく、`.yoi/memory` と local/runtime/log/lock/secret-like paths だけを sparse checkout で除外する。
|
||
|
||
3. coder Pod spawn
|
||
- read scope: original workspace root 全体、または実装に必要な bounded read scope。
|
||
- write scope: child worktree、または必要最小 directory。
|
||
- task には以下を明示する。
|
||
- child worktree path / branch
|
||
- 対象 ticket path
|
||
- intent packet
|
||
- SpawnPod の `cwd` は child worktree に設定すること（`cwd` は process/tool default cwd であり、scope/authority ではない）
|
||
- Orchestrator workspace / recorded Ticket backend の `TODO.md` / Ticket records / `docs/report/` / `.yoi` は編集しないこと
|
||
- child worktree 内の tracked `.yoi` project records は実装対象に必要な branch-local artifacts/dossiers として編集してよいが、`.yoi/memory` や local/runtime/secret-like files は作らないこと
|
||
- active orchestration progress と最終 review/approval/close は Orchestrator workspace または recorded Ticket backend の責任として残すこと
|
||
- 遵守すべき binding decisions / invariants と escalation conditions
|
||
- 実行すべき build / test / format
|
||
- 完了報告項目
|
||
|
||
4. coder 完了確認
|
||
- `ReadPodOutput` で報告を読む。
|
||
- 通知が来ない場合でも、worktree の `git status` / `git diff` / test で完了状態を確認する。
|
||
- coder が止まった場合、worktree 状態を見て再 spawn / rollback / 親 escalation を判断する。
|
||
|
||
5. reviewer Pod spawn
|
||
- reviewer は coder の子ではなく orchestrator 配下の sibling として立てる。
|
||
- 原則 read-only scope にする。
|
||
- reviewer に渡すもの:
|
||
- ticket / intent packet
|
||
- branch / commit / diff の読み方
|
||
- 実行済み validation
|
||
- blocker / non-blocker / acceptable の分類基準
|
||
- reviewer の主目的は「コードの詳細を親の代わりに説明し、intent / invariant 違反を見つけること」。
|
||
|
||
6. review → 修正 loop
|
||
- reviewer finding を orchestrator が読む。
|
||
- blocker は coder に修正依頼する。
|
||
- reviewer の指摘を却下する場合は、orchestrator が理由を dossier に残す。
|
||
- 修正後は focused validation を実行し、必要なら reviewer に再確認させる。
|
||
- reviewer の blocker が未解決のまま親に提出しない。
|
||
|
||
7. merge-ready dossier 作成
|
||
- 親がコードを直接理解しなくても判断できるよう、変更の概念的説明と evidence をまとめる。
|
||
|
||
8. merge / lifecycle
|
||
- 最上位 orchestrator または人間の許可を持つ orchestrator が recorded merge target workspace へ merge する。
|
||
- Ticket を完了処理して commit する。TODO cleanup が対象 Ticket の明示要件なら recorded merge target workspace で行う。
|
||
- recorded merge target workspace で必要な test / `cargo check --workspace` / `cargo fmt --check` を再実行する。
|
||
|
||
## coder Pod の責務
|
||
|
||
- child worktree 内でのみ実装する。
|
||
- main workspace の管理ファイルを書かない。
|
||
- child worktree 内の tracked `.yoi` project records は ticket 要件に必要な branch-local artifact/dossier として扱ってよい。
|
||
- `.yoi/memory`、local/runtime state、logs、locks、secret-like files を child worktree に作らない。
|
||
- intent / requirements / acceptance criteria / binding decisions / invariants / implementation latitude / escalation conditions を読んでから実装する。
|
||
- 実装ファイルの探索、既存コード読解、局所的な tactic 選択は、intent packet の implementation latitude 内で行ってよい。
|
||
- 指定された build / test / format を実行する。
|
||
- ticket 要件外または binding decisions/invariants 外の設計変更、依存関係追加、scope / permission / history persistence / prompt context 加工原則に触れる変更が必要なら止めて orchestrator に報告する。
|
||
- 完了時に以下を報告する。
|
||
- worktree path / branch
|
||
- commit hash（commit した場合）
|
||
- 変更ファイル
|
||
- 実装概要
|
||
- 実行した build / test / format
|
||
- 未解決事項
|
||
- review に回せるか
|
||
|
||
## reviewer Pod の責務
|
||
|
||
reviewer は coder の subordinate ではない。orchestrator 配下の sibling として、実装 diff を外部から読む。
|
||
|
||
- 原則 read-only で作業する。
|
||
- ticket / intent packet / diff / validation 結果を読む。
|
||
- 実際のコード変更が概念的に何を変えたかを説明する。
|
||
- 親や上位 orchestrator が line-by-line diff を読まずに判断できるよう、以下を整理する。
|
||
- 変更の概念モデル
|
||
- recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / explicit escalation conditions との対応
|
||
- binding decisions / invariants 違反の有無
|
||
- 旧概念・禁止語彙・不要な互換層の残存
|
||
- validation の妥当性
|
||
- blocker / non-blocker / follow-up
|
||
- reviewer は直接 merge しない。
|
||
- reviewer は coder に直接作業指示を出さず、orchestrator に finding を返す。
|
||
|
||
## commit 方針
|
||
|
||
coder Pod には child worktree 内での commit を許可してよい。
|
||
|
||
- commit は ticket 内で意味のある粒度にする。
|
||
- 例: `feat: ...`、`fix: ...`、`test: ...`、`docs: ...`
|
||
- coder Pod は merge / push / branch deletion / worktree remove をしない。
|
||
- coder Pod は recorded Ticket backend の Ticket 完了処理 commit、最終 review/approval/close をしない。child worktree 側には branch-local dossier や実装証跡を残してよい。
|
||
- orchestrator は review 時に commit 粒度も確認する。
|
||
- 必要な修正は、原則追加 commit として積む。履歴改変や squash は人間の明示指示がある時だけ行う。
|
||
|
||
## Review → 修正 → 完了の標準形
|
||
|
||
### Approve
|
||
|
||
reviewer が approve し blocker が残っていない場合、明示的な standing policy として merge / validate / close / cleanup まで進める。migration boundary、runtime refresh boundary、未解決の human gate が明示されている時だけ、merge-ready dossier で止める。
|
||
|
||
1. coder Pod / reviewer Pod を停止し、scope を回収する。
|
||
2. orchestrator が merge-ready dossier を確認する。
|
||
3. 最上位 orchestrator が必要最小限の spot check を行う。
|
||
4. recorded merge target workspace で `git merge --no-ff <branch>` する。
|
||
5. Ticket を完了処理して commit する。TODO cleanup が対象 Ticket の明示要件なら同じ merge target workspace で行う。
|
||
6. recorded merge target workspace で検証コマンドを再実行する。
|
||
7. 変更内容・commit・検証結果・残 dirty changes を報告する。
|
||
|
||
### Request changes
|
||
|
||
1. reviewer finding または orchestrator finding を blocker / non-blocker に分ける。
|
||
2. blocker はファイル / 行 / 理由 / 修正方針つきで coder に戻す。
|
||
3. coder が停止済みなら、同じ worktree / branch / scope で再 spawn する。
|
||
4. 修正後に focused test と必要な broader test を再実行する。
|
||
5. 必要なら reviewer に再確認させる。
|
||
6. blocker が解消したら dossier を更新する。
|
||
|
||
### Non-blocking comments
|
||
|
||
- ticket 要件外の改善はその場で混ぜない。
|
||
- 必要なら後続 ticket / docs/report にする。
|
||
- non-blocking を理由に completion を遅らせない。
|
||
|
||
## 並列実装時の注意
|
||
|
||
- 1 ticket = 1 worktree = 1 branch を基本にする。
|
||
- 複数 Pod に同じ write scope を渡さない。parallel Coder Pod は別 worktree と narrow write scope を持つ。
|
||
- parent / orchestrator は coder の write scope 配下を直接編集しない。
|
||
- reviewer は read-only を基本にする。明示的に別 scope を与える判断がない限り、review artifact を書かせる場合も ticket artifacts など限定 scope にする。
|
||
- independent queued Ticket は、blocking relation/dependency がなく、`do_not_parallelize` や relevant `conflicts_with` がなく、source/write surface が disjoint または conflict risk が小さく機械的で、coder/reviewer follow-up capacity があり、workspace records を side effect 前に commit でき、別 worktree/branch/scope を切れる場合に並列開始を優先する。
|
||
- 依存関係がある ticket、同一 migration boundary や同一 schema/tool/panel surface を大きく触る ticket、または reviewer/coder bottleneck がある ticket は、土台 branch を merge してから次 worktree を切るか、bounded defer reason を記録して idle にする。
|
||
- capacity が見えるのに queued Ticket を開始しない場合、dependency / conflict / capacity / missing planning decision / dirty workspace / reviewer-coder bottleneck / migration boundary / human gate のいずれかを bounded reason として Ticket thread または `TicketOrchestrationPlanRecord` に残す。
|
||
- parallel に走らせた Pod の完了通知は取りこぼしうるため、`ReadPodOutput` と worktree 状態で確認する。
|
||
- この節は自動 scheduler、background runner、resource graph solver、automatic queue drain loop を導入しない。parallel start は明示的な routing/acceptance の結果であり、unqueued Ticket を開始する根拠ではない。
|
||
|
||
## merge-ready dossier の標準形
|
||
|
||
```text
|
||
Status:
|
||
- completed / blocked / needs parent decision
|
||
|
||
Scope:
|
||
- ticket(s): <path>
|
||
- branch: <name>
|
||
- commits:
|
||
- <hash> <subject>
|
||
|
||
Intent check:
|
||
- invariant 1: ok / violated / not applicable, evidence ...
|
||
- invariant 2: ok / violated / not applicable, evidence ...
|
||
|
||
Implementation summary:
|
||
- 変更の概念的説明: ...
|
||
- 主要変更ファイル: ...
|
||
- compatibility / migration: ...
|
||
|
||
Coder loop:
|
||
- coder pod: <name>
|
||
- produced commits: ...
|
||
- unresolved coder notes: ...
|
||
|
||
External review:
|
||
- reviewer pod: <name>
|
||
- blockers found: ...
|
||
- blockers fixed: ...
|
||
- rejected findings and reasons: ...
|
||
- non-blocking follow-ups: ...
|
||
|
||
Validation:
|
||
- cargo fmt --check
|
||
- cargo check --workspace
|
||
- cargo test ...
|
||
- yoi ticket doctor
|
||
|
||
Parent decision needed:
|
||
- none / specific question
|
||
|
||
Residual risk:
|
||
- ...
|
||
|
||
Dirty state:
|
||
- ...
|
||
```
|
||
|
||
## 最上位 orchestrator の acceptance
|
||
|
||
最上位 orchestrator は、下位 orchestrator の成果を code review するのではなく acceptance する。
|
||
|
||
確認するもの:
|
||
|
||
- intent packet が保持されているか。
|
||
- reviewer が coder と独立した sibling として機能したか。
|
||
- blocker が未解決のまま握りつぶされていないか。
|
||
- 変更の概念的説明が要件と対応しているか。
|
||
- validation が ticket のリスクに対して十分か。
|
||
- escalation すべき判断を下位が勝手に決めていないか。
|
||
|
||
必要なら spot check するが、常態的な line-by-line review に戻らない。
|
||
|
||
## この Workflow で扱わないもの
|
||
|
||
以下は `$user/ticket-intake-workflow`、`$user/ticket-orchestrator-routing`、または別の設計相談で扱う。
|
||
|
||
- ユーザー依頼を Ticket 化すること。
|
||
- Ticket の next action を分類すること。
|
||
- QA feedback / AI feedback を Ticket / report / workflow に落とす判断。
|
||
- 長期 maintainer loop / scheduler / LeaseStore の設計。
|
||
- reviewer Pod の品質評価を機械的に採点する仕組み。
|