Back to Blog

Claude Code Harness Chapter 1: AI Coding Agent 的完整技术架构

2026-04-04
AI Claude Code Agent Architecture Harness Engineering

Claude Code Harness Chapter 1: AI Coding Agent 的完整技术架构

引言：当语言模型获得双手

想象一下，如果你有一个编程伙伴，它能阅读你的整个代码库、编写代码、运行测试、调试问题，甚至部署应用——所有这些都通过自然语言对话完成。这不是科幻小说，这是 Claude Code 每天都在做的事情。

但问题来了：它是如何做到的？

一个 Language Model 本质上只是文本预测引擎。给它一个 prompt，它预测接下来应该说什么。但如果没有工具，它无法行动——它只能建议人类去执行某些操作。

Claude Code 的真正威力不在于使用了多么强大的模型，而在于它构建了一个精密的系统架构，让 AI 能够：

  • 📖 理解整个代码库
  • ✏️ 编写和修改代码
  • 🔧 运行命令和测试
  • 🐛 调试复杂问题
  • 🚀 部署应用程序
  • 🛡️ 安全地执行所有操作

本章将深入剖析 Claude Code 的完整技术栈，揭示如何通过精心设计的多层架构，将一个语言模型转化为真正的软件工程 Agent。

大图景：六层架构的系统设计

Claude Code 远不止"一个模型加上 API 调用"。它是一个复杂的系统工程，包含多个专门化的层次，每层都有明确的职责：

graph TB
    subgraph "User Interface Layer"
        A[CLI Terminal]
        B[Web Interface]
    end

    subgraph "Orchestration Layer"
        C[Query Engine]
        D[Agent Loop Controller]
        E[Tool Executor]
    end

    subgraph "Intelligence Layer"
        F[Claude API]
        G[System Prompts]
        H[Prompt Templates]
    end

    subgraph "Capability Layer"
        I[40+ Tools]
        J[Permission System]
        K[Context Manager]
        L[Skills System]
    end

    subgraph "Security & Governance Layer"
        M[YOLO Classifier]
        N[Hooks System]
        O[CLAUDE.md Override]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    E --> I
    D --> F
    F --> G
    G --> H
    E --> J
    E --> K
    D --> L
    J --> M
    J --> N
    J --> O

图：Claude Code 的六层架构展示

这种分层架构确保了关注点分离（Separation of Concerns），同时使各组件能够以复杂的方式交互。每一层都有特定职责，共同创造了一个比各部分总和更强大的系统。

各层职责对比

层次 核心职责 关键组件 价值
用户界面层 用户交互 CLI, Web UI 提供直观的对话界面
编排层 决策和协调 Query Engine, Agent Loop 管理复杂的任务流程
智能层 AI 推理 Claude API, Prompts 提供语言理解和推理能力
能力层 实际操作 Tools, Context, Skills 执行具体的技术任务
安全治理层 风险控制 Permissions, YOLO, Hooks 确保操作的安全可控

第 1 层：基础设施 - Language Models 和 API

Claude API 集成

在基础层，Claude Code 使用 Anthropic 的 Claude API 作为智能引擎。但这不是静态的选择——系统支持多种模型配置：

模型 使用场景 Context 窗口 速度
Claude Opus 4.5 最复杂的推理任务 200K tokens 较慢
Claude Sonnet 4.5 平衡性能（默认） 200K tokens 中等
Claude Haiku 快速、常规任务 200K tokens 最快

这种灵活性允许系统根据任务复杂度、用户偏好和性能要求动态选择最合适的模型。

API 通信模式

Claude Code 实现了复杂的 API 通信模式，支持实时流式响应和工具调用：

sequenceDiagram
    participant User
    participant QueryEngine
    participant ClaudeAPI
    participant Tools

    User->>QueryEngine: Send message
    QueryEngine->>ClaudeAPI: Prepare request (with context)
    ClaudeAPI-->>QueryEngine: Streaming response

    loop Tool use detected
        QueryEngine->>Tools: Execute tool
        Tools-->>QueryEngine: Return result
        QueryEngine->>ClaudeAPI: Continue conversation (with tool result)
    end

    ClaudeAPI-->>User: Stream final response

图：Claude API 的流式通信模式

这种流式方法实现了实时反馈，同时保持了在对话展开时中断和引导的能力。

第 2 层：编排系统 - Query Engine 和 Agent Loop

Query Engine：中央协调者

Query Engine（QueryEngine.ts）是中央协调者——就像管弦乐队的指挥。它管理：

  • 请求生命周期：从用户输入到最终响应
  • Context 收集：收集相关代码、文件和系统状态
  • 工具编排：决定使用哪些工具以及何时使用
  • 错误恢复：优雅地处理失败
  • 流式响应：管理实时输出给用户
flowchart LR
    A[User Input] --> B[Query Engine]
    B --> C[Collect Context]
    C --> D[Build Request]
    D --> E[Call Claude API]
    E --> F{Need tools?}
    F -->|Yes| G[Execute Tool]
    F -->|No| H[Generate Response]
    G --> I[Process Result]
    I --> E
    H --> J[Stream Output]
    J --> K{User interrupt?}
    K -->|Yes| L[Stop and wait]
    K -->|No| M[Complete]

图：Query Engine 的工作流程

Agent Loop 决策流程

Agent Loop 实现了核心决策循环：

flowchart TD
    A[Receive user input] --> B{Analyze request}
    B --> C[Plan actions]
    C --> D{Need tools?}
    D -->|Yes| E[Select tool]
    E --> F[Execute tool]
    F --> G[Process result]
    G --> H{More work needed?}
    D -->|No| I[Generate response]
    H -->|Yes| B
    H -->|No| I
    I --> J[Stream to user]
    J --> K{User interrupt?}
    K -->|Yes| L[Stop and wait]
    K -->|No| M[Complete]
    L --> N{Continue?}
    N -->|Yes| B
    N -->|No| M

图：Agent Loop 的决策流程

这个循环持续到任务完成、用户干预或出现错误。每次迭代可能涉及多个工具执行、context 更新和基于新信息的重新规划。

第 3 层：能力层 - 工具系统

Claude Code 的真正力量来自于其广泛的工具库。这些工具是让 Language Model 能够与世界交互的"双手"：

mindmap
    root((Claude Code Tools))
        File System
            FileRead
            FileWrite
            FileEdit
            Glob
            Grep
        Development
            Bash
            PowerShell
            REPL
            LSP
        AI & Agent
            Agent
            Skill
            MCP
        Collaboration
            TaskCreate
            SendMessage
            TeamCreate
        Web Tools
            WebFetch
            WebSearch
        System
            Config
            ScheduleCron
            Sleep

图：Claude Code 的工具分类

每个工具都经过精心设计，具有：

  • 明确的目的：单一职责，范围清晰
  • 类型安全：完整的输入输出 TypeScript schemas
  • 错误处理：优雅的失败和信息丰富的消息
  • 文档化：通过 schemas 和示例自我描述

工具执行架构

工具不是单独调用的——它们通过复杂的执行系统进行编排：

特性 描述 优势
并发执行 多个工具可以同时运行 更快的完成速度
依赖跟踪 工具可以依赖其他工具的输出 正确的执行顺序
状态跟踪 每个工具的实时状态 更好的用户反馈
中止控制器 每个工具有独立的取消功能 细粒度控制
结果缓冲 结果被收集和排序 一致的输出

Skills 系统：用户定义的能力

除了内置工具，Claude Code 还支持 Skills——用户定义的、参数化的 prompt 模板，可以扩展功能：

flowchart LR
    A[User Skill] --> B[Skill Definition]
    B --> C[Parameter Extraction]
    C --> D[Prompt Template]
    D --> E[Extended Instructions]
    E --> F[Execute as Agent]

    style A fill:#e1f5ff
    style F fill:#e1f5ff

图：Skills 系统的执行流程

这允许用户创建可重用的工作流、自定义行为和专门的功能，而无需修改核心系统。

第 4 层：Context 管理 - 200K Token 的竞技场

理解 Context 窗口

现代 Language Model 支持大的 context 窗口（Claude 为 200K tokens），但有效管理这个容量至关重要：

graph TD
    A[Token Budget: 200K] --> B[System Prompt]
    A --> C[User Messages]
    A --> D[Conversation History]
    A --> E[File Context]
    A --> F[Tool Results]
    A --> G[Reserved Buffer]

    style A fill:#f9f,stroke:#333,stroke-width:4px
    style G fill:#f66,stroke:#333,stroke-width:2px

图：Context 窗口的 token 分配

自动压缩策略

当 Context 接近限制时，Claude Code 实现自动压缩：

策略 使用时机 作用
微压缩 接近 token 限制 移除冗余的工具结果
历史摘要 Context 超过阈值 摘要旧的对话轮次
文件剪枝 打开太多文件 关闭最近最少使用的文件
智能缓冲 大输出 截断非必要输出

这些策略透明地发生，在保持限制内维护对话的连续性。

第 5 层：安全与权限 - 多层防护体系

安全是当 AI Agent 可以修改文件和运行命令时的首要任务。Claude Code 实现纵深防御：

flowchart TD
    A[User Command] --> B{YOLO Classifier}
    B -->|Safe| C{Permission Mode}
    B -->|Risky| D[Require Confirmation]
    C -->|auto| E[Execute]
    C -->|ask| F[Prompt User]
    C -->|deny| G[Block]

    F -->|Allow| E
    F -->|Deny| G

    E --> H{Has Hooks?}
    H -->|Yes| I[Run Pre-Execution Hooks]
    H -->|No| J[Execute Tool]
    I --> J
    J --> K{Has Hooks?}
    K -->|Yes| L[Run Post-Execution Hooks]
    K -->|No| M[Return Result]
    L --> M

图：安全与权限系统的多层防护

权限模式对比

模式 行为 使用场景
default 询问权限 正常操作
auto 自动批准安全操作 可信环境
ask 总是确认 高安全场景
deny 阻止一切 测试/验证
bypass 无权限检查 YOLO 模式（小心使用！）

YOLO Classifier

YOLO（You Only Live Once）Classifier 使用 AI 评估风险：

  • 基于模式训练：从安全 vs 有风险的操作中学习
  • Context 感知：考虑仓库、文件类型和操作
  • 用户可调：根据风险容忍度调整敏感度
  • 持续学习：从用户反馈中改进

这种智能过滤减少了不必要的提示，同时防止危险操作。

Hooks：用户定义的拦截点

Hooks 允许在关键执行点运行自定义代码：

flowchart LR
    A[Pre-Hook] --> B[Tool Execution]
    B --> C[Post-Hook]

    A --> A1[Custom Validation]
    A --> A2[Modify Input]
    A --> A3[Logging/Tracing]

    C --> C1[Validate Output]
    C --> C2[Trigger Action]
    C --> C3[Update State]

    style A fill:#e1f5ff
    style C fill:#e1f5ff

图：Hooks 系统的执行点

这实现了自定义工作流、合规性检查和与外部系统的集成。

第 6 层：Prompt 工程 - 控制平面

System Prompt 架构

System Prompts 是塑造 AI 行为的"控制平面"。Claude Code 使用复杂的优先级层级：

graph TD
    A[Override System Prompt
CLAUDE.md] -->|Highest Priority| B[Final System Prompt]
    C[Coordinator Prompt
Multi-Agent Mode] --> B
    D[Agent System Prompt
Custom Agent] --> B
    E[Custom System Prompt
--system-prompt flag] --> B
    F[Default System Prompt
Standard Claude Code] --> B
    G[Append System Prompt
Always Add] -->|Lowest Priority| B

    style A fill:#f66,stroke:#333,stroke-width:3px
    style G fill:#6f6,stroke:#333,stroke-width:1px

图：System Prompt 的优先级层级

这种层级允许用户指令（CLAUDE.md）覆盖默认行为，同时保持合理的默认值。

模型特定的调优

不同模型需要不同的提示策略：

方面 Opus Sonnet Haiku
详细程度 最大 平衡 最小
推理步骤 显式 隐式 跳过
示例使用 广泛 适中 罕见
语气 正式 对话式 简洁

Claude Code 根据选择的模型自动调整 prompts，优化每个模型的优势。

完整技术栈总览

将所有内容整合在一起，这是完整的技术栈：

graph TB
    subgraph "Infrastructure"
        I1[Node.js Runtime]
        I2[TypeScript]
        I3[React/Ink UI]
    end

    subgraph "Core Services"
        C1[Query Engine]
        C2[Tool Executor]
        C3[Context Manager]
        C4[Permission System]
        C5[Prompt Builder]
    end

    subgraph "AI Integration"
        A1[Claude API Client]
        A2[Streaming Handler]
        A3[Model Selector]
    end

    subgraph "Tools & Skills"
        T1[40+ Built-in Tools]
        T2[Skills Engine]
        T3[MCP Integration]
    end

    subgraph "Security"
        S1[YOLO Classifier]
        S2[Permission Modes]
        S3[Hooks System]
        S4[CLAUDE.md Override]
    end

    subgraph "Data & State"
        D1[Git Context]
        D2[File System Cache]
        D3[Conversation Memory]
        D4[Settings Storage]
    end

    I1 --> C1
    I2 --> C1
    I3 --> C1

    C1 --> A1
    C2 --> T1
    C3 --> D1
    C4 --> S1
    C5 --> A2

    A1 --> A3
    A2 --> C1

    T1 --> C2
    T2 --> C1
    T3 --> C2

    S1 --> C4
    S2 --> C4
    S3 --> C4
    S4 --> C5

    D1 --> C3
    D2 --> C3
    D3 --> C1
    D4 --> C1

图：Claude Code 的完整技术栈

关键设计原则

几个架构原则使这个系统工作：

1. 模块化

每个组件都有单一、明确定义的职责。这使系统更易于理解、测试和扩展。

2. 类型安全

全面的 TypeScript 覆盖防止了整类 bug，并使重构更安全。

3. 可观察性

每个操作都被日志记录和跟踪，启用调试和优化。

4. 用户控制

用户控制权限，可以覆盖行为（CLAUDE.md），并扩展功能（Skills）。

5. 优雅降级

当事情失败时，系统优雅地降级而不是崩溃。

6. 性能优化

缓存、流式加载和延迟加载保持系统响应。

这个架构实现了什么

这种复杂的架构使 Claude Code 能够：

能力 实现方式
理解大型代码库 Context 管理 + 文件读取工具
编写和修改代码 文件编辑工具 + 权限系统
运行命令和测试 Bash 工具 + 权限 hooks
调试失败 错误解析 + 迭代推理
部署应用 部署工具 + 确认流程
学习用户偏好 CLAUDE.md + 内存系统
安全工作 多层权限系统
扩展功能 Skills + MCP 集成

结论

Claude Code 远远不止是一个带有 API 访问权限的语言模型。它是一个精心架构的系统，结合了：

  • 多个语言模型用于不同用例
  • 复杂的编排用于管理工作流程
  • 40+ 专门工具用于与开发环境交互
  • 高级 Context 管理用于理解大型代码库
  • 多层安全系统用于保护用户项目
  • 可扩展架构用于添加新功能

理解这个架构对于有效使用 Claude Code 和构建类似的 AI 驱动开发工具都至关重要。这展示了 Harness Engineering 的核心原则：设计 AI 智能与实际能力无缝协作的系统。

在下一章中，我们将深入探讨工具系统——让 AI Agents 能够操控现实世界的双手。

关键要点

  1. 分层架构：Claude Code 使用多个专门化层次，每个层次都有明确的职责
  2. 编排是关键：Query Engine 和 Agent Loop 协调所有其他组件
  3. 工具扩展能力：40+ 工具提供了与代码交互的实际能力
  4. 安全是基础：多层重叠系统确保安全操作
  5. Context 管理至关重要：复杂的策略管理 200K token context 窗口
  6. 可扩展性很重要：Skills 和 MCP 允许在不改变核心的情况下添加自定义能力

延伸阅读

  • 第 2 章：深入探讨工具系统及其设计
  • 第 3 章：Agent Loop 以及如何做出决策
  • 第 4 章：工具执行编排、并发和中断
  • Claude Code 仓库：github.com/anthropics/claude-code
Enjoyed this article? Share it with others!