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

完成品長什麼樣

三個 AI CLI 工具，三條 git worktree，一個全端任務管理應用程式，30 分鐘內同步建構完成。

最終結果：Node.js/Express API、React 前端、PostgreSQL schema 加上 migration 和種子資料。每一層由不同的 AI agent 同時產生。三條分支合併後，docker compose up 就能跑起來，localhost:3000 看到可用的任務看板。

這篇文章走一遍完整流程。每一行指令都可以直接複製貼上。這個工作流適用於任何全端專案。

為什麼要用三個工具

每個 AI CLI 工具的強項不同。只用一個工具做所有事，要不就是在簡單任務上花了頂級費用，要不就是在複雜任務上忍受較差的產出。

Claude Code 是目前最強的 agent，處理複雜多步驟工作。它也最貴。把它分配給後端 API（架構決策會影響整個應用程式的地方）能最大化投資報酬。

Gemini CLI 免費方案每天 1,000 次模型請求。前端開發需要大量迭代：產生元件、調整排版、修改樣式。用免費額度處理這些工作，而非消耗 Claude Code 的付費額度，是合理的選擇。

Codex CLI 擅長專注、模版驅動的任務。資料庫 schema、migration 檔案、種子資料，結構可預測。Codex CLI 產生這類檔案穩定且快速。

三個工具的完整能力和定價比較，可以參考 2026 AI CLI 工具完全指南。

事前準備

需要安裝的工具：

• Claude Code：需要 Claude 訂閱（Pro 方案 $20/月或 Max 方案 $100+/月）。安裝：curl -fsSL https://claude.ai/install.sh | bash
• Gemini CLI：Google 帳號即可免費使用。安裝：npm install -g @google/gemini-cli
• Codex CLI：需要 OpenAI API key。安裝：npm install -g @openai/codex
• Git 2.20+：支援 worktree
• Node.js 18+ 和 Docker：執行最終的應用程式

所需時間： 建構約 30 分鐘，整合和測試另外 10-15 分鐘。

第一步：建立專案和 Worktree

從空的 repository 開始。

mkdir taskboard && cd taskboard
git init
echo "node_modules/" > .gitignore
git add .gitignore && git commit -m "init"

建立三條 worktree，各負責一層。

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

現在你有四個目錄，共用同一份 .git 歷史紀錄：

~/taskboard           → main 分支（統籌用）
~/taskboard-api       → feature/api（Claude Code）
~/taskboard-ui        → feature/ui（Gemini CLI）
~/taskboard-db        → feature/db（Codex CLI）

每個 agent 有獨立的檔案系統。不會衝突、不會覆寫。Worktree 在多 agent 工作中為什麼必要，完整說明在 Git Worktree 多 Agent 設定指南。

第二步：撰寫共用規格

啟動任何 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

## 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，確保每條 worktree 都能讀取：

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

把 SPEC.md 複製或建立 symlink 到每條 worktree，讓 agent 都能參照。

第三步：同時啟動三個 Agent

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

面板 1：Claude Code → 後端 API

cd ~/taskboard-api
claude

> Read SPEC.md. Scaffold a complete 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、設定錯誤處理。這是多檔案架構工作，正是 Claude Code 推理深度的價值所在。

面板 2：Gemini CLI → 前端 UI

cd ~/taskboard-ui
gemini

> Read SPEC.md. 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.

Gemini CLI 負責高迭代的元件工作。元件不對就重新生，免費的。模型路由器會把簡單的元件生成任務送到 Gemini Flash，速度快。

面板 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
> - Integration tests using vitest: test each API endpoint's
>   expected DB behavior (CRUD operations, filters, soft delete)
> Structure: db/ directory with schema.ts, migrate.ts, seed.ts,
> and a tests/ directory.

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

第四步：監控和調整

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

常見需要注意的問題：

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

多數 agent 在 5-10 分鐘內完成建構。Claude Code 通常花最久，因為後端有更多架構決策。Gemini CLI 通常最快完成，因為元件生成速度很快。

第五步：合併三條分支

三個 agent 都完成後，回到 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"

如果依照規格走，每個 agent 在自己的目錄工作（db/、src/、前端根目錄），這些合併應該不會有衝突。各層佔據不同的檔案路徑。

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

第六步：整合串接

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

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

claude

> The backend in 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.

Claude Code 讀取兩層的程式碼，理解它們之間的契約，然後串接起來。這正是跨邊界、多檔案的工作，也是使用最強 agent 的理由。

第七步：執行和驗證

docker compose up -d db       # 啟動 PostgreSQL
npm run db:migrate             # 執行 migration
npm run db:seed                # 載入範例資料
npm run dev                    # 同時啟動 API + 前端

打開 localhost:3000。你應該看到一個看板，三個欄位，10 個範例任務。把一個任務從「Todo」拖到「In Progress」，PATCH 請求打到 API，API 更新資料庫，UI 反映變更。

執行整合測試：

npm run test

Codex CLI 生成的測試會對真實資料庫狀態驗證每個 endpoint。

工作流總覽

沒有平行化的話，同樣的工作依序做需要 60-90 分鐘。專案越複雜，平行建構省的時間越多。

這裡的工作流和雙工具策略指南描述的平行開發模式相同，只是延伸到三個工具。

套用到你自己的專案

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

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

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

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

共用規格是必要的。 沒有 SPEC.md，三個 agent 會產生資料模型互不相容的三層程式碼。花 5 分鐘寫規格，省下合併後 30 分鐘的除錯。

常見問題排除

Gemini CLI 建構到一半撞到速率限制。 免費方案每分鐘 60 次請求，每天 1,000 次。複雜的建構加上多次迭代會快速消耗額度。解法：用精確的 prompt 減少 agent 的探索行為。如果撞到每日上限，剩餘的建構可以手動完成或交給 Claude Code。注意：2026 年 3 月 25 日起，免費方案的 Pro 模型存取正在收緊，目前的限制可以參考免費 AI CLI 工具比較。

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

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

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

同時跑三個 agent，對應三個終端面板，這就是整個工作流的核心。三個 agent 的輸出同時可見、面板可以拉大縮小聚焦在需要注意的那個、終端當掉還能恢復 session，這就是有效統籌 agent 和不斷失去脈絡之間的差別。