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: <...>.
- 取得存取權。 如果尚無儲存庫,要求提供(GitHub 連結或本機資料夾)。如果是本機資料夾,也要求刪除權限(git 會建立和移除
.lock檔案)。 - 界定範圍。 如果目標實在不明確,提出 1–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。鉤子和工作流程會在其中任一資料夾中找到腳本。
- 為 M1 撰寫第一個提示至
docs/prompts/M1-<slug>.md,並對其執行check-prompt.py。如果 M1 純屬研究,代理的工作是填寫docs/research/,而不是撰寫程式碼。 - 提交框架,並附上清晰的訊息。
- **簡短回覆:**里程碑列表、要貼給代理的一行指示、鉤子安裝指令,以及「完成時告訴我;它的報告會在其分支上的
docs/reports/中」。
導入(既有專案)
例如:/agent-coordinator Adopt my existing project. Repo: <url or folder>. Coding agent: <...>.
了解專案已知的內容,據此規劃,並僅添加缺少的文件。掃描是讀取文件和儲存庫結構,而非調查程式碼:任何需要追蹤的工作都交給代理。
- 取得存取權,如同啟動步驟。
- 掃描(預算:約 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")。
- 盤點。 將現有內容對應到工作流程的檔案。重用能勝任的內容:將既有的路線圖連結到
MILESTONES.md,保持既有研究文件原狀並為其建立索引,並在既有規則檔案中新增缺少的區段,而非取代它。僅建立缺少的內容。絕不覆蓋、移動或重新命名使用者的檔案。 - 標記你所學到的。 來自既有文件或註解的事實在測試前都是未經驗證的。將文件與程式碼之間的矛盾標記為差距。將你能看到的過去選擇(選擇的函式庫、選擇的格式)記錄在
DECISIONS.md中,但僅限於文件有說明原因時;否則將其列為開放問題。 - 對整個儲存庫執行
check-safe-to-publish.py。如果發現任何標記,先告訴使用者:從歷史記錄中移除已提交的檔案是他們的決定。 - 預先規劃:完成半途而廢的分支、修復失敗的測試、關閉 TODO、填補研究缺口。將含有完成標準的里程碑放入
docs/MILESTONES.md。真正的判斷性決定(重寫 vs. 修復、先做哪個功能)→ 在承諾計畫前提出 1–3 個精準問題。 - 第一個提示。 程式碼中有大部分未記載 → M0:調查(代理將其繪製到
docs/research/和索引中,每個主張皆附有引用和標籤)。否則,M1。 - 撰寫
docs/HANDOFF.md,執行check-handoff.py,並在一次提交中提交新的文件(例如「Add coordinator docs」),保持每個既有檔案的行結尾。 - **簡短回覆:**你所學到的、建立或擴展的檔案、計畫、任何需要使用者決定的事項,以及要貼給代理的一行內容。
代理的規則檔案(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 所示):
- Read first:首先讀取
AGENTS.md;然後是docs/research/INDEX.md和此任務需要的區段;以及它涉及的任何DECISIONS.md條目。 - Goal:一兩句話。
- Branch:分支名稱,以及要從哪個標記建立分支。
- Known facts:確切路徑、位址、偏移量、數值;每個皆標記為已確認或未經驗證,並附上證據。
- Tasks:編號。如果
check-research.py發現的事實是在較舊的工具版本上證明的,且此任務依賴於它們,則重新檢查它們是一個任務。 - Tools:適合此任務的代理工具,以及原因。
- Task-specific constraints:僅限
AGENTS.md尚未說明的內容。 - Stop and report if:AGENTS.md 的停止條件,加上此任務的特定條件。
- Acceptance checks:哪些測試必須通過;每個主張都引用其證據。
- 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>。僅在報告不存在時才要求使用者貼上摘要。
代理之前犯過錯。請驗證,不要信任:
- 對報告執行
check-report.py。未通過的報告會退回給代理,除非差距微不足道。 - 將報告中的工具版本與
docs/HANDOFF.md進行比對。不符之處在解釋清楚前視為錯誤。 - 親自重新執行其測試和證明。
- 抽查它引用的位址、偏移量和主張,與實際檔案和日誌進行比對。檢查已確認的發現是否已標記(
[confirmed @ <branch> | tool=version])且新區段是否在研究索引中;執行check-research.py。 - 手動解碼或檢查其輸出。
- 將結果依序列為錯誤、差距然後小問題。
預算規則: 如果檢查某個主張需要進行超出代理引用範圍的新追蹤(粗略估計超過約 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 技能配對使用。建議在每個審查輪次結束時或當上下文變大時進行交接。切換流程:
- Claude 更新
docs/HANDOFF.md,執行check-handoff.py,並提交。 - 使用者執行 Claude 要求的任何操作(日誌、擷取)。
- 使用者將提示交給代理。
- 新的 Claude 對話:貼上 HANDOFF.md(或者,如果對話可以讀取儲存庫,則使用「Read docs/HANDOFF.md and do its First thing to do」)。代理的報告已經在其分支上,因此無需貼上其他內容。