# 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 协调 —— 两个子智能体之间不能直接通信。

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

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

## 通用禁止事项

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

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

## 完成检查清单

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

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