5.2d Agent 高级技巧

#### 3. 描述要像优秀的 docstring

工具描述应该包含：
- **功能说明**：这个工具做什么
- **使用示例**：典型用法
- **边界情况**：什么时候不该用
- **输入格式**：参数要求

### Anthropic 的实际经验

> "在构建 SWE-bench Agent 时，我们花在优化工具上的时间比优化整体 prompt 还多。"

他们发现模型会在使用相对路径时出错（当 Agent 移出根目录后）。解决方案：改为要求**绝对路径**——模型完美执行。

**启示**：如果 Agent 频繁在某个工具上出错，问题可能在工具设计，而非 prompt。

---

## Prompt 工程

<AdInArticle />

### 系统提示词结构

一个好的 Agent prompt 应该包含：

```markdown
---
description: 简短描述（影响自动选择）
mode: subagent
temperature: 0.2
---

# 角色定义
你是谁、擅长什么。

# 工作流程
1. 第一步做什么
2. 第二步做什么
3. ...

# 约束条件
- 不要做什么
- 什么情况下停止

# 输出格式
- 如何组织输出
- 包含哪些部分

# 自我检查（可选）
完成前问自己几个问题。

{
  "agent": {
    "deep-thinker": {
      "description": "深度思考，处理复杂问题",
      "model": "openai/o1",
      "reasoningEffort": "high",     // OpenAI 特定参数
      "textVerbosity": "low"          // OpenAI 特定参数
    },
    "quick-helper": {
      "description": "快速响应，处理简单问题",
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.3
    }
  }
}

.opencode/agent/
├── review/
│   ├── security.md       → 名称: review/security
│   └── performance.md    → 名称: review/performance
├── docs/
│   └── api.md            → 名称: docs/api
└── translator.md         → 名称: translator

@review/security 帮我审计这段代码

{
  "agent": {
    "safe-agent": {
      "permission": {
        "mymcp_*": "deny",           // 禁用 mymcp 的所有工具
        "postgres_query": "ask"       // 数据库查询需确认
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "pr-reviewer": {
      "description": "PR 审查机器人，自动审查代码变更",
      "mode": "primary",
      "model": "anthropic/claude-opus-4-5-thinking",
      "steps": 100,
      "temperature": 0.1,
      "prompt": "{file:./prompts/pr-reviewer.md}",
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "deny",
          "git log*": "allow",
          "git diff*": "allow",
          "git show*": "allow",
          "npm test": "allow"
        },
        "task": {
          "*": "deny",
          "security-auditor": "allow",
          "performance-checker": "allow",
          "style-checker": "allow"
        }
      }
    }
  }
}

{
  "agent": {
    "planner": {
      "description": "规划者：分析需求，制定计划",
      "mode": "primary",
      "model": "anthropic/claude-opus-4-5-thinking",
      "temperature": 0.2,
      "steps": 20
    },
    "executor": {
      "description": "执行者：实现具体代码",
      "mode": "primary", 
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "steps": 100
    },
    "reviewer": {
      "description": "审查者：检查代码质量",
      "mode": "subagent",
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.1,
      "permission": {
        "edit": "deny"
      }
    }
  }
}