Claude Code架构深度解析：从核心文件到Harness的确定性控制体系

前言Claude Code凭借强大的代码理解、编辑与执行能力成为AI研发工程师的高效工具但多数使用者仅停留在功能调用层面对其底层架构尤其是核心控制层Harness知之甚少。作为Claude Code架构师本文将从项目架构视角拆解其核心文件构成深度解析Harness的本质与实现逻辑解答「如何用确定性代码约束概率性LLM」的核心问题同时结合工程化实践梳理架构设计的痛点与解决方案为AI Agent的工程化落地提供参考。一、背景LLM时代AI Code工具的架构挑战大语言模型LLM的出现让代码智能工具迎来爆发但LLM本身是概率推理引擎——它能根据输入生成大概率合理的结果却无法保证100%的确定性更不具备原生的文件操作、命令执行、会话管理能力。Anthropic推出的Claude模型作为底层大脑仅能实现「文本输入-下一个词的概率计算」的核心功能为了将其打造成可落地的Claude Code工具需要在模型之上搭建多层架构解决能力扩展与风险控制两大核心问题能力扩展让Claude拥有读文件、执行命令、上网、记忆会话的能力风险控制约束LLM的灵活性避免其执行危险命令、违反项目规范保证工具使用的安全性与合规性。在此背景下Claude Code形成了「七层蛋糕」的分层架构而Harness作为核心控制层成为连接LLM能力与工程化落地的关键也是整个项目架构的灵魂。Claude Code整体分层架构Mermaid图注橙色标注为核心控制层Harness是本文解析的重点。二、痛点无控制的LLM工具高效却危险在Harness出现之前早期的AI Code工具直接基于LLM API做简单的能力封装暴露出一系列工程化痛点也是Claude Code架构设计必须解决的核心问题1. LLM的概率性导致规则执行不严谨通过prompt向LLM下达的规则如「禁止使用cat命令」「不准执行rm -rf」在长对话、上下文压缩场景下遵守率仅85%-95%。对于生产环境1%的违规概率都可能导致数据丢失、系统崩溃软约束无法满足工程化的合规要求。2. 能力扩展与风险控制的矛盾LLM的价值在于灵活性能处理开发者未预料到的代码问题但灵活性同时带来不可控性LLM可能随意执行高危命令、修改核心文件完全放开则工具危险完全锁死则工具失去智能性难以找到平衡。3. 会话与上下文管理的混乱LLM本身是无状态的无法记忆上一轮对话且上下文窗口有长度限制。长对话中若无法自动压缩上下文、保存会话检查点会导致工具「断片」无法完成复杂的代码调试、项目重构等长周期任务。4. 工程化落地的效率与成本问题直接使用大模型Opus处理所有任务会导致token成本飙升Opus价格是Haiku的60倍硬编码的规则修改需要重启服务无法热更新工具调用的无拦截流程会导致执行效率低、卡顿明显。5. 核心文件职责不清晰架构可维护性差若未对配置文件、控制文件、操作文件做分层设计会出现「规则写在prompt里、约束散在代码中」的问题项目迭代时修改成本高难以规模化落地。三、实现Claude Code项目架构全解析Claude Code的架构实现围绕「分层解耦、软硬结合、确定性控制」三大原则展开核心分为核心文件构成、Harness的本质与定位、Harness核心实现、一次请求的完整执行流程四部分从文件到层从层到流程实现对LLM的全链路控制。一Claude Code核心文件构成Claude Code的项目文件围绕七层架构做模块化设计核心文件可分为配置文件、控制文件、应用核心文件、工具集文件四大类各文件与架构层一一对应职责清晰、解耦性强以下为核心文件及作用文件类型核心文件对应架构层核心作用配置文件CLAUDE.mdLayer6项目「宪法」写入持久化指令、编码规范、禁止事项实现prompt级软约束settings.jsonLayer5Harness的核心配置文件定义Hooks脚本、权限规则、模型路由策略支持热更新skills.yaml/.mdLayer7技能手册封装/tdd//review等prompt模板实现知识注入控制文件harness.pyLayer5Harness的核心实现文件封装Hooks、权限、会话、上下文管理的核心逻辑context_manager.pyLayer5上下文压缩与管理的子模块隶属于Harnesssession_manager.pyLayer5会话检查点、恢复的子模块隶属于Harness应用核心文件claude_code_cli.pyLayer3Claude Code的CLI应用入口实现Agent循环输入→拼装prompt→调API→执行工具→循环agent_cycle.pyLayer3Agent循环的核心逻辑处理用户输入与模型输出的交互工具集文件tools.pyLayer4封装Read/Edit/Bash/Glob等可调用工具提供LLM的「手脚」bash_tool.py/read_tool.pyLayer4各工具的独立实现解耦工具集逻辑接口文件claude_api_client.pyLayer2Claude API的调用客户端实现HTTP无状态通信核心设计亮点所有控制规则与业务逻辑解耦配置文件与代码文件分离如Harness的规则通过settings.json配置无需修改harness.py即可更新约束策略支持热更新提升工程化可维护性。二Harness的本质与定位不是功能是全链路控制体系很多开发者将Harness理解为一个「功能模块」这是典型的认知偏差。Harness是Claude Code中所有控制机制的统称是架设在Claude Code应用与工具集之间的「安检门」也是连接软约束CLAUDE.md与硬执行Tools的核心桥梁。从架构定位看Claude Model是大脑概率推理Claude Code是身体Agent循环应用Tools是手脚具体操作Harness是方向盘安全带仪表盘确定性控制。其核心哲学是用确定性的代码逻辑约束概率性的LLM模型让LLM的灵活性在可控范围内发挥既保证能力又规避风险。三Harness的核心实现四大机制三大Hook检查站Harness的核心实现围绕四大控制机制展开同时通过三大Hook检查站将控制逻辑嵌入到Claude Code的全执行流程中实现「事前拦截、事中控制、事后处理」的全链路管控也是Harness作为「控制核心」的关键。1. Harness四大核心控制机制Mermaid图Harness 核心控制机制Hooks 钩子机制生命周期脚本拦截Permissions 权限机制allow/deny/ask白名单规则Context Manager上下文管理自动压缩裁剪Session Manager会话管理检查点/恢复注蓝色标注为Harness最核心的机制——Hooks钩子机制。四大机制的具体作用与实现要点机制核心作用实现要点一句话总结Hooks在生命周期事件上执行自定义脚本实现拦截/放行定义三个检查站脚本返回exit 0放行exit 2拦截提示每次Claude想用工具先过我这关Permissions对工具/命令做权限控制基于白名单设计白名单之外的操作一律拦截支持ask模式询问用户后执行非白名单零执行Context Manager解决上下文窗口溢出问题基于语义分析自动压缩长对话保留核心信息裁剪冗余内容快超窗口我来裁剪Session Manager解决LLM无状态问题定时保存会话检查点断连后可恢复对话状态记录操作日志聊到一半断了我帮你接上2. Harness三大Hook检查站嵌入全流程的确定性拦截Hooks是Harness的核心其通过三个生命周期检查站将控制逻辑嵌入到Claude Code的关键执行节点实现对用户输入、工具调用、工具执行结果的全链路管控也是「代码级强制约束」的核心体现。三大检查站的执行节点与作用检查站执行时间核心作用工程化实操示例UserPromptSubmit用户按下回车输入还未发给模型时预处理用户输入注入上下文如搜索相关代码过滤无效输入用户要求修复auth.py提前搜索auth.py的相关代码拼接到prompt中PreToolUse模型决定调用某个工具/命令还未执行时检查工具/命令的安全性、合规性拦截违规操作拦截以cat/rm -rf开头的Bash命令返回「请用Read工具代替」PostToolUse工具执行完成结果还未返回给模型时处理执行结果如压缩长结果、过滤敏感信息、记录审计日志Bash执行结果有1000行自动压缩为核心关键信息再返回给模型核心实现思路在settings.json中为每个Hook配置自定义脚本harness.py加载配置并在对应节点执行脚本脚本采用退出码机制实现拦截/放行与LLM的概率性完全解耦保证100%的执行确定性。3. Harness与其他层的协同软硬结合层层约束Harness并非孤立存在其与CLAUDE.md、Skills、Tools形成协同体系实现「软约束引导硬约束兜底」的分层控制这也是Claude Code架构设计的智慧所在CLAUDE.md立法告诉LLM「你应该这样做」是prompt级的强建议让LLM理解规则意图主动配合Harness执法告诉LLM「你必须这样做」是代码级的强制约束兜底防绕过保证规则100%执行Skills知识告诉LLM「该怎么做好」是prompt模板的知识注入让LLM按规范使用工具Tools操作为LLM提供可调用的操作集Harness对操作集做权限与拦截控制。CLAUDE.md与Harness的核心差异对比维度CLAUDE.mdHarness Hook控制逻辑你应该这样做你必须这样做控制力建议prompt级强制代码级可绕过性是模型可能忘记/忽略否退出码硬拦截100%生效工程化定位立法执法四Claude Code一次请求的完整执行流程以「修复auth.py的登录bug」为例结合核心文件与Harness的控制逻辑梳理Claude Code一次请求的全链路执行流程清晰看到Harness在其中的三次核心介入用户输入修复auth.py的登录bugSkills层无特定命令跳过CLAUDE.md层注入system prompt「调试用假设驱动二分法」Harness层-UserPromptSubmit搜索auth.py相关代码注入上下文Claude Code层拼装messages调用claude_api_client.py请求API循环模型继续推理重复「调用工具-Harness检查-执行工具」Harness层-PreToolUse检查命令安全性放行Tools层执行Bash命令返回搜索结果Harness层-PostToolUse压缩长结果过滤冗余模型推理完成输出bug修复方案与总结返回给用户核心结论Claude Code的每一次操作都绕不开Harness的控制Harness是整个应用的「守门人」也是实现确定性控制的关键。五Harness工程化落地的关键实现要点作为架构师在实现Harness时需兼顾安全性、效率、成本、可维护性以下为四大核心工程化实现要点双层保险原则核心规则如禁止rm -rf必须同时配置在CLAUDE.md和Harness Hook中软约束引导硬约束兜底保证100%合规Hook脚本性能优化Hook脚本理想执行时间50ms超过200ms用户会感知到卡顿需避免在Hook中执行耗时操作如大文件搜索模型路由成本优化在Harness层实现模型路由策略简单任务如代码搜索、文件读取调用小模型Haiku复杂推理如bug修复、重构调用大模型Opus可实现数量级的成本降低声明式配置优于命令式硬编码将Harness的规则配置在settings.json/YAML等声明式配置文件中与harness.py的核心逻辑解耦支持热更新无需重启服务即可修改规则。四、总结与进展一架构核心总结Claude Code的架构设计本质是为概率性的LLM搭建一套工程化的确定性控制体系其核心亮点可总结为三句话分层解耦层层赋能七层架构从底层模型到顶层技能每一层都有明确的职责底层提供能力中层实现扩展顶层完成控制解耦性强可维护性高软硬结合刚柔并济以CLAUDE.md、Skills为软约束实现意图引导以Harness为硬约束实现代码级强制在灵活性与可控性之间找到最优平衡控制核心落地关键Harness不是一个简单的功能模块而是Claude Code的控制灵魂其四大机制三大Hook实现了对LLM的全链路确定性控制也是AI Code工具从「实验室」走向「生产环境」的关键。Claude Code核心组件的定位与本质可通过一张表清晰理解组件本质控制力架构类比Claude Model概率推理引擎无大脑Claude APIHTTP通信接口无神经Claude CodeAgent循环应用执行层身体Tools可调用的操作集被动手脚Harness控制面Hooks权限会话强制方向盘安全带CLAUDE.md写入prompt的规则集强建议宪法Skillsprompt模板集建议技能手册二当前进展与未来方向目前Claude Code的Harness层已实现基础控制能力Hooks、权限、上下文、会话管理并在企业环境中落地了工程化增强特性声明式配置、模型路由、成本预算、审计日志成为AI Agent大规模使用的基础设施。从架构师的视角Claude Code及Harness的未来发展方向围绕**「更精准的控制、更低的成本、更灵活的扩展」**展开Harness策略引擎化将Harness从「控制机制集」升级为「策略引擎」支持可视化配置规则、动态调整控制策略降低开发者的使用门槛多模型协同的智能路由在Harness层实现更智能的模型路由结合任务复杂度、token消耗、执行效率做动态决策实现成本与效果的最优平衡Hook生态化开放Harness的Hook接口支持开发者自定义开发Hook脚本形成生态化的控制规则库适配不同行业、不同项目的个性化需求端到端的审计与溯源在Harness层强化审计日志能力实现对所有操作的端到端溯源支持违规操作的回溯与分析满足企业级的合规要求。三给开发者的实践建议根据不同的使用阶段为Claude Code开发者提供针对性的Harness与架构实践建议实现从「基础使用」到「极致定制」的进阶入门阶段先写好CLAUDE.md这是投入产出比最高的一步无需懂代码只需将项目规范、编码习惯、禁止事项写清楚实现基础的软约束进阶阶段学习settings.json的Hooks配置从简单的PreToolUse Hook开始如拦截高危Bash命令体会「5行脚本胜过50行prompt规则」的确定性控制企业阶段在Harness层建设策略引擎实现声明式配置、模型路由、成本预算、审计日志的一体化将Harness打造成AI Agent大规模落地的核心基础设施。后记AI工程化的核心从来不是让模型变得更强而是让对模型的控制变得更精准。Claude Code的架构设计尤其是Harness层的确定性控制体系为LLM的工程化落地提供了一个优秀的参考范式。在LLM时代开发者不仅要学会使用AI工具更要理解其底层架构掌握「用代码约束模型」的能力。而Harness作为Claude Code的隐藏Boss正是我们解锁AI Code工具极致能力的关键钥匙。