Orca ADE 完整指南：多 AI Agent 並行開發與 Git Worktree 實戰

AI
, , , ,
1

學會用 Orca ADE 協調 Claude Code、Codex、OpenCode 等 Agent，透過 Git worktree 實現真正平行開發、Diff 比對與自動化流程，提升團隊產出品質。

Orca ADE 是什麼？

Orca 是 Agent Development Environment（ADE），不是新的 AI 模型，而是一個協調層：把 Claude Code、Codex、OpenCode、Gemini CLI、Cursor CLI 等現有的 Coding Agent 放進同一個工作環境，透過 Git worktree 讓多個 Agent 同時處理不同分支，並集中管理 Terminal、Diff、GitHub、SSH 與行動裝置控制。

關鍵差異：Orca 不提供模型或訂閱，它使用你已安裝並登入的 CLI 工具與既有帳號。

1. 安裝與前置準備

macOS 安裝

brew install --cask stablyai/orca/orca

也可從 官網 或 GitHub Releases 下載。支援 macOS、Windows、Linux，採 MIT 開源授權。

安裝你要用的 Agent CLI

Orca 只負責協調，必須先在系統安裝並登入各 Agent：

# Claude Code
npm install -g @anthropic-ai/claude-code
claude

# Codex CLI
npm install -g @openai/codex
codex

OpenCode、Gemini、Cursor CLI 同理，依官方文件完成安裝與認證。

2. 首次啟動建議順序

  1. 授予 Orca 存取 Home Directory 權限
  2. 匯入現有設定（~/.claude、~/.codex、Terminal 設定）
  3. Add Repo 加入既有本地 Git Repository
  4. 確認 Orca 偵測到 Default Branch（通常是 main 或 master）
  5. 確認 Claude Code、Codex 等 Agent 在 Orca 中可被選取

新專案可從 GitHub Clone 或建立新 Project。

3. 核心概念：Worktree-Native Workflow

Orca 的核心不是開很多 Terminal，而是每個 Agent 都在獨立的 Git Worktree 中工作：

main
├── orca/fix-auth-claude
├── orca/fix-auth-codex
└── orca/fix-auth-opencode

每個 Worktree 擁有獨立檔案與 Branch，多 Agent 可同時修改同一專案，不會互相覆蓋、不需頻繁 Stash。

4. 建立第一個 Agent 任務

  1. 左側 Sidebar 選擇 Repository
  2. 點 Repository 名稱旁 +
  3. 輸入 Worktree/Task 名稱，如 fix-login-race
  4. 選擇起始 Branch/Ref（如 main）
  5. 選擇 Agent（如 Claude Code）
  6. Terminal 輸入任務 Prompt：
Investigate the login race condition.
First inspect the authentication flow and reproduce the issue.
Then implement a minimal fix, add regression tests, and run the relevant test suite.
Do not modify unrelated files.

Orca 會建立獨立 Worktree 並在正確目錄啟動 Agent。

5. 平行執行多個 Agents：比較與交叉驗證

最實用的方式是把同一問題交給不同 Agents，再比較結果。

建立三個 Worktrees

fix-login-race-claude
fix-login-race-codex
fix-login-race-opencode

分工建議

Agent 角色
Claude Code 理解既有架構、提出修正方案
Codex 實作與測試
OpenCode / 其他 提供第二種 Implementation，交叉比較

統一 Prompt 範例

Fix the login race condition in this repository.

Requirements:
- Reproduce or identify the root cause.
- Make the smallest safe change.
- Add regression tests.
- Run lint, typecheck, and relevant tests.
- Explain the files changed and any remaining risks.

完成後可將不同 Worktree 拖曳至左右或上下 Pane，同時觀察進度。Orca 支援 Terminal Tabs、Splits、多 Agent 並行。

6. Review、挑選與合併：別直接 Merge

Agent 完成後，建議流程：

  1. 開啟 Worktree 的 Git Diff
  2. 檢查是否修改不相關檔案
  3. 執行測試、Lint、Typecheck
  4. 比較 Claude Code、Codex、其他 Agent 的實作
  5. 選擇最小、最容易維護的版本
  6. 在 Orca 中 Commit
  7. Push Branch 並建立/更新 Pull Request
  8. 刪除未採用的 Worktrees

Orca 內建 Source Control、Diff Review、GitHub PR、Issues、Actions Checks 整合；部分流程支援在 Diff 上留 Inline Annotation 再送回 Agent。

Commit 前檢查清單

Node.js 專案

git diff --stat
git diff
pnpm test
pnpm lint
pnpm typecheck

Python 專案

git diff --stat
pytest
ruff check .
mypy .

實際指令以專案既有 package.json、Makefile 或 CI 設定為準。

7. Orca CLI：納入自動化 Pipeline

若要把 Orca 放進 CI/CD 或腳本，可使用 Orca CLI（參考 GitHub README）。

基本概念

# 建立 worktree
orca worktree create --base main --name fix-auth-bug

# 在 worktree 執行 agent
orca agent run \
  --worktree fix-auth-bug \
  --agent claude-code \
  --prompt "Fix the authentication bug and add regression tests."

另一 Agent 在不同 Worktree：

orca worktree create --base main --name add-health-endpoint
orca agent run \
  --worktree add-health-endpoint \
  --agent codex \
  --prompt "Add a /health endpoint and tests."

正式寫 Script 前，先執行 orca --help、orca worktree --help、orca agent --help 確認最新參數。

8. 實戰 Workflow 建議：AI Agent / 電商專案分工

Agent 任務
Claude Code 分析大型 Codebase、規劃架構、跨檔案重構
Codex 實作功能、撰寫測試、修正明確 Bug
OpenCode 開源 Agent 第二套方案驗證
Browser / Design Mode 檢查 UI、Landing Page、瀏覽器互動
Reviewer Agent 審查 Diff、找 Security、Regression、Edge Cases

推薦 Prompt Pipeline

Agent 1 — Research:
Analyze the repository and propose three implementation approaches.
Do not edit files.

Agent 2 — Implementation:
Implement the safest approach in this worktree.
Add tests and run validation.

Agent 3 — Review:
Review the implementation for correctness, security, regressions,
performance issues, and unnecessary changes.
Do not modify files unless explicitly asked.

Agent 間協作：寫入 Repo 檔案，別只靠 Terminal History

docs/agent-research.md
docs/agent-review.md

後續 Agent 可讀取前一個 Agent 的分析，所有決策進入 Git History。

9. SSH 與行動裝置控制

SSH Worktrees：在 Remote Machine/VPS 執行 Agent

適合長時間 Build、Scraping、測試、Deployment。

  1. Orca 新增 Remote Machine
  2. 設定 SSH Key 與 Host
  3. 選擇遠端 Repository
  4. 建立 Remote Worktree
  5. 遠端啟動 Claude Code、Codex 或其他 CLI Agent

iOS / Android Companion App

  • 查看 Agent 狀態
  • 切換帳號
  • 接收通知
  • 從手機繼續管理 Terminal Session

10. 常見問題與解決

Agents 找不到

which claude
which codex
which opencode

確認 CLI 已安裝、在 Orca 啟動的 Shell 中可執行、PATH 設定一致。

Git Worktree 建立失敗

git status
git worktree list

常見原因：Branch 被其他 Worktree 佔用、目錄已存在、未完成 Rebase/Merge、Agent 仍在使用、權限或檔案鎖定。

多 Agents 互相干擾

不要讓多個 Agents 共用同一工作目錄。每個獨立任務建立自己的 Worktree；共享資源（Dev Database、固定 Port、.env）需額外隔離。

成本失控

  • Orca 本身不代表免費，使用你既有的 Provider Subscription/API
  • 先用單一 Agent 做 Planning
  • 只對高風險/需比較的任務啟動多 Agent
  • Lint、測試、格式化交給便宜或本地 Agent
  • 大型專案限制同時 Worktree 數量
  • 別讓多 Agent 同時跑 Migration 或 Production Deployment

11. 建議起手式：從最小可行流程開始

階段 1：單一 Agent

安裝 Orca
→ 加入 Git Repository
→ 建立一個 Worktree
→ 啟動 Claude Code 或 Codex
→ 執行任務與測試
→ Review Diff
→ Commit / PR

階段 2：平行比較（熟悉後）

一個需求
→ 建立 2–3 個獨立 Worktrees
→ 使用不同 Agents 平行實作
→ 比較 Diff 與測試結果
→ 選擇最佳方案
→ 合併並刪除其餘 Worktrees

對已習慣 Claude Code、Codex CLI、Terminal-First Workflow 的開發者，Orca 最大價值在於 Worktree Lifecycle、平行 Agent 管理與集中式 Diff Review，而非取代既有 Coding Agent。

結語

Orca ADE 解決了「多 AI Agent 同時改同一專案會互相踩踏」的痛點。透過 Git Worktree 隔離環境、統一介面管理 Diff 與 PR、CLI 可納入自動化、行動裝置隨時掌控，讓團隊能安全地平行實驗、快速交叉驗證、自信地合併。下一步：先跑一個小專案的雙 Agent 比較，體驗 Worktree 帶來的自由度。