mcpField
S
swarm-coordination

swarm-coordination

github.com/dralgorhythmAgent 工作流12977 次安装14 周前更新
代码仓库

关于 swarm-coordination

swarm-coordination 为 Claude Code 多 Agent 协作提供任务跟踪、文件锁定和交接规范，面向在同一代码库并行开发的团队。它将持久任务记录与进行中任务分开，并规定协调者与执行者的协作方式。

主要功能

  1. 01区分持久任务记录与进行中任务
  2. 02通过钩子管理文件锁
  3. 03以会话 ID 隔离 Agent 状态
  4. 04要求交接附带可验证的产物引用
  5. 05规定协调者与执行者的协作流程

适用场景

  1. 01多个 Agent 并行处理代码库任务
  2. 02协调不同文件或功能的独立开发流
  3. 03为未完成工作留下可继续的交接信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dralgorhythm/claude-agentic-framework --skill swarm-coordination

安装后在 Claude Code 中输入/swarm-coordination确认已加载。

详细介绍

Swarm 协作

确保多 Agent 开发一致且无冲突的协议和模式。在与同一代码库中的其他 Claude Code Agent 协作时，请遵循这些准则。

核心原则

  1. 双层任务跟踪：持久工作项记录在 GitHub Issues（或已提交的 ISSUES.md）中；进行中的工作记录在编排器的原生任务列表（TaskCreate/TaskUpdate/TaskList）中
  2. 文件锁定：钩子会自动管理文件锁，请遵守锁定状态
  3. 会话隔离：每个 Agent 都有唯一的会话 ID，用于跟踪
  4. 清晰交接：始终留下状态和工件引用，以便其他 Agent 接手后继续工作

双层任务跟踪

  • 第一层 — 持久记录：GitHub Issues（对于没有跟踪工具的仓库，则使用 ISSUES.md）保存工作项的永久历史记录：请求内容、原因以及最终处理结果。
  • 第二层 — 进行中的工作：编排器负责维护原生任务列表（TaskCreate/TaskUpdate/TaskList）。每个工作项对应一个任务，并明确列出验收标准。执行者不维护自己的任务列表（无共享状态规则见 .claude/rules/agent-constraints.md）。
  • 交接：参见核心指令 §7“遵循命令协议”——每次交接都需要可验证的工件引用。

基于文件的输出

执行者将结果写入 scratchpad/<task-id>.md，而不是直接写入上下文。只有持久工件（ADR、计划、PRD）才写入 artifacts/。编排器在启动执行者之前创建输出目标；执行者写入指定文件；编排器读取并整合内容。

工作流

开始工作
  • 检查任务列表：编排器检查 TaskList，找出未被阻塞且尚未认领的任务
  • 创建任务：每个工作项对应一个任务，并明确列出验收标准
  • 检查冲突：查看 .claude/hooks/.file-tracker.log 中的近期编辑记录
  • 分派任务：向执行者发送重点明确、内容完整的提示词（参见 agent-constraints.md）
工作期间
  • 原子化修改：进行小而完整的修改，避免留下损坏状态
  • 频繁提交：经常提交以减少合并冲突
  • 更新任务状态：执行者汇报进展后，编排器更新 TaskUpdate
  • 遵守锁定状态：如果文件已锁定，请等待或处理其他工作
完成工作
  • 运行测试：确认修改不会破坏现有功能
  • 标记任务完成：编排器在原生任务列表中关闭任务并记录结果
  • 更新持久记录：在 GitHub Issue / ISSUES.md 中更新完成情况
  • 清理状态：提交所有修改，不留下未提交的工作

避免冲突

文件锁定协议

钩子会自动获取和释放锁。如果遇到锁：

# Check who holds the lock
cat .claude/hooks/.locks/<filename>.lock

# Lock automatically expires after 60 seconds
# If urgent, wait or pick a different task from the task list
合并冲突策略
  1. 频繁拉取：保持分支更新
  2. 小型 PR：比大型修改更容易合并
  3. 协调工作：编辑前，先在编排器的任务列表中认领任务（及其对应文件）
  4. 快速解决：发现冲突后立即处理

沟通模式

交接消息

如果结束会话时仍有未完成的工作，请留下交接信息并指向具体工件：

echo '{"message": "Continue implementing auth middleware. Tests passing but needs error handling in src/auth.ts:45", "artifact": "artifacts/plan_auth_middleware.md"}' > .claude/hooks/.state/handoff.json

多 Agent 模式

编排器—执行者模式

对于复杂任务，由一个 Agent 负责编排，其他 Agent 负责执行：

  1. 编排器：制定计划，将工作拆分为原生任务列表中的任务，并分派给执行者
  2. 执行者：接收重点明确的提示词、实现任务并返回结果（执行者之间不共享状态——参见 agent-constraints.md）
  3. 同步点：编排器收集所有执行者的结果，并在最终集成前进行协调
并行工作流

对于相互独立的功能：

  1. 为每个工作流创建单独的任务（并注明验收标准）
  2. 每个执行者通过分配给自己的任务认领一个工作流
  3. 避免不同工作流修改相同文件
  4. 在指定的集成节点合并各工作流

预算与工作波次

仅作为成本断路器：这只能在事后限制失控的支出，无法检测步骤重复或循环——这是另一种故障模式，不在此处讨论。

  • 协调器在分派一批工作者时声明令牌数／工作波次上限——应在启动前设置上限，而不是启动后
  • 达到上限时：停止分派，报告目前的支出和剩余工作，并在继续前征求用户同意
  • 分派的任务标题带有 [Wave N/M] 前缀（例如 [Wave 1/3] Explore auth patterns），以便一眼看出支出和进度属于哪个工作波次

状态文件

文件用途
.claude/hooks/.state/session_*.json活跃的 Agent 会话
.claude/hooks/.state/handoff.json会话之间的交接消息
.claude/hooks/.locks/*.lock文件编辑锁
.claude/hooks/.file-tracker.log最近的文件修改记录

最佳实践

  1. 编辑前检查：始终确认目标文件没有活跃的锁
  2. 完成工作单元：切换任务前先完成逻辑上的工作单元
  3. 记录意图：使用任务列表声明你正在处理的工作及验收标准
  4. 本地测试：推送前运行测试，及早发现问题
  5. 经常同步：与其他 Agent 保持任务列表、持久化问题记录和 git 同步

紧急处理流程

死锁检测

如果 Agent 彼此等待：

# Check active sessions
ls -la .claude/hooks/.state/session_*.json

# Check active locks
ls -la .claude/hooks/.locks/

# Force release stale locks (use with caution)
find .claude/hooks/.locks -mmin +5 -delete
冲突恢复
  1. 将当前工作保存到新分支
  2. 与 main 同步：git fetch && git rebase origin/main
  3. 逐个文件解决冲突
  4. 更新原生任务列表和持久化问题记录，以反映当前状态
  5. 继续工作

评论

支持 Markdown