agent.md

通用子智能体（subagent）委派指南 —— 适用于本仓库中通过 Claude Code Agent 工具派发任务的场景。

何时应该委派子智能体

适合委派：

跨多个文件 / 跨模块 的批量改动，需要并行检索或并行实现。
大规模搜索 —— 例如"找出所有调用某接口的页面"这种无需返回文件全文、只需结论的任务。
独立子任务 —— 任务 A 与任务 B 之间无数据依赖，可并行执行。
架构方案设计 —— 在写代码前需要先梳理出步骤、识别关键文件、权衡取舍。

不应委派：

单行修改、明显 typo、单个 API 的事实查询。
已经知道答案的本地查找（自己 Read / Grep 更快，且能保留上下文）。
与当前对话强耦合的、需要来回追问的多步任务（这种应留在主对话中）。
任务涉及权限边界或可能触发外部副作用（git push、删文件、付费 API）—— 委派前需要用户确认。

三种内置 Agent 的选用

任务类型	推荐 Agent	原因
只读搜索 / 取证式排查	`Explore`	跨目录扫文件，但不修改、不审阅
复杂多步研究 / 实施	`general-purpose`	可读写、可调用工具，适合端到端任务
纯方案设计（不写代码）	`Plan`	只产出步骤、关键文件、权衡，零副作用

选错 Agent 类型的代价：给 Explore 派了写代码任务 → 它没有 Edit / Write；给 Plan 派了执行任务 → 它只返回方案不实施。先想清楚是要"找东西"、"设计方案"还是"完成实施"。

编写委派 prompt 的通用模板

子智能体只看到你写在 prompt 中的内容，不会自动继承主对话的所有上下文。一份合格的 prompt 应包含：

## 目标
用一句话说清要达成什么。

## 范围
- 必须修改的文件 / 目录
- 不要触碰的文件 / 目录
- 是否允许新增文件

## 约束
- 包管理器、框架版本、代码风格
- 命名 / 目录约定
- 不要引入的依赖

## 上下文
- 必要的代码片段（用 file_path:line 引用，避免长粘贴）
- 已知的相关接口、配置项

## 验收标准
- 怎么算完成（测试通过？编译成功？某个文件出现？）
- 是否需要回报变更清单

## 工具使用提示（可选）
- 应优先使用 Read / Grep / Glob 而不是 Bash
- 是否需要运行测试 / lint

反模式：

只写"修一下这个 bug" —— 子智能体会反复追问。
把整个仓库的内容粘贴进去 —— 浪费 token，应改为引用 + 关键摘要。
把决策甩给子智能体 —— "用你觉得合适的方式重构" 这种开放式指令容易跑偏。

并行委派的注意事项

相互独立才能并行：两个 agent 不能同时改同一个文件，也不能互相读取对方刚写的内容。
把任务 ID / 文件路径写进 prompt，让结果可以交叉引用。
不要在主对话里 poll 子智能体的进度 —— 等待任务通知即可。

子智能体的边界与回退

子智能体的能力来自其工具集与上下文窗口，没有的能力包括：

跨会话长期记忆（除非明确写在项目 memory 文件中）。
访问用户的本地 IDE / 编辑器状态。
直接询问用户澄清问题（除非使用 AskUserQuestion，但需谨慎）。
跨 Agent 协调 —— 两个子智能体之间不能直接通信。

如果子智能体的产出不符合预期：

检查 prompt 是否清晰（80% 的问题是 prompt 模糊）。
把任务拆小再委派，不要一次性塞太多。
自己接手剩余部分，而不是无限重试。

通用禁止事项

无论派给哪种 Agent，都不应让它：

执行 git push、rm -rf、修改 CI secrets、付费 API 调用 —— 这些是主对话向用户确认的边界。
引入与现有架构冲突的大型依赖（如"加一个 Redux"），除非任务明确要求。
修改 .claude/settings.json 的权限规则 —— 这会改变所有后续会话的行为。
在没有 prompt 要求的情况下写测试、改 README、加注释 —— 子智能体倾向于过度产出。

完成检查清单

子智能体返回后，主对话应核对：

变更的文件是否都在 prompt 声明的范围内
是否产生了意外的副作用（新文件、依赖变更、配置文件改动）
是否有未声明的"顺手优化" —— 子智能体经常做超出范围的事
是否需要运行验证（build / test / lint）
是否需要向用户报告结果

agent.md 4.6 KB Histórico Raw