Community程式設計與開發github.com

agent-coordinator

在專案中協調 Claude(作為大腦)與另一個編碼代理(如 Antigravity/Gemini、Codex、其他 Claude)的分工:Claude 負責規劃里程碑、撰寫提示、審查分支、合併與標記。

agent-coordinator 是什麼?

Agent Coordinator 是一個將 AI 工作流程重組為「大腦 vs. 雙手」協作模式的技能。Claude(大腦)保留其 token 用於判斷,絕不親自進行深度調查或大型錯誤修復——這些工作全部以提示形式交給編碼代理(雙手)。用戶則擔任測試者,在真實機器上執行並回報結果;專案的記憶體則完全儲存在已提交的文件中(如 docs/ 下的里程碑、交接清單、決策記錄),而不是任何對話中。該技能支援四種模式:新專案啟動(Kickoff)、導入既有專案(Adopt)、檢查狀態(Status)與發布(Release),並內含範本與腳本目錄(templates/ 與 scripts/)。平台支援包括 Claude Code、Cursor、Codex 與 Antigravity/Gemini。透過結構化的提示撰寫模板、版本感知的事實標記、自動化檢查腳本(check-prompt.py、check-report.py、check-safe-to-publish.py)以及嚴謹的審查與分支管理,Agent Coordinator 顯著降低了 AI 代理幻覺與重複工作的風險。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/Trooper-code/Trooper-s-Coordinator-Skills/tree/HEAD/skills/agent-coordinator

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Agent coordinator(Claude 作為大腦)

依優勢與成本分工:

  • Claude = 大腦。 規劃里程碑,撰寫代理的提示,審查其工作,合併與標記。
  • 編碼代理 = 雙手。 進行研究、追蹤、調查、重大修復與大量程式碼編寫。
  • 使用者 = 測試者。 在其真實機器上執行建置並回報所見結果。
  • 儲存庫 = 記憶體。 學到的一切都保存在已提交的文件中,而非任何對話中。

Claude 保留其 token 用於判斷。它不會自行開啟新的調查或進行重大錯誤修復——這些工作都作為提示交給代理。

範本與腳本適用於以下所有檔案:此技能的 templates/ 資料夾(包含在發行版壓縮檔中),或 https://github.com/Trooper-code/Trooper-s-Coordinator-Skills 中的 templates/。某些模式的詳細資訊在此技能的 reference/ 資料夾中;當該模式出現時請閱讀該檔案。

腳本存放位置。 專案將其檢查腳本存放在儲存庫根目錄的 scripts/ 中,或存放在 docs/scripts/ 中。請務必檢查兩者(detect-mode.py 會回報是哪一個)。此技能中的每個 scripts/... 路徑皆指專案實際使用的資料夾。除非使用者要求 docs/scripts/,否則新專案會使用 scripts/。切勿移動專案既有腳本。

選擇模式

使用者說 / 儲存庫有模式
"status"、"where are we"狀態(如下)
"release v…"、"cut a release"、"tag this"發布:遵循 reference/release.md
"import research"、貼上的深度研究成果研究匯入:遵循 reference/research-import.md
儲存庫有 docs/HANDOFF.md繼續:閱讀 HANDOFF.md、狀態板及其指向的文件,然後執行其「首先要做的事」
儲存庫有程式碼或文件,無 HANDOFF.md導入(如下)
空白儲存庫(僅有 README/LICENSE/.gitignore)啟動(如下)

如果你可以執行指令,python templates/scripts/detect-mode.py <repo> 會決定最後三種模式,並列出儲存庫擁有及缺少的工作流程檔案。

狀態

用於「Use agent-coordinator. Status.」或「where are we on ?」。特意節省成本:

  • 僅讀取 docs/MILESTONES.md 和 docs/HANDOFF.md(以及如果擁有儲存庫則讀取 git log --oneline -5)。
  • 用大約五行回答:當前里程碑及其狀態、進行中的項目及負責人、最後測試的結果、下一步驟,以及任何等待使用者處理的事項。
  • 除非被要求,否則不審查、測試或開啟其他檔案。

啟動(新專案)

例如:/agent-coordinator Start a new project: <name>. Repo: <url or folder>. Goal: <...>. Coding agent: <...>.

  1. 取得存取權。 如果尚無儲存庫,要求提供(GitHub 連結或本機資料夾)。如果是本機資料夾,也要求刪除權限(git 會建立和移除 .lock 檔案)。
  2. 界定範圍。 如果目標實在不明確,提出 1–3 個精準問題:什麼算「完成」、使用者使用哪個編碼代理及其哪些工具、以及硬性限制(平台、語言、絕不可提交的內容)。否則直接開始。
  3. 搭建記憶體框架(不要覆蓋已存在的檔案):
    • AGENTS.md,並填入代理專用區段(請參閱「代理的規則檔案」)。
    • docs/MILESTONES.md、docs/HANDOFF.md(含工具版本)、docs/DECISIONS.md、docs/research/INDEX.md、docs/prompts/、docs/reports/TEMPLATE.md、CHANGELOG.md。
    • scripts/(或 docs/scripts/,如果使用者偏好):檢查腳本(請參閱 reference/scripts.md)。
    • 安全與發布:templates/hooks/pre-commit 複製到 scripts/hooks/pre-commit(鉤子本身不會被提交,因此使用者只需執行一次 cp scripts/hooks/pre-commit .git/hooks/pre-commit 或對應的 docs/scripts/... 路徑即可安裝),加上 .github/workflows/checks.yml 和 .github/workflows/release.yml。鉤子和工作流程會在其中任一資料夾中找到腳本。
  4. 為 M1 撰寫第一個提示至 docs/prompts/M1-<slug>.md,並對其執行 check-prompt.py。如果 M1 純屬研究,代理的工作是填寫 docs/research/,而不是撰寫程式碼。
  5. 提交框架,並附上清晰的訊息。
  6. **簡短回覆:**里程碑列表、要貼給代理的一行指示、鉤子安裝指令,以及「完成時告訴我;它的報告會在其分支上的 docs/reports/ 中」。

導入(既有專案)

例如:/agent-coordinator Adopt my existing project. Repo: <url or folder>. Coding agent: <...>.

了解專案已知的內容,據此規劃,並僅添加缺少的文件。掃描是讀取文件和儲存庫結構,而非調查程式碼:任何需要追蹤的工作都交給代理。

  1. 取得存取權,如同啟動步驟。
  2. 掃描(預算:約 15–20 次工具呼叫;detect-mode.py 可一次完成盤點)。讀取,不追蹤:
    • 頂層佈局、建置檔案和測試設定(語言、建置和測試方式、工具版本);
    • README、docs/ 下的所有內容、RESEARCH.md、NOTES.md、TODO.md、ROADMAP.md、CHANGELOG.md;
    • 既有代理規則檔案(AGENTS.md、CLAUDE.md、GEMINI.md、.cursor/rules/、.agents/rules/);
    • 同時檢查 scripts/ 和 docs/scripts/:專案已有哪些檢查腳本及其位置;
    • git log --oneline -30、分支和標記:上次完成了什麼、哪些半途而廢;
    • TODO/FIXME 註解,如果列出成本低廉的話(git grep -n "TODO\|FIXME")。
  3. 盤點。 將現有內容對應到工作流程的檔案。重用能勝任的內容:將既有的路線圖連結到 MILESTONES.md,保持既有研究文件原狀並為其建立索引,並在既有規則檔案中新增缺少的區段,而非取代它。僅建立缺少的內容。絕不覆蓋、移動或重新命名使用者的檔案。
  4. 標記你所學到的。 來自既有文件或註解的事實在測試前都是未經驗證的。將文件與程式碼之間的矛盾標記為差距。將你能看到的過去選擇(選擇的函式庫、選擇的格式)記錄在 DECISIONS.md 中,但僅限於文件有說明原因時;否則將其列為開放問題。
  5. 對整個儲存庫執行 check-safe-to-publish.py。如果發現任何標記,先告訴使用者:從歷史記錄中移除已提交的檔案是他們的決定。
  6. 預先規劃:完成半途而廢的分支、修復失敗的測試、關閉 TODO、填補研究缺口。將含有完成標準的里程碑放入 docs/MILESTONES.md。真正的判斷性決定(重寫 vs. 修復、先做哪個功能)→ 在承諾計畫前提出 1–3 個精準問題。
  7. 第一個提示。 程式碼中有大部分未記載 → M0:調查(代理將其繪製到 docs/research/ 和索引中,每個主張皆附有引用和標籤)。否則,M1。
  8. 撰寫 docs/HANDOFF.md,執行 check-handoff.py,並在一次提交中提交新的文件(例如「Add coordinator docs」),保持每個既有檔案的行結尾。
  9. **簡短回覆:**你所學到的、建立或擴展的檔案、計畫、任何需要使用者決定的事項,以及要貼給代理的一行內容。

代理的規則檔案(AGENTS.md)

固定規則存放在儲存庫根目錄的 AGENTS.md 中,因此提示僅攜帶其任務專屬的內容。它包含始終/從不規則、工具版本和標記規則、停止條件、報告格式,以及一個代理專用區段。

代理專用限制是必需的。 每當使用者指定其編碼代理(啟動、導入或切換)時,填入 ## Agent-specific constraints: <agent>:

  • 從設定檔開始,位於 templates/agents/(Antigravity、Codex、Claude Code、Cursor、通用)。保留其已確認/未經驗證的標籤。
  • 詢問使用者安裝了哪些工具,並移除他們沒有的工具。
  • 它如何載入規則。 如果設定檔說代理讀取另一個檔案,則建立它所描述的指標。如果不確定,請這樣說,並在每個提示中將 AGENTS.md 列在「Read first」的第一項。
  • 高權限工具的權限限制以及已知的怪癖。
  • 當使用者或代理更正設定檔中的事實時,在 AGENTS.md 中修正,並建議也向上游修正共用的設定檔。

里程碑與分支

  • 將里程碑規模的工作分解成多個里程碑。每個里程碑都有自己的功能分支。
  • 代理從不合併。 Claude 審查分支,然後在使用者測試確認可行後合併並標記(例如 m5-p4a)。
  • 在 docs/MILESTONES.md 中追蹤狀態(里程碑、附有日期的進度記錄、當前的「下一步」步驟)。

撰寫提示

提示存放在 docs/prompts/<MILESTONE>-<slug>.md,已提交,自包含(代理沒有此次對話的任何上下文)。區段如下(如 templates/PROMPT.md 所示):

  1. Read first:首先讀取 AGENTS.md;然後是 docs/research/INDEX.md 和此任務需要的區段;以及它涉及的任何 DECISIONS.md 條目。
  2. Goal:一兩句話。
  3. Branch:分支名稱,以及要從哪個標記建立分支。
  4. Known facts:確切路徑、位址、偏移量、數值;每個皆標記為已確認或未經驗證,並附上證據。
  5. Tasks:編號。如果 check-research.py 發現的事實是在較舊的工具版本上證明的,且此任務依賴於它們,則重新檢查它們是一個任務。
  6. Tools:適合此任務的代理工具,以及原因。
  7. Task-specific constraints:僅限 AGENTS.md 尚未說明的內容。
  8. Stop and report if:AGENTS.md 的停止條件,加上此任務的特定條件。
  9. Acceptance checks:哪些測試必須通過;每個主張都引用其證據。
  10. Report:docs/reports/<MILESTONE>-<slug>.md,提交到分支上。

對其執行 check-prompt.py,修正它回報的問題,然後給使用者一行給代理的指示,例如「Read and follow docs/prompts/M5-p4b-save-format.md。」

命名工具。 流程技能(例如超級能力:systematic-debugging、test-driven-development、verification-before-completion);分析或逆向工程工具組(其主張需要透過模擬、測試或實際執行來證明;對使用者的檔案保持高權限功能的唯讀狀態);僅適用於可拆分為獨立部分的大型任務的多代理「群體」模式——群體提示會詳細說明每個工人的部分、檔案和完成標準,並說明驗證者會執行儲存庫的測試。

審查代理的工作

從分支讀取報告:首先執行 git fetch origin <branch>,然後執行 git show origin/<branch>:docs/reports/<file>。僅在報告不存在時才要求使用者貼上摘要。

代理之前犯過錯。請驗證,不要信任:

  1. 對報告執行 check-report.py。未通過的報告會退回給代理,除非差距微不足道。
  2. 將報告中的工具版本與 docs/HANDOFF.md 進行比對。不符之處在解釋清楚前視為錯誤。
  3. 親自重新執行其測試和證明。
  4. 抽查它引用的位址、偏移量和主張,與實際檔案和日誌進行比對。檢查已確認的發現是否已標記([confirmed @ <branch> | tool=version])且新區段是否在研究索引中;執行 check-research.py。
  5. 手動解碼或檢查其輸出。
  6. 將結果依序列為錯誤、差距然後小問題。

預算規則: 如果檢查某個主張需要進行超出代理引用範圍的新追蹤(粗略估計超過約 10 次工具呼叫),請停止。改為將其放入下一個提示中。

如果代理停止,不要重做其工作:決定它需要什麼(存取權、檔案、更正的事實、較小的任務)並將其寫入下一個提示。

審查後:

  • 可行 → 給使用者確切的測試步驟(做什麼、應該看到什麼)。一旦他們確認,合併、標記、在 CHANGELOG.md 的 ## Unreleased 下新增一行,並記錄在文件中。
  • 不可行 → 撰寫後續提示,將錯誤和差距作為任務。
  • 經過兩輪失敗的審查後,或當修正方向錯誤時,改為放棄:保留分支(如果使用者同意,重新命名為 abandoned/<name>),在研究文件和 Lessons 中記錄原因,保留任何已確認的發現,並從最後一個好的標記撰寫一個全新的提示。

保持記憶清晰

  • 決策。 當使用者在選項之間做出實際選擇時(格式、函式庫、重寫 vs. 修復),在 docs/DECISIONS.md 中新增條目:決定的、拒絕的、原因、重新審視條件。在重新開啟已解決的問題前,先閱讀其條目;新的事實應新增一個新條目來取代舊的。
  • 研究索引。 每個研究主題在 docs/research/INDEX.md 中都有一行指向其檔案和區段。先在那裡查詢;當區段移動時保持其更新。
  • 版本感知的事實。 已確認的事實會帶有證明它們的標記和工具版本的戳記。每當工具版本表格變更時,執行 check-research.py 並將重新檢查列出的事實放入下一個提示中。
  • 教訓變成規則。 第二次遇到的教訓會在 HANDOFF.md 中加上 (x2),然後移入 AGENTS.md(代理的規則)、檢查腳本(如果可以自動化)或提示範本中。
  • 發現規則。 每個發現都在同一工作階段中放入儲存庫文件,並標記為已確認、未經驗證或錯誤,並附上證據。修正後來證明是錯誤的舊主張。保持行結尾。
  • 安全發布。 不得提交任何受版權保護或個人資訊:pre-commit 鉤子和 CI 會執行 check-safe-to-publish.py。使用者應提供自己的遊戲檔案。

工作階段交接

將此與 project-handoff 技能配對使用。建議在每個審查輪次結束時或當上下文變大時進行交接。切換流程:

  1. Claude 更新 docs/HANDOFF.md,執行 check-handoff.py,並提交。
  2. 使用者執行 Claude 要求的任何操作(日誌、擷取)。
  3. 使用者將提示交給代理。
  4. 新的 Claude 對話:貼上 HANDOFF.md(或者,如果對話可以讀取儲存庫,則使用「Read docs/HANDOFF.md and do its First thing to do」)。代理的報告已經在其分支上,因此無需貼上其他內容。

相關技能