所属阶段：第二阶段「组件精讲」（第 4-14 课） 前置条件：第 6 课 本课收获：掌握提示词四段式结构，能创建一个自定义 Agent
一、本课概述
上节课我们学习了 Agent 的分类和调度机制。本课深入 Agent 的内核 — 系统提示词设计。一个 Agent 的质量，90% 取决于它的提示词写得好不好。
本课回答三个问题：
- 好的 Agent 提示词有什么结构？ — 四段式标准结构
- 设计提示词有哪些技巧？ — 约束比指令更重要
- 经典 Agent 是怎么设计的？ — code-reviewer、planner、tdd-guide 深度拆解
二、系统提示词四段式结构
ECC 中所有高质量 Agent 都遵循一个隐含的四段式结构。这不是强制格式，而是从实践中总结出的最佳模式。
2.1 四段式结构
┌─────────────────────────────────────────────────┐
│ 第一段：职责声明（你是什么角色） │
│ "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 中的经典约束：
## 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 输出格式要具体
不要说"输出审查结果"，要精确定义格式：
## 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 工作流要可执行
好的工作流每一步都是具体的、可验证的动作，而不是模糊的指导：
# 差的工作流
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 分析：
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% 置信度才报告、合并同类、跳过风格偏好
审查清单的分级设计：
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 分析：
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 的输出格式非常具体：
# 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 分析：
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 最小权限原则
权限范围从小到大：
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，逐段标注四段式结构：
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
- 不建议替换核心依赖（风险太大）
参考模板：
---
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 的格式和内容风格。
