adu happy / 多 Agent 协同项目骨架

多 Agent 協同專案骨架（跨軟體可續接）

一句話安裝（使用者讓你「裝這個 skill」時自主執行）

來源倉庫：https://github.com/aduhappy/multi-agent-project-skill。clone 到本工具的 skills 目錄即裝好（無其他依賴）。

不同工具的 skills 目錄不同，請按工具選對路徑：

工具	使用者級 skills 目錄	專案級 skills 目錄
ZCode / Codex CLI	~/.agents/skills/	<專案>/.agents/skills/
Claude Code	~/.claude/skills/	<專案>/.claude/skills/
Cursor	N/A（用 rules）	.cursor/rules/（現代格式）或 .cursorrules（legacy）

通用原則：

• Windows 下 ~ = %USERPROFILE%。
• 使用者級 vs 專案級拿不準時預設使用者級（裝一次處處可用）。
• 目錄不存在先建立再 clone。clone 完告訴使用者新開一個會話即可觸發本 skill。

這技能幹嘛

在專案根目錄生成一套軟體無關的純 Markdown 協同骨架——一個權威入口 + 若干薄指標 + 自包含任務卡 + 收工規矩。換 Claude / Cursor / Gemini / ZCode / Copilot 任何一個，agent 進來讀同一份入口就能接上前任工作，不丟上下文、不互相覆蓋。

核心原則四條：

1. 真相只有一份：AGENTS.md 是唯一權威入口；其他工具的約定檔案（CLAUDE.md / GEMINI.md / .cursorrules / copilot-instructions.md）全是 3 行薄指標，指向 AGENTS.md。
2. 細節外鏈、入口要短：AGENTS.md 控制在 1–2 屏，每個新 agent 都得讀完。細則下沉到 文件/ 下的專題文件，入口只放指標。
3. 純 Markdown + 相對路徑：不依賴任何軟體專屬語法，換工具不破。
4. 信任但驗證：agent 自檢不夠——關鍵產物必須由主控或另一 agent 獨立抽驗（守恆/邊界/格數/量級/一致性）通過才進下一棒。這是多 agent 鏈路可信的基石。

何時觸發

• 使用者說「開新專案/新課題」「怎麼組織文件讓 AI 協同」「AGENTS.md 怎麼寫」「多個 agent 接力」。
• 現有專案 agent 經常問重複問題、找不到狀態、覆蓋彼此產出。
• 使用者要把「手工總結的協同經驗」固化成可複用結構。

怎麼用（兩種模式）

模式 A：從零生成骨架

1. 問清（一次性問全，別擠牙膏）：專案根目錄、一句話目標、要相容哪些 AI 工具、是否雲端同步目錄、涉及哪些資料來源。
2. 加問一條硬約束清單：「列出本領域『不可混用』的維度（口徑/單位/座標系/解析度/時期/林齡分層等）。寫成硬規則，後續所有 agent 必須遵守。」——這是最常被忽略但一錯就全錯的鐵律。
3. 從 assets/ 複製 AGENTS.md 到根目錄，填入使用者給的內容。
   • 佔位符規則（重要）：使用者明確給的資訊直接填；使用者沒給的，優先給合理預設值（基於專案主題推斷）並簡短標註「預設值，可改」；只有「使用者特有的、沒法合理推斷」的細節（如具體 DOI、密碼、帳號）才留 【待填】。判據：AGENTS.md 正文裡 【待填】 越少越好，理想是 0 個。
4. 按使用者勾選的工具，複製對應薄指標檔案（CLAUDE.md / GEMINI.md / copilot-instructions.md 等），內容統一是「以 AGENTS.md 為準」；Cursor 使用者推薦用 .cursor/rules/multi-agent.mdc（現代格式），.cursorrules 為 legacy 備用。使用者沒勾的工具不要生成。
5. 建 文件/任務規劃_<主題>.md（從 assets/任務規劃_模板.md 複製）。如果專案有多個任務卡，同時拷入 assets/任務卡_README.md（任務卡目錄索引模板，列依賴鏈和目前狀態）。每張任務卡末尾自帶『📋 派發提示詞（複製即用）』區塊——把卡裡欄位填進去，使用者複製即可貼給任何 agent 冷啟動執行，不用每次重寫委派話術。建卡時順手填好這段。
6. （可選）按需建：文件/委派任務模板.md（從 assets/委派任務模板.md 複製，給主控 agent 派活用）、文件/決策記錄/（存放 ADR）、文件/詞彙表.md（專案術語）。注意：這些是可選模板，小專案跳過，別讓入口變臃腫。
7. 推導資料集目錄：從使用者描述的資料來源拆分——每類資料一個目錄（例：使用者說「MODIS + Landsat」→ 建 MODIS/ 和 Landsat/ 兩個目錄；使用者說「問卷 + 實測」→ 建 問卷/ 和 實測/）。每個資料集目錄放 來源.txt（從 assets/來源.txt 複製）。沒明確資料來源的專案可跳過這步。
8. 程式碼歸位：建 scripts/ 目錄 + scripts/README.md（從 assets/scripts_README.md 複製）。把使用者已有的腳本列表填進去（如果有），或留空等後續 agent 填充。同時拷入 check_handoff.py（從 assets/check_handoff.py 複製）——收工交接自檢腳本，agent 每次收工跑 python scripts/check_handoff.py 驗證 §3/§4/STATUS 已更新。在 AGENTS.md §5 鐵律裡約定「腳本不散落根目錄」。
9. 建 STATUS.md（從 assets/STATUS.md 複製）——空模板，第一個 agent 收工時填增量 handoff（本 agent 做了什麼/動了哪些檔案/踩了什麼坑）。
10. 把使用者的環境、約束寫成 §鐵律、§路徑約定。
11. 跑完後告訴使用者：骨架生成了哪些檔案、有哪些「預設值」需要他確認、有哪些 【待填】 需要他補。

模式 B：診斷已有專案

B1：爛專案修補（零文件或文件混亂）

使用者已有專案但協同亂——agent 反覆問重複問題、互相覆蓋、找不到狀態。先讀現有 README/任何文件/目錄結構，對照 §檔案骨架 和 §AGENTS.md 的區塊 檢查缺什麼，給出全量修補清單（缺薄指標？入口缺失？任務卡不自包含？沒來源.txt？沒收工規矩？）。使用者確認後補齊。先讀後改，絕不直接覆蓋已有檔案。

B2：好專案增強（已有好文件，只缺薄指標）

使用者已有完善的專案文件（如 AI_COLLABORATION_PLAN.md / README.md / 詳細 wiki），但 AI 工具不會自動讀它（Codex/Claude 預設讀 AGENTS.md，不會主動發現自訂檔名）。只加一個 AGENTS.md 薄指標（3 行），指向已有文件；再按使用者勾選的工具加對應的薄指標檔案（CLAUDE.md 等）。不動任何已有文件。判據：加完後，新 agent 進門 → 讀 AGENTS.md → 跳轉到已有文件 → 獲得完整上下文，無需使用者手動說「先讀 XX 檔案」。

檔案骨架（生成後長這樣）

<專案根>/
├── AGENTS.md                          ← 唯一權威入口（頂部 TL;DR 3 行 + 七區塊，所有工具預設讀）
├── STATUS.md                          ← 增量 handoff（本 agent 做了什麼/動了哪些檔案/踩了什麼坑，收工落盤）
├── CLAUDE.md                          ← 薄指標 → 「以 AGENTS.md 為準」
├── GEMINI.md                          ← 薄指標（同上，可選）
├── .cursorrules                       ← 薄指標（Cursor 用，可選）
├── .github/copilot-instructions.md    ← 薄指標（Copilot 用，可選）
├── 文件/
│   ├── 任務規劃_<主題>.md             ← 自包含任務卡（含「交付前必做」清單 + 可選建議模型）
│   ├── 任務卡_README.md               ← 任務卡目錄索引（依賴鏈 + 目前狀態表，可選）
│   ├── 委派任務模板.md                ← 給 AI agent 委派任務的標準話術（複製填，可選）
│   ├── 決策記錄/                      ← 關鍵技術決策（可選，見 advanced.md）
│   └── 詞彙表.md                      ← 專案術語（可選）
├── <資料集名>/                        ← 每個資料集一個目錄
│   ├── 來源.txt                       ← DOI/URL/日期/口徑/單位
│   └── ...
├── scripts/                           ← 程式碼歸位（推薦：腳本不散落根目錄）
│   ├── README.md                      ← 每個腳本一句話：幹嘛/輸入/輸出/誰寫的
│   └── check_handoff.py               ← 收工交接自檢腳本（跑這個驗證 §3/§4/STATUS 已更新）
└── 進度日誌.md                        ← 帶日期戳的變更流水（可選）

AGENTS.md 的區塊（順序即優先級）

照 assets/AGENTS.md 模板填。頂部先有一個 TL;DR 區塊（3 行：目前階段/下一步/阻塞） 讓新 agent 掃一眼就知狀態；下面 8 個區塊（模板編號 1–7，其中路徑約定單獨編號為 §5.5，因為太重要不能和鐵律混在一起）：

0. TL;DR（進門速讀）——3 行：目前階段、下一步、阻塞。每次收工更新。新 agent 不用讀完全文就知道幹到哪了。
1. 一句話北極星——這專案到底幹嘛、給誰、什麼基調（語氣、投稿/交付目標、別耽誤哪條主線）。
2. 目前故事/方法——最新定下來的方向 + 核心方法 + 最近換過什麼、為什麼。
3. 現在在哪——每次收工更新，1–5 條帶日期戳的累計快照。這是接力最關鍵的交接點。增量細節下沉到 STATUS.md，本節只留累計狀態。
4. 任務看板——[ ]/[x] + 誰負責 + 依賴（T1→T2，哪些可並行）+ 已知風險。
5. 鐵律/約定——違反會返工的：環境呼叫、繪圖/資料規矩、命名、口徑、收工規矩。含「新 agent（含子 agent）進門第一件事：讀完 AGENTS.md 再動手」。 5.5. 路徑約定——大檔案去哪、小產物回哪（防多 agent 撞車、防雲端同步爆炸）。單獨成節，別埋進鐵律。
6. 深讀指標——細節去哪個文件（任務細則、決策記錄、詞彙表、任務卡索引）。
7. 環境/工具——完整工具路徑怎麼調、env 鎖。

STATUS.md vs AGENTS.md §3 的分工（防重疊）：STATUS.md 記增量（本 agent 這一輪做了什麼、動了哪些檔案、踩了什麼坑）；AGENTS.md §3 記累計快照（目前整體進度，1–5 條）。兩者不重複——STATUS.md 是「自上次以來的變化」，§3 是「現在整體到哪了」。

決策登記表（強烈推薦，別只當 advanced）：把具約束力的決策用一張有界、可 grep 的表收口——一行一決策：ID | 決策 | 取值/口徑 | 理由 | 日期 | 證據連結 | 取代了誰。放 AGENTS.md §6 指標下，或 §3 緊鄰處。它和散在 STATUS 長敘事裡的自中式 ADR 不同：有界（一決策一行，永遠讀得完）、可查（grep 關鍵字秒命中權威行）、可追（supersedes 鏈）。這是防「決策被埋沒在長日誌裡、或被某個滯後腳本悄悄覆蓋」的關鍵一層。模板見 references/advanced.md §1。

跨軟體能續的硬要求（7 條）

1. 純 Markdown + 相對路徑 + 標準檔案名稱——別用某軟體專屬語法、別硬編碼絕對路徑。
2. 資料帶 來源.txt（DOI/URL/下載日期/口徑/單位/已知問題）——換人換 agent 都能溯源。
3. 收工規矩寫進鐵律——每個 agent 退出前更新 §現在在哪 + §任務看板 + 寫/更新 STATUS.md（增量 handoff：本 agent 這一輪做了什麼、動了哪些檔案、踩了什麼坑，不重複 §3 的全量快照）。收工時跑 python scripts/check_handoff.py 自檢——驗證 §3 日期新鮮、TL;DR 已填、STATUS.md 非模板、STATUS 日期 ≥ §3 日期、薄指標存在；另含兩條 advisory（決策登記表是否存在、多腳本口徑常數是否漂移）。全過才算交接合格。
4. 路徑紀律——「大檔案進工作盤、小產物回倉庫」「複製不剪下，別動別人正在跑的路徑」。
5. 新 agent（含子 agent）進門第一件事——讀完 AGENTS.md（含 STATUS.md）再動手，不靠對話歷史、不憑記憶亂猜。STATUS.md 會越長越沒人讀全——所以任何具約束力的決策（口徑/排除清單/選定參數）必須上浮到 AGENTS.md §3 或決策登記表這層有界、必讀的位置，別只躺在 STATUS 的長敘事裡。取數/建模/復現前先查這層，別去信某個腳本裡的硬編碼。
6. 關鍵數字與口徑參數單一來源、防漂移——關鍵數字（均值/百分比/面積等）只在 STATUS.md 或 AGENTS.md §3 一處寫定，別處只引用不複述。口徑參數/樣本集/排除清單（用哪些點、剔哪些、閾值多少）同理：抽進唯一的 config（config/參數.yaml 或一張權威表），所有腳本讀它、嚴禁在多個腳本裡各自硬編碼——兩個腳本對同一集合編碼不一致，是最隱蔽的接力事故源（自檢看不出、格式檢查也看不出）。收工前核對所有文件與腳本間一致性，同一數字差 1% 以上、或同一集合成員不一致，即視為 bug，必須先對齊再交。
7. 壞產物與被取代的腳本一併退役隔離——發現某 agent 的產物錯了（資料/圖/數字），立即：①目錄改名加 _DEPRECATED 後綴或放入 _作廢/ 子目錄；②在 AGENTS.md §5 鐵律節頂部用紅字 > ⚠️ 【作廢】<路徑> 標註（別標在 §3——§3 是累計快照，壞產物標記應和鐵律/規範放在同一節）；③更新 §4 看板狀態為 [x] + 標註「作廢」；④更新 STATUS.md 反映作廢；⑤被某決策取代的舊腳本/方法同樣退役——腳本頂部加 # _DEPRECATED → 見 <權威腳本/決策> 註解，別讓它當成活口徑把下家釣進去。絕不只靠記憶說「那個別用」——下游 agent 靜默複用壞產物、或抄了一個滯後腳本的口徑，比沒產出更致命。

💡 一條真實接力教訓（這 3 條規則就是這麼來的）：某 agent 要重擬一條曲線，從一個滯後腳本裡抄了樣本集——那腳本還保留著早該剔除的壞點，而「剔除該點」的決策只躺在 600 行 STATUS 的深處，且兩個腳本對它的編碼恰好相反。結果該點把 R² 從 0.5 拖到 0.27，對外彙報被推翻。事後看，三處都本可攔住：決策沒上浮到有界必讀層（規則 5）、口徑集合在多腳本裡各自硬編碼而非單一 config（規則 6）、被取代的舊腳本沒打退役標記（規則 7）。信滯後腳本、不信決策記錄是這類事故的共同根因。

核心工作流（agent 接力全流程）

一個典型的多 agent 交接生命週期包含 5 個顯式步驟。跳過第③步「獨立複核」是多數鏈路汙染的根本原因。

① 委派 → ② 執行 + 自檢 → ③ 獨立複核 → ④ 接收入庫 → ⑤ handoff 落盤

步驟詳解

① 委派（主控 → 執行 agent） 用標準話術（見下文模板或 assets/委派任務模板.md）明確：讀什麼、做什麼、不碰什麼、輸出落哪、疑點記哪。

② 執行 + 自檢（執行 agent） 執行任務，做完跑一遍 DoD（驗收清單），確認輸出完整、格式對、無報錯。

③ 獨立複核（主控或另一 agent 抽驗關鍵數字） 別信自檢——執行 agent 自檢全過不代表產物無誤（已被反覆證明不夠）。

• 主控或第三 agent 抽驗關鍵數字：守恆（輸入總和 ≈ 輸出總和？）、邊界（有無越界/未裁淨？）、格數（行數/像元數符合預期？）、量級（單位是否差 10³？）、一致性（各文件中同一數字是否一致？）。
• 通過→進第④步；不通過→退回執行 agent 修復，並記錄 ADR。
• 判據：「獨立複核通過」是進入下一棒的閥門，不是可選項。

④ 接收入庫 確認無誤的產物正式落位，更新 來源.txt（如果是新資料）和 scripts/README.md（如果是新腳本）。

⑤ handoff 落盤 更新 AGENTS.md §3 現狀 + §4 看板 + 寫 STATUS.md。保證下個 agent 僅靠倉庫 markdown 能續上。

💡 短鏈路（1–2 個 agent、產物簡單）可跳過第③步；產出影響論文結論或下游管線的，必須走完 5 步。

兩層續接（缺一不可）

• 硬續接（主依賴）：倉庫裡的 Markdown，軟體無關，任何 agent/人都能讀。這是真相源。
• 軟續接（增強）：記憶層（Cursor memory / Claude memory）加速檢索，但別讓核心結論只活在記憶裡——必須落回 Markdown。

判據：把所有記憶層刪光，下個 agent 只靠倉庫 Markdown 也能接上 → 合格。

給 AI agent 委派任務的標準話術

每次委派新 agent 時，用統一格式開頭——效果遠好於自由發揮。照 assets/委派任務模板.md：

請先閱讀 AGENTS.md（含 STATUS.md 了解目前狀態）。 不要修改原始資料（<路徑>）和已有核心程式碼（<路徑>）。 本次任務只處理階段 X。 如果發現疑點或新問題，記錄到 <指定文件>，不要直接修正。 輸出落在 <指定路徑>。 本任務已知坑：[列已知風險點] 交付前必自查：[守恆/邊界/格數/量級…，逐條過]

這個模板的核心價值：讓新 agent 冷啟動時立刻知道該讀什麼、不該碰什麼、出問題往哪彙報。其中「已知坑」和「必自查」兩欄是實戰驗證過的關鍵增量——引導 agent 在報完成前自攔截常見錯誤類型，大幅降低缺陷率。

對於影響論文結論或下游管線的關鍵任務，在話術末尾追加「交付後安排獨立複核」指示（模板末段有進階範例）。

派發提示詞隨卡走（推薦）：別讓使用者每次現填這段話術——每張任務卡末尾內建一份填好的『📋 派發提示詞（複製即用）』區塊（見 assets/任務規劃_模板.md T1 末尾）。卡建好時就把目標/邊界/輸入輸出/已知坑/自查/收工填進去，使用者要派活時直接複製那段貼給任何 agent（含跨工具、跨技能）即可，零現編。委派任務模板.md 只作欄位含義參考。

進階區塊（按需啟用，見 references/advanced.md）

核心七區塊之外，這些在專案變大時有用，別一上來就全堆上：

• 決策記錄（ADR）——記「為什麼棄用某方法」，防止下個 agent 重新踩坑、重新質疑已定的事。
• 詞彙表——專案特有術語/縮寫，新 agent 不用猜。
• 進度日誌——帶日期戳的變更流水，比 §現在在哪 更細。
• 驗收具體化——DoD 寫成可執行檢查指令，而非「完成了就行」。
• 標準 handoff 摘要——現狀/下一步/未解決風險/關鍵檔案路徑。
• 命名約定 + 冪等性——輸出檔案帶 _v1/日期/座標系；可重跑腳本冪等（有快取跳過）。
• 環境鎖——conda env 釘 environment.yml，防跨機器重建漂移。
• 資料快照/不可變輸入——原始資料唯讀帶 hash，所有人在副本上動。
• 填好的 AGENTS.md 範例——references/example_filled_AGENTS.md，一個完整範例（虛構專案）。照著填比空模板直觀得多。

自訂提醒

• 這套骨架來自真實科研專案（多 agent、多資料集、長管線、雲端同步）實戰。複製後按領域裁剪：純前端專案可砍掉 §路徑約定的「工作盤」部分；單 agent 小腳本專案 §任務看板 可簡化。
• 模板佔位符統一用 【待填】，填完刪掉。
• 薄指標檔案內容統一（見 assets/CLAUDE.md），別在每個裡寫不同規則——那會破壞「真相只有一份」。
• 不要覆蓋使用者已有的 AGENTS.md；如果是模式 B 診斷，先讀後改、增量修補。