一個人管十幾個專案的 AI 系統架構 — 不是故事，是技術細節
AI 開發實踐·15 分鐘

一個人管十幾個專案的 AI 系統架構 — 不是故事，是技術細節

17 個專案、53 個 agents、142 個 skills、34 個 hook scripts，一個人跑起來。不是用了什麼神奇工具，是系統架構設計的問題。這篇文章把所有技術細節攤開來講。

Y
Young Tsai

這篇不寫故事，直接講架構——如果你想知道「一個人怎麼管那麼多專案」，答案不是時間管理術，不是優先順序矩陣，而是系統設計，以下是這套系統的完整技術細節

現況數字

  • 17 個專案
  • 53 個 agents
  • 142 個 skills（可被任何 agent 呼叫的可重用 SOP）
  • 8 個 hook events、25 條 hook 規則、34 個 hook scripts
  • 17 個 official plugins 啟用

這不是什麼特別炫耀的數字，這是系統跑到今天自然累積的規模，而且大多數時間它在背景安靜地工作，我不需要主動管它

三層知識架構

這是整個系統最核心的設計決定，理解了這個，其他東西都是延伸

CLAUDE.md（路由層）Agent（小抄層）Skill（手冊層）

第一層：CLAUDE.md = 路由

CLAUDE.md 回答的問題是：遇到 X，找誰？

概念上它長這樣：遇到 bug → 派給 bug-fixer agent，遇到 #N issue → 派給 git-issue-pr-flow agent，主 agent 禁止自己動手——每條規則背後都有一個具體的 postmortem

CLAUDE.md 不存放知識，它存放路由邏輯——把技術細節放進去是常見錯誤，後果是文件越長越臃腫，AI 讀到後面注意力早已稀釋，每一條規則的份量都被稀掉了

第二層：Agent = 專案小抄

每個專案有自己的 agent，只存放該專案特有的知識：技術棧、部署方式、哪些 API 怎麼打、業務邏輯的邊界

每個 agent 文件的結構很簡單：專案概述（技術棧、部署方式）、特殊業務邏輯（這個專案有但別的沒有的規則）、邊界條件（例如隱私限制、時間限制），不超過一頁

關鍵是：agent 只存放這個專案有、其他專案沒有的東西，共用規則在 CLAUDE.md 繼承，不重複寫

這讓每個 agent 文件保持精簡，AI 讀到的都是有效資訊

第三層：Skill = 完整 SOP 手冊

Skill 是可被任何 agent 呼叫的標準作業程序

/bug-fix-sop — 7 步驟 bug 生命週期（reproduceroot causefixverifyPR）/git-branch-strategy — 分支策略設定 SOP/frontend-design — 單次 UI 生成（不走完整 design flow 時）/quick-verify — Chrome MCP 快速驗證（2-5 分鐘）/prd-workflow — BDD 需求規格撰寫流程

一個 skill 一件事，寫清楚就可以跨所有專案重用，不用每個 agent 各自記一份

視窗職責分離

現在有兩種 terminal 視窗在跑：

指揮部視窗（young_job_maanger repo）扮演唯讀角色：讀狀態、建 GitHub Issues、分發任務，不改代碼、不 commit、不 push 到任何前線專案

前線視窗（各專案 repo）負責執行：寫代碼、跑測試、commit、push

這個分離不是形式，是強制的——指揮部的 CLAUDE.md 明確列出禁止動作清單，不能改別的專案的代碼、不能代替前線 commit/push，違反的話 hook 會攔截

這樣做的原因其實很直覺：一個視窗裝不下所有專案的上下文，強迫分離反而讓每個視窗的 AI 更精準

同步流程：Haiku 平行掃描

每次需要掌握所有專案狀態，不是一個 agent 跑 17 個專案，而是同時派出 17 個 Haiku subagents，各自回報：

Phase 1: sync all↓ 平行啟動 17 個 Haiku subagents↓ 每個 agent: gh issue list + gh pr list + git log↓ 匯回指揮部Phase 2: 分類派發↓ 建 GitHub Issues 到各專案Phase 3: 各專案視窗執行Phase 4: 下次 sync偵測完成循環

為什麼用 Haiku？這是純讀取任務，不需要推理深度，Haiku 夠快夠便宜，Sonnet 或 Opus 跑這種任務是資源浪費

Hook 系統：自動守衛

Hook 是整個系統最容易被忽略、也最有效的部分

現在啟用的 8 個 hook events：

PreToolUse — 工具執行前攔截PostToolUse — 工具執行後記錄Stop — agent 宣告完成時Notification — 需要人工確認時...

關鍵 hook 規則舉例：

舉幾個例子說明 hook 的作用，不講具體實作：

  • 分支保護：直接 push 到 main/staging？Hook 攔截，強制走 PR
  • GCP 自動切換：不同專案用不同 GCP 帳號，根據目錄自動切換，不用手動 gcloud auth
  • 驗證守衛：agent 說「完成了」但沒附 proof（截圖、curl response、commit hash）？攔截，要求先驗證
  • Code review 追蹤：寫了 code 但沒跑測試？記錄下來，防止跳過

這些 hook 不是建議，是物理限制，AI 在壓力下走捷徑是可預測的行為，hook 的作用是讓某些捷徑在技術上無法執行

Agent 策略選擇

這是最常被用錯的地方

不是 agent 越多越好，而是用正確的策略對應正確的場景：

場景策略原因
讀 1-3 個檔案回答問題Direct tools不需要 agent
掃描 17 個專案狀態Task() subagents平行、獨立、無交叉
Bug 調查 → 修復 → 驗證單一 Task()循序、不需平行
後端改動影響前端Agent Teams需要情報共享

Agent Teams（讓多個 agent 互相協作）大約是 Task() subagents 的 3.5 倍 token 成本，用在不需要跨 agent 協調的場景是純粹浪費

Bug 路由：一個痛苦的 postmortem

2026-02-16 的事故：一個前端 bug，我（主 agent）開始自己讀代碼分析，花了 10 分鐘讀程式碼，但沒有打開瀏覽器，沒有重現 bug，後來發現用戶 30 秒就能在瀏覽器看到問題的所在

這個事故讓我在 CLAUDE.md 寫下：

NEVER investigate bugs directly主 agent 禁止自己讀代碼分析 bug。必須 spawn bug-fixer。即使「只是看一下」也不行，因為看一下分析修了忘了重現沒截圖。

現在的 bug 路由是：

收到 bug 報告↓spawn bug-fixer agent↓bug-fixer: 重現root causefix（Steps 1-6）↓git-issue-pr-flow: branchPRIssue 留言（Step 7）

主 agent 不讀代碼，不分析，只派發，這違反直覺，但效果比「自己先看一下」好很多

前端 bug 驗證有兩階段：

  • Phase 1（必做）：quick-verify skill — Chrome MCP 快速驗證（2-5 分鐘）
  • Phase 2（需要時）：frontend-bug-verification — Playwright 完整驗證（10-15 分鐘）

Issue-Based Development：另一個 postmortem

2026-02-22 的事故：#31 UI fix 直接在 main 上改，沒有建 worktree、沒有建 branch、沒有開 PR、沒有部署 preview，CLAUDE.md 當時沒有明確規定 feature 要走 git flow，hook 也沒有攔截

現在的規則：

Issue-Based Development (CRITICAL):ALL #N issue work MUST use git-issue-pr-flow agentFlow: worktreefeature branchimplementationPRdeploy previewNEVER edit code directly on main/staging

git-issue-pr-flow agent 是一個標準流程 agent，接到任何 #N issue 任務就自動建 worktree、建 branch、push、開 PR，執行代碼的 agent（backend-developer、frontend-developer）只管寫代碼，不管 git 流程——職責分離到 agent 層級

Single Source of Truth

所有專案的 metadata 存在一個地方：projects-registry.json

{
  "projects": [
    { "id": "project-a", "status": "active", ... },
    { "id": "project-b", "status": "active", ... },
    { "id": "project-c", "status": "shelved", ... }
  ]
}

每個專案條目包含路徑、repo、部署設定、狀態，所有 agent 都從這個檔案讀取，不允許任何 agent 在自己的定義裡寫死任何值

好處：改一個地方，全部更新

什麼有效，什麼沒有

有效的：

  • CLAUDE.md 作為路由而不是知識庫——第一版我把所有細節都塞進 CLAUDE.md，讀到後面 AI 注意力掉了；現在 CLAUDE.md 只有路由邏輯和邊界規則，細節下放到 agent 和 skill，精簡很多
  • Hook 作為物理限制而不是提醒——貼「請記得建 PR」的提醒沒有用，hook 攔截才有用
  • Agent 繼承架構——共用規則在 CLAUDE.md，agent 只存專案特有知識，53 個 agent 的維護成本因此可控，不用每個 agent 重複維護同一份規則
  • Haiku 跑 sync 任務——便宜、快、夠用，這種純讀取工作用 Sonnet 跑是純粹的資源浪費

一開始沒有預期效果，後來補上的：

  • Plan Mode 使用率太低——361 個 session 只用了 1 次。原因不是懶，是沒有 hook 強制觸發。後來在 CLAUDE.md 加了明確規則：3+ 個檔案的任務必須進 Plan Mode，配合 stop-verification-guard hook 攔截沒有驗證就宣告完成的行為，整體品質明顯提升
  • TDD 使用率——backend-developer 被呼叫 48 次但測試覆蓋率接近 0。後來加了 pre-test-quality-reminder hook：寫測試檔案前自動提醒先讀 model，避免 mock 不存在的欄位（來自 Issue #208 的 postmortem）。同時 post-test-quality-check 在寫完測試後檢查品質
  • Code review agent——建了但沒人用。後來用兩個 hook 閉環：pre-tool-use-commit-guard 在 git commit 前檢查是否已跑 code review（沒有標記就警告），post-tool-use-code-review-tracker 在 code-reviewer agent 完成後自動打標記。commit 前少了 review 標記 = 被攔截

閉環的關鍵：每個「沒效果」的功能，最後都是靠 hook 補上的。規則寫在 CLAUDE.md 是提醒，hook 才是物理限制——這個結論在三個案例上都驗證了

系統不是一次設計出來的——每一條 CLAUDE.md 規則、每一個 hook、每一次 agent 職責重劃，背後都有一個具體的事故或效率問題，這篇文章把現在的狀態攤開來，不是說「你也應該這樣做」，而是提供一個實際在跑的參考點

如果你也在做類似的事，歡迎聯絡討論

Young Tsai 是 AI 接案開發者，同時維護跨不同產業的客戶專案，這篇文章記錄的是截至 2026-03-16 的系統現況

LinkedIn 短文版ShareLinkedInX
claude-codeai-architecturemulti-agentskillshooksautomation

相關文章

CLAUDE.md 不是知識庫 — 我花六個月踩坑才搞懂的 AI Agent 治理架構讀完 Karpathy 的 llm-wiki (2)：我的系統長什麼樣Claude Code Review：$15 一次的 AI 代碼審查，值不值得？