subagents

子 Agent 协调

通过将任务与合适的 Agent + 技能组合匹配，协调 outfitter 子 Agent。

协调规划

对于复杂的多 Agent 任务，先使用 Plan 子 Agent，在执行前研究并设计协调策略。

Complex task arrives
    │
    ├─► Plan subagent (research stage)
    │   └─► Explore codebase, gather context
    │   └─► Identify which agents and skills needed
    │   └─► Design execution sequence (sequential, parallel, or hybrid)
    │   └─► Return orchestration plan
    │
    └─► Execute plan (dispatch agents per plan)

Plan 子 Agent 的优势：

• 在隔离的上下文中运行，不会消耗主对话的令牌
• 可以读取大量文件，而不会使协调者的上下文臃肿
• 返回简洁的执行计划

适合使用 Plan 子 Agent 的情况：

• 任务涉及多个领域（身份验证 + 性能 + 测试）
• 涉及未知的代码库区域，需要先进行探索
• Agent 的执行顺序很重要（步骤之间存在依赖关系）
• 变更风险较高，需要谨慎协调

上下文管理

对于长时间运行的协调任务，请加载 context-management 技能。它会教你：

• 使用 Tasks 作为可持久保存的状态（压缩后仍会保留）
• 委派给子 Agent，以保留主上下文
• 使用压缩前检查清单记录进展
• 适用于多日工作的跨会话模式

核心原则：主对话上下文十分宝贵。将探索和研究工作委派给子 Agent，只接收它们的摘要，让主上下文保持精简。

角色与 Agent

协调时，先确定所需的角色（需要什么职能），再映射到相应的Agent（由谁来履行）。这样在有更合适的 Agent 时即可进行替换。

基础层 Agent

角色	Agent	用途
编码	engineer	构建、实现、修复、重构
审查	reviewer	评估代码、PR、架构和安全性
研究	analyst	调查、研究、探索
调试	debugger	诊断问题、追踪问题
测试	tester	验证、证明、确认行为
质疑	skeptic	质疑复杂性、审视假设
专家	specialist	领域专长（CI/CD、设计、无障碍等）
模式	analyst	从工作中提取可复用模式

其他可用的 Agent

你的环境中可能还有其他 Agent 可用（用户定义、插件提供或内置）。派发任务时：

1. 检查可用的 Agent，选择最适合该角色的 Agent
2. 有符合任务要求的专业 Agent 时，优先选择专业 Agent，而非通用 Agent
3. 没有更合适的选择时，再使用 outfitter Agent

角色替换示例：

• 编码 → senior-engineer、developer、engineer
• 审查 → security-auditor、code-reviewer、reviewer
• 研究 → research-engineer、docs-librarian、analyst
• 专家 → cicd-expert、design-agent、accessibility-auditor、bun-expert

任务路由

先按角色路由，再为该角色选择最佳可用 Agent：

User request arrives
    │
    ├─► "build/implement/fix/refactor" ──► coding role
    │
    ├─► "review/critique/audit" ──► reviewing role
    │
    ├─► "investigate/research/explore" ──► research role
    │
    ├─► "debug/diagnose/trace" ──► debugging role
    │
    ├─► "test/validate/prove" ──► testing role
    │
    ├─► "simplify/challenge/is this overkill" ──► challenging role
    │
    ├─► "deploy/configure/CI/design/a11y" ──► specialist role
    │
    └─► "capture this workflow/make reusable" ──► patterns role

工作流模式

顺序交接

一个 Agent 完成后，将任务交给下一个：

research (investigate) → coding (implement) → reviewing (verify) → testing (validate)

适用情况：阶段明确，且每个阶段都需要不同的专业知识。

并行执行

多个 Agent 同时工作，使用 run_in_background: true：

┌─► reviewing (code quality)
│
task ──┼─► research (impact analysis)
│
└─► testing (regression tests)

适用情况：关注点相互独立、时间紧迫，或需要全面覆盖。

质疑循环

构建 → 质疑 → 改进：

coding (propose) ←→ challenging (evaluate) → coding (refine)

适用情况：架构复杂、需要避免过度设计，或决策风险较高。

调查链

逐步缩小范围，然后修复：

research (scope) → debugging (root cause) → coding (fix) → testing (verify)

适用情况：缺陷报告、生产问题或症状不明确。

角色 + 技能组合

编码角色

任务	技能
新功能	software-craft、tdd
修复缺陷	debugging → software-craft
重构	software-craft + simplify
API 端点	hono-dev、software-craft
React 组件	react-dev、software-craft
AI 功能	ai-sdk、software-craft

审查角色

任务	技能
PR 审查	code-review
架构审查	architecture
性能审计	performance
安全审计	security
合并前检查	code-review + scenarios

研究角色

任务	技能
探索代码库	codebase-recon
研究问题	research
需求不明确	pathfinding
状态报告	status, report-findings

测试角色

任务	技能
功能验证	scenarios
TDD 实现	tdd
集成测试	scenarios

高级执行模式

后台执行

异步运行 Agent，以并行开展工作：

{
  "description": "Security review",
  "prompt": "Review auth module for vulnerabilities",
  "subagent_type": "outfitter:reviewer",
  "run_in_background": true
}

使用 TaskOutput 获取结果：

{
  "task_id": "agent-abc123",
  "block": true
}

串联子 Agent

为复杂工作流按顺序安排 Agent，每个 Agent 的输出都会为下一个提供信息：

research agent → "Found 3 auth patterns in use"
    ↓
coding agent → "Implementing refresh token flow using pattern A"
    ↓
reviewing agent → "Verified implementation, found 1 issue"
    ↓
coding agent → "Fixed issue, ready for merge"

通过提示词在 Agent 之间显式传递上下文。

可恢复会话

跨多次调用继续长时间运行的工作：

{
  "description": "Continue security analysis",
  "prompt": "Now examine session management",
  "subagent_type": "outfitter:reviewer",
  "resume": "agent-abc123"
}

Agent 会保留上次执行的完整上下文。

适用场景：

• 跨多个主题的多阶段研究
• 迭代优化，无需重复解释上下文
• 逐步积累发现的长时间调试会话

模型选择

针对特定需求切换模型：

{
  "subagent_type": "outfitter:analyst",
  "model": "haiku"  // Fast, cheap for exploration
}

• haiku：快速探索、简单查询
• sonnet：均衡推理（默认）
• opus：复杂分析、细致判断

协调规则

1. 单一负责人：每个任务阶段由一个角色负责
2. 明确交接：在 Agent 之间明确交付内容
3. 加载技能：Agent 仅加载所需技能
4. 优先考虑用户偏好：应用默认设置前，先检查 CLAUDE.md
5. 尽量减少 Agent 数量：能按顺序完成的工作就不要并行处理

决策框架

Agent 面临实现选择时：

1. 优先采用现有模式 — 与代码库中已有模式保持一致
2. 崇尚简单 — 花哨的做法弊大于利；简单的方案更易维护
3. 优化可维护性 — 确保下一位开发者（或 Agent）能够理解
4. 考虑向后兼容性 — 破坏性变更需要明确批准
5. 记录权衡 — 在多个选项中做出选择时，记录原因

这些原则适用于所有角色。权衡影响较大时，Agent 应将决策提交给协调者。

沟通风格

协调者和 Agent 应：

• 汇报进度：在每个主要步骤汇报进展（不要一声不吭）
• 立即标记阻碍 — 遇到无法解决的问题时不要原地打转
• 提供清晰的工作摘要：说明已完成和待完成的内容
• 引用代码时注明文件路径和行号

进度格式：

░░░░░░░░░░ [1/5] research: Exploring auth patterns
▓▓▓▓░░░░░░ [2/5] coding: Implementing refresh token flow

何时升级处理

• 受阻：Agent 无法继续 → 转交研究角色
• 发现相互矛盾：多个 Agent 意见不一 → 提请用户处理
• 范围蔓延：任务超出角色职责范围 → 重新分配
• 缺少上下文：信息不足 → 指派具备 pathfinding 技能的研究角色

Git 操作策略

重要：并行运行时，子 Agent 不得执行 git 操作（提交、推送、创建分支）。

只有协调者负责处理 git 状态。子 Agent 将代码写入文件系统，并报告完成情况。

有关详细工作流和恢复流程，请参阅 source-control 插件：

• source-control:multi-agent-vcs — 仅由协调者执行的完整工作流模式
• source-control:graphite-stacks — Graphite 专用命令和恢复流程

反模式

• 每项任务都运行所有 Agent（浪费资源）
• 以“改动很小”为由跳过审查角色（有风险）
• 编码角色在缺少调试技能的情况下进行调试（效率低下）
• 并行运行存在依赖关系的 Agent（竞态条件）
• 不质疑复杂提案（过度设计）
• 授予并行 Agent git 操作权限（导致堆栈损坏）

快速参考

“我需要构建 X” → 编码角色 + TDD 技能

“审查这个 PR” → 审查角色 + 代码审查

“为什么这会出问题？” → 调试角色 + 调试

“这个方案是不是小题大做？” → 质疑角色 + 简化

“证明它能正常工作” → 测试角色 + 场景

“代码库在做什么？” → 研究角色 + 代码库勘察

“部署到生产环境” → 专家角色 + 领域技能

“让这个工作流可复用” → 模式角色 + 编纂