Agent Team 穩定的關鍵：spawn 之前先建好兩份文件

同樣是用 Claude Code 跑 Agent Team，有人的 team 順暢完成、互動極少，有人的 team 一直卡住、不斷要人介入。

差距不在任務複雜度，不在模型，在一件事：有沒有在 spawn agents 之前先建好文件。

為什麼 Agent Team 會卡住

要理解這個問題，先理解 agent 的本質。

當你 spawn 一個 agent，它只知道你在那一刻的 prompt 裡說了什麼。你的對話歷史、你之前說的規則、其他 agent 做了什麼——它全都不知道。

這代表什麼？

如果你沒有把規則寫進文件，你（orchestrator）就是整個 team 唯一的記憶體。你要記住所有規則，要在每個 spawn prompt 裡正確地說一遍，要把 agent A 的結果正確地轉述給 agent B。

這就是卡住的來源：

• Prompt 寫漏一條規則 → agent 做出不符合期望的結果
• Agent A 的結果透過我轉述給 Agent B → 轉述過程中遺漏細節
• 對話太長，舊的 context 被壓縮 → 規則消失
• 某個 agent 失敗重啟 → 什麼都不記得，要重頭說
• 多個 agent 平行跑 → 每個人收到的規則說法略有不同

每一個都是可能的失敗點。越複雜的 team，失敗的機率越高。

讓 Team 穩定的解法：兩份文件

穩定的 Agent Team 做一件事：把所有 agent 需要知道的東西，從對話記憶移到磁碟上的文件。

文件是客觀存在的。所有 agent 讀同一份，規則永遠一致。Agent 失敗重啟，讀一遍文件就恢復。多個 agent 平行跑，各自讀文件，不需要我轉述。

需要兩份文件，職責不同：

文件	寫什麼	類比
CLAUDE.md	專案現況：ID、路徑、已完成的項目、已知問題、版本	新人入職的專案交接文件
AGENTS.md	團隊規則：誰做什麼、如何交接、鐵律、失敗怎麼處理	公司的工作手冊

CLAUDE.md 要寫什麼

寫所有「agent 每次都要重新查，但其實不需要查」的東西：

# 專案名稱

## 關鍵 ID 和路徑
- WordPress 分類 ID：失智照顧=76、家屬心聲=78
- 已發布文章：[Post ID 清單]
- 輸出目錄：./content/drafts/

## 技術環境
- 使用版本：XXX
- API endpoint：[測試] / [正式]

## 已知的坑
- 台灣失智症協會網站用 http:// 不支援 https
- 這個 API 的日期格式是 YYYYMMDD 不是 ISO 8601

## 已完成 / 待處理
- ✅ 已完成：XXX
- ⚠️ 待處理：YYY

沒有 CLAUDE.md，agent 每次都要重新查分類 ID、確認文章有沒有發過、試連結通不通。每一步都是潛在的失敗點。

AGENTS.md 要寫什麼

AGENTS.md 有四個必要部分：

1. 鐵律（所有 agent 不可違反）

## 鐵律
- 所有醫療資訊必須附上可驗證的來源 URL
- 不能修改 iDempiere core 代碼，只能在 plugin 層擴充
- 沒有測試的代碼不算完成

2. 每個 agent 的定義

### researcher（研究員）
職責：搜尋資料，每筆資訊必須記錄來源 URL
工具：WebSearch, WebFetch, Read
輸出格式：[明確定義]

3. 交接協議（最關鍵、最常被忽略）

## 交接協議
researcher 完成 → 存到 ./drafts/research-[topic]-[YYYYMMDD].md
writer 開始前  → 必須讀取上面那個檔案
writer 完成   → 存到 ./drafts/article-[topic]-[YYYYMMDD].md
publisher 開始前 → 讀取 article 檔案，驗證 References 後才發布

4. 失敗處理規則

## 失敗處理
- 找不到可信來源：停止，回報「無法找到符合鐵律的來源」，等待指示
- 需求不清楚：列出疑問，等確認後再開始，不要自行假設
- 任何 agent：遇到不確定的事，停下來問，不要猜

具體案例：iDempiere 台灣統一發票 Plugin

用一個真實場景說明這套做法。假設要用 Agent Team 開發一個 iDempiere 的台灣統一發票 plugin，team 成員是 PM、RD、架構師。

CLAUDE.md（專案現況）

# iDempiere 統一發票 Plugin

## 技術環境
- iDempiere 版本：11.0，Java 17
- Plugin 目錄：/path/to/plugin
- 財政部電子發票規格書版本：5.0（2025年）

## 已知 iDempiere 約束
- Callout 用 @Callout annotation（見 idempiere-callout-generator skill）
- 不能用 Spring，只能用 OSGi service
- DB 操作只能透過 PO 或 DB class，不能直接 JDBC

## 已完成的模組
- ✅ 發票開立
- ⚠️ 作廢（待測試）
- ❌ 查詢（未開始）

AGENTS.md 的交接協議

## 新功能開發流程

pm 寫需求 → 存到 ./specs/req-[feature].md
    ↓
architect 設計 → 讀 req 檔案 → 存到 ./specs/arch-[feature].md
    ↓
rd 實作 → 讀 req + arch 檔案 → 代碼 + ./specs/impl-[feature].md
    ↓
architect review → 讀 impl 摘要 → 存到 ./reviews/review-[feature].md

每個 agent 知道自己要讀什麼、存到哪裡。PM 和 RD 不需要「對話」，他們透過檔案交接。Architect 不需要等 PM 說完才知道需求，直接讀需求檔案。

每次 spawn agent 的啟動句

請先閱讀 CLAUDE.md 和 AGENTS.md，
確認你的角色、鐵律和交接路徑後再開始工作。

這一句話讓 agent 在開始工作前自己去讀規則，不需要我每次重複說一遍。

不穩定 vs 穩定：對照表

	沒有文件（常見做法）	有文件（穩定做法）
規則從哪來	我的 prompt（每次可能不同）	AGENTS.md（永遠一致）
專案狀態	我的記憶（可能過時或漏掉）	CLAUDE.md（客觀存在）
Agent 間交接	我轉述（容易漏細節）	實體檔案（完整保留）
Agent 失敗重啟	什麼都不記得	讀文件即恢復
平行跑多個 agent	規則可能不一致	讀同一份文件，完全一致
需要人工介入	頻繁	只在真正需要決策時

標準流程：每次建立 Agent Team 前

1. 建立 CLAUDE.md：寫入專案現況（ID、路徑、已知問題、版本、已完成項目）
2. 建立 AGENTS.md：寫入鐵律、每個 agent 的定義、交接協議、失敗處理規則
3. Spawn agent 時第一句：「請先閱讀 CLAUDE.md 和 AGENTS.md，確認規則後再開始」
4. 交接一律用實體檔案：agent 完成後存到指定路徑，下一個 agent 從那裡讀

沒有做完這四步就開始 spawn，你就是在用對話記憶撐整個 team。任務越複雜，遲早會卡住。

常見問題

Q：簡單的任務也需要這兩份文件嗎？

一個 agent 做一件事，不需要。兩個以上的 agent 有交接，就需要。判斷標準很簡單：如果你需要「把 A 做完的東西交給 B」，就要用文件定義這個交接。

Q：CLAUDE.md 和 AGENTS.md 要多詳細？

CLAUDE.md：詳細到「新加入的 agent 不需要問任何問題就能知道專案現況」。AGENTS.md：詳細到「每個 agent 知道自己的輸出要存到哪個路徑」。最常被忽略的就是交接路徑，這是 team 失敗最常見的原因。

Q：文件要每次重寫嗎？

AGENTS.md 的團隊結構通常固定，一次寫好後很少改。CLAUDE.md 的專案狀態會變，每次任務完成後更新「已完成項目」。把更新 CLAUDE.md 當作任務完成的一部分，下次 team 啟動時文件就是最新的。