agent-execution-with-worktree（使用工作树执行 Agent）

🤖 Agent Execution with Worktree

Version: 2.0.0 Last Updated: 2025-11-22 Priority: ⭐⭐⭐⭐⭐ (P0 Level) Purpose: Miyabi Agent実行とWorktree分離による並列処理

📋 概要

Miyabiの7 Coding Agentsを、Git Worktree分離により安全な並列実行で処理。 コンフリクトフリーな開発を実現します。

🎯 P0: 呼び出しトリガー

🔧 P1: Agent分類と実行ルール

Agent優先順位表

並列実行ルール

✅ 安全な並列実行:
- 🟢 CodeGenAgent + 🟢 ReviewAgent (異なるIssue)
- 🟢 CodeGenAgent + 🟢 IssueAgent
- 🟢 IssueAgent + 🟢 IssueAgent (異なるIssue)

❌ 禁止される並列実行:
- 🔴 CoordinatorAgent × 2 (Sequential only)
- 同じAgentで同じIssue (Race condition)

⚠️ 条件付き実行:
- 🟡 DeploymentAgent: ReviewAgent品質チェックpass後
- 🟡 PRAgent: CodeGenAgent実装完了後

🚀 P2: 実行方法別パターン

Pattern 1: 単一Issue処理

# CoordinatorAgent経由（推奨）
cargo run --bin miyabi -- agent run coordinator --issue 270

フロー:

graph LR
    A[Issue #270] --> B[Coordinator]
    B --> C[CodeGen]
    C --> D[Review]
    D --> E{Pass?}
    E -->|Yes| F[PR作成]
    E -->|No| C

Pattern 2: 複数Issue並列処理

# 並列度指定
cargo run --bin miyabi -- agent run coordinator --issues 270,271,272 --concurrency 3

フロー:

graph TD
    A[Issues 270,271,272] --> B[Coordinator]
    B --> C1[Worktree #270]
    B --> C2[Worktree #271]
    B --> C3[Worktree #272]
    C1 --> D1[CodeGen]
    C2 --> D2[CodeGen]
    C3 --> D3[CodeGen]
    D1 --> E[Merge]
    D2 --> E
    D3 --> E

Pattern 3: 直接Agent実行（開発用）

# 特定Agentの直接実行
cd crates/miyabi-agents
cargo run --example codegen_agent -- --issue 270

⚡ P3: Worktreeライフサイクル

Phase 1: Worktree作成

# 分離されたWorktree作成
git worktree add .worktrees/issue-270 -b issue-270-feature

Phase 2: コンテキスト設定

各Worktreeに自動生成:

.worktrees/issue-270/
├── .agent-context.json      # 機械可読コンテキスト
├── EXECUTION_CONTEXT.md     # 人間可読指示書
└── [Agent-specific files]

Phase 3: Agent実行

cd .worktrees/issue-270
# Claude CodeがEXECUTION_CONTEXT.mdを読み込み
# Agent固有ワークフロー実行
# Conventional Commitsでコミット

Phase 4: マージ＆クリーンアップ

# ブランチプッシュ
git -C .worktrees/issue-270 push -u origin issue-270-feature

# PR作成またはマージ
gh pr create --title "feat: Issue #270" --draft

# Worktree削除
git worktree remove .worktrees/issue-270
git branch -d issue-270-feature

📊 Agent別最適設定

CodeGenAgent（つくるん）

最適コマンド:

tmux send-keys -t %2 "cd '.worktrees/issue-270' && あなたは「カエデ」です。以下を実行:

1. cargo build --release
2. cargo test --package miyabi-core
3. cargo clippy -- -D warnings

完了したら [カエデ] 実装完了 と発言。" Enter

ReviewAgent（めだまん）

品質スコア基準:

90-100点: quality:excellent
80-89点:  quality:good
70-79点:  quality:fair
<70点:    quality:needs-improvement (要修正)

🛡️ エラーハンドリング

Worktree作成失敗

# 既存Worktree確認
git worktree list

# 古いWorktree削除
git worktree prune

# 再作成
git worktree add .worktrees/issue-270 -b issue-270-feature

マージコンフリクト

# Worktree内でコンフリクト解決
cd .worktrees/issue-270
git status
# [コンフリクト解決]
git add .
git commit -m "fix: resolve merge conflicts"

Agent実行失敗

# コンテキスト確認
cat .worktrees/issue-270/.agent-context.json
cat .worktrees/issue-270/EXECUTION_CONTEXT.md

# 強制再実行
cargo run --bin miyabi -- agent run codegen --issue 270 --force

✅ 成功基準

🔗 関連ドキュメント

📝 関連Skills

• Rust Development: Agent実行前のビルド
• Issue Analysis: Agent割り当て前の分析
• Git Workflow: Worktreeブランチ管理