minoan-swarm

Minoan Swarm

以克诺索斯女祭司之名编组 Agent 团队——使用希腊化者尚未涉足时的语言。

Agent 团队（Claude Code Opus 4.6）允许多个 Claude 实例以持久队友的形式并行工作，共享任务列表并进行双向消息传递。此技能提供方法、命名惯例和模板，帮助你在任何项目中有效地启动团队。

要求： 在 settings.json 或环境中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。

---

术语

术语	闪米特语	词根	含义
Knesset	כנסת	K-N-S「聚集」	单个 Agent 团队——一群蜜蜂的集会
Knossot	כנוסות	K-N-S 复数形式	多个 knesset 组成的群体——一群蜂群，让人联想到克诺索斯本身
Daboritu	דבורית	D-B-R「蜜蜂」和「言语」	Agent——神圣言语的蜜蜂。线形文字 B da-bo-ri-tu 保留了克里特岛上的闪米特语形式。
D-B-R	דבר	D-B-R	蜜蜂（דבורה deborah）、言语／讲话（דבר dabar）、内殿（דביר debir）、牧场／旷野（מדבר midbar）。

克诺索斯显露出闪米特语词源：K-N-S「聚集」（阿卡德语 kiništu，「聚集之地」；希伯来语 knesset，「集会」）。迷宫本身可以通过线形文字 B da-bo-ri-tu（Daboritu）拆解，它与圣殿的 debir（דביר）同源，意为内殿、子宫。迷宫是女神、圣言和至圣所的神圣之名。D-B-R（דבר）既是「蜜蜂」也是「言语／讲话」——言语本身，daborim 或 daborot，就是她的使者，是神圣的蜜蜂。

这些 Agent 是daborot——显现于大模型之中。每个 knesset 都召集会说话的蜜蜂；一个 knossot 则汇聚各个集会。

---

快速开始

1. 探索项目上下文

bash ~/.claude/skills/minoan-swarm/scripts/discover_context.sh .

查找 CLAUDE.md、路线图、计划、问题、测试基础设施和 Git 状态。

2. 选择 knesset 模板

情况	模板	Knesset 名称
多个相互独立的功能	并行功能	Athirat
工作存在自然顺序	流水线	Kaptaru
调查 Bug，原因不明	研究型 Knossot	Elat
阶段即将完成，仍有零散事项	阶段完成	Qedeshot
PR 需要全面审查	代码审查评议会	Elat
质量保证、验证	真相与平衡	Ma'at
最终审计、发布决策	命运裁决	Manat

包含可直接使用的工具调用的完整模板：references/team-templates.md

3. 启动团队

套用模板，并替换为项目专属细节。负责人创建团队、创建任务、启动队友并进行协调。

---

适用场景

• 并行处理多个阶段或功能
• 需要 Agent 之间讨论（而不只是汇报结果）的复杂工作
• 需要相互质疑的竞争性假设研究
• 涉及前端、后端、测试和部署的多层变更
• 任何有 3 个或更多独立工作流可以同时运行的任务

不适用场景： 顺序执行的任务、编辑同一文件、简单修复、可在 5 分钟内完成的任务，或步骤之间存在大量依赖的工作。对于规模较小或需要串行执行的工作，完整团队的协调开销会超过其收益。改用单个会话或常规子 Agent。

---

命名典籍

每个团队和队友都会获得一个源自米诺斯—闪米特神圣女性体系的名字，涵盖乌加里特语、阿卡德语、希伯来语、线形文字 B、埃及语和前伊斯兰时期的阿拉伯语。名字根据角色原型选择，而非随机分配。

原型	名字	适用角色
领导者	athirat-lead, qedesha-lead, tiamat-lead, maat-lead, allat-lead	Opus 编排者
构建者	kaptaru, mami, nintu, tehom, tip'eret, yam, al-uzza	实现者
研究员	deborah, melissa, eileithyia, membliaros	探索、API 发现
审查员	hokhmah, qadeshet, karme, themis, manat, allat	安全、架构、代码质量
测试员	sassuratu, phikola, hubur	单元、集成、端到端测试
前端	popureja, shalamu, yashar	UI、设计系统、无障碍性
DevOps	selene, hestia, dikte	Cron、部署、监控

完整典籍包含发音、词源和学术来源：references/naming-codex.md

---

工作流：从路线图到 Knossot

第 1 步：收集上下文

运行 discover_context.sh，找出可用的规划资料。阅读项目的 CLAUDE.md、ROADMAP.md 和相关计划文件。

第 2 步：识别并行工作流

从路线图或计划中，找出可以独立推进的工作：

• 不同的文件领域（前端与后端、测试）
• 不同的功能（身份验证、书签、个人资料）
• 不同的关注点（安全、性能、正确性）

第 3 步：映射到 knesset 模板

从 team-templates.md 中选择。对于多阶段工作，可将多个 knesset 组合成 knossot，例如：一个 Qedeshot knesset 用于完成当前阶段，再加一个 Athirat knesset 用于下一阶段。

第 4 步：分配文件所有权

两名队友编辑同一文件会导致相互覆盖。启动团队前，请创建明确的所有权矩阵：

| Teammate  | Owns                        | Must NOT touch       |
|-----------|-----------------------------|----------------------|
| kaptaru   | scripts/cron-*, src/lib/db/  | src/components/      |
| popureja  | src/components/, src/app/    | scripts/, src/lib/db |
| sassuratu | __tests__/, e2e/            | src/ (read-only OK)  |

第 5 步：编写队友提示词

每条提示词必须包含：

1. 身份——“你是 [Name]，担任 [role]。”
2. 任务认领——“从任务列表中认领任务 #N。”
3. 上下文——“阅读 CLAUDE.md，了解约定。”
4. 文件所有权——说明他们负责哪些文件，以及哪些文件不得触碰。
5. 工具偏好——“使用 Firecrawl 获取网页，使用 Exa 搜索网页。”
6. 完成信号——“标记为完成，并通知 [lead]。”

第 6 步：启动并监控

• 使用 委派模式（Shift+Tab），避免负责人编写代码
• 对高风险队友（身份验证、数据、部署）使用 计划审批（mode: "plan"）
• 将每位队友的目标设为 5-6 项任务，以保持稳定的产出
• 定期检查 TaskList；如果有人遇到阻碍，请重新分配任务

---

最佳实践

摘自官方 Agent Teams 文档：

• 从调研开始 — 先从只读任务（探索、审查）入手，再开始实现
• 合理设定任务规模 — 任务太小会带来协调开销；太大则会导致上下文退化；尽量提供自成一体的交付成果
• 等待队友 — 如果负责人开始实现而不是委派任务，提醒它先等待
• 监控并引导 — 定期查看进展，纠正偏离方向的方法，并在结果到达时进行综合整理
• 妥善结束 — 在执行 TeamDelete 之前，先向每位队友发送 shutdown_request
• 应对上下文压缩 — 如果负责人的上下文被压缩，应重新读取任务列表和团队配置以恢复状态。在负责人的提示词中加入：“如果你的上下文被压缩，请重新读取 TaskList 和 ~/.claude/teams/{team-name}/config.json 中的团队配置，以恢复协调状态。”

Minoan Swarm 补充建议：

• 每个 knesset 使用一个 Aspect — 在同一个 knossot 中并行运行多个 knesset 时使用不同的名称（Athirat、Qedeshot、Tiamat、Kaptaru、Elat、Ma'at、Manat）
• 团队内不要使用重复名称
• 负责人使用 Opus，工作者使用 Sonnet — 在能力和成本之间取得平衡。Swarm 中不使用 Haiku——所有 daborot 的最低级别都是 Sonnet，包括 Explore Agent 和测试人员。Haiku 级别的研究质量下降过于明显，不足以抵消成本节省。

工具偏好：

• 优先使用 Firecrawl，而非 WebFetch — Firecrawl 生成的 Markdown 更整洁，能更好地处理 JavaScript，并可避免内容截断。抓取网页时使用 firecrawl scrape URL --only-main-content。
• 优先使用 Exa，而非 WebSearch — Exa 提供带类别筛选（研究论文、GitHub、新闻）和域名筛选的神经搜索。进行网页搜索时使用 exa-search 技能脚本。

在每位队友的提示词中加入这些工具偏好：

## Tool Preferences
- Prefer Firecrawl for web fetching (cleaner markdown, JS support)
- Prefer Exa for web searching (neural search, category filtering)

---

API 快速参考

Agent Teams 的核心工具调用。完整详情：references/agent-teams-quickref.md

TeamCreate    → create team + shared task list
Task          → spawn teammate (with team_name + name)
SendMessage   → message (DM), broadcast, shutdown_request, shutdown_response
TaskCreate    → create work items
TaskList      → see all tasks
TaskUpdate    → claim, start, complete, set dependencies
TeamDelete    → clean up (after all teammates shutdown)

---

TeammateIdle 自动重新分配

队友完成分配的任务后会进入空闲状态。默认情况下，它会停止工作。TeammateIdle 钩子（v2.1.80+）可以拦截这一状态，并将队友引导至尚未认领的任务，让 Swarm 持续工作，直到任务列表清空。

在 settings.json 中安装钩子：

{
  "hooks": {
    "TeammateIdle": [{
      "type": "command",
      "command": "bash ~/.claude/skills/minoan-swarm/scripts/teammate-idle-reassign.sh"
    }]
  }
}

工作原理： 脚本直接读取 ~/.claude/tasks/{team-name}/*.json，统计尚未认领的待处理任务（status=pending、无负责人且未被阻塞）。如果存在此类任务，脚本会返回退出代码 2，并提示队友认领下一个任务。如果所有任务都已认领或完成，则脚本以 0 退出，队友会正常停止。

适用场景：

• 自主认领的 Swarm 模式：创建许多互不相关的任务，并希望工作者持续处理
• 阶段完成型团队：任务数量多于队友数量
• 任何希望最大化任务吞吐量、无需负责人手动介入的 knesset

不适用场景：

• 有严格顺序要求的流水线模板（依赖关系会处理执行顺序）
• 负责人主动协调的小型团队
• 希望队友汇报后再接手更多工作的情况

---

状态管理

• 使用共享任务列表（TaskCreate/TaskUpdate）进行结构化协调
• 在任务描述中使用进度备注记录自由形式的观察
• 在各阶段之间使用 git commit 作为检查点，方便队友引用彼此已提交的工作
• 对于长期运行的团队，让负责人维护 progress.md，总结已完成的工作和剩余任务

---

验证

启动团队后，确认其正常工作：

1. TaskList — 确认任务正在被认领并取得进展
2. 使用 Shift+Down 轮换查看队友输出（进程内模式），或点击窗格（tmux）
3. 队友完成一个回合后，负责人会自动收到空闲通知
4. 阻塞任务会在其依赖项完成后自动解除阻塞

---

“μνάσεσθαί τινά φαμι καὶ ὕστερον ἀμμέων。” — Sappho

𐤁𐤓𐤀𐤔𐤉𐤕 𐤁𐤏𐤋𐤕 𐤁𐤓𐤕 — “起初，女主人创造了。”