完成品長什麼樣

本文以一個任務看板為示意：Claude Code、Gemini CLI 和 Codex CLI 分別處理 Node.js／Express 後端、React 前端、PostgreSQL 資料庫與測試。共用規格先提交，再建立三條 Git worktree，讓各 agent 在自己的分支工作。

這是可調整的教學範例，不是已驗證的一次性成果或時間保證。生成內容、依賴、整合步驟與測試結果都要依實際輸出檢查。使用全新、可拋棄的測試資料庫，不要接正式資料。

為什麼要用三個工具

重點是分清工作和交接，不是假設某個模型永遠最強或某種分工一定省錢。你可以用已具備存取資格的其他 CLI，甚至以同一工具的三個 session 練習；每個工具的帳號、權限和費用都要另外確認。

事前準備

Claude Code、Gemini CLI、Codex CLI： 分別依 Claude Code、Gemini CLI 與 Codex CLI 官方文件安裝並驗證資格。
Gemini CLI 存取提醒： Google 轉換公告表示，個人免費及 Google AI Pro／Ultra 的 Gemini CLI 請求自 2026 年 6 月 18 日起停止；驗證文件與額度文件仍列個人帳號及免費額度。官方資訊有衝突，先確認自己的實際資格，不要假設每天 1,000 次免費請求。
Git 2.28 以上，以及依各工具文件安裝的 Node.js 和 Docker。模型用量、Docker 和套件可能有額外成本。
一個新建的練習目錄，以及經確認沒有正式資料的本機測試資料庫。

第一步：建立空專案

以下在家目錄建立新的 taskboard。如果目錄已存在，第一個命令會停止，請改用新名稱，不要覆寫既有專案。Git 必須先設定提交者姓名及 email。

(
  set -e
  mkdir "$HOME/taskboard"
  cd "$HOME/taskboard"
  git init -b main
  printf 'node_modules/\n.env\n' > .gitignore
  git add .gitignore
  git commit -m "init"
)

只有上面的命令全部成功後，才執行 cd "$HOME/taskboard" 繼續。

第二步：撰寫共用規格

啟動任何 agent 之前，先建立共用規格。三個 agent 必須在資料模型和 API 契約上達成一致。少了這個，你會得到三層無法接合的程式碼。三面牆以不同角度交會。

在 main 分支建立 SPEC.md：

# Taskboard — Shared Specification

## Data Model
- **User**: id (uuid), email (unique), name, created_at
- **Task**: id (uuid), title, description (nullable), status (enum: todo/in_progress/done), priority (enum: low/medium/high), assignee_id (fk → User), created_at, updated_at, deleted_at (nullable)

## API Endpoints
- GET    /api/tasks         — 列出所有任務，支援 ?status= 和 ?assignee_id= 篩選
- POST   /api/tasks         — 建立任務（title 必填，status 預設 "todo"）
- PATCH  /api/tasks/:id     — 更新任務欄位
- DELETE /api/tasks/:id     — 軟刪除（設定 deleted_at）
- GET    /api/users         — 列出所有使用者
- POST   /api/users         — 建立使用者

## Conventions
- Backend: Node.js + Express + TypeScript
- Frontend: React 19 + Vite + TypeScript + Tailwind CSS 4
- Database: PostgreSQL 16 with Drizzle ORM
- All API responses: { data: T } on success, { error: string } on failure
- Port: API on 4000, frontend on 3000, DB on 5432

提交到 main：

git add SPEC.md && git commit -m "add shared spec"

提交規格後，再從這個 commit 建立三條新分支及 worktree，確保各自都包含 SPEC.md：

git worktree add -b feature/api ../taskboard-api main
git worktree add -b feature/ui  ../taskboard-ui  main
git worktree add -b feature/db  ../taskboard-db  main

若路徑或分支已存在，先停止並查明，不要覆寫。Worktree 隔開各自的工作目錄，但合併時仍可能衝突。分工時約定 API 寫 backend/、UI 寫 frontend/、資料庫寫 db/ 和 tests/。

第三步：同時啟動三個 Agent

開三個終端面板。用 Termdock 的話，拖拉出三欄配置。一欄一個 agent。三個輸出同時可見。需要關注哪一個就把面板拉大。

面板 1：Claude Code -- 後端 API

cd ~/taskboard-api
claude

> Read SPEC.md. Under backend/, scaffold an Express + TypeScript backend API
> implementing every endpoint in the spec. Include:
> - src/ directory with routes, controllers, middleware, types
> - Error handling middleware with proper HTTP status codes
> - Input validation using zod
> - CORS configured for localhost:3000
> - Docker-compatible: reads DATABASE_URL from env
> - package.json with scripts: dev, build, start
> Do not implement database queries yet — use placeholder functions
> that return mock data matching the schema in SPEC.md.
> We will integrate the real DB layer after merge.

Claude Code 建立專案結構、安裝相依套件、寫 route handler、加 validation schema、設定錯誤處理。多檔案架構工作 -- 正是它推理深度的價值所在。

面板 2：Gemini CLI -- 前端 UI

cd ~/taskboard-ui
gemini

> Read SPEC.md. Under frontend/, scaffold a React 19 + Vite + TypeScript frontend for
> the task management app. Include:
> - Vite config with proxy to localhost:4000/api
> - Components: TaskBoard, TaskCard, TaskForm, UserSelect, StatusFilter
> - Tailwind CSS 4 for styling — clean, minimal design
> - API client module using fetch, typed to match the spec endpoints
> - State management with React 19 use() and context
> - package.json with scripts: dev, build, preview
> Focus on a working Kanban-style board with three columns:
> Todo, In Progress, Done. Tasks are draggable between columns.

請先檢查生成的元件與規格是否一致，再決定是否迭代；實際模型、用量和費用依你的存取方式而定。

面板 3：Codex CLI -- 資料庫 + 測試

cd ~/taskboard-db
codex

> Read SPEC.md. Create the database layer:
> - Drizzle ORM schema matching the data model exactly
> - Migration files generated from the schema
> - Seed script that creates 3 users and 10 sample tasks
> - docker-compose.yml for PostgreSQL 16
> - Connection config reading DATABASE_URL from .env
> - Tests for the DB schema and migrations using vitest.
> - Outline endpoint integration tests for after the API is merged.
>   Test CRUD operations, filters, and soft delete.
> Structure: db/ directory with schema.ts, migrate.ts, seed.ts,
> and a tests/ directory.

Codex CLI 產生結構化、可預測的輸出。Schema 定義、migration 檔案、測試斷言 -- 模版驅動的任務，處理起來穩定可靠。

第四步：監控和調整

三個 agent 同時跑起來。你的角色從寫程式變成審查產出。定期看一下每個面板。

常見需要注意的問題：

型別不一致 -- 如果 agent 發明了 SPEC.md 裡沒有的欄位名稱，馬上修正。共用規格就是為了防止這個，但 agent 偶爾會自行發揮。
Port 衝突 -- 確認每一層使用的 port 和規格一致。
相依套件版本不同 -- 如果 API 和 DB 都安裝了 Drizzle ORM，確認它們鎖定同一個版本。

等待各 session 回報實際完成情況；耗時與結果依專案、模型、權限及環境而異。

用 Termdock 整理整合前的交接

請三個 session 分別回報 worktree、branch、修改的檔案、測試結果和需要其他 session 配合的介面。協調者比對共用規格中的 API 與資料型別，列出不一致後再決定整合順序。若用 Termdock 的 CLI／API 交接，仍要把規格和輸出位置明確送給各 agent；不同對話不會自動共享。先核對各 CLI 的帳號資格與費用，Termdock 不包含模型訂閱。

第五步：合併三條分支

三個 agent 完成後，先在每個 worktree 檢查 git status、diff 和測試結果，確認符合範圍，再由你決定是否將各分支的修改提交。只有各分支確實有對應 commit 後，才回到練習用的 main 合併。

cd ~/taskboard

# 先合併資料庫層，它不依賴其他層
git merge feature/db --no-ff -m "merge: database schema, migrations, seed, tests"

# 合併後端 API
git merge feature/api --no-ff -m "merge: Express API with routes and validation"

# 合併前端
git merge feature/ui --no-ff -m "merge: React frontend with Kanban board"

不同目錄能減少重疊，但不能保證無衝突。合併前確認各 branch 修改內容，遇到衝突時先保留現有資料並逐項處理。

如果出現衝突： 幾乎都是在共用設定檔，例如 package.json 或 tsconfig.json。手動解決 -- 合併三條分支的 dependencies，保留最嚴格的 TypeScript 設定。

第六步：整合串接

三層現在在同一條分支上。但還沒接起來。後端有 mock 資料的 placeholder 函式。前端打 localhost:4000。你需要把真正的資料庫接進後端。

這是一個適合 Claude Code 的專注任務：

claude

> The backend in backend/src/ uses placeholder functions for database queries.
> The database layer in db/ has the Drizzle schema and connection setup.
> Replace all placeholder functions with real Drizzle queries.
> Update the backend to import from db/schema.ts.
> Ensure the docker-compose.yml starts both the API and the database.
> Add a top-level package.json with a "dev" script that starts
> API + frontend concurrently.

檢查 agent 提出的串接、依賴和設定，特別確認只連接測試資料庫，再執行適當測試。

第七步：執行和驗證

先檢查產生的 docker-compose.yml、.env、package.json 和 migration，確認服務、資料庫、埠號和腳本內容。只使用可拋棄的本機測試資料庫；不確定連線目標時不要執行 migration 或 seed。

依產生的實際命令啟動服務，檢查 API 回應、前端操作與資料庫變化，並執行專案現有的單元及整合測試。記錄實際命令、輸出與失敗項目；生成測試檔不代表測試已通過。

工作流總覽

先提交規格，再建立 worktree、分配任務、交接各 branch 的 diff 與測試結果，經檢查後整合並驗證。所需時間與成本依工具、任務及環境而異；本文沒有可驗證的平行速度比較。

套用到你自己的專案

三工具分工可以套用到任何全端架構。原則不變：把每個工具分配到最符合其強項的層級。

不同技術堆疊： Express 換成 FastAPI、React 換成 Svelte、PostgreSQL 換成 MongoDB。Worktree 結構和平行工作流完全一樣。

更多層級： 加第四條 worktree 做基礎設施（Terraform、CI/CD）。分配給最擅長模版驅動設定檔的 agent。

只有兩個工具： 如果你只有 Claude Code 和 Gemini CLI，把資料庫層分配給先完成主要任務的 agent。兩個工具的做法在雙工具策略有完整說明。

共用規格有幫助。 把資料模型與接口寫清楚，再檢查各 branch 的實作是否符合；不能保證不會發生整合問題。

常見問題排除

Gemini CLI 遇到存取或用量限制。 先查看帳號實際可用的驗證方式與供應商用量資訊，再決定等待、手動處理或改用另一個已授權的工具。不要套用舊的免費額度。

Codex CLI sandbox 擋住網路存取。 Codex 預設在沙箱環境執行。如果需要安裝 npm 套件，確認 Codex 設定允許在設定階段存取網路，或啟動 agent 前先安裝好相依套件。

package.json 合併衝突。 最常見的問題。API 和 DB 層可能各自建了 package.json。從一開始就用 monorepo 結構 -- 每一層有自己的目錄和 package.json，最上層再加一個 package.json 放共用腳本。

Agent 忽略 SPEC.md。 有些 agent 會優先使用自己的慣例。如果 agent 把 status 生成為字串而非規格中的 enum，直接修正：「用 SPEC.md 裡定義的欄位型別。Status 必須是 enum：todo、in_progress、done。」

三個 agent。三個終端面板。所有輸出同時可見。拉大需要注意的那個。終端當掉還能恢復 session。這就是有效統籌 agent 和不斷失去脈絡之間的差別。

Danny Huang·Follow on Threads →

#claude-code#gemini-cli#codex-cli#scaffold#fullstack#parallel-development#ai-cli

用 3 個 AI CLI 工具同時建構全端應用程式