代理模式 (Agent Patterns)
概述
代理模式定义了 Sprint 插件中多代理冲刺执行的协调协议。它规定了主架构师如何生成实现和测试代理，代理如何通过结构化报告进行通信，以及并行代理如何避免冲突。
前提条件
- 已安装并配置 Sprint 插件 (
/plugin install sprint) - Sprint 目录已在
.claude/sprint/[N]/初始化 specs.md已编写，包含清晰的范围和测试配置- 熟悉冲刺阶段生命周期（请参阅
sprint-workflow技能）
说明
- 使用 SPAWN REQUEST 格式结构化每个代理生成。包含代理名称、应读取的规范文件以及任何范围约束：
SPAWN REQUEST Agent: python-dev Specs: .claude/sprint/1/backend-specs.md Contract: .claude/sprint/1/api-contract.md Scope: Authentication endpoints only - 确保每个生成的代理仅接收与其范围相关的文件。将
api-contract.md作为共享接口传递，以使后端和前端代理保持同步。 - 在完成后从每个代理收集结构化报告。每个报告必须包括：完成的工作、修改的文件、添加的测试以及相对于规范的符合性状态。
- 在并行运行代理时，根据域边界划分工作（例如，后端 vs. 前端 vs. CI/CD）。切勿将重叠的文件路径分配给并发代理。
- 将代理报告反馈给主架构师进行审查。架构师决定是迭代（使用更窄的规范重新生成）还是进入下一阶段。
- 对于测试代理，传递
${CLAUDE_SKILL_DIR}/references/ui-test-report.md中显示的 UI 测试报告格式，以便结果遵循一致的架构，包括测试计数、覆盖率、失败和控制台错误。
输出
- SPAWN REQUEST 块，由冲刺编排器使用以启动代理
- 结构化代理报告，包含：摘要、更改的文件、测试结果和符合性状态
- UI 测试报告，包含通过/失败计数、覆盖率详情、失败描述和控制台错误日志
- 每次迭代后更新的
status.md，反映已完成和待完成的工作
错误处理
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 代理接收到错误的规范文件 | SPAWN REQUEST 中的路径不正确 | 在生成前验证冲刺目录编号和文件名 |
| 并行代理的修改文件重叠 | 范围边界未明确定义 | 按域划分工作；为每个代理分配不同的目录 |
| 代理报告缺少必填字段 | 代理指令缺少报告格式 | 在代理提示中包含结构化报告模板 |
| 无限迭代循环 | 规范从未完全满足 | 检查 status.md 以查找阻塞问题；编排器在 5 次迭代后暂停 |
| 代理未找到 | SPAWN REQUEST 中的代理名称拼写错误 | 验证 agents/ 目录中存在代理 markdown 文件 |
示例
生成并行实现代理：
SPAWN REQUEST
Agent: python-dev
Specs: .claude/sprint/1/backend-specs.md
Contract: .claude/sprint/1/api-contract.md
SPAWN REQUEST
Agent: nextjs-dev
Specs: .claude/sprint/1/frontend-specs.md
Contract: .claude/sprint/1/api-contract.md
两个代理共享相同的 api-contract.md，以确保 API 兼容性。
结构化代理报告格式：
AGENT REPORT
Agent: python-dev
Status: COMPLETE
Files Modified: src/auth/routes.py, src/auth/models.py, tests/test_auth.py
Tests: 12 passed, 0 failed
Conformity: All backend-specs requirements implemented
Notes: JWT token expiry set to 24h per spec
测试代理协调：
SPAWN REQUEST
Agent: qa-test-agent
Specs: .claude/sprint/1/specs.md
Run After: python-dev, nextjs-dev
SPAWN REQUEST
Agent: ui-test-agent
Specs: .claude/sprint/1/specs.md
Run After: qa-test-agent
资源
${CLAUDE_SKILL_DIR}/references/ui-test-report.md-- 结构化的 UI 测试报告格式，包含覆盖率和失败跟踪- Sprint 工作流技能，用于阶段生命周期上下文
- API 合同技能，用于共享接口设计
- Sprint 插件 README，用于代理架构概述