第 7 课：Agents（下）— 系统提示词设计

所属阶段：第二阶段「组件精讲」（第 4-14 课）前置条件：第 6 课本课收获：掌握提示词四段式结构，能创建一个自定义 Agent

一、本课概述

上节课我们学习了 Agent 的分类和调度机制。本课深入 Agent 的内核 --- 系统提示词设计。一个 Agent 的质量，90% 取决于它的提示词写得好不好。

本课回答三个问题：

好的 Agent 提示词有什么结构？ --- 四段式标准结构
设计提示词有哪些技巧？ --- 约束比指令更重要
经典 Agent 是怎么设计的？ --- code-reviewer、planner、tdd-guide 深度拆解

二、系统提示词四段式结构

ECC 中所有高质量 Agent 都遵循一个隐含的四段式结构。这不是强制格式，而是从实践中总结出的最佳模式。

2.1 四段式结构

arduino 复制代码

┌─────────────────────────────────────────────────┐
│  第一段：职责声明（你是什么角色）                   │
│  "You are a senior code reviewer..."             │
│                                                  │
│  第二段：工作流程（分步骤操作）                     │
│  "## Review Process"                             │
│  "1. Gather context  2. Understand scope  ..."   │
│                                                  │
│  第三段：输出格式（结构化可预测）                   │
│  "## Review Output Format"                       │
│  "[CRITICAL] ... File: ... Issue: ... Fix: ..."  │
│                                                  │
│  第四段：约束条件（不能做什么）                     │
│  "Only report issues >80% confident"             │
│  "Skip stylistic preferences..."                 │
└─────────────────────────────────────────────────┘

2.2 每段的作用

段落	作用	缺失的后果
职责声明	锚定角色，限定能力边界	AI 角色漂移，什么都想做
工作流程	确保执行顺序一致	每次执行结果不可预测
输出格式	让下游消费者（人或 Agent）能解析	输出散乱，无法自动化处理
约束条件	防止过度行为、减少噪音	输出冗余，误报率高

2.3 为什么是这四段

这四段对应了软件工程中的一个经典模式 --- 契约式设计（Design by Contract）：

职责声明 = 接口定义（这个模块做什么）
工作流程 = 算法实现（怎么做）
输出格式 = 返回值类型（输出什么）
约束条件 = 前置/后置条件（边界在哪里）

三、设计技巧

3.1 约束比指令更重要

这是 Agent 设计中最反直觉的原则。很多人花大量篇幅写"要做什么"，却忽略了"不能做什么"。

原因：大语言模型天然倾向于"多做"。如果你不明确限制，它会：

审查代码时顺便修改代码
规划时顺便写实现
报告问题时把低置信度的猜测也报上来

code-reviewer.md 中的经典约束：

markdown 复制代码

## Confidence-Based Filtering

**IMPORTANT**: Do not flood the review with noise. Apply these filters:

- **Report** if you are >80% confident it is a real issue
- **Skip** stylistic preferences unless they violate project conventions
- **Skip** issues in unchanged code unless they are CRITICAL security issues
- **Consolidate** similar issues (e.g., "5 functions missing error handling"
  not 5 separate findings)

注意：这段约束的价值远超任何"请仔细审查代码"的正面指令。它把一个可能产出 50 条噪音的审查，收敛为 5-10 条高价值发现。

3.2 输出格式要具体

不要说"输出审查结果"，要精确定义格式：

markdown 复制代码

## Review Output Format

[CRITICAL] Hardcoded API key in source
File: src/api/client.ts:42
Issue: API key "sk-abc..." exposed in source code.
Fix: Move to environment variable and add to .gitignore/.env.example

按严重度分级是 ECC 的标准做法：

严重度	含义	处理方式
CRITICAL	安全漏洞、数据丢失风险	必须修复才能合并
HIGH	代码质量严重问题	应该修复，可酌情合并
MEDIUM	性能问题、潜在风险	建议修复
LOW	风格建议、小改进	可选修复

3.3 工作流要可执行

好的工作流每一步都是具体的、可验证的动作，而不是模糊的指导：

markdown 复制代码

# 差的工作流
1. 理解代码
2. 找到问题
3. 报告结果

# 好的工作流（planner.md 的做法）
1. Requirements Analysis --- 列出成功标准和约束条件
2. Architecture Review --- 用 Grep/Glob 分析现有代码结构
3. Step Breakdown --- 为每步指定文件路径、依赖关系、风险等级
4. Implementation Order --- 按依赖排序，启用增量测试

四、经典案例深度分析

4.1 code-reviewer.md --- 只读不写的审查专家

文件位置 ：agents/code-reviewer.md

frontmatter 分析：

yaml 复制代码

name: code-reviewer
description: Expert code review specialist. Proactively reviews code for
  quality, security, and maintainability. Use immediately after writing
  or modifying code. MUST BE USED for all code changes.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet

关键设计决策：

设计点	选择	原因
tools	只有 Read/Grep/Glob/Bash	没有 Write/Edit --- 审查者不能修改代码
model	sonnet	审查需要较强理解力但不需要最深推理
description	含 "MUST BE USED"	强制触发，确保所有代码变更都经过审查

四段式结构映射：

职责声明 （第 8 行）：You are a senior code reviewer ensuring high standards of code quality and security.
工作流程（Review Process）：5 步 --- 收集上下文 → 理解范围 → 阅读周边代码 → 应用检查清单 → 报告发现
输出格式（Review Output Format）：按严重度分级的结构化输出 + Summary 表格 + Verdict
约束条件（Confidence-Based Filtering）：>80% 置信度才报告、合并同类、跳过风格偏好

审查清单的分级设计：

scss 复制代码

Security (CRITICAL)    --- 硬编码密钥、SQL注入、XSS、路径遍历
Code Quality (HIGH)    --- 大函数、深嵌套、缺少错误处理、mutation
Performance (MEDIUM)   --- O(n^2) 算法、缺少缓存、同步 I/O
Best Practices (LOW)   --- TODO 没关联 issue、命名不佳、魔法数字

4.2 planner.md --- 只读搜索再规划

文件位置 ：agents/planner.md

frontmatter 分析：

yaml 复制代码

name: planner
description: Expert planning specialist for complex features and refactoring.
  Use PROACTIVELY when users request feature implementation, architectural
  changes, or complex refactoring.
tools: ["Read", "Grep", "Glob"]
model: opus

与 code-reviewer 的关键差异：

对比项	code-reviewer	planner
tools	Read, Grep, Glob, Bash	Read, Grep, Glob（无 Bash）
model	sonnet	opus
能否执行命令	能（git diff 等）	不能
能否写文件	不能	不能

为什么 planner 不需要 Bash？

规划阶段只需要阅读和搜索代码来理解架构，不需要执行命令。去掉 Bash 权限是一种安全约束 --- 防止规划者在规划阶段就开始执行操作。

为什么 planner 用 opus 模型？

规划需要最深度的推理能力 --- 要理解复杂的架构关系、预判风险、设计分阶段实施方案。这是 opus 模型的典型使用场景。

planner 的输出格式非常具体：

markdown 复制代码

# Implementation Plan: [Feature Name]
## Overview            --- 2-3 句话概述
## Requirements        --- 需求列表
## Architecture Changes --- 受影响的文件和变更描述
## Implementation Steps --- 分阶段，每步有文件路径、依赖、风险等级
## Testing Strategy    --- 单元/集成/E2E 测试计划
## Risks & Mitigations --- 风险和缓解措施
## Success Criteria    --- 成功标准清单

4.3 tdd-guide.md --- 完整读写权限

文件位置 ：agents/tdd-guide.md

frontmatter 分析：

yaml 复制代码

name: tdd-guide
description: Test-Driven Development specialist enforcing write-tests-first
  methodology. Use PROACTIVELY when writing new features, fixing bugs,
  or refactoring code. Ensures 80%+ test coverage.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet

与前两个 Agent 的本质区别：

tdd-guide 拥有 Write 和 Edit 权限 --- 因为 TDD 流程需要实际编写测试和代码。

三个 Agent 的权限对比：

权限	code-reviewer	planner	tdd-guide
Read	O	O	O
Grep	O	O	O
Glob	O	O	-
Bash	O	-	O
Write	-	-	O
Edit	-	-	O

设计哲学 ：权限 = 职责边界。tools 列表不是"给得越多越好"，而是"刚好够用"：

审查者只能看，不能改（防止审查者自己改代码然后自己审查通过）
规划者只能读和搜索，不能执行（防止规划阶段就开始动手）
TDD 引导者需要写测试和代码，所以需要完整权限

五、tools 列表设计原则

5.1 最小权限原则

arduino 复制代码

权限范围从小到大：
Read/Grep/Glob → + Bash → + Write/Edit → + Task（嵌套 Agent）
     ↑               ↑           ↑              ↑
  只读分析        可执行命令    可修改文件    可委派子任务

5.2 选择依据

场景	推荐 tools	示例 Agent
纯分析/审查	Read, Grep, Glob	security-reviewer
需要运行命令看结果	+ Bash	code-reviewer
需要修改文件	+ Write, Edit	tdd-guide
需要委派子任务	+ Task	architect（可能调用 planner）

5.3 model 选择

模型	成本	适用场景	示例
haiku	低	轻量级、高频任务	格式检查、简单分类
sonnet	中	主力编码和审查	code-reviewer、tdd-guide
opus	高	深度推理、复杂决策	planner、architect

六、本课练习

练习 1：识别四段式结构（10 分钟）

打开 agents/code-reviewer.md，逐段标注四段式结构：

bash 复制代码

cat agents/code-reviewer.md

回答问题：

职责声明在第几行？
工作流程有几个步骤？
输出格式中包含哪些字段？
约束条件中 80% 这个数字指什么？

练习 2：对比 tools 列表（10 分钟）

打开 agents/planner.md 和 agents/code-reviewer.md，对比它们的 frontmatter。

回答问题：

planner 为什么没有 Bash？
code-reviewer 为什么没有 Write/Edit？
如果给 code-reviewer 加上 Write 权限，会发生什么？

练习 3：创建"依赖审查 Agent"（30 分钟）

这是本课最重要的练习。

创建一个 dependency-auditor.md Agent，用于检查项目依赖的安全性和时效性。要求：

四段式结构完整
职责声明：你是一个依赖安全审查专家
工作流程 ：
- 读取 package.json / requirements.txt / go.mod 等依赖文件
- 检查已知安全漏洞（通过 npm audit / pip-audit 等）
- 检查过期依赖（距离最新版本的差距）
- 评估依赖健康度（维护活跃度、下载量、开源协议）
输出格式：按 CRITICAL/HIGH/MEDIUM/LOW 分级
约束条件 ：
- 不修改任何文件
- 只在确认漏洞有 CVE 编号时标记 CRITICAL
- 不建议替换核心依赖（风险太大）

参考模板：

markdown 复制代码

---
name: dependency-auditor
description: [你来写]
tools: [你来选]
model: [你来选]
---

[四段式内容]

练习 4（选做）：思考题

如果要设计一个"数据库迁移 Agent"（负责生成和验证数据库迁移脚本），它应该有哪些 tools？用 sonnet 还是 opus？为什么？

七、本课小结

你应该记住的	内容
四段式结构	职责声明 → 工作流程 → 输出格式 → 约束条件
核心技巧	约束比指令更重要；输出格式要具体；工作流每步可执行
tools = 职责边界	只读分析给 Read/Grep；需要执行加 Bash；需要修改加 Write/Edit
model 选择	haiku 轻量、sonnet 主力、opus 深度推理
置信度过滤	>80% 置信度才报告，减少噪音

八、下节预告

第 8 课：Skills（上）--- 结构与本质

下节课我们将进入 Skill 组件。你将理解 Skill 与传统文档的本质差异 --- Skill 不是写给人看的，是写给 AI 执行的。你将掌握 Skill 的标准四段式结构，理解 description 字段为什么是整个 Skill 中最关键的一行。

预习建议 ：打开 skills/coding-standards/SKILL.md 和 skills/tdd-workflow/SKILL.md，感受一下 Skill 的格式和内容风格。