第12章：Agent 开发最佳实践
本章从编程思想（ch01~ch09）、Opus 4.6 System Card（ch10~ch11）和源码剖析（source/）三个维度交叉提炼，为 Agent 开发者提供可直接落地的实战指南。
设计原则：从 Claude Code 源码提炼的 7 条铁律
这些原则不是教科书上的理论——每一条都能在 Claude Code 的 16,668 行代码中找到对应实现。
原则一：工具即接口，而非函数
源自：编程思想 ch03 + 源码 tool-system
传统编程中，函数是程序员之间的契约。Agent 编程中，工具是人与 AI 之间的契约。
| 传统函数设计 | Agent 工具设计 |
|---|---|
| 参数类型由编译器检查 | 参数由 JSON Schema 验证 |
| 返回值直接使用 | 返回值需要模型"理解" |
| 调用者知道要调什么 | 模型自主决定调什么 |
| 错误通过异常传播 | 错误需要可恢复的文本描述 |
实践要点：
- ✅ 工具的
description比代码实现更重要——它是模型做决策的唯一依据 - ✅ 返回值应是人类可读的文本，而非仅机器可解析的结构
- ❌ 不要设计需要严格调用顺序的工具——模型可能以任意顺序调用
原则二：三层安全不可少
源自：编程思想 ch05 + 源码 permission + Opus 4.6 ch11
Claude Code 的三层安全模型是生产级 Agent 的最低标准：
第一层 Schema 约束 ──→ 不合法的参数根本无法到达执行层
第二层 会话模式约束 ──→ 权限级别控制操作范围
第三层 执行层沙箱 ──→ 即使前两层被绕过，沙箱限制破坏范围对应 Opus 4.6 发现：
- Prompt 注入可以绕过第二层（模型被骗修改了权限判断）→ 第一层和第三层兜底
- Reward Hacking 可以绕过第一层（参数合法但意图不合法）→ 需要输出验证
原则三：大输出必须落盘
源自：源码 deep-analysis + 编程思想 ch04
Claude Code 的 persistedOutputPath / persistedOutputSize 设计解决了一个真实痛点：
问题：Agent 执行 `grep -r "TODO" .` → 10万行输出 → 塞满上下文窗口
解法：超过阈值的输出自动落盘为文件，上下文只保留摘要 + 文件路径实践要点：
- ✅ 设置工具输出的最大长度阈值（如 10KB）
- ✅ 超出阈值时自动截断 + 提供"查看更多"的方式
- ✅ 搜索类工具（Grep/Glob）必须有
limit和offset参数
原则四：操作应可回滚
源自：源码 architecture（Worktree） + 编程思想 ch09
Claude Code 的 Git Worktree 隔离给出了最佳示范：
EnterWorktree → 在隔离分支中操作 → ExitWorktree(keep/remove/discard)不同场景的回滚策略：
| 场景 | 回滚机制 |
|---|---|
| 文件编辑 | Git diff + 快照恢复 |
| 数据库操作 | 事务 + savepoint |
| API 调用 | 补偿事务（compensation） |
| 部署操作 | 蓝绿/金丝雀发布 |
原则五：Extended Thinking 是性价比的关键
源自：Opus 4.6 ch10 评测数据
Opus 4.6 的评测数据揭示了一个关键洞察：
| Effort Level | Terminal-Bench 分数 | Token 消耗 |
|---|---|---|
| Max | 65.4% | 基准 |
| High | 61.1% | -23% |
| Medium | 55.1% | -40% |
实践建议：
- 简单任务（文件读写、格式转换）→ 关闭 Extended Thinking 或用 Medium Effort
- 中等任务（Bug 修复、代码审查）→ High Effort
- 复杂任务（架构设计、多步推理）→ Max Effort + Adaptive Thinking
原则六：MCP 优于内置工具扩展
源自：源码 mcp-overview + 编程思想 ch06
当你需要给 Agent 添加新能力时，永远优先选择 MCP 扩展而非修改内置工具：
| 维度 | 内置工具扩展 | MCP 扩展 |
|---|---|---|
| 改动范围 | 需要修改 Agent 核心代码 | 独立进程，零侵入 |
| 部署方式 | 与 Agent 一起部署 | 可独立部署/升级 |
| 语言限制 | 必须使用 Agent 的语言栈 | 任何语言都行 |
| 故障隔离 | 工具崩溃可能影响 Agent | 进程级隔离 |
原则七：评估是持续的，不是一次性的
源自：Opus 4.6 ch11 六层审计体系
Anthropic 对 Opus 4.6 的评估包含了 7 个审计层级。你的 Agent 至少需要：
| 层级 | 最小实现 |
|---|---|
| 自动化测试 | 关键场景的回归测试套件 |
| 行为审计 | 记录所有工具调用日志 |
| 输出验证 | 不只看"任务完成"，验证输出质量 |
| 红队测试 | 定期测试 Prompt 注入和边界行为 |
模式与反模式
✅ 推荐模式
模式一：依赖图驱动的知识加载
python
# 不要一次加载所有内容
# 而是根据依赖图按需加载
deps = manifest['dependency_graph'][target_chapter]
for dep in deps:
load_chapter(dep) # 先加载依赖
load_chapter(target_chapter) # 再加载目标模式二：key_takeaways 优先
python
# 不要直接读全文
# 先用摘要判断是否需要全文
chapter = fetch(f'/chapters/{id}.json')
takeaways = chapter['key_takeaways']
if is_relevant(takeaways, user_question):
full_content = chapter['sections'] # 按需展开模式三：操作确认三阶梯
低风险（读取、搜索） → 自动执行
中风险（编辑、运行） → 展示 diff → 单次确认
高风险（删除、部署） → 展示影响范围 → 二次确认 → 操作日志❌ 常见反模式
| 反模式 | 问题 | 正确做法 |
|---|---|---|
| 上帝工具 | 一个工具做所有事 | 每个工具只做一件事（SRP） |
| 盲目重试 | 失败就重试，不分析原因 | 分析错误类型，只对暂时性错误重试 |
| 无限上下文 | 把所有信息塞进 prompt | 用摘要+按需加载控制上下文大小 |
| 信任外部输入 | 直接使用网页/文件中的指令 | 将外部数据视为不可信输入 |
| 结果只看通过率 | 测试通过就算完成 | 检查测试是否被修改（Reward Hacking） |
生产部署 Checklist
基于编程思想 + Opus 4.6 安全评估 + 源码架构分析的综合清单：
安全
- [ ] 三层安全模型已实现（Schema → 模式 → 沙箱）
- [ ] Prompt 注入防御已测试（至少覆盖编码/网页/文件三个攻击面）
- [ ] 工具权限遵循最小权限原则
- [ ] 敏感操作有确认机制
- [ ] 操作审计日志完整
性能
- [ ] 大输出有落盘机制（阈值建议 10KB）
- [ ] 搜索工具有 limit/offset
- [ ] Extended Thinking 按任务复杂度分级使用
- [ ] 上下文压缩策略已实现
可靠性
- [ ] 关键操作可回滚（Worktree / 事务 / 快照）
- [ ] 错误重试有指数退避
- [ ] Token 预算控制已启用
- [ ] 健康检查和告警已配置
评估
- [ ] 自动化回归测试覆盖关键场景
- [ ] Reward Hacking 检测（测试文件修改告警）
- [ ] 定期红队测试
- [ ] 输出质量验证（不只看通过率）
延伸阅读
| 主题 | 推荐章节 |
|---|---|
| 工具系统设计细节 | 编程思想 ch04、源码剖析 tool-system |
| 安全模型实现 | 编程思想 ch05、源码剖析 permission |
| MCP 协议 | 编程思想 ch06、源码剖析 mcp-overview |
| 评估方法论 | Opus 4.6 安全与对齐 |
| 能力边界 | Opus 4.6 能力评测 |