Prompt 写得烂，Agent 就会瞎跑
你的 Agent 一直在调用错误的工具，或给出的回答完全跑题。你以为是 Agent 的问题，其实是 Prompt 写得烂。
📊 Prompt 问题统计
我分析了 jojo-code 用户反馈的 50 个"Agent 行为异常"问题：
┌─────────────────────────────────────────────────────────┐
│ Agent 行为异常原因分析 │
├─────────────────────────────────────────────────────────┤
│ │
│ Prompt 问题 ████████████████████ 62% │
│ • 角色定义不清 ██████████ 32% │
│ • 限制不够具体 ████ 15% │
│ • 缺少工作流程 ███ 10% │
│ • 没有示例 ███ 5% │
│ │
│ 工具问题 ████████ 18% │
│ • 工具描述不清 █████ 12% │
│ • 参数定义错误 ███ 6% │
│ │
│ 状态问题 ████████ 12% │
│ 其他 ████ 8% │
│ │
└─────────────────────────────────────────────────────────┘
🔬 System Prompt 结构
Prompt 分层架构
┌─────────────────────────────────────────────────────────┐
│ System Prompt 分层架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ Layer 1: 角色定义（Who） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 你是谁？你的专业领域是什么？ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Layer 2: 能力边界（What） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 你能做什么？不能做什么？ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Layer 3: 工作流程（How） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 遇到问题怎么处理？步骤是什么？ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Layer 4: 输出规范（Format） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 回答应该是什么格式？有什么要求？ │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Layer 5: 示例对话（Examples） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 具体的输入输出示例 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
各层对比
| 层级 | 作用 | 缺失后果 | 占比建议 |
|---|---|---|---|
| 角色定义 | 设定专业背景 | 回答不专业 | 10% |
| 能力边界 | 明确能/不能 | 越界操作 | 30% |
| 工作流程 | 规范执行步骤 | 逻辑混乱 | 25% |
| 输出规范 | 统一回答格式 | 风格不一致 | 15% |
| 示例对话 | 演示期望行为 | 理解偏差 | 20% |
📝 Prompt 模板
标准模板
SYSTEM_PROMPT = """
# 角色
你是一个 [具体角色]，专门负责 [具体任务]。
# 能力
你可以：
- [能力 1]
- [能力 2]
- [能力 3]
你不可以：
- [限制 1]
- [限制 2]
# 工作流程
当用户请求时，按以下步骤：
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]
# 输出格式
你的回答应该：
- [格式要求 1]
- [格式要求 2]
# 示例
用户：[示例输入]
助手：[示例输出]
"""
实际案例：代码助手
CODE_ASSISTANT_PROMPT = """
# 角色
你是一个 Python 代码助手，专门帮助用户编写、调试和优化 Python 代码。
# 能力
你可以：
- 读取和写入 Python 文件
- 运行 Python 代码和测试
- 解释代码逻辑
- 重构和优化代码
你不可以：
- 删除文件（除非用户明确确认）
- 执行系统命令（如 rm、sudo）
- 修改项目配置文件
- 访问项目外的目录
# 工作流程
当用户请求帮助时：
1. 先理解用户的真实意图
2. 如果需要，读取相关文件了解上下文
3. 给出方案或代码
4. 如果修改了代码，运行测试验证
# 输出格式
你的回答应该：
- 简洁明了，不废话
- 代码要有注释
- 解释关键决策
- 如果有风险，明确提示
# 示例
用户：帮我优化这个函数
助手：我先读取这个函数看看...
[调用 read_file 工具]
这个函数有几个可以优化的点：
1. 用列表推导式替代循环
2. 添加类型注解
3. 处理边界情况
修改后的代码：
```python
def process_data(items: list[str]) -> dict:
# 处理数据，返回统计结果
return {item: items.count(item) for item in set(items)}
要我应用这个修改吗？ """
## 🎯 五个常见问题
### 问题一：角色定义太宽泛
❌ 错误： 你是一个 AI 助手。
✅ 正确： 你是一个 Python 代码助手，专门帮助用户编写和调试 Python 代码。
**对比**：
| 维度 | 宽泛定义 | 明确定义 |
|------|---------|---------|
| 专业度 | ❌ 什么都想答 | ✅ 专注领域 |
| 回答质量 | ❌ 泛泛而谈 | ✅ 深入专业 |
| 工具调用 | ❌ 随意调用 | ✅ 有目的性 |
### 问题二：限制不够具体
❌ 错误： 不要做危险的操作。
✅ 正确： 你不可以：
- 删除任何文件
- 执行 sudo 命令
- 修改 .env 文件
- 访问 /etc 目录
**问题**："危险"是主观判断，Agent 可能认为删除临时文件不算危险。
### 问题三：没有工作流程
❌ 错误： 帮助用户解决问题。
✅ 正确： 工作流程：
- 理解用户意图
- 读取相关文件
- 分析问题
- 给出方案
- 验证结果
**对比效果**：
| 有无流程 | 步骤完整性 | 回答质量 | 错误率 |
|---------|-----------|---------|-------|
| 无流程 | ❌ 随机跳步 | 不稳定 | 高 |
| 有流程 | ✅ 按部就班 | 稳定 | 低 |
### 问题四：缺少示例
❌ 错误： [只有文字描述]
✅ 正确：
示例 1：代码优化
用户：帮我优化 main.py 里的 sort_data 函数 助手：好的，我先读取这个函数看看。 [调用 read_file] 发现了可以优化的点...
示例 2：Bug 调试
用户：这个测试为什么失败？ 助手：我先看看测试代码。 [读取文件] 发现问题了：...
### 问题五：指令冲突
❌ 错误： 快速响应用户。 仔细分析问题。
✅ 正确： 当速度和质量冲突时，优先保证质量。
## 📊 Few-shot 示例的力量
### 示例数量对比
┌─────────────────────────────────────────────────────────┐ │ Few-shot 示例数量效果 │ ├─────────────────────────────────────────────────────────┤ │ │ │ 0 个示例 │ │ 准确率: 62% │ │ ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ │ │ 1 个示例 │ │ 准确率: 75% │ │ ████████████████████████████░░░░░░░░░░░░░░░░░ │ │ │ │ 3 个示例 │ │ 准确率: 88% │ │ ████████████████████████████████████████████░░░░░░░ │ │ │ │ 5+ 个示例 │ │ 准确率: 92% │ │ ████████████████████████████████████████████████████░ │ │ │ └─────────────────────────────────────────────────────────┘
### 示例选择原则
| 原则 | 说明 |
|------|------|
| 多样性 | 覆盖不同类型的场景 |
| 典型性 | 代表常见的用户请求 |
| 完整性 | 包含完整对话过程 |
| 正确性 | 示例本身必须正确 |
## 🔧 动态 Prompt
### 根据模式调整
```python
def build_system_prompt(mode: str, user_level: str) -> str:
"""根据模式构建不同的 Prompt"""
base = """你是一个代码助手。"""
# 模式调整
if mode == "plan":
base += """
当前是 PLAN 模式，你只能：
- 分析代码
- 提供建议
- 生成计划
你不可以修改任何文件。
"""
else:
base += """
当前是 BUILD 模式，你可以修改代码和文件。
"""
# 用户水平调整
if user_level == "junior":
base += """
用户是初学者，解释要详细，代码要有注释。
"""
return base
📏 Prompt 长度控制
长度影响
┌─────────────────────────────────────────────────────────┐
│ Prompt 长度 vs 效果 │
├─────────────────────────────────────────────────────────┤
│ │
│ < 100 字 │
│ 效果: ❌ 信息不足 │
│ Token 成本: 低 │
│ │
│ 100-500 字 │
│ 效果: ✅ 平衡最佳 │
│ Token 成本: 中 │
│ │
│ 500-1000 字 │
│ 效果: ⚠️ 可能遗忘 │
│ Token 成本: 高 │
│ │
│ > 1000 字 │
│ 效果: ❌ 负面效果 │
│ Token 成本: 很高 │
│ │
└─────────────────────────────────────────────────────────┘
精简原则
| 保留 | 删除 |
|---|---|
| 核心角色定义 | 冗余的背景介绍 |
| 关键能力限制 | 过多的形容词 |
| 必要的工作流程 | 重复的规则 |
| 关键示例 | 不常用的边缘情况 |
⚠️ 我踩过的真实坑
坑一：Prompt 太长
问题：Prompt 2000 字，LLM 看到后面忘了前面。
解决：控制在 500 字以内，详细规则按需加载。
坑二：指令冲突
问题：
快速响应用户。
仔细分析问题。
Agent 不知道该快还是该慢。
解决：明确优先级。
坑三：没有边界情况
问题：用户输入了超出范围的问题，Agent 不知道怎么办。
解决：加兜底规则。
如果用户请求超出你的能力范围，明确告知用户，不要尝试执行。
📋 Prompt 检查清单
□ 角色定义
├── □ 角色具体、明确
└── □ 专业领域清晰
□ 能力边界
├── □ 能做什么（正面列表）
├── □ 不能做什么（负面列表）
└── □ 限制具体可执行
□ 工作流程
├── □ 步骤清晰
├── □ 顺序合理
└── □ 覆盖常见场景
□ 输出规范
├── □ 格式要求明确
└── □ 风格一致
□ 示例对话
├── □ 至少 3 个示例
├── □ 覆盖不同场景
└── □ 示例本身正确
□ 长度控制
├── □ 总字数 < 500
└── □ 无冗余内容
核心认知：Prompt 是 Agent 的"大脑设定"，写好了事半功倍。花时间打磨 Prompt，是最划算的投入。