引言

在《Claude Code 高效使用指南》里，讲了 CLAUDE.md、Skills、Hooks、Subagents 这些上层扩展能力怎么配置和组合。

但你有没有想过一个问题：这些东西底下，Claude Code 到底是怎么跑起来的？

一个几百万行的 monorepo，Claude Code 怎么知道该读哪个文件？一个长会话跑了几百轮，为什么不会越来越慢、越来越贵？为什么 Claude Code、Codex 这些最火的 Agent 产品，不约而同都选了命令行？

这三个问题，指向同一个答案：Agent 的底层工程，才是真正拉开差距的地方。

这篇文章就把这三层机制拆开讲清楚。

很多人第一反应是：大代码库是不是要先建索引、做向量化、上 RAG？

Anthropic 给了一个很明确的答案：不是。

为什么索引方案在大代码库里容易失效

索引方案有一个致命的假设——代码是静态的。但大规模活跃代码库里，几千个工程师每天都在改代码：函数今天改名，模块明天迁移，旧服务后天删掉。如果索引管线跟不上，模型拿到的是旧世界的地图——它可能引用一个两周前已经改名的函数，也可能调一个上个 sprint 已经删掉的模块。

更麻烦的是，召回结果本身不会告诉你：“我过期了。”

Agentic Search：像工程师一样边搜边读

Claude Code 的思路更像一个真实工程师的工作方式：

  1. 先看报错关键词
  2. 用 grep 找相关接口
  3. 读调用链上的关键文件
  4. 找到核心逻辑
  5. 看测试怎么覆盖
  6. 修改最小范围
  7. 跑对应测试

它不是在某个中心索引里检索答案，而是在开发者机器上的实时代码库里工作。用 Anthropic 的话说，这叫 Agentic Search——不是"先把答案搜出来给模型"，而是让 Agent 自己根据当前任务，一步一步决定下一步该搜什么、读什么、验证什么。

大代码库的关键不是"看更多"，而是"找得准"

很多人觉得大代码库需要更大的上下文窗口。窗口大当然有用，但真正的问题不是"放不下全部代码"——因为无论窗口多大，你都不应该把整个仓库塞进去。

真正的问题是：Claude Code 能不能在读很少文件的情况下，找到真正相关的那几个文件？

所以大代码库要做的是上下文治理：

  • 该加载的规则提前加载
  • 不相关的目录不要读
  • 生成代码和构建产物要排除
  • 测试命令要按子目录收敛
  • 同名函数要靠 LSP 区分
  • 大范围探索交给 subagent

太多上下文会降低性能，太少上下文会让 Claude 盲搜。 这句话很适合放到团队规范里。

大代码库的配置顺序

落地顺序不是一步到位，而是逐步收敛：

  1. 先写根 CLAUDE.md——仓库结构、常用命令、全局禁区、最容易踩的坑
  2. 补子目录 CLAUDE.md——哪个目录最常被改就先补哪个，写本目录命令和规则
  3. 配置忽略和权限——生成代码、构建产物、三方依赖别让 Agent 去读
  4. 接 Hooks——format、lint、typecheck、单测，把"提醒模型"变成"触发就做"
  5. 重复流程抽成 Skills——安全审查、文档更新、发布检查，按需加载
  6. 再考虑 Plugins、MCP、LSP、Subagents——前面基础没做好，直接上复杂插件容易越配越乱

两个被低估的用法：Skills 渐进式披露、Hooks 自我改进

大代码库里有大量专家知识：安全审查怎么做、支付模块怎么部署、文档更新流程是什么。如果全塞进 CLAUDE.md，它一定会爆炸，而且很多任务根本用不到。Skills 的关键是按需加载——Anthropic 管这叫 progressive disclosure（渐进式披露），用大白话说就是：

别一上来把所有专家都请进会议室，谁用得上，再叫谁进来。

稳定通用规则放 CLAUDE.md，专门任务流程放 Skills，这条边界划清楚，Claude 每次启动才不会背一堆无关知识。

Hooks 也有一个被低估的用法：不只是拦截错误，还能让配置自我改进。 比如 stop hook 在会话结束时回看这次过程——Claude 今天是不是绕了远路？是不是某个目录规则不清楚？是不是某个测试命令该写进子目录 CLAUDE.md？如果是，就提出更新建议。这样项目规则不是一次性写完，而是随着团队使用不断迭代——这才是大团队落地 AI 编程真正需要的能力。

团队落地：为什么需要一个 Agent 管理人

技术配置只是第一步，大团队里真正难的是组织落地。如果每个工程师都自己写 CLAUDE.md、自己配 hooks、自己接 MCP，很快就会各玩各的：好经验留在个人电脑里，踩过的坑没人沉淀，新人进来还要重新摸索。

Anthropic 文章里提到了一个角色：agent manager（Agent 管理人）——负责维护 AI 编程工程体系的人。他不一定是专职，小团队里一个 DRI 就够，但要负责：

  • 统一 CLAUDE.md 层级规范
  • 管理 hooks 和权限策略
  • 维护团队可用的 Skills
  • 选择和分发 Plugins
  • 管理 MCP 接入边界
  • 推动代码审查和安全流程
  • 定期清理过期规则

大公司里，这个角色通常落在 DevEx、开发效率或基础架构团队下面，因为它本质上是开发者工具的一部分。Anthropic 说得挺现实：自下而上的使用会带来热情，但没有集中维护，知识会停留在小圈子里。 很多公司现在都是几个工程师先偷偷用，用得好的那个人效率很高，但团队并没有真正吃到红利——因为方法没有标准化，也没有沉淀成项目资产。

普通开发者怎么开始

如果你不是团队负责人，只是个普通开发者，也能做很多事，不用一上来就搭 MCP、写 plugin、搞平台：

  1. 给当前项目写一个根 CLAUDE.md——哪怕只有 20 行，写清楚项目结构、常用命令、禁止事项
  2. 把你反复提醒 Claude Code 的话沉淀进去——凡是你连续说过三次的规则，都该考虑写进文件
  3. 给常改目录补子目录 CLAUDE.md——经常改 docs/ 就写文档规则，经常改 services/payment/ 就写支付模块规则
  4. 排除明显无关文件——生成代码、构建产物、三方依赖，别让 Agent 老去读
  5. 把重复流程整理成 skill 或脚本——比如每次发版前要检查的 5 件事，别每次口头提醒

大代码库里，AI 编程不是"换个更强模型"就完了。真正拉开差距的，是你能不能把项目知识、工具链和团队规范，变成 Claude Code 可以稳定使用的工程支架。

二、Prompt Cache：为什么长会话不会越跑越慢

Anthropic 有一篇博客标题就叫"Prompt caching is everything"。很多人以为缓存就是"问过的问题下次直接拿答案"。完全不是。

Prompt Cache 缓存的不是答案，是中间计算

Claude Code 每一轮跟模型交互，并不是只把你刚输入的那句话发过去。它要发一整套东西：系统提示词、工具定义、CLAUDE.md 里的项目规则、前面所有对话消息、工具调用结果、你这一轮的新输入。

模型本身不会在两次 API 请求之间"记住"上一次聊到哪了，所以每一轮都要带上完整上下文。如果没有缓存，长会话越聊越贵、越聊越慢。

Prompt Cache 解决的就是这个问题：前面已经算过、下一轮又完全一样的部分，就不要再算一遍。

缓存的死穴：前缀必须完全匹配

Prompt Cache 靠的是前缀匹配。不是"这段内容大概一样"，也不是"这个文件之前读过"——而是从请求开头开始，连续一段内容必须一致，才能命中缓存。

这意味着什么？你改一个系统提示词里的时间戳，改一个工具定义的顺序，改一个 MCP 工具的加载方式——前缀一变，后面全断。

Claude Code 的请求组织非常讲究这一点：

  • 静态内容放前面：系统提示词、工具定义——全局稳定，不同项目都能复用
  • 项目上下文放中间：CLAUDE.md——同一个项目里稳定
  • 对话和工具结果放后面：随着聊天增长
  • 本轮新输入在末尾：每轮只让最后一点点内容变化

几个反直觉的工程结论

动态信息别改系统提示词，放进消息里。 当前时间变了、用户改了文件、权限状态变了——这些动态信息如果在系统提示词里更新，缓存就断了。正确的做法是：在下一条消息里追加一条系统提醒，前面的稳定前缀保持不变。

不要中途切模型，可能更贵。 Prompt Cache 按模型隔离。你在 Opus 里聊了 100k token，缓存在。你切到 Haiku——便宜？对，单次输出便宜。但 Haiku 没有 Opus 的缓存，要重新处理整段上下文。为了省一点输出成本，反而付出一大笔未缓存输入成本。

Plan Mode 不能靠"删掉写入工具"实现。 很多人设计 Plan Mode，第一反应是把编辑工具移除。但这会换掉工具集合，等于动前缀。Claude Code 的做法更聪明：始终保留完整工具集，把 EnterPlanMode / ExitPlanMode 做成工具，模式切换的信息放在对话末尾追加，不动前缀。

MCP 工具多了，不要每轮动态删工具。 工具集合变了，缓存前缀就变了。Claude Code 的思路不是"动态删工具"，而是"延迟加载工具详情"——先在稳定前缀放轻量 stub（工具名 + 极少元信息），模型真需要时才加载完整 schema。

上下文压缩不能另起一个请求。 如果你单独发一个请求让模型总结，它的系统提示词和父会话完全不一样，缓存全废。Claude Code 走缓存友好分叉：用和父会话一样的前缀，只在末尾追加压缩指令，复用父会话缓存。这也带来一个工程要求：系统必须预留压缩缓冲区——不能等上下文窗口真的塞满了才想着"现在总结一下吧"，那时候已经没空间放压缩指令和摘要输出了。compact 不是最后一刻的急救，而是上下文生命周期管理的一部分。

缓存命中率要像服务可用性一样监控

很多 Agent 性能问题，不是模型问题，是上下文组织问题。如果你的系统提示词每轮都变、工具定义顺序不稳定、MCP 工具动态增删、中途切了模型——缓存命中率就会很难看。用户体感就是：怎么突然变慢了？

做 Agent 要多看两类 token：cache creation input tokens（本轮写入缓存）和 cache read input tokens（本轮从缓存读取）。如果 read 很高、creation 很低，说明缓存用得好。如果 creation 连续很高，先别怀疑模型，先查上下文组织。

对普通开发者的五条实用建议

如果只是日常使用 Claude Code，记住这几条就够了：

  1. 别在长任务中频繁切模型——切一次模型，下一轮缓存要重建，可能明显变慢
  2. CLAUDE.md 改完不一定立刻生效——它是会话开头加载的项目上下文，中途改了不影响当前会话；要么重新开会话，要么在当前对话里明确补充
  3. MCP 别边做任务边频繁接入、断开——工具定义影响缓存，最好在任务开始前就把需要的 MCP 配好
  4. compact 放在自然断点——比如一个子任务完成后再压缩，而不是在关键编辑中间突然压缩
  5. 别把所有临时要求都塞进项目规则文件——稳定规则写进 CLAUDE.md，临时要求直接在当前对话里说

如果是自己做 Agent 产品，还要更进一步：Prompt 结构按稳定性分层、工具定义顺序必须确定、工具集合尽量会话内稳定、动态状态用消息追加、多模型用 subagent 隔离、工具详情用延迟加载、compact 走父会话缓存友好分叉、缓存命中率纳入监控。这不是优化清单，是架构清单。

三、Agent CLI：为什么最火的 Agent 产品都回了命令行

这可能是最反直觉的一个趋势：AI 都发展到 Agent 了，最火的产品反而钻回了黑乎乎的命令行。

2025 年 2 月，Anthropic 把 Claude Code 作为终端里的研究预览发布；同年 4 月，OpenAI 上线开源的 Codex CLI，5 月才推出 Codex Web。两家公司同时撞上了同一个工程事实：聊天框适合模型"说"，CLI 才方便 Agent 真正"做"。

CLI 的前世今生：它从来不只是"黑框里敲字"

先把三个词掰清楚：Terminal 是承载输入输出的终端，Shell 是解释命令的程序，CLI 是用文本命令和软件交互的方式。Claude Code、Codex CLI 今天已经是带面板、状态和快捷键的 TUI，但它们真正依赖的底座，仍然是 Shell、文件系统和一整套命令行工具。

最早的计算机甚至谈不上命令行——人把程序打在卡片上交给机器批处理，结果晚点再拿回来，人和机器之间没有实时对话。后来分时系统和终端出现，人终于可以输入一行命令、马上看到一行结果。到了 Unix，Shell 又做了一次关键升级：它不只是启动程序的入口，还是一门可以组合程序的控制语言。stdin、stdout、stderr、退出码、重定向、管道——这几个设计看起来朴素，却把一堆小工具接成了工作流。1978 年 Bourne 对 Unix Shell 的定义里，就已经同时强调了控制流、环境、重定向和进程管道。

GUI 兴起后命令行没有消失，因为两者解决的是不同成本：GUI 解决人的发现成本——按钮摆在那里，不会写命令也能点；CLI 解决系统的组合成本——一个命令能进脚本、进 CI、跑远程机器，还能把输出交给下一个程序。到了云原生时代，Git、Docker、Kubernetes、Terraform 几乎都把 CLI 当成一等公民，原因很简单：服务器没有必要配一块屏幕，自动化也不会拿鼠标点按钮。

Agent 时代命令行又转了一圈回来，但这次敲命令的主角从人变成了模型。变化的不是命令行突然变好用了，而是**“把人的意图翻译成精确语法"这份苦活，从人转移给了 Agent**——CLI 原本最劝退人的门槛，恰好被大模型吃掉了。

CLI 不是"黑框里敲字”，是可执行、可观察、可组合的反馈系统

你让 Claude Code 修一个登录 Bug，它不是吐一段代码就完事，而是顺着仓库继续干：搜索定位调用链，读取文件，修改代码，跑单测，看报错，再读 diff，直到证据说明任务完成。

CLI 把整个软件工具链压成了统一结构：

  • 输入是文本：需求、路径、参数都能明确传入
  • 动作是命令：Git、编译器、测试框架、数据库都能被调用
  • 反馈是证据：stdout、stderr、退出码、测试报告都能回到上下文
  • 组合靠管道：一次成功的交互，很容易固化成可重复执行的流程
  • 边界由操作系统兜底：工作目录、文件权限、网络策略限制爆炸半径

GUI 没输，只是它更适合人

GUI 最大的优势是把功能摊开给人看。设计稿、数据大盘、可视化调试，这些场景让人直接看比读几百行文本舒服得多。

但 Agent 操作 GUI，很多时候是在"猜像素"：按钮换个位置、弹窗多一层、页面加载慢一点，执行路径就变了。CLI 则把动作命名了——git status 不会因为窗口缩放跑到右上角，退出码 1 也比截图里一行红字更容易判断。

真正的分工不是 CLI 干掉 GUI，而是分成两层：人用 IDE、App、Web 看计划、审 diff、做授权；Agent 在下面用 CLI、API、MCP 执行和取证。

CLI 还可递归

Agent 不只会调用 CLI，自己也能变成 CLI 的一环：

cat build-error.txt | claude -p "定位根因并给出修复建议"
git diff | codex exec "检查这次修改是否引入并发问题"

交互工具因此变成了脚本组件，可以进 CI、定时任务和无人值守流程。网页聊天框很难自然做到这一点。

但今天很多 CLI，并没有为 Agent 准备好

别因为 Agent 能跑命令，就觉得所有 CLI 都天然可靠。大量老工具默认操作者是人：会弹交互确认、输出彩色进度条、把错误混进 stdout，甚至失败了还返回 0。人能凭经验看懂，Agent 接进流水线就容易翻车。

真正 Agent 友好的 CLI，至少要做到几件事：

  • 支持 --json 或稳定 Schema，不逼模型从花哨日志里猜字段
  • stdout 放结果、stderr 放诊断，退出码真实反映成功或失败
  • 提供 --dry-run、diff 和幂等操作，让 Agent 能先预演、失败后安全重试
  • 支持非交互模式、超时和取消，不要半夜卡在"是否继续？Y/n"
  • 权限最小化，凭证可按任务、目录、命令和时间收口
  • 输出可审计，明确谁执行了什么、改了哪里、依据是什么

未来 CLI 的竞争，不只是给人写得顺不顺手，还要看它能不能被 Agent 稳定调用。 这也是为什么 Claude Code 和 Codex 都在权限模型上花重力气——Agent 越能干，误操作和提示注入的爆炸半径越大。没有边界的 CLI，不是自动化，是把生产事故也自动化。

CLI 不是终局，但会长期存在

当 Agent 从一次处理一个任务，变成同时管理十几个长期任务，纯终端很快就不够用了。你需要任务队列、并行状态、权限面板、diff 审核、通知和跨设备接力。

CLI 更像 Agent 世界里的"窄腰层"：上面可以是 IDE、桌面 App、网页、手机，下面可以接 Git、测试、数据库、容器和云服务，中间通过命令和结构化结果完成交接。未来不会由一个入口通吃，而是"人类监督层—Agent 编排层—工具执行层"三层分工。

另外，CLI 也不是所有工具的最佳协议——API 和 MCP 有明确 Schema，通常比解析自然语言日志更稳；Computer Use 则负责那些既没有 API、也没有 CLI 的最后一公里。但 CLI 不会消失，真正的终局是：所有软件都长出一套 Agent 能调用、能验证、能审计、也能被安全关住的接口，而 CLI 只是最早准备好的那一个。

总结

三件事串起来看，其实是一条主线：

  • Agentic Search 解决了 Agent 在大代码库中"怎么找"的问题——不靠索引，靠边搜边读的工程化探索
  • Prompt Cache 解决了 Agent 在长会话中"怎么不越来越慢"的问题——前缀匹配的缓存策略，影响着产品设计的每一个决定
  • Agent CLI 解决了 Agent “在哪干活"的问题——命令行提供了可执行、可观察、可组合的最小执行单元

这三层不是独立的。CLI 执行的命令产出的反馈，是 Agentic Search 下一轮探索的依据；Prompt Cache 的分层策略，决定了上下文里哪些信息稳定、哪些可以动态变化。

Claude Code 不是在 CLI 里塞了一个强模型。它是在模型之外，做了一整套能长期运行的工程基础设施。理解了这三层，你对 Claude Code 的认知就不会停留在"它写代码挺快”——你会看到它底下那套让 Agent 能持续工作的架构。

参考链接