子智能体 Brief
主智能体在召唤子智能体时下发的一份标准化任务书，用固定字段把任务边界、权限、输出位置和停止条件提前写死，让子智能体”不自由发挥”，是多智能体协作可控性的基础单元
简介
子智能体 Brief（sub-agent brief）是多智能体编排中，主智能体（coordinator）每次创建或调用一个子智能体时下发的标准化”任务书”。它的核心价值不在于告诉子智能体”做什么”，而在于用一组固定字段把任务边界、允许的编辑范围、禁止事项、工具权限、输出位置、完成标准、停止条件全部提前显性化，从而避免子智能体自由发挥、越权改动或陷入无限探索。
在 Coding Agent 进入复杂任务阶段后，单个 Agent 容易出现上下文污染、角色混淆、责任边界不清等问题。子智能体 Brief 正是把”临时创建的工程成员”的职责说明书标准化——主智能体像项目负责人，每个子智能体像被明确授权的工程成员。没有 Brief，多智能体很容易退化成”一句话派活”（如”你去测试一下”），结果是子智能体边界模糊、返回内容不可控。
关键信息
- 类型：任务契约 / 编排规范
- 领域：多智能体协作 / Coding Agent 工程化
- 核心作用：把任务边界与权限提前写死，约束子智能体行为
- 必须字段：11 个（见下）
- 配套机制：文件交接协议（输出协议）、验证策略、重试与阻塞策略
- 相关概念：Multi-Agent 系统、多Agent架构、Coding Agent、Skill
核心特性
标准 Brief 的 11 个字段
每次创建或调用子智能体，都应给出一份包含以下字段的完整 Brief：
| 字段 | 含义 |
|---|---|
role_name | 本次子智能体的角色名，必须贴合当前任务 |
mission | 本次唯一任务目标，只能有一个主要目标 |
when_to_use | 为什么当前任务需要这个角色 |
input_files | 开始前必须读取哪些文件 |
allowed_edit_scope | 允许修改哪些文件或目录 |
forbidden_actions | 禁止做什么（不能删文件、改配置、提交代码、改测试等） |
tools_policy | 允许使用哪些工具（只读 / 可编辑 / 可跑测试 / 可启服务） |
output_path | 结果必须写到哪里 |
success_criteria | 什么叫完成，必须可验证 |
stop_condition | 什么时候必须停止（需求不清、测试失败、权限不足、超范围） |
handoff_format | 如何把结果交还给主智能体 |
一个”实现型”子智能体 Brief 示例
role_name: auth-api-implementer
mission: 实现用户登录接口的参数校验和错误返回逻辑
input_files:
- src/routes/auth.ts
- src/services/auth-service.ts
- tests/auth.test.ts
allowed_edit_scope:
- src/routes/auth.ts
- src/services/auth-service.ts
forbidden_actions:
- 不允许修改测试文件
- 不允许改数据库 schema
- 不允许删除现有接口
- 不允许提交 git commit
tools_policy:
- 可以读取文件
- 可以编辑 allowed_edit_scope 内的文件
- 可以运行相关测试
output_path: .agent-runs/2026-07-01/task-003/implementation-report.md
success_criteria:
- 登录接口能正确处理缺失参数
- 错误返回格式与现有接口一致
- 相关测试可以通过
stop_condition:
- 如果发现现有测试与需求冲突，立即停止并报告
- 如果需要修改 allowed_edit_scope 之外的文件，立即停止并请求主智能体判断
handoff_format: STATUS / REPORT / CHANGED_FILES / TEST_COMMAND / NOTES
为什么字段要”提前写死”
Brief 的价值在于它不会让子智能体自由发挥：
allowed_edit_scope+forbidden_actions圈定改动范围，防止”改 A 坏 B”式的连带修改stop_condition让子智能体在遇到超范围、需求冲突时主动停下来请示，而不是硬猜success_criteria强制”完成”必须可验证，配合验证策略防止”说完成”却无证据output_path+handoff_format保证结果落到固定位置、以固定结构回传，衔接 文件交接协议
子智能体不决定下一步
一个关键约束：子智能体完成任务后只返回状态和结果地址，不自己决定下一步召唤谁。下一步由主智能体判断。这防止多智能体失控成”Agent 继续召唤 Agent”，让上下文、成本、任务边界始终由 coordinator 掌控。Brief 中的 handoff_format 就是为这个约束服务的——它只回传状态，不回传”决策”。
不同素材中的观点
来自 2026-07-01-woshipm-multi-agent-coding-pipeline：
- Brief 是多智能体可控性的最小单元：作者认为不应提前写死 planner/developer/tester/reviewer 等固定角色，而应建立”动态子智能体生成规范”——每次按任务动态生成一份 Brief。主智能体像项目负责人，子智能体像临时创建的工程成员，每个成员都必须有明确任务、明确权限、明确输出位置
- 强制完整 Brief 优于”一句话派活”：在设计 Skill 时，
role-attribute-schema.md这个文件的作用就是强制主智能体生成完整 Brief，“不要让主智能体随便写一句’你去测试一下’” - Brief 与验证/重试机制配套：
success_criteria必须可验证，stop_condition定义何时停下请示，这两个字段直接支撑了”验证策略”和”重试与阻塞策略”的落地
实用信息
如何为不同角色写 Brief
- 调查型（只读）：
tools_policy设为只读，allowed_edit_scope为空，output_path指向调查报告 - 实现型：
allowed_edit_scope精确到具体文件，forbidden_actions明确禁止改测试/配置/提交 - 测试型：
tools_policy允许跑测试，forbidden_actions禁止改实现代码，output_path指向测试报告 - 审查型：只读，
forbidden_actions禁止改任何代码，输出审查报告 - UI 验证型：允许启动服务/截图，
output_path指向截图目录和观察结果
注意事项
- 一个 Brief 只承载一个 mission：多目标会让子智能体分心、边界模糊，需要拆成多个 Brief
forbidden_actions要显式列出：AI 擅长遵守”禁止”规则，明确禁止比模糊授权更有效success_criteria必须可验证：“功能正常”不算标准，“相关测试通过”才算- Brief 应做成 Skill 的强制规范：把字段 schema 写进
role-attribute-schema.md，让主智能体每次自动生成而非临时拼凑