LLM Wiki

Claude Code 源码解析主题

9分钟阅读

Claude Code 源码解析主题

主题定义

Claude Code 源码解析涵盖 2026 年上半年社区对 Anthropic 官方 AI 编程助手 Claude Code 的源码级深度分析。这些文章从不同角度拆解了 Claude Code 的 TypeScript 实现，揭示了其作为 Harness Engineering 集大成者的工程设计哲学——从 System Prompt 动态组装、CLAUDE.md 四级注入、三层渐进式上下文压缩，到 Hooks 机制、工具调度系统和多 Agent 扩展层，构成了一个完整的 AI Coding Agent 工程体系。

核心要点

  1. 三层架构分离关注点：Claude Code 的核心架构从内到外分为 Prompt 层（解决”如何让模型理解角色”）、Context 层（解决”如何在有限窗口内保留关键信息”）、Harness 层（解决”如何让 Agent 在生产环境中稳定运行”）。这三层分别对应 Prompt Engineering、Context Engineering 和 Harness Engineering 三次范式进化，仅靠 Prompt Engineering 只能达到约 70 分，Context Engineering 提升到 80-85 分，Harness Engineering 将其带到 90-95 分

  2. System Prompt 动态组装而非静态文本：System Prompt 由 QueryEngine.ts 的 ask() 函数入口触发，通过 fetchSystemPromptParts() 并行获取 defaultSystemPrompt、systemContext（Git 状态信息）、userContext（CLAUDE.md 内容 + 当前日期），再按优先级决策（overrideSystemPrompt > Coordinator > Agent > customSystemPrompt > defaultSystemPrompt）组装最终 Prompt，最后通过 splitSysPromptPrefix() 拆分为适合 KV Cache 前缀的分块

  3. CLAUDE.md 四级注入成为行业标准：个人通用偏好（~/.claude/CLAUDE.md）、项目共享规范（项目根目录/CLAUDE.md）、个人私有指令（项目根目录/CLAUDE.local.md）、文件类型特定规则（.claude/rules/*.md）四级文件注入机制，后来被 OpenClaw、Cursor 等竞品广泛借鉴，成为 AI Coding Agent 领域的事实标准

  4. 三层渐进式上下文压缩体系解决长任务失忆：MicroCompact（规则驱动微压缩，不调用 LLM，仅压缩 Bash/Read/Grep/Glob 的大型输出）、Session Memory Compact（利用之前生成的会话记忆替换冗长原始历史，无额外 LLM 调用）、Full LLM Compact（通过 LLM 生成结构化 9 段摘要，隐式 CoT 优化，NO_TOOLS_PREAMBLE 禁止压缩期间调用工具），AutoCompact 触发机制设置 13,000 token 安全缓冲水位线

  5. Hooks 机制将确定性行为从 LLM 记忆迁移到工程流程：Hooks 在每次工具调用前后确定性地执行，用于注入规范、验证输出、触发自动化流程，不依赖模型判断。这是 Harness Engineering 的核心实践——把确定性的工作交给脚本和 lint，让 AI 只做理解和决策

  6. 长任务执行的六大核心机制：任务编排元数据文件化（将计划、进度、决策写入文件系统而非依赖脆弱的对话上下文）、TODO 驱动开发（将 TODO 直接插入代码文件）、接力赛式子代理调度（避免并行处理导致的文件冲突）、三步循环（生成任务 → 生成计划 → 实现代码，成功率从 50% 提升到 95%+）、消费约 9 亿 token 的长时连续操作能力、结构化 Memdir 记忆系统

  7. 四层工程模型有助于组件选型：记忆层提供项目事实，扩展层放 commands、Skills、Subagents、Hooks，集成层用 headless 与 MCP 接到外部系统，编程层由 SDK 构造工作流；需要确定性拦截的高风险工具操作必须放到 Hook，而不是寄望 Skill 或 prompt 自觉遵守。

  8. Skill 的“按需加载”可追到具体运行链路：标准目录是 <skill-name>/SKILL.md，多个来源合并后先以描述形成可发现索引，调用期才展开正文、参数和 supporting files；MCP 来源不运行内嵌 shell，说明扩展机制同时承担上下文管理与安全隔离。

  9. 51.2 万行源码揭示的工程规模：Claude Code 泄露的约 51.2 万行 TypeScript 代码展现了其作为工业级 AI 编程系统的完整度——从 QueryEngine.ts 主入口到 services/compact/ 三层压缩、services/tools/ 工具注册与执行、constants/prompts.ts System Prompt 构建、utils/systemPrompt.ts 优先级决策、context.ts Git 状态 + CLAUDE.md 加载、memdir/ 结构化记忆系统，每一个模块都经过精心设计

  10. Claude Code 的优势也可能来自训练与产品飞轮：除了源码中的 Harness，Claude 代码能力还可以从训练侧理解：代码任务有可验证奖励，Constitutional AI 给安全和可读性加辅助约束，Claude 产品端的复制、修改、追问、重生成等行为形成高质量偏好反馈。这个视角不能替代源码分析，但能解释为什么工具外壳与模型能力会相互强化。

  11. Claude Code 生态正在形成外围工程层：oh-my-claudecode 把 Claude Code 会话扩展成 Team、skills、HUD、通知、tmux workers 和多模型 advisor 的工作流发行版；oh-my-pi 则从独立 coding agent 方向验证 LSP/DAP、Hashline、subagent、advisor、collab 和 filesystem-shaped internal schemes 的工具协议化路线。

涉及实体

  • Claude-Code —— 被深度解析的 AI 编程助手主体
  • Harness-Engineering —— Claude Code 是 Harness Engineering 理念最完整的工程实现
  • Anthropic —— Claude Code 的开发方，也提供 Constitutional AI、模型卡和产品反馈飞轮的训练侧线索
  • oh-my-claudecode —— Claude Code 外围编排与技能扩展层
  • oh-my-pi —— 与 Claude Code 同类的开放式终端 AI Coding Agent 对照样本

对比矩阵

维度Prompt 层Context 层Harness 层
解决问题如何让模型理解角色如何在有限窗口内保留关键信息如何让 Agent 稳定运行
典型产物System Prompt 动态组装三层渐进式压缩Hooks + CLAUDE.md + 权限管道
得分上限~70 分80-85 分90-95 分
工程复杂度低中高

关键来源

关系图谱

反向链接