Claude Code Harness深度分析：从RAG、Skill、Memory到企业Agent落地

这篇文章我想解决的不是“Claude Code 源码里有哪些文件”，而是三个更实际的问题：

  1. 看完源码后，RAG 在 agent harness 里到底应该怎么理解？
  2. skill 和 memory 到底是什么，它们和 prompt、tool、agent 的边界在哪里？
  3. 如果我后面要在公司里做提效、做 skill、做 agent，有哪些东西可以直接借鉴？

如果你也有类似困惑，那这篇会比普通源码感想更适合你。

先说明边界：
本文基于 Claude Code 相关公开发布包和还原出来的工程样本做分析，也参考了 Claude Code 源码教学指南 这种章节化讲解方式，但下面的内容是我结合自己阅读源码后的原创整理与判断，重点放在“怎样用这些理解去做自己的系统”。

一、先给一张图：Claude Code 这类 harness 到底在干嘛

很多人会把 Claude Code 理解成：

1
用户输入 -> 模型回答 -> 偶尔调工具

但如果你从源码角度看，它其实更像下面这套系统：

这张图里最重要的结论是：

  • RAG 不是孤立模块，而是上下文装配机制
  • skill 不是一段 prompt，而是任务方法包
  • memory 不是神秘长期记忆，而是多层上下文系统
  • session 不是聊天记录，而是运行时状态资产

你如果把这几层关系看懂了，后面自己做 agent 时就不会只盯着模型。

二、一次任务是怎么跑完的：流程图先立住

这条链路说明，真正的 agent runtime 在做的是：

  • 把任务放到正确轨道
  • 给当前轨道装配合适上下文
  • 让执行结果能沉淀回系统

这比“让模型回答更聪明”重要得多。

三、看完源码后，我对 RAG 的理解改变了

这是我最想讲清楚的一段。

很多人一说 RAG，脑子里只剩：

  • chunk
  • embedding
  • vector db
  • top-k

但看完 Claude Code 这类 harness 以后，我现在更愿意把 RAG 定义成：

在任务执行前，把当前这轮真正需要的上下文，从多个知识源里检出来，再装配进模型可用上下文。

这个定义比“向量检索”大很多，也更接近工程现实。

1. 在 Claude 这类 harness 里，RAG 至少有四层

层 来源 它解决什么问题 更像什么
静态规则检索 CLAUDE.md / instructions 这次执行必须遵守哪些长期规则 文件注入
skill 检索 loadSkillsDir / skillSearch 这类任务该走哪套 workflow 方法检索
memory 检索 memdir/findRelevantMemories 当前 query 还需要哪些经验或提醒 相关经验检索
session 检索 SessionMemory / compact summary 当前会话已经形成了哪些阶段性结论 状态回收

所以从 harness 角度讲，RAG 不只是“查知识库”，而是：

规则、方法、经验、状态，这四类上下文的统一检索与装配。

2. 这份源码里最有启发的一点：它不迷信“必须向量化”

比如 findRelevantMemories.ts 的思路，给我的冲击挺大。

它没有一上来就做那种标准企业宣传版 RAG：

1
全量切块 -> embedding -> ANN 检索 -> rerank

它更像是：

  1. 先扫描 memory 文件头部和描述
  2. 形成结构化候选列表
  3. 再用一个侧路模型判断哪些 memory 确实有帮助

这说明一个很重要的现实：

很多企业内部知识场景，先把知识组织好、先把候选缩小，再做模型选择，已经比盲目全量向量化更有性价比。

这对你后面在公司里做提效特别重要，因为它意味着你完全可以先走这条更稳的路线：

  • 先把知识做成结构化文档、规则文件、FAQ、案例卡片
  • 再做目录扫描、标签过滤、头部摘要
  • 最后让模型做轻量选择

如果连知识组织都没做好，直接上向量库，通常只是把混乱放大。

3. 所以，企业里真正该做的 RAG，不是“搭一个库”，而是“搭一条检索链”

我现在会把企业 agent 的 RAG 拆成这几个动作：

  1. 当前任务属于哪个域
  2. 这个域有哪些固定规则
  3. 这个任务要不要命中特定 skill
  4. 这个 skill 需要哪些工具和资料
  5. 当前会话已有结论里哪些需要带入下一轮
  6. 有没有历史案例值得补进来

这才是一个真正能工作的 RAG。

四、看完源码后，我对 skill 的理解是什么

如果说以前我会把 skill 理解成“一个写得不错的提示词模板”，那现在我会更明确地说：

skill 是 workflow + policy + tool contract 的组合。

为什么？

因为从 loadSkillsDir.ts 暴露出来的字段看，一个 skill 不是只有正文，它还会带上这些信息：

  • description
  • when_to_use
  • allowed-tools
  • arguments
  • hooks
  • model
  • effort
  • paths
  • executionContext

这意味着 skill 的职责不是“多说几句怎么做”，而是把整个任务方法显式化。

1. skill 不是知识点，而是方法包

这点非常关键。

比如：

  • remember 不是在讲记忆理论，而是在告诉系统“什么时候该沉淀记忆”
  • verify 不是在讲测试概念，而是在固化“做完以后怎么验证”
  • stuck 不是在讲 debugging，而是在约束“卡住时怎么脱困”

这说明好的 skill 不是“解释”，而是“带执行语义的工作流”。

2. skill 和 tool 的边界

这也是很多人做 agent 时最容易混掉的地方。

  • tool 是动作能力
    比如读文件、改文件、跑命令、查 MCP 资源

  • skill 是动作编排
    比如先搜代码，再找相似实现，再改，再跑测试，再总结

一个 skill 可能会用到多个 tool；
一个 tool 也会被多个 skill 复用。

所以 skill 永远不该被做成“某个工具的说明书”，而应该是“某类任务的最佳路径”。

3. skill 和 agent 的边界

我现在会这么分：

  • skill 负责沉淀做事方法
  • agent 负责执行和调度
  • tool 负责完成具体动作

这三层拆开以后，你的系统才能复用。

如果把 skill 和 agent 写死绑定，后面一旦流程变化，整个系统很快会变得很重。

4. 对你做公司 skill 的直接帮助

以后你在公司里写 skill，建议强制自己回答这 6 个问题：

  1. 这个 skill 解决哪类任务？
  2. 触发时先查什么？
  3. 哪些工具优先用？
  4. 输出格式是什么？
  5. 成功标准是什么？
  6. 如果证据不够或执行失败，下一步怎么补救？

如果这 6 个问题答不清，这个 skill 大概率还是 prompt，不是 workflow。

五、看完源码后，我对 memory 的理解是什么

以前很多人一听 memory，会先想到“长期记忆”“跨会话记住用户偏好”。

但从 Claude Code 这类 harness 的实现来看，memory 的价值其实更工程化：

memory 的本质不是记住一切，而是让系统在多轮和跨轮执行中保持稳定工作方式。

更具体一点说，它是个分层系统。

1. 第一层：静态规则型 memory

比如：

  • CLAUDE.md
  • .claude/instructions.md
  • 项目级约束文件

这一层保存的不是临时事实，而是长期有效的约束：

  • 项目规范
  • 测试命令
  • 提交约定
  • 工具偏好
  • 风险边界

这一层对企业最有价值，因为它：

  • 可见
  • 可 review
  • 可 diff
  • 可版本化
  • 可协作

它比“神秘自动记忆”更适合团队环境。

2. 第二层：会话摘要型 memory

SessionMemory/sessionMemory.ts 非常有意思。

它不是让主线程每一轮都自己回忆，而是后台周期性提取当前会话里的关键结论，整理成 markdown 形式的会话记忆。

这意味着它在做的其实是：

把长链路、多噪声的会话过程，提纯成可继续利用的阶段状态。

对企业任务这非常重要，因为真实工作流往往是：

  • 先澄清需求
  • 再查代码
  • 再查日志
  • 再试修改
  • 再验证
  • 再回顾

如果没有这层摘要型 memory，任务一长，系统就会开始遗忘自己已经做到了哪一步。

3. 第三层：动态相关 memory

这层最像 memdir/findRelevantMemories.ts。

它不是把所有 memory 全塞进上下文，而是只选当前 query 真能用上的几个。

所以动态 memory 的重点不是“多存”，而是“选准”。

4. 我现在对 memory 的最终理解

如果让我压成一句话：

  • 静态规则 memory 负责稳定约束
  • 会话摘要 memory 负责阶段状态
  • 动态相关 memory 负责当前命中

这三层加起来，才是一个真正可运行的 memory 系统。

六、把 RAG、Skill、Memory 放在一起看，它们分别扮演什么角色

这一段最适合你后面做自己的系统时反复回来看。

能力 回答的问题 最像什么 对系统的价值
RAG 这轮需要什么上下文？ 检索与装配 降低上下文噪声
Skill 这类任务应该怎么做？ 工作流模板 提高执行稳定性
Memory 系统应该记住什么？ 规则与状态层 提高多轮连续性

如果把它们混在一起，你的系统会很难长大。

最常见的错误是：

错误 1：把 skill 写成 memory

比如把一整个排障流程写进长期规则里。
结果是规则文件越来越臃肿，系统每轮都背着无关流程跑。

错误 2：把 memory 当 skill

比如把“数据库表 owner 是谁”“某个接口调用链是什么”这类知识写进 skill。
结果 skill 变成知识垃圾桶。

错误 3：把 RAG 当成万能修复器

很多系统上下文乱、方法乱、状态乱，最后希望“多检索一点”来补。

但 RAG 解决的是“拿什么上下文”，不是“方法本身对不对”。

七、如果你后面要做公司提效，最值得借鉴什么

我尽量只讲可落地的。

1. 先跑通一个高价值闭环，不要一开始做“大而全平台”

看完这类源码后很容易上头，想做“公司版 Claude Code”。

但更现实的做法是先只打通一个高价值闭环，比如：

  • 需求单 -> 技术方案草稿
  • traceId / issue -> 问题分析报告
  • 代码 diff -> 风险点与测试建议
  • 发布单 -> 发布前核对清单

先把一条链路打深，比同时做十条半残链路更值钱。

2. 最先值得 skill 化的，一定是高频、稳定、可标准化的流程

我会优先选这些：

  • 问题排查 skill
  • 技术方案生成 skill
  • 代码审查 / 风险评估 skill
  • 集成测试设计 skill
  • 发布校验 skill

为什么？

因为这些场景：

  • 高频出现
  • 步骤相对稳定
  • 输出格式容易约束
  • 特别适合把经验沉淀下来

3. 企业 memory 先做“文件化规则”，不要急着做“超级记忆大脑”

第一批最值钱的 memory，通常是这些：

  • 项目规范
  • 模块边界说明
  • 常见故障案例
  • 术语字典
  • 默认链路与 owner 约定
  • 工具选路约定

只要这些能被结构化、可检索、可维护，你的 agent 就已经比“裸模型”强很多。

4. 真正要补的不是“万能问答”，而是“上下文装配”

很多企业 agent 做不起来，不是模型弱，而是每次执行前拿到的上下文太乱。

你真正该补的是：

  • 当前任务归属哪个域
  • 对应 skill 是什么
  • 该加载哪些规则文件
  • 该检索哪些经验
  • 允许调用哪些工具
  • 当前会话已经产出了哪些阶段结论

这就是 harness 思维。

5. session 一定要当资产管理

如果你做公司 agent，session 至少要做到：

  • 可回放
  • 可审计
  • 可恢复
  • 可摘要
  • 可导出

否则它永远只能停留在 demo 阶段。

八、如果你现在就要做一个公司内提效 agent，我建议的最小架构

别追求完整，先做下面这个：

这套最小架构里，最该先补的不是更强模型，而是这五层：

  1. 任务分类
  2. skill 选择
  3. 静态规则装配
  4. 动态记忆检索
  5. session summary

这五件事顺起来，你的系统就会开始从“偶尔有用”变成“逐渐稳定”。

九、你可以马上做的 3 类 skill

如果你现在就想动手，我建议你优先做下面这三类。

1. 问题分析型 skill

适用场景：

  • 线上报错
  • traceId 排查
  • Jira 问题定位

输出应该固定为：

  • 现象
  • 证据
  • 归属模块
  • 风险面
  • 下一步建议

2. 方案生成型 skill

适用场景：

  • 需求评审前
  • 技术方案初稿
  • 系统边界梳理

输出应该固定为：

  • 背景
  • 现状
  • 目标
  • 改造点
  • 风险点
  • 测试点

3. 变更验证型 skill

适用场景：

  • 代码改完以后
  • 提交 PR / MR 前
  • 联调前

输出应该固定为：

  • 改动摘要
  • 风险点
  • 覆盖测试
  • 未验证项
  • 发布注意事项

这三类 skill 的共同点是：

  • 高频
  • 复用价值高
  • 对稳定格式有强需求

最适合当企业提效的第一批抓手。

十、你可以马上做的 2 种 agent 形态

我不建议一开始就做十几个 agent team。

先做这两种就够了：

1. 单主控 + 多 skill 的 agent

特点：

  • 一个主 agent 负责理解任务
  • 按需选择 skill
  • 统一调工具
  • 统一写 session 与 memory

优点是简单、稳、容易审计。

2. 主控 agent + 子 agent 的有限协作

适合场景：

  • 主 agent 做调度
  • 子 agent 分别负责搜索、实现、验证

但前提是你已经把：

  • session
  • memory
  • tool contract
  • 输出格式

这些基础设施打稳。

否则 multi-agent 只会放大混乱。

十一、最后压一句最关键的话

如果要我把整篇文章只压成一句判断，我会说：

Claude Code 这类 harness 真正值得学的，不是它“用了哪个模型”，而是它把 检索、方法、记忆、执行、压缩 做成了一个能长期运转的系统。

对你后面做公司提效来说，这个启发非常直接：

  • 别先追求“万能智能体”
  • 先做清楚上下文装配
  • 先沉淀高频 skill
  • 先建立文件化 memory
  • 先把 session 当资产

当这些基础设施长出来以后，agent 才会开始真的有复利。

延伸阅读