從零開始打造 Claude Code 工程團隊（一）：為什麼一個 AI 不夠

這是「從零開始打造 Claude Code 工程團隊」系列的第一篇。整個系列共六篇，從 0 教到能在自己的專案複製這套流程。每一篇都可以獨立讀，但建議照順序。

一個常見的開場故事

新手用 Claude Code 時，最自然的做法就是在主對話視窗裡丟一個需求過去：

「幫我加一個忘記密碼功能。」

接著 AI 開始動，跑 Bash、改檔案、寫測試。十分鐘後它說「完成了」，你打開瀏覽器，發現按鈕長對了、流程跑得起來。看起來成功。

但兩天後你會碰到至少一個下面的狀況：

1. 某個邊界沒被考慮到——使用者輸入空字串，後端直接 500。
2. 改壞了不相關的功能——登入頁的某個小元件因為共用了某段樣式，現在也不能用了。
3. 測試明明寫了卻沒跑過——因為 AI 寫了測試但沒在最後執行，你以為通過了。

這些不是 AI 「能力不足」的問題。同一個模型，換個用法，這些坑都可以閃掉。問題在於你把它當成一個全能員工，而不是一個團隊。

---

把 AI 當成一個人 vs 一個團隊

想像你開一家小公司，從接需求到交付產品全部你一個人做。你會發現：

• 你寫需求時，腦袋還在想昨天的 bug，於是規格寫得有缺漏。
• 你寫程式時，已經沒力氣再回頭挑戰自己的設計。
• 你測試時，會自然避開你「直覺它會壞」的地方——但壞的地方往往就是你不直覺的那邊。

這不是你不夠專業，是單一視角的天然限制。所以真實公司會把這些工作分給不同人：

每一行的「不做什麼」比「職責」更重要。不重疊的職責才能形成真正的檢查點。

把這個結構搬到 AI 身上，就是 multi-agent pipeline 的核心：讓不同的 agent 用不同 prompt、不同上下文、不同 model 處理同一個任務的不同階段。彼此 handoff 時必須對齊產出，不能跨界。

---

六角色 pipeline 鳥瞰

這個系列要教的版本長這樣：

                    [需求進來]
                        │
                        ▼
                       PM ─────► AC + ticket
                        │
                        ▼
                    Architect ──► 三個方案 + 邊界預判
                        │
                        ▼
                    Engineer ──► 實作 + 自我挑戰表
                        │
                        ▼
                    Reviewer ──► breadth scan + plan 對齊
                        │
                        ▼
                       QA ─────► 邊界值掃描 + 跨頁一致性
                        │
                        ▼
                       PM ─────► Phase Gate（過或退）

                  [Designer 旁支]
                  在 visual-delta: yes 時介入
                  讀 Pencil SSOT、輸出 frame 截圖

六個角色是一條主線，Designer 是旁支——只有當需求動到視覺才需要它。後端 bug 修復、純資料邏輯改動、文件 PR 都不要拉 Designer 進來，否則只是噪音。

每個角色都有自己的 persona 檔案（~/.claude/agents/<role>.md），裡面寫明：

• 職責範圍
• Refusal Clause（什麼情況要拒絕）
• Never Do（永遠不做的事）
• Handoff 規則（什麼條件下傳給下一個角色）

這六個角色詳細規則會在 Part 2、Part 3 拆解。

---

三條輔助軌：Agent / Skill / Hook

光有六個角色還不夠。同一條 pipeline 跑久了，你會遇到三類問題：

1. 同一個流程要重跑很多次（例如「收工前先寫 retro 再 commit」）。
2. 同一個錯踩過好幾次（例如「不小心 commit 到 main」）。
3. 不同 agent 之間要有共同的判斷標準（例如「什麼叫做完成」）。

對應的工具：

舉個具體場景。你想要每次 commit 前都先寫 retrospective：

• 用 prompt rule 規定：寫在 CLAUDE.md 裡，agent 大部分時候會記得，但偶爾會忘——因為 LLM 是機率裝置。
• 用 Skill 封裝：寫 /commit-diary skill，內含 Step 1 跑 /retrospect、Step 2 寫日記、Step 3 才 commit。agent 看到 skill 會照做，但人類仍可以繞過。
• 用 Hook 強制：寫 pre-commit hook 檢查 retro 檔案有沒有更新。沒更新就 abort。從工具層擋下來，連繞都繞不過。

哪一條規則該放在哪一層？這是 Part 4 的核心話題，這裡先記得：規則重要程度越高，越往下層放。

---

系列導讀：你會在第幾篇學到什麼

---

給新手的最小起點

如果你剛開始用 Claude Code，不要一開始就導入六個角色。我自己跑了 50 多個 ticket 後才慢慢長出這套結構，倒過來做只會被細節淹沒。

建議的起點：

1. 第一週：只開三個 persona——PM、Engineer、Reviewer。先讓最基本的「需求 → 實作 → 審查」三段跑起來。
2. 第二週：加入 /retrospect skill，每次 PR 收工前跑一次。把踩到的雷記下來。
3. 第三週：加入 pre-edit-branch-check hook，避免直接動 main 分支。
4. 第四週：累積三個同類型的錯誤之後，把 retro 中重複出現的規則升級成 hook。

這個漸進路徑在 Part 6 會展開。先有意識：這套系統不是一次蓋好，是用每個踩過的雷換來的。

---

小結：今天記得這三件事

1. 一個 AI 同時當 PM、Engineer、QA，會因為單一視角漏掉很多邊界。
2. 六角色 pipeline 用不重疊的職責形成檢查點，每個角色都有自己的 persona 與 Refusal Clause。
3. Agent 是誰、Skill 是 SOP、Hook 是門禁——三層工具負責不同強度的規則執行。

下一篇我們開始拆主線前段：PM 怎麼把模糊需求變成可驗收的 ticket、Architect 為什麼一定要寫三個方案、Engineer 動手前要過哪些檢查。