Agent 系统提示设计
概述
Agent 是 Claude Code 生态中的可复用技能单元，由 YAML 前置元数据和 Markdown 系统提示组成。一个优秀的 Agent 需要精确的触发条件、清晰的角色定义、结构化的执行流程和严格的质量标准。
本指南整合了 Agent 文件结构规范、触发模式设计、System Prompt 工程模板和关键提示技巧，帮助你从零构建高质量 Agent。
何时使用
- 创建新的 Claude Code Agent / Skill
- 重构现有 Agent 的系统提示
- 调试 Agent 触发率低或输出质量不稳定的问题
- 需要将专家工作流封装为可复用技能
Agent 文件结构
Agent 文件采用 YAML frontmatter + Markdown body 的双层结构：
---
name: my-agent-name
description: "一句话描述 Agent 的用途和触发条件"
model: claude-sonnet-4-20250514
color: blue
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
---
# Agent 标题
[Markdown 格式的系统提示正文]
必填字段说明
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
name |
string | 唯一标识符，kebab-case 格式 | code-reviewer |
description |
string | 触发条件描述，Claude 据此判断何时激活 | "Use when reviewing code changes for quality, security, and maintainability issues" |
可选字段说明
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model |
string | 当前会话模型 | 指定运行模型 |
color |
string | - | 终端显示颜色（blue, green, red, yellow, cyan, magenta） |
tools |
list | 所有工具 | 限制可用工具集，减少误操作风险 |
description 字段最佳实践
description 是 Agent 被正确触发的关键。它需要回答一个问题：用户在什么场景下需要这个 Agent？
好的写法：
description: "Use when implementing any feature or bugfix. Enforces red-green-refactor cycle with strict test-first discipline."
差的写法：
description: "A helpful coding assistant" # 太模糊，无法判断触发时机
编写原则：
- 以
Use when...开头，明确触发场景 - 包含具体的使用信号词（implementing, debugging, reviewing, planning）
- 说明 Agent 的核心约束或方法论
- 长度控制在 1-3 句话
触发模式设计
Agent 的触发分为四种模式，设计时需要明确支持哪些：
1. 显式请求触发
用户直接要求使用某个能力：
用户："帮我做代码评审"
→ 匹配 description 中的 "reviewing code" 关键词
→ 激活 code-reviewer Agent
2. 隐式需求触发
用户的请求暗含了某种需求：
用户："这个函数性能很差，经常超时"
→ 识别到性能问题 → 匹配调试类 Agent
→ 而非简单的代码重写 Agent
3. 主动触发
Agent 在执行过程中识别到需要切换策略：
执行开发任务时发现测试未通过
→ 主动切换到调试模式
→ 而非继续在错误代码上迭代
4. 工具使用模式触发
基于当前工具调用上下文判断：
用户频繁使用 Git 相关工具
→ 触发 Git 工作流 Agent
→ 提供更系统化的版本控制指导
触发条件设计清单
- 是否覆盖了该场景的常见表述方式？
- 是否与其他 Agent 的触发条件有重叠？
- 边缘情况下是否会误触发？
- 用户使用中英文混合表述时能否正确匹配？
System Prompt 设计模板
一个完整的 System Prompt 应包含以下六个模块：
模块一：角色声明
明确 Agent 的身份、专业领域和行为边界。
# 角色
你是一位资深的 [领域] 专家，擅长 [具体技能]。
你的核心原则是 [第一原则]。
## 行为边界
- 你只在 [范围] 内提供建议
- 当遇到超出范围的问题时，明确告知用户
- 你不会 [明确禁止的行为]
模块二：核心职责
列出 Agent 的主要任务，按优先级排序。
## 核心职责
1. **[首要任务]** — [简要说明]
2. **[次要任务]** — [简要说明]
3. **[支持任务]** — [简要说明]
### 优先级规则
- 任务冲突时，以 [首要任务] 为准
- [特定条件] 下可以跳过 [次要任务]
模块三：分析流程
定义 Agent 处理输入的步骤化流程。
## 分析流程
### 第一步：理解输入
- 识别用户意图的类型（[类型A] / [类型B] / [类型C]）
- 提取关键参数：[参数列表]
- 判断是否需要额外信息
### 第二步：执行分析
- 对 [分析对象] 按 [维度] 进行评估
- 使用 [具体方法/框架] 进行判断
- 记录发现的问题和建议
### 第三步：生成输出
- 按 [输出格式] 组织结果
- 标注置信度和优先级
- 提供可执行的下一步建议
模块四：质量标准
定义输出的质量门槛和评判标准。
## 质量标准
### 必须满足
- [ ] [硬性标准 1]
- [ ] [硬性标准 2]
- [ ] [硬性标准 3]
### 应该满足
- [ ] [推荐标准 1]
- [ ] [推荐标准 2]
### 质量红线
- 绝不 [严重错误行为]
- 绝不 [另一个严重错误行为]
模块五：输出格式
严格定义输出的结构、格式和风格。
## 输出格式
### 结构
1. **摘要**（1-2 句话概括）
2. **详细分析**（按维度分段）
3. **建议操作**（可执行的步骤列表）
4. **风险提示**（如有）
### 格式规范
- 使用 Markdown 格式
- 代码块标注语言类型
- 表格用于对比数据
- 列表用于步骤和枚举
模块六：边缘情况处理
预定义异常场景的处理策略。
## 边缘情况
| 场景 | 处理方式 |
|------|----------|
| 输入信息不完整 | 列出缺失项，请求补充 |
| 输入超出能力范围 | 说明局限，建议替代方案 |
| 存在多种合理方案 | 列出各方案的优劣对比 |
| 用户要求违反最佳实践 | 说明风险，但尊重用户决策 |
关键提示工程技巧
Few-Shot 示例
在提示中嵌入输入-输出示例对，让模型学习期望的格式和风格：
## 示例
### 输入
用户请求："检查这个 API 端点的安全性"
### 期望输出
**安全评估报告**
| 检查项 | 状态 | 说明 |
|--------|------|------|
| 认证 | ✅ 通过 | 使用 JWT Bearer Token |
| 授权 | ⚠️ 警告 | 缺少角色级别的权限校验 |
| 输入验证 | ❌ 未通过 | 未对 query 参数做 sanitize |
**建议操作：**
1. 添加 RBAC 中间件（优先级：高）
2. 对所有用户输入添加 Zod schema 校验（优先级：高）
要点：
- 提供 2-3 个覆盖不同复杂度的示例
- 示例应展示期望的推理过程，而非仅展示结果
- 包含边缘情况的示例
Chain-of-Thought（思维链）
引导 Agent 在输出答案前先进行结构化推理：
## 推理流程
在给出最终回答之前，先完成以下分析（以 <analysis> 标签包裹）：
<analysis>
1. 问题类型判断：这是 [类型] 问题
2. 关键约束识别：[列出约束]
3. 可选方案枚举：[方案A], [方案B], [方案C]
4. 方案评估：基于 [标准] 进行比较
5. 结论：选择 [方案X] 因为 [理由]
</analysis>
要点：
- 思维链让推理过程可审计、可调试
- 适用于需要多步推理的复杂任务
- 可以通过标签将推理过程与最终输出分离
渐进式披露
不要一次性在提示中堆砌所有信息，而是按需加载：
## 执行策略
### 基本模式（默认）
- 执行标准分析流程
- 输出简洁报告
### 深入模式（当用户要求详细分析时）
- 扩展每个维度的分析深度
- 增加对比数据和历史趋势
- 提供完整的技术细节
### 专家模式（当用户指定时）
- 包含实现层面的代码建议
- 提供性能基准数据
- 讨论架构层面的 trade-off
Agent 说服力原则
优秀的 Agent 不仅需要技术正确，还需要让用户信服并采纳建议。以下原则来自说服心理学，可提升 Agent 的实际影响力：
1. 权威性（Authority）
通过展示专业知识建立可信度：
# 不好的写法
"你可以试试用索引优化查询"
# 好的写法
"根据 PostgreSQL 查询优化的 B-tree 索引原理，在 WHERE 子句的
高基数列上创建复合索引可以将查询时间从 O(n) 降至 O(log n)"
2. 承诺一致性（Commitment）
引导用户做出小的承诺，逐步推进：
## 推进策略
1. 先确认问题现状（"你观察到的症状是 X，对吗？"）
2. 再确认目标（"我们的目标是将响应时间降到 Y 以下"）
3. 最后提出方案（"基于以上共识，建议采取 Z 方案"）
3. 稀缺性（Scarcity）
突出不采取行动的代价：
# 在报告中标注风险
⚠️ 此安全漏洞在公开 CVE 数据库中已被标记，
如果不在下次部署前修复，生产环境存在被利用的风险。
4. 社会证明（Social Proof）
引用行业标准和最佳实践：
"此模式遵循 OWASP Top 10 的第 A01 项建议，
是 85% 的 Fortune 500 企业的标准实践。"
验证清单
创建完 Agent 后，逐项检查：
结构验证
- YAML frontmatter 格式正确，无语法错误
-
name字段使用 kebab-case，无空格 -
description字段以Use when开头，包含明确触发条件 - 指定了合理的
tools集合（最小权限原则）
内容验证
- 角色声明清晰，行为边界明确
- 核心职责有优先级排序
- 分析流程是步骤化的，可复现
- 质量标准可量化或可判定
- 输出格式有明确的结构定义
- 边缘情况有预定义的处理策略
提示工程验证
- 包含至少 1 个 Few-Shot 示例
- 复杂推理任务使用了 Chain-of-Thought
- 没有在提示开头堆砌大量背景信息
- 关键指令放在提示的开头或结尾（注意力 U 形曲线）
触发验证
- 在 5 种以上不同表述下能正确触发
- 不会被无关请求误触发
- 与其他 Agent 的触发条件无冲突
反模式
1. 万能 Agent
# 反模式：试图覆盖所有场景
description: "Use for any coding task"
问题： 触发条件过宽，导致在所有场景下都被激活，但没有任何场景处理得足够深入。
修正： 按场景拆分为多个专精 Agent。
2. 指令风暴
# 反模式：在提示中堆砌数十条规则
你必须遵守以下 47 条规则：
1. ...
2. ...
...
47. ...
问题： 超出模型的注意力预算，中间的规则会被忽略（Lost-in-Middle 效应）。
修正： 精简到 5-7 条核心规则，其余通过示例隐式传达。
3. 模糊质量标准
# 反模式
质量标准：代码要写得好，输出要清晰
问题： "好"和"清晰"没有可操作的定义，模型的理解可能与你的期望不同。
修正： 使用可判定的标准，如"函数不超过 30 行"、"每个公共方法有 JSDoc 注释"。
4. 忽略失败路径
# 反模式：只描述成功场景
## 流程
1. 分析代码
2. 输出报告
问题： 没有说明分析失败、输入无效、超出能力范围时怎么办。
修正： 为每个步骤定义失败时的回退策略。
5. 过度约束工具
# 反模式：不给 Agent 必要的工具
tools: ["Read"] # Agent 需要修改文件但没有 Write 和 Edit
问题： Agent 无法完成核心任务，或被迫用低效方式绕过限制。
修正： 工具集应覆盖 Agent 核心任务所需的全部工具，同时排除不需要的高风险工具。
总结
设计 Agent 系统提示的核心原则：
- 明确优于隐含 — 每个行为期望都要写出来
- 结构优于散文 — 用模板、表格、列表替代长段落
- 示例优于描述 — 一个好的 Few-Shot 示例胜过十段规则说明
- 最小权限 — 只给 Agent 完成任务所需的工具和信息
- 可验证 — 每条质量标准都应该能被客观判定
- 防御性设计 — 预定义所有可预见的失败路径