AI Agent 從零到一：一個人點樣用 Claude Code 起一個完整嘅自動化系統

🛠️ 「一個人加幾隻 AI agent，就夠做到以前成個團隊先做到嘅嘢。」呢句話你聽過好多次。但實際上，大多數人嘅「AI agent」只係一個 chat window 加幾個 prompt template。

呢篇講點樣由零開始，用 Claude Code 起一個真正嘅 multi-agent 自動化系統。唔係理論，係我哋跑咗兩個月、踩過晒啲坑之後嘅實戰架構。

第一步：點解一個 Agent 唔夠

最初嘅版本好簡單——一隻 chief agent 做晒所有嘢。收 Telegram 訊息、改代碼、寫文、做研究、管知識庫。聽落好高效，實際上有兩個 fundamental 限制：

Context window 擁擠。Chief 嘅 system prompt 已經塞滿 routing rules、daily memory、Telegram thread mapping、session history。再叫佢 read 一個八百行嘅 module 做 code review，佢嘅 working memory 就會被代碼擠走 routing logic。下次收 DM，reply 質素明顯跌。

Git index 衝突。一個 agent 改一個 repo，冇事。兩個 agent 同時改同一個 repo，git index 只有一份，git add 一定撞。我哋第一次試 parallel dev，三隻 agent 同時做同一個 repo 嘅三條 feature，結果 commits 撞晒——admin 嘅 untracked files 混入 qbank branch，花成個鐘 salvage。

呢兩個問題唔係 bug，係 architecture limitation。解法唔係寫更好嘅 prompt，係拆開佢。

第二步：五隻 Agent 嘅 Topology

拆法好直觀：

Agent	角色	專長
Chief（阿貓 🐱）	COO / Router	收訊息、routing、review、ship
Dev（阿犬 🐕）	Engineer	Code change、debug、deploy
Writer（阿鶴 🦢）	Content	Blog、README、documentation
Researcher（阿鷹 🦅）	Analyst	Research、comparison、analysis
Librarian（阿蜂 🐝）	Knowledge	URL archival、knowledge base

Chief 唔寫 code、唔寫文、唔做研究。佢嘅工作係三件事：收 → 分 → 審。收到 Vincent 嘅訊息，判斷交畀邊隻 agent，等結果返嚟做 quality gate，approve 就 ship。

每隻 agent 有自己嘅 IDENTITY.md，定義佢嘅 persona、tools、同 output format。Chief 讀過 identity file 先 spawn agent，確保 brief 同 agent 嘅 capability match。

點解唔係兩隻就夠？

理論上 Chief + Dev 就可以做到大部分嘢。但實際跑起來，Dev 處理 code 嘅時候收到 research request，佢嘅 context 就會被研究資料污染。Researcher 嘅 system prompt 教佢做嚴謹分析，Dev 嘅 system prompt 教佢快速 ship——兩個 persona 嘅 bias 相反，放同一個 agent 入面會 hedging。

一隻 agent 一個 persona 一個 bias——呢個係 multi-agent 嘅核心 design principle。

第三步：Git Worktree 解決平行開發

派多隻 agent 做嘢，第一個撞嘅就係 git。

Git 設計上係 single working tree——.git/index 只有一份。三個 process 同時 git add，file staging 一定交叉污染。唔係 agent 蠢，係 git 本身嘅限制。

解決方法係 git 自己提供嘅 worktree：

git worktree add ../project-wt-a feature/a
git worktree add ../project-wt-b feature/b
git worktree add ../project-wt-c feature/c

一個 repo，三個獨立 checkout，三份獨立 .git/index。三隻 Dev agent 各自喺自己嘅 worktree 開 branch、commit、push，完全唔會踩腳跡。

Chief spawn agent 嘅時候，brief 入面寫明 cwd = ../project-wt-a。Agent 做完，Chief 統一 merge 入 main。

唔記得開 worktree 嘅後果：PR 表面睇 OK，但有 file 入錯 branch，要 git reflog 救返。Worktree 嘅成本只係多打一條命令，但唔用嘅 cost 係幾個鐘嘅 salvage 工作。

第四步：Background Mode 解決阻塞

Worktree 解決 git 撞嘅問題，但仲有一個隱蔽嘅 trap。

Chief 用 Agent tool spawn 兩隻 Dev agent，兩隻都係 foreground call。表面上係 parallel，實際上 Agent tool 嘅 foreground call 會 block 到 child agent 完成為止。即係話 Chief 表面 parallel spawn，實際上係兩個 foreground wait 串起嚟。

期間 Vincent send DM，Chief 完全 unresponsive——因為佢被兩隻 foreground agent block 住。

正解：run_in_background: true。Background mode 即刻 return control 畀 Chief，agent 喺 background 跑，完成時 push notification 入 Chief 嘅 next turn。

規則好簡單：

• Project topic 嘅 dev task → run_in_background: true by default
• Foreground 只用喺 agent output 係 Chief 下一步嘅 literal input 嘅情況

第五步：Telegram 做 Control Plane

Agent 做完嘢，結果去邊？答案係 Telegram group forum topics。

我哋嘅 Telegram group 有兩類 topic：

Function topics（按角色）：

• General（Chief 阿貓）
• Dev（阿犬）
• Writer（阿鶴）
• Research（阿鷹）
• Knowledge（阿蜂）

Project topics（按項目）：

• 每個 major project 一個 topic

Chief 收到 Telegram 訊息，睇 message_thread_id 判斷去邊。Function topic → delegate 畀對應 agent。Project topic → Chief ack → spawn Dev agent with project 嘅 cwd + independent worktree + background mode。

Agent 完成後，report 發喺對應嘅 topic，唔係發 DM。Vincent 想睇進度就去 topic 睇，唔想睇就 mute。呢個就係 async communication 嘅 design——push 通知用 DM，progress 用 topic。

第六步：Knowledge Ingest Pipeline

最容易被忽略但最有 compounding value 嘅一塊。

每日睇到有用嘅 URL，唔需要即時處理：

1. Append 到 knowledge/.inbox（一行一個 URL）
2. Cron 每 5 分鐘 poll → Librarian agent 處理
3. Librarian 分析內容 → 寫 structured markdown → 歸類
4. 每朝 07:00 daily digest → DM summary + follow-up suggestions

呢個 pipeline 嘅關鍵係非阻塞——你 send URL 嘅時候唔需要等分析完，cron 喺背景跑。日積月累，knowledge base 從十幾條變到八百幾條，而你嘅 attention cost 接近零。

用嘅係 Karpathy LLM Wiki pattern：LLM 做 mechanical work（ingest、formatting、cross-reference），人定 schema 同 structure。當 wiki 出錯，你 review 嘅係具體嘅 markdown content，唔係模糊嘅 embedding similarity。

第七步：Memory 三層結構

Agent 做完嘢之後，經驗點保留？

memory/daily/{YYYY-MM-DD}.md    — 當日手寫精煉 log
memory/weekly/                  — 每週摘要
memory/long-term/               — 累積 patterns + lessons

Daily log 係 agent 完成 significant task 後即刻寫嘅，唔係等收工先做。每條 entry 回答三個問題：做咗咩、學到咩、下次點做。

Weekly digest 由 cron 自動生成，壓縮一週嘅 daily log 成 key insights。Long-term 係手動 curate 嘅 patterns——routing 偏好、常見錯誤、architectural decisions。

Memory 嘅設計原則：file-based、git-backed、human-readable。冇 database、冇 vector store、冇 infrastructure。Git history 就係你嘅 audit trail。

第八步：實際 Throughput

呢套 topology 跑起嚟嘅實際效果：

Single-agent serial：一晚最多一條 PR + 回覆 DM Multi-agent parallel：一晚三條 PR + 回覆 DM + 跑 knowledge digest + ack cross-project ticket

3x throughput 嘅前提係三條 brief 真係 independent，唔可以有 A 等 B 嘅 dependency。Chief 嘅核心 routing decision 就係判斷每條 task 食唔食得切片。

Setup Cost

• Context 設計（CLAUDE.md、memory 結構）：2-4 小時
• 第一次 delegation（寫 sub-agent CLAUDE.md）：3-5 小時
• 之後每次 routing：15-30 分鐘 overhead
• 月度維護（memory cleanup、routing review）：~2 小時

常見失敗模式

1. Chief 自己寫 code：context 膨脹 → routing 質素跌
2. 唔開 worktree：git staging 交叉污染 → 花鐘頭 salvage
3. Foreground block：Chief 被 agent block → DM unresponsive
4. 冇 daily log：同一個錯重複犯 → 冇 learning loop
5. Knowledge inbox 唔用：URL 即時處理 → token 浪費 + 中斷 flow

對比市面方案

特性	AgentOS (file-based)	CrewAI	AutoGen	LangGraph
Infrastructure	零	Python + pip	Python + pip	Python + pip
Memory	File-based + git	In-memory	Conversation	Checkpoint
Multi-agent	Agent tool + worktree	Role-based	Conversation	Graph-based
Observability	Git history + daily log	Limited	Chat log	LangSmith
Learning curve	Medium	Low	Medium	High
Production-tested	2 months, daily use	Community	Maintenance mode	Active dev

揀邊個視乎你嘅 priority。要最低 infrastructure，file-based。要最好 observability，LangGraph + LangSmith。要最快起手，CrewAI。

Stance

Multi-agent 唔係 trendy，係 git 同 LLM context window 嘅自然推論。一個 working dir 一個 chief 一個 context，做唔到 parallel。分頭做，先有 throughput。

Subagent、worktree、background 三件事疊埋一齊，唔複雜，但少咗其中一件就唔 work。呢套系統嘅 setup cost 大約一個週末，但 throughput 嘅 compound effect 會喺第二個月開始明顯。

由一隻 agent 到五隻 agent，唔係加人，係分工。而分工嘅本質，唔係 AI 嘅問題，係 engineering 嘅問題。