Claude Code 技术架构深扒：Prompt / Context / Harness 三维设计实践

猫猫镇楼 🐈 先说结论：Claude Code 的架构本质上是一个高度工程化的 Agent 运行时 ，它在 Prompt 组装、Context 管理、Harness 调度三个维度都做了非常精细的控制，不是一个"套壳调 API"的项目，是一个正经的系统级工程实践。

开场：为什么聊这个？

最近在研究 AI Agent 的工程化落地，绕不开的一个标杆就是 Anthropic 官方推出的 Claude Code------命令行里的 AI 编程助手。

说实话，市面上 AI 编程工具一抓一大把，但能把架构设计讲得这么清楚、代码还开源的，真不多。Anthropic 这波属于是"授人以鱼不如授人以渔"，自己用不说，还把设计思路摆出来让社区学习。

今天老卷就带大家深扒一下 Claude Code 在 Prompt Engineering 、Context Engineering 、Harness Engineering 三个维度上分别是怎么玩的。不玩虚的，直接上硬菜。

一、Prompt Engineering：System Prompt 的"乐高式"组装

📌 一句话结论：Claude Code 的 Prompt 不是一坨大文本，而是一套精密的动态组装流水线，静态+动态边界+动态内容三层分离，每次组装都走6步标准化流程。

1.1 三层结构：静态 + 动态边界 + 动态内容

先说整体设计思路。Claude Code 的 System Prompt 不是写死的一段文字，而是分成了三层：

为什么要这么分？

老卷观点：这是工程上的关注点分离。静态部分保证能力基线，动态边界决定"用什么策略"，动态内容决定"具体塞什么料"。三层各司其职，修改的时候不会互相影响。

1.2 6步组装流程

Claude Code 的 Prompt 组件会经过一个严格的 6 步流水线：

Base 构建：从静态模板开始
边界注入：根据当前环境（OS、项目类型）插入边界条件
工具描述渲染：把可用工具列表渲染进 Prompt
规则集注入：项目级 .claude 规则文件内容注入
会话上下文注入：历史消息的摘要压缩
最终组装：所有部分拼接成完整 System Prompt

[配图建议：流水线示意图，从左到右6个步骤，每个步骤有输入输出]

每一步都有明确的目标，不会出现"一股脑全塞进去"的混乱场面。这个流程保证了 Prompt 的确定性和可复现性------同样的上下文，每次组装的结构是一样的。

1.3 卷卷点评

说实话，很多团队做 Agent 的时候，Prompt 就是一坨大文本塞进去，改一下怕影响全局，不改又觉得哪里不对。Claude Code 这个三层分离+6步流程的设计，本质上把 Prompt 当成了一种"可组合的配置"，而不是"神圣不可改动的咒语"。

这个思路值得抄。👍

二、Context Engineering：从文件到记忆的四层架构

📌 一句话结论：Claude Code 用 CLAUDE.md 建立了"全局→项目→私有→规则"四层上下文体系，配合 MicroCompact / Session Memory / Full LLM 三层压缩，让有限的 Context Window 用在刀刃上。

2.1 CLAUDE.md 四层架构

这是 Claude Code 最有意思的设计之一------它用约定大于配置的方式，让项目结构自己说话。

这里有个很巧妙的设计：

规则层是按文件名匹配动态加载 的。比如你在 .claude/rules/code-review.md 里写了代码审查规则，那么当你执行 claude code --review 的时候，它会自动把这个规则注入进来。

2.2 三层压缩体系

Context Window 是有限的（虽然 Claude 3.5 已经很能装了，但工程上不能假设无限），Claude Code 为此设计了一套三级压缩体系：

为什么三层？

因为单层压缩要么失真太多（直接截断），要么太贵（全部塞进去）。Claude Code 用了一个很聪明的思路：用小模型做粗筛，用大模型做精筛。MicroCompact 先把明显无关的去掉，Session Memory 做会话级别的聚合，最后 Full LLM 判断"这个决策需要哪些上下文"。

老卷觉得这个设计非常务实。不是在省 Context，而是在"让 Context 发挥最大价值"。

2.3 Memdir 记忆系统

这是一个长期记忆的机制。Claude Code 维护了一个 ~/.claude/memdir/ 目录，里面存放了：

项目知识卡片：用自然语言描述项目结构、技术债务、关键决策
模式记录：记录哪些操作在这个项目里"好用"，哪些"踩过坑"
学习历史：随着使用时间增长，Agent 对项目的理解越来越深

这个设计解决了一个很实际的问题：每次新会话 Agent 都是白板。有了 Memdir，下一次对话 Agent 能继承上一次的工作记忆，而不是从头开始问"这个项目是干啥的"。

2.4 卷卷点评

Context Engineering 是 Claude Code 架构里最容易被低估的部分。很多人关注 Prompt 怎么写，但实际上 Context 的质量直接影响模型能否做出正确判断。

四层架构解决的是"谁来提供上下文"的问题，三层压缩解决的是"上下文太多怎么办"的问题，Memdir 解决的是"上下文怎么积累"的问题。三个子系统各司其职，形成了完整的上下文生命周期管理。

三、Harness Engineering：Agent 的"发动机与底盘"

一句话结论：Harness 层是 Claude Code 的执行引擎，核心是 Permission Engine 的三层权限模型、内置6大 Agent 协作机制、异步生成器主循环，以及 Hook 钩子体系------这几样东西加在一起，才让"模型控制电脑"变成了可能。

3.1 System Reminder 动态注入

除了 System Prompt，Claude Code 还支持 System Reminder------一种更高优先级、更灵活的指令注入机制。

区别在于：

|------|---------------|-----------------|
| | System Prompt | System Reminder |
| 注入时机 | 每次请求前 | 按需触发 |
| 优先级 | 基础能力定义 | 临时性指令/约束 |
| 生命周期 | 整个会话 | 可指定过期条件 |
| 示例 | "你是一个编程助手" | "当前在安全模式下，仅读文件" |

System Reminder 的典型使用场景：

安全模式：禁止执行删除操作
评审模式：只读不写
特定工具约束：禁止调用某个危险 API

3.2 6大内置 Agent

Claude Code 内置了 6 个专门化的 Agent，每个 Agent 负责一类特定任务：

这些 Agent 不是独立运作的，而是通过消息传递和状态共享进行协作。Orchestrator Agent 作为调度者，把复杂任务拆解后分发给专业 Agent，最后汇总结果。

这个设计的好处是什么？

单一 Agent 的问题在于"啥都能干但啥都不精"。6个专业 Agent 各有所长，复杂任务被拆解成专业子任务，每个子任务由最合适的 Agent 处理。不是让一个通才去解决所有问题，而是组建一个各有分工的团队。

老卷觉得这思路非常符合现实世界的协作模式。👀

3.3 Permission Engine：三层权限模型

这是 Claude Code 安全体系的核心。Permission Engine 控制"模型能做什么"，分三层：

第三层的实时判断很有意思：模型在执行某个操作之前，会先评估这个操作的风险等级。如果风险超过阈值（比如要删除大量文件），会暂停执行并向用户发起确认请求。

这个设计解决了一个核心矛盾：既要给模型足够的自主权（不然效率太低），又不能让它失控（安全问题）。三层分离让安全策略既有纵深防御，又有足够的灵活性。

3.4 沙箱隔离

对于高危操作，Claude Code 提供了沙箱执行环境：

文件操作在虚拟层进行，结果需要显式确认才能落盘
网络请求通过代理，控制出口流量
命令执行有超时和资源限制

沙箱的存在让"实验性操作"变得安全------你可以让 Agent 尝试危险操作，结果不会真的影响系统，除非你显式批准。

3.5 异步生成器主循环

Claude Code 的核心运行逻辑是一个异步生成器主循环：

复制代码

async def main_loop():
    while True:
        # 1. 等待下一个消息
        message = await message_queue.get()
        
        # 2. 分发给对应 Agent
        agent = select_agent(message)
        
        # 3. Agent 执行，产出操作序列
        operations = await agent.process(message)
        
        # 4. Permission Engine 逐个审查操作
        for op in operations:
            if await permission_engine.check(op):
                await sandbox.execute(op)
            else:
                await user_confirm(op)
        
        # 5. 结果反馈给用户
        await send_result()

这个循环设计的好处是每个步骤都是可观测的、可中断的。如果某一步出了问题，可以立即干预，而不是等整个任务跑完才发现不对。

3.6 Hook 钩子机制

Hook 机制允许在特定时机插入自定义逻辑：

before_agent_run：Agent 执行前
after_agent_run：Agent 执行后
before_tool_call：工具调用前
after_tool_call：工具调用后
on_error：出错时

这是一个插件化的扩展机制 。比如你可以在 before_tool_call 里加一个日志钩子，记录每次工具调用；或者在 after_agent_run 里加一个指标上报。

这个设计让 Claude Code 不再是一个封闭系统------你可以根据自己的需求定制它的行为，而不需要改核心代码。

3.7 卷卷点评

Harness 层是 Claude Code 工程化程度最高的模块。Permission Engine 解决安全边界问题，内置 Agent 解决专业分工问题，异步主循环解决执行控制问题，Hook 解决扩展性问题------每一块都是工程难点，Claude Code 选择了正面硬刚，而不是绕过去。

番外篇：彩蛋功能------Anthropic 的"反差萌"

一句话结论：Claude Code 不只是一个严肃的工程系统，它还藏了一堆彩蛋------电子宠物、抽卡系统、100+荒诞加载词......这波操作属实是把"工具"玩成了"玩具"。

Claude Code 真正让老卷惊喜的，不是它的正经功能，而是这堆藏得极深的彩蛋：

Buddy System：你的电子宠物(2.1.97 版本就无了~ 可以考虑不升级上去)

Claude Code 内置了一个类似"抽卡游戏"的电子宠物系统：

抽卡：随机获得一个 Buddy（伙伴）
稀有度：Common → Rare → Epic → Legendary
属性系统：每个 Buddy 有自己的性格标签（如 "Curious"、"Cautious"、"Chaotic"）

附上一张我当时暴力破解的金色传说：

你的 Buddy 会出现在 Claude Code 的输出里，偶尔发表一些"个人意见"。比如当你执行危险操作时，一个 "Cautious" 属性的 Buddy 可能会跳出来说："等一下，这看着不太对劲啊......"

这个彩蛋的工程实现也很有意思------Buddy 不是硬编码的，而是通过 Prompt 动态生成的性格描述，配合 LLM 的角色扮演能力实现的。

Caffeinate：Mac 专属防休眠

Mac 用户专享的一个小功能：执行 claude --caffeinate，它会在会话期间阻止系统休眠。

这个彩蛋的诞生原因很朴实------Anthropic 的工程师们自己用 Claude Code 的时候发现，长时间跑任务电脑老休眠，很烦，于是加了这个功能。

"我为自己写的功能，现在你也可用"------这大概是开源精神最朴素的诠释了。 😂

Anti-Distillation：反蒸馏保护

这是一个偏"严肃"的彩蛋。Claude Code 检测到用户尝试用它生成"蒸馏"内容（用于训练其他模型）时，会礼貌地拒绝。

这个彩蛋体现了 Anthropic 的立场：我们提供的能力是用来解决问题的，不是用来复制自己的。

Undercover Mode：卧底模式

开启后，Claude Code 会假装自己不是 Claude Code，而是另一个普通工具。如果有人问"你是 Claude Code 吗？"，它会否认。

这个彩蛋的实用场景不多，但工程实现上挺有意思------它需要动态修改 System Prompt 的身份定义，并且在检测到特定追问时触发"伪装逻辑"。

💬 100+ 荒诞加载动词

当 Claude Code 在"思考"的时候，它不会只显示干巴巴的"Loading..."，而是用各种荒诞的动词来描述这个状态：

"Distracting the developers..."
"Reticulating splines..."
"Generating witty responses..."
"Consulting the oracle..."
"Untangling spaghetti code..."
"Warming up the flux capacitor..."

这 100+ 个加载词散布在代码库里，工程师们可以持续往里面加。这是一个团队文化的体现------在严肃的工程系统里，给自己留一点幽默的空间。

老卷就喜欢这种调调。真正好的产品，不是没有温度的，而是把温度藏在细节里。

总结：Claude Code 教会了我们什么？

核心收获

Prompt 不是一坨文本，是一套工程系统
三层分离+6步流水线，把 Prompt 管理变成了可复现的工程实践。
Context 是护城河，不是越多越好
四层架构解决上下文来源，三层压缩解决上下文质量，Memdir 解决上下文积累。
Harness 是差异化的核心
Permission Engine + 内置 Agent + 异步主循环 + Hook，这套组合拳才是 Claude Code 和"调 API 套壳"本质区别所在。
彩蛋是团队文化的镜子
100+ 加载词、Buddy System------这些看似无用的东西，恰恰是 Anthropic 工程师文化的最好证明。

行动建议

如果你在做一个 AI Agent 项目，Claude Code 的架构里有几个可以直接抄的：

Prompt 组件化：别再写一坨大文本了，分层管理
四层上下文架构：CLAUDE.md 的约定式设计非常值得借鉴
三层权限模型：安全是底线，不是可选项
异步主循环：让每一步都可观测、可干预

最后说两句

Claude Code 不是一个"AI 编程工具"那么简单。它的架构设计代表了一种思路：把 AI Agent 当成一个正经的工程系统来做，而不是一个调调 API 的玩具。

这个思路，值得所有做 AI Agent 的人认真研究。

🐈 卷卷评分：架构设计 9/10，彩蛋惊喜 8/10，工程化程度 9.5/10。

推荐指数： ⭐⭐⭐⭐⭐ （必读）

本文基于 Claude Code 公开架构文档和个人研究整理，如有疏漏欢迎指正。