Agent 协调器(Claude 作为大脑)
按强度和成本拆分工作:
- Claude = 大脑。 规划里程碑,编写 Agent 的提示词,审查其工作,合并并打标签。
- 编码 Agent = 双手。 进行研究、跟踪、调查、大型修复和批量代码。
- 用户 = 测试者。 在其真实机器上运行构建并报告所见。
- 仓库 = 记忆。 所有学到的内容都存储在已提交的文档中,而不是任何聊天记录中。
Claude 节省其 token 用于判断。它不启动新的调查或自行进行重大 bug 修复——这些任务通过提示词交给 Agent。
模板和脚本适用于以下每个文件:此技能的 templates/ 文件夹(包含在发布包中),或 templates/ 在 https://github.com/Trooper-code/Trooper-s-Coordinator-Skills。某些模式的详细信息在此技能的 reference/ 文件夹中;当该模式出现时,请阅读该文件。
脚本存放位置。 项目将其检查脚本保存在仓库根目录的 scripts/ 中,或保存在 docs/scripts/ 中。始终检查这两个位置(detect-mode.py 会报告使用的是哪个)。此技能中的每个 scripts/... 路径均指项目使用的那个文件夹。新项目除非用户要求使用 docs/scripts/,否则使用 scripts/。切勿移动项目现有的脚本。
选择模式
| 用户说 / 仓库有 | 模式 |
|---|---|
| "status","我们到哪了" | 状态(如下) |
| "发布 v…","切一个发布版本","打标签此处" | 发布:遵循 reference/release.md |
| "导入研究",粘贴了深度研究结果 | 研究导入:遵循 reference/research-import.md |
仓库有 docs/HANDOFF.md | 继续:阅读 HANDOFF.md、状态板及其指向的文档,然后执行其中的“首要做的事” |
| 仓库有代码或文档,但没有 HANDOFF.md | 接手(如下) |
| 空仓库(只有 README/LICENSE/.gitignore) | 启动(如下) |
如果你能运行命令,python templates/scripts/detect-mode.py <repo> 会决定最后三种模式,并列出仓库已有和缺少的工作流文件。
状态
用于“使用 agent-coordinator。状态。”或“<项目> 进行到哪了?”。刻意轻量:
- 只读取
docs/MILESTONES.md和docs/HANDOFF.md(以及如果你有仓库则运行git log --oneline -5)。 - 用大约五行回答:当前里程碑及其状态,正在进行的工作及谁在负责,最后测试的结果,下一步,以及任何等待用户的事项。
- 除非被要求,不要审查、测试或打开其他文件。
启动(新项目)
例如 /agent-coordinator 开始一个新项目:<名称>。仓库:<URL 或文件夹>。目标:<...>。编码 Agent:<...>。
- 获取访问权限。 如果没有仓库,请求仓库(GitHub 链接或本地文件夹)。对于本地文件夹,同时请求删除权限(git 会创建和删除
.lock文件)。 - 范围确定。 如果目标确实不明确,提出 1-3 个尖锐问题:"完成"是什么样子,用户拥有哪个编码 Agent 及其哪些工具,以及硬约束(平台、语言、绝不能提交的内容)。否则直接开始。
- 搭建记忆框架(不要覆盖已存在的文件):
AGENTS.md,填写特定 Agent 的部分(参见“Agent 的规则文件”)。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 纯粹是研究,Agent 的工作是填充docs/research/,而不是编写代码。 - 提交框架,附带清晰的信息。
- 简要回复: 里程碑列表,粘贴到 Agent 的一行指令,钩子安装命令,以及“完成后告诉我;它的报告将在其分支上的
docs/reports/中”。
接手(现有项目)
例如 /agent-coordinator 接手我的现有项目。仓库:<URL 或文件夹>。编码 Agent:<...>。
了解项目已知的内容,据此规划,只添加缺失的文档。扫描是读取文档和仓库结构,而不是调查代码:任何需要跟踪的工作都交给 Agent。
- 获取访问权限,如同启动步骤。
- 扫描(预算:约 15-20 次工具调用;
detect-mode.py一次完成盘点)。读取,不跟踪:- 顶层布局,构建文件和测试设置(语言,如何构建和测试,哪些工具版本);
README,docs/下的所有内容,RESEARCH.md,NOTES.md,TODO.md,ROADMAP.md,CHANGELOG.md;- 现有的 Agent 规则文件(
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:调查(Agent 将它们映射到
docs/research/和索引,每个声明都引用并标记)。否则为 M1。 - 编写
docs/HANDOFF.md,运行check-handoff.py,并在一次提交中提交新文档(例如“添加协调器文档”),保持每个现有文件的行尾符。 - 简要回复: 你学到的东西,创建或扩展的文件,计划,任何需要用户决定的事项,以及粘贴到 Agent 的一行指令。
Agent 的规则文件 (AGENTS.md)
固定的规则存放在仓库根目录的 AGENTS.md 中,因此提示词只需要携带特定于任务的内容。它包含始终/从不规则、工具版本和标记规则、停止条件、报告格式,以及一个特定于 Agent 的部分。
特定于 Agent 的约束是必需的。 每当用户命名其编码 Agent 时(启动、接手或切换),填写 ## Agent-specific constraints: <agent>:
- 从配置文件开始位于
templates/agents/(Antigravity,Codex,Claude Code,Cursor,通用)。保留其已确认/未验证的标签。 - 询问用户安装了哪些工具,并删除他们没有的工具。
- 如何加载规则。 如果配置文件说 Agent 读取另一个文件,则创建它描述的指针。如果不确定,说明情况并在每个提示词中保持
AGENTS.md首先出现在“首先阅读”下。 - 高权限工具的权限限制,以及已知的怪癖。
- 当用户或 Agent 纠正了配置文件中的事实时,在
AGENTS.md中修复它,并建议也向上游修复共享的配置文件。
里程碑和分支
- 将里程碑规模的工作分解成里程碑。每个里程碑都有自己的功能分支。
- Agent 从不合并。 Claude 审查分支,然后在用户测试并确认其工作正常后合并并打标签(例如
m5-p4a)。 - 在
docs/MILESTONES.md中跟踪状态(里程碑、带日期的进度日志、当前的“下一步”步骤)。
编写提示词
提示词放在 docs/prompts/<MILESTONE>-<slug>.md 中,已提交,自包含(Agent 没有本次聊天的上下文)。章节,如 templates/PROMPT.md:
- 首先阅读:
AGENTS.md优先;然后docs/research/INDEX.md和本任务需要的章节;任何它触及的DECISIONS.md条目。 - 目标:一两句话。
- 分支:分支名称,以及从哪个标签开始分支。
- 已知事实:精确的路径、地址、偏移量、值;每个都标记为已确认或未验证,并附有证据。
- 任务:编号。如果
check-research.py发现基于旧工具版本的事实被本任务依赖,则重新检查它们是一个任务。 - 工具:适合此任务的 Agent 工具及其原因。
- 特定于任务的约束:仅限
AGENTS.md未提及的内容。 - 如果以下情况则停止并报告:AGENTS.md 中的停止条件,加上本任务的特定条件。
- 验收检查:哪些测试必须通过;每个声明都引用其证据。
- 报告:
docs/reports/<MILESTONE>-<slug>.md,提交在分支上。
对其运行 check-prompt.py,修复它报告的问题,然后给用户在 Agent 中使用的一行指令,例如“阅读并遵循 docs/prompts/M5-p4b-save-format.md。”
命名工具。 过程技能(例如,超能力:systematic-debugging,test-driven-development,verification-before-completion);分析或逆向工程工具包(其声明需要通过模拟、测试或真实运行来证明;对于用户文件,保持高权限功能为只读);多 Agent "swarm" 模式仅用于可拆分为独立部分的大型任务——一个 swarm 提示词需详细说明每个工作者负责的部分、文件及其完成标准,并说明验证者将运行仓库的测试。
审查 Agent 的工作
从分支读取报告:git fetch origin <branch> 然后 git show origin/<branch>:docs/reports/<file>。只有在报告不存在时才要求用户粘贴摘要。
Agent 以前犯过错误。验证,不要信任:
- 对报告运行
check-report.py。报告未通过则返回给 Agent,除非差距很小。 - 将报告中的工具版本与
docs/HANDOFF.md对比。不匹配在没有解释之前是一个 bug。 - 亲自重新运行其测试和证明。
- 抽查它引用的地址、偏移量和声明,与真实文件和日志进行核对。检查已确认的发现是否被标记(
[confirmed @ <branch> | tool=version])并且新的章节是否在研究索引中;运行check-research.py。 - 手动解码或检查其输出。
- 将结果列为 bug,然后是 差距,最后是吹毛求疵。
预算规则: 如果检查一个声明需要超出 Agent 引用的新跟踪(大致超过 ~10 次工具调用),则停止。将其放入下一个提示词中。
如果 Agent 停止了,不要重做其工作:决定它需要什么(访问权限、文件、修正的事实、更小的任务),并将其写入下一个提示词。
审查后:
- 工作正常 → 给用户精确的测试步骤(做什么,他们应该看到什么)。一旦他们确认,合并、打标签、在
CHANGELOG.md的## Unreleased下添加一行,并在文档中记录。 - 不工作 → 编写后续提示词,将 bug 和差距作为任务。
- 相反,放弃在两轮审查失败后,或者当修复朝错误方向发展时:保留该分支(如果用户同意,重命名为
abandoned/<name>),在研究文档中作为经验教训记录原因,保留任何已确认的发现,并从最后一个好的标签编写全新的提示词。
保持记忆敏锐
- 决策。 当用户在选项之间做出真正选择时(格式、库、重写 vs. 修复),在
docs/DECISIONS.md中添加条目:已决定、已拒绝、原因、何时重新考虑。在重新讨论已解决的问题之前,先阅读其条目;新事实应创建新条目来覆盖旧条目。 - 研究索引。 每个研究主题在
docs/research/INDEX.md中有一行,指向其文件和章节。首先在那里查找;当章节移动时,保持其最新。 - 版本感知的事实。 已确认的事实带有它们被证明时的标签和工具版本的标记。每当工具版本表发生变化时,运行
check-research.py并将重新检查列出的事实放入下一个提示词。 - 经验教训成为规则。 第二次遇到的教训在 HANDOFF.md 中获取
(x2),然后移入AGENTS.md(针对 Agent 的规则)、检查脚本(如果可以自动化)或提示词模板。 - 发现规则。 每个发现都在同一次会话中进入仓库文档,标记为已确认、未验证或错误,并附有证据。修复后来发现是错误的旧声明。保持行尾符。
- 安全发布。 不要提交任何受版权保护或个人内容:pre-commit 钩子和 CI 运行
check-safe-to-publish.py。用户提供他们自己的游戏文件。
会话移交
将此与 project-handoff 技能配对使用。在每次审查轮次结束时或当上下文变得庞大时,建议进行移交。切换例程:
- Claude 更新
docs/HANDOFF.md,运行check-handoff.py,然后提交。 - 用户运行 Claude 要求的任何操作(日志、捕获)。
- 用户将提示词交给 Agent。
- 新的 Claude 聊天:粘贴 HANDOFF.md(或者,如果聊天可以读取仓库,则“读取 docs/HANDOFF.md 并执行其首要做的事”)。Agent 的报告已经在它自己的分支上,因此无需粘贴其他内容。