03-Agent 文件结构与系统提示设计

Agent 文件结构与系统提示设计

学习目标

本章将掌握 Claude Code Agent 的定义规范，通过 feature-dev、pr-review-toolkit 和 agent-sdk-dev 中的 Agent 实例，掌握：

• Agent frontmatter 的标准字段和模型选择策略
• 系统提示的结构化设计模式
• 置信度打分系统的落地实现
• 只读分析 Agent 的工具权限设计

---

前置知识

• 多 Agent 编排与置信度过滤

---

项目实践

Agent Frontmatter

---
name: code-explorer
description: Deeply analyzes existing codebase features by tracing execution paths...
tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
model: sonnet
color: yellow
---

标准字段说明：

字段	必需	可选值	用途
name	是	kebab-case	Agent 唯一标识符
description	是	自由文本	触发描述，决定何时调用此 Agent
tools	是	工具名列表	允许使用的工具
model	否	opus, sonnet, inherit	使用的模型
color	否	yellow, green, red, cyan, magenta, pink	UI 颜色标识

模型选择策略

模型	适用场景	官方示例
opus	深度代码审查、代码简化	pr-review-toolkit 的 code-reviewer 和 code-simplifier
sonnet	代码探索、架构设计	feature-dev 的 code-explorer、code-architect
inherit	轻量分析任务	pr-review-toolkit 的 comment-analyzer、pr-test-analyzer

系统提示设计模式

所有官方 Agent 遵循统一的结构化系统提示：

## Role
[角色定义，1-2 句话]

## Core Mission
[核心使命，回答什么问题]

## Analysis Approach
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]

## Output Requirements
[输出格式和内容的要求]

## Key Directives
[关键指令，如 "Make confident choices" 或 "Only report issues with confidence >= 80"]

feature-dev 的 code-architect Agent 包含关键指令：

“Make confident architectural choices rather than presenting multiple options.”

这防止了 Agent 输出多个方案让用户选择的行为——它应该做一个决策并坚持。

置信度打分实现

code-reviewer Agent 的 0-100 置信度打分：

## Confidence Scoring

Rate each finding 0-100:
- 0: Not confident at all — false positive or pre-existing issue
- 25: Somewhat confident — might be real, might be stylistic
- 50: Moderately confident — real issue but might be a nitpick
- 75: Highly confident — double-checked, very likely real
- 100: Absolutely certain — definitely real, will happen frequently

Only report issues with confidence >= 80.

报告分组：

• Critical: 90-100
• Important: 80-89

只读分析 Agent 的工具权限

feature-dev 的所有分析 Agent 使用完全相同的只读工具集：

Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput

注意：没有 Write、Edit、Bash（写入模式）。这是有意的——分析 Agent 不应该修改代码。

Agent <example> 触发块

Agent 描述中可以包含 <example> 块，教导 Claude 何时主动调用该 Agent：

## Proactive Usage

Use this agent when:
<example>
User: "I just finished implementing the auth module, can you review it?"
Assistant: "I'll run the code-reviewer agent to check for bugs and quality issues."
</example>

这使 Claude 能够在没有显式 Agent 调用请求的情况下，自动触发合适的 Agent。

陷阱与对策

陷阱	表现	对策
Agent description 过于宽泛	被不必要地触发	在 description 中包含具体的能力描述和触发条件
Agent tools 包含多余写入工具	分析 Agent 意外修改代码	只包含 Read/Glob/Grep 等只读工具
model: inherit 在 Opus 上下文中	轻量 Agent 使用了过强的模型，浪费 Token	对于明确是轻量的任务，指定 sonnet
系统提示中缺少输出模板	不同 Agent 的输出格式不一致，难以聚合	在系统提示中明确输出格式

设计取舍

为什么 Agent 用 Markdown 而非 JSON 定义？

Agent 的核心是系统提示（自然语言指令），Markdown 是人类和模型都直接可读的格式。JSON 需要额外的转义，且不利于人类阅读和编辑。

为什么所有分析 Agent 使用相同的工具集？

统一的工具集简化了权限管理和测试。每个 Agent 都能完成分析所需的所有操作（读取文件、搜索代码、浏览目录），同时都没有写入能力——保持角色清晰。

参考来源

• Claude Code Subagent 文档
• 源码: plugins/feature-dev/agents/*.md
• 源码: plugins/pr-review-toolkit/agents/*.md
• 源码: plugins/agent-sdk-dev/agents/*.md