第十三章：可行动洞察：从中能学到什么

导读｜读完这章能做什么

  • 29 条建议按 7 类索引，对照自己的项目逐条检查
  • 重点看 Prompt 工程和安全的 9 条
  • 5 个核心要点作为设计原则

本章从 Claude Code 源码中提炼出具有实际参考价值的工程实践。

一、Prompt 工程 (5 条)

1. "先读后改"原则

Claude Code 的 prompt 反复强调: 修改代码前必须先读取。

自己的 Agent 也应该： 在任何修改操作前，强制模型先获取当前状态。

2. 反过度工程 Prompt

LLM 倾向于过度工程化 (加注释、提取函数、增加错误处理)。

Agent 需要： 明确告诉模型"只做被要求的事"。

3. 不暴力重试

LLM Agent 常见反模式: 遇到错误就无脑重试相同操作。

Agent 需要： prompt 中明确禁止，要求分析原因后尝试不同方法。

4. 权限不扩散

一次授权不等于永久授权。

Agent 需要： 每次敏感操作单独确认。

5. 动态 Prompt 组装

不要用一个巨大的静态 prompt。

Agent 应该： 分段缓存 + 动态拼装 + 按需注入上下文。

二、架构设计 (5 条)

6. 工具结果大小管理

这是 Agent 系统中常见的问题: 工具返回太多数据撑爆上下文。

解决方案: 设定 maxResultSize，超出存磁盘，只给模型摘要，内容哈希去重。

7. 上下文压缩策略

长对话必然超出 Token 限制。

三层方案:

  1. 手动压缩 (/compact)
  2. 自动压缩 (超阈值触发)
  3. 增量压缩 (只压缩新增部分)

8. 多层权限系统

Agent 安全不能只靠一层检查。

推荐架构: Deny → Allow → Hook → 分类器 → 用户确认

9. Feature Flags + 死代码消除

大型 Agent 项目需要管理大量实验性功能。

建议: 编译期 feature flags，未启用的功能不进入产物。

10. Context Object 模式

工具执行需要传递大量上下文。

建议: 单一上下文对象，方便子 Agent 上下文克隆。

三、多 Agent 协作 (4 条)

11. Fork Agent 的 Cache 共享

如果 Agent 需要生成子 Agent：保持子 Agent 的 system prompt 与父相同，利用 API 侧 prompt cache 节省成本。

12. Worker 工具集限制

后台 Agent 不应该有完整权限。

建议: 定义受限的工具子集，防止失控。

13. Scratchpad 模式

多 Agent 间数据交换: 通过共享目录 (Scratchpad) 而不是消息传递。更高效，支持大数据量。

14. 任务自动转后台

长时间运行的任务不应阻塞用户交互。

建议: 超时后自动转后台 + 完成通知。

四、用户体验 (4 条)

15. 权限疲劳检测

频繁弹权限确认会让用户烦躁。

建议: 检测连续拒绝模式，升级为批量权限请求。

16. 流式输出 + 进度反馈

工具执行超过 2 秒就应显示进度。

建议: 流式回调 + 进度指示器。

17. 命令语义折叠

安全的搜索/读取命令可以在 UI 中折叠。

建议: 基于命令语义分类决定 UI 展示粒度。

18. 多语言自适应

检测用户语言，用相同语言回复。

建议: system prompt 中包含语言偏好段。

五、性能优化 (4 条)

19. 并行预取

CLI 启动时将可并行的 I/O 提前到 import 解析之前。

建议: 不要等模块加载完才发起网络请求。

20. 懒加载重型模块

OpenTelemetry、React 组件、分析模块等按需加载。

建议: 只在首次使用时加载重型依赖。

21. Memoized Prompt Sections

System prompt 段按需计算，缓存到显式清除。

建议: 将 prompt 分为静态和动态部分，分别缓存。

22. Git 状态快照

会话内不更新 Git 状态，避免缓存失效。

权衡: 实时性 vs 性能，Claude Code 选择了性能。

六、记忆系统 (3 条)

23. 分层记忆架构

MEMORY.md (索引, 200行限制)
  └── 子文件 (详细内容, 按主题组织)
      └── Agent 记忆 (user/project/local 三级)

24. 记忆漂移保护

记忆可能过期，prompt 要求模型使用前先验证。

建议: 在 prompt 中明确要求 "verify before acting on memories"。

25. 自动记忆提取

不依赖用户主动说"记住这个"，自动从对话中提取。

建议: 会话结束时运行记忆提取流程。

七、安全 (4 条)

26. Bash AST 级分析

不是正则匹配命令字符串，而是解析 Bash AST。

优势: 不会被简单的字符串混淆绕过，理解管道、重定向、子 shell。

27. 分类器 + 人工双重审核

ML 分类器作为第一道过滤: 高置信度 → 自动决策，低置信度 → 上报用户。

28. 沙盒执行

Bash 命令在沙盒中执行，限制文件系统和网络访问。

建议: 任何执行外部代码的 Agent 都应考虑沙盒。

29. 设备文件阻止

阻止读取 /dev/zero 等设备文件。

要点: 安全防护需要考虑边缘情况。

总结: 5 个核心要点

1. Prompt 是产品。 Claude Code 的 prompt 不是随手写的，而是经过大量迭代的产品工件。投入与代码同等的精力在 prompt 上。

2. 安全是多层的。 单点安全检查不够。需要 Deny → Allow → Hook → Classifier → User 的决策链。

3. 上下文是有限的。 工具结果管理、压缩策略、磁盘持久化——围绕"上下文窗口有限"这个核心约束的一整套工程。

4. 子 Agent 需要隔离。 权限隔离、工具集限制、上下文隔离——子 Agent 不应继承父的全部能力。

5. 性能源于架构。 并行预取、懒加载、缓存分段、prompt cache 共享——性能不是事后优化，而是架构内建。

results matching ""

    No results matching ""