OpenCode Agents 教程：Subagents 与 AGENTS.md 的 7 个检查

直接结论：AGENTS.md 适合写仓库级通用规则，OpenCode agents 适合定义带有独立提示词、模型、工具和安全边界的专门角色。先创建一个角色，用只读任务验证，再在能检查 diff 和回滚路径后开放写入能力。

AGENTS.md 适合沉淀长期有效的仓库规则，例如测试命令、代码风格、生成目录、review 要求和项目禁区。它不适合塞进所有专门工作流，否则共享规则会越来越难维护，也会限制无关任务。

OpenCode agents 更适合角色化行为。只要任务需要更窄的提示词、不同模型、受限工具集，或固定角色如 reviewer、planner、docs-editor、migration-checker，就应该考虑独立 agent。

subagent 适合处理可分离的问题：检查大目录、审阅高风险 diff、调研 API 或整理迁移清单。如果只是一次很小的修改，额外代理通常只会增加沟通成本。

有效的角色必须有明确产出。例如 review agent 返回带文件位置的发现，docs agent 返回受影响页面和补丁计划。不要用 helper、expert 这类宽泛名称。

代码审查、架构判断、安全相关分析和迁移规划可以使用推理能力更强的模型；摘要、格式化说明和简单文档草稿可以用更快或更便宜的模型。目标不是让每个 agent 都最强，而是让每个角色稳定可预期。

工具权限应尽量比主会话更窄。文档 agent 可能只需要读写 docs，测试 agent 可能需要 shell 但不需要访问密钥文件，研究 agent 可能需要联网但不需要写仓库。

团队配置可以进仓库，但 API key、provider token、私有 endpoint 和服务凭据不能进仓库。需要 token 的工具只记录环境变量名和最小 scope。

角色名称要稳定可读，例如 reviewer 或 docs-editor。实验角色可以保持禁用，或明确说明什么时候才使用，不要默认塞进所有会话。

第一次验证不要碰生产代码。可以让 agent 解释文件、列出假设、审阅一个小 diff，确认它遵守角色、范围和输出格式。

之后再允许一个小写入任务并检查 Git diff。如果它改了无关文件、忽略说明、执行错误命令或说不清改动，就先修提示词和权限边界。

1. 命名角色使用 reviewer、planner、docs-editor 等清晰名称。
2. 写清产出说明 agent 应该返回什么、禁止做什么。
3. 选择模型让推理深度和成本匹配角色风险。
4. 限制工具从能完成任务的最小工具集开始。
5. 只读验证先做解释、检查或审阅。
6. 检查小 diff首个写入任务干净后再扩大使用。
7. 记录规则写清什么时候用 agent，什么时候主会话足够。

最常见错误是还没验证一个角色是否有用，就先创建一堆 agents。每个角色都会增加选择成本，也可能造成任务路由混乱。

另一个错误是把 AGENTS.md 和 agent 规则混在一起。仓库事实放 AGENTS.md，角色行为放 agent；同一规则写两处很容易漂移。

agents 与窄集成组合时价值更高。reviewer 可以用只读 GitHub 或 issue MCP，release agent 可以依赖 hooks 跑检查，docs agent 可以复用写作 skill。集成应该服务角色，而不是让角色无限变宽。

任何能修改文件、issue、数据库或生产系统的集成都应逐层开放：先验证 agent 提示词，再验证工具，再验证写入路径。

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

团队配置可以进仓库，但 API key、provider token、私有 endpoint 和服务凭据不能进仓库。需要 token 的工具只记录环境变量名和最小 scope。