15.3 Claude Code 的可验证工程实践
⚠️ 诚实声明：商业产品的内部实现对用户是黑盒，且会随版本频繁变化。本章不依赖任何"源码泄露""内部漏洞细节"或"未公开功能"作为事实来源——这些说法无法被读者独立核验，也不应成为学习依据。下面只讲两类内容：(1) 官方文档明确公开、且可在自己机器上复现的行为；(2) 值得借鉴的、与本书其他章节一致的工程原则。
一、Prompt Caching 与上下文边界
Claude Code 这类长会话 CLI 的核心成本问题，是同一份很长的 System Prompt / 项目上下文，会在每次请求里重复发送。Anthropic 提供的官方能力是 Prompt Caching：给消息的某一段打上 cache_control: {"type": "ephemeral"}，前缀不变时直接复用缓存，命中后该段计费大幅下降、延迟也更低。
由此产生一个可验证的设计原则：把"不变的内容"和"每次都变的内容"分开。
- 静态区：身份说明、工具使用规范、行为契约等固定规则 → 适合打缓存标记。
- 动态区：当前文件列表、Git 状态、本次用户输入等 → 每次变化，不应污染静态缓存。
你可以用自己写的 Agent 复现这个思路：把稳定的"宪法/规则"放在 system prompt 前缀并启用缓存，把易变的上下文放在 user / tool 消息里。这和第 7 章"上下文工程"、第 8 章 Harness Engineering 的 AGENTS.md 思路一致。
📌 验证方式：在 Anthropic 官方文档搜索 "Prompt Caching"，用你自己的 API Key 跑两次相同前缀的请求，对比返回中的
cache_creation/cache_readtoken 计费。
二、权限模式：把"能不能做"显式说出来
AI Coding CLI 的价值不只是"会写代码"，更是在自动化执行和人工确认之间给出清晰的权限边界。以下模式是官方文档公开描述的（不同版本名称可能微调，以你本地 claude --help 或官方文档为准）：
| 模式 | 行为 | 适用场景 | 风险 |
|---|---|---|---|
default | 危险操作弹窗确认 | 日常交互使用 | 低 |
plan | 只产出计划，不执行改动 | 先评审再动手 | 低 |
acceptEdits | 自动接受文件编辑 | 信任度高的迭代 | 中 |
dontAsk / headless | 尽量少打扰地自动执行 | CI、批处理 | 中高 |
bypassPermissions | 跳过所有权限检查 | 仅完全受控沙箱 | 极高 |
关键原则：
- 最小权限：本地开发用
default；自动化场景能用plan就别用dontAsk，能限定目录就别给整盘权限。 - 不可逆操作必须确认：
rm -rf、DROP TABLE、强制推送等，永远不该在无人确认下静默执行。 bypassPermissions是逃生舱，不是默认档：它关闭的是所有安全检查。任何挂着真实数据或凭证的环境都不应使用。
这一点和本书第 19 章"权限控制与沙箱隔离"完全对应：权限不是"体验选项"，而是 Agent 上线前必须设计的安全边界。
三、项目记忆的注入策略：CLAUDE.md
Claude Code 使用 CLAUDE.md（项目级）和 ~/CLAUDE.md（用户级）作为"项目宪法"。它的公开用法是：把项目约定、命令、禁忌写进 Markdown，CLI 在会话开始时读入上下文。
可验证的做法（你今天就能在自己的仓库里试）：
- 在项目根目录新建
CLAUDE.md，写清"构建命令是什么""测试怎么跑""不要改哪些文件"。 - 让 CLI 读取后执行一个具体任务，观察它是否遵守你写下的规则。
- 把"没遵守"的案例写成更精确的条款，迭代
CLAUDE.md。
这和第 8.3 节"AGENTS.md / CLAUDE.md 写作指南"是同一件事。注意：CLAUDE.md 是追加进对话上下文的，它会占用上下文窗口并影响缓存——所以应当精炼，而不是堆成文档库。
四、可借鉴的工程原则（与本书一致）
无论具体 CLI 怎么实现，下面几条是公开可观察、且被多家风控实践印证的：
- 先读再改：改动文件前先 Read，避免基于过时假设编辑。对应第 8 章 Harness 的"失败先诊断、不盲目重试"。
- 不过度生成：优先编辑已有文件，不无谓新建文件；三行相似代码好过过早抽象。对应第 8.2 节"六大工程支柱"。
- 不把未验证结果说成成功：工具返回了"看起来对"的输出，不等于任务真的完成。对应第 18 章评估与第 19 章事实性保障。
- 把约束写进系统：权限、确认、沙箱应当是机制的一部分，而不是依赖用户"记得小心"。
💡 核心洞察：Claude Code 真正值得学的，不是某个内部函数，而是它把"工程约束"编码进了 Agent 本身——这正是 Harness Engineering（第 8 章）在产品层面的体现。
小结
| 主题 | 可验证要点 |
|---|---|
| Prompt Caching | 静态/动态区分离，前缀缓存降本；可用自己 API Key 复现 |
| 权限模式 | default/plan/acceptEdits/dontAsk/bypassPermissions；最小权限原则 |
| CLAUDE.md | 项目级"宪法"，读入上下文；应精炼以免影响缓存 |
| 工程原则 | 先读再改、不过度生成、不谎报成功、约束机制化 |
想看真实可运行的最小 Agent（含工具调用、权限守卫、可测服务），见仓库根目录
reference-agent/，第 12–23 章的实战均以其为准。