深入解析 Claude Code 架构：Harness Engineering 构建 AI 编程代理
- 什么是 Harness Engineering？
- 阶段 1：核心代理循环
- 阶段 2：知识与上下文管理
- 阶段 3：异步执行与多代理团队
- 阶段 4：生产环境加固
- 阶段 5：高性能异步运行时
- 阶段 6：企业级升级
- 如何进一步改进这套架构
- 总结
2026 年初，Claude Code 在发布后仅六个月内就突破了 10 亿美元的年化收入。它成功的原因不是提示词写得更好，而是 Anthropic 构建了正确的”装备层”（Harness）：一个流式代理循环、权限管控的工具调度系统、以及能让模型在任意长会话中保持专注的上下文管理层。本文将深入解析 Claude Code 的完整架构。
什么是 Harness Engineering？
Harness Engineering（装备工程）是指围绕 LLM 构建的结构化运行时环境，用于约束、引导和增强模型的能力。与单纯的提示工程不同，Harness 在模型外部构建了一套完整的工具链和治理系统。Claude Code 的核心装备由六个阶段组成，从基础代理循环到企业级集群升级。
阶段 1：核心代理循环
最小 While 循环
Claude Code 的引擎是一个简单的 while 循环：感知 → 推理 → 执行 → 反馈。
from anthropic import Anthropic
ANTHROPIC_API_KEY = "sk-ant-xxx"
MODEL_ID = "claude-sonnet-4-6"
client = Anthropic(base_url="https://api.anthropic.com", api_key=ANTHROPIC_API_KEY)
MODEL = MODEL_ID
DEFAULT_SYSTEM = f"You are a coding agent at {os.getcwd()}. Use tools to solve tasks."
工具调度映射模式
每个工具都有严格的输入 schema，约束模型的表达能力：
BASIC_TOOLS = [
{
"name": "bash",
"description": "Run a shell command.",
"input_schema": {
"type": "object",
"properties": {"command": {"type": "string"}},
"required": ["command"],
},
},
]
BASIC_DISPATCH = {
"bash": lambda inp: run_bash(inp["command"]),
}
调度函数负责路由和执行：
def dispatch_tools(response_content, dispatch):
results = []
for block in response_content:
if block.type != "tool_use":
continue
tool_name = block.name
tool_input = block.input
tool_use_id = block.id
handler = dispatch.get(tool_name)
if handler:
output = handler(tool_input)
else:
output = f"Error: Unknown tool '{tool_name}'"
results.append({
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": str(output),
})
return results
TodoWrite：执行前规划
在执行复杂任务前，Claude Code 使用 TodoWrite 工具生成结构化计划：
{
"name": "TodoWrite",
"description": "Create a checklist of subtasks.",
"input_schema": {
"type": "object",
"properties": {
"todos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {"type": "string"},
"status": {"type": "string", "enum": ["pending", "completed"]},
"id": {"type": "string"},
},
},
}
},
"required": ["todos"],
},
}
子代理上下文隔离
当任务足够复杂时，主代理会生成子代理。每个子代理拥有独立的对话上下文、工作目录和工具集，互不干扰。
阶段 2：知识与上下文管理
按需技能加载
CLAUDE.md 文件按需注入到系统提示中。Claude Code 不会一次性加载所有内容，而是在需要时获取相关部分，大幅减少上下文窗口占用。
三层上下文压缩
- 层级一：Token 预算监控 — 持续追踪当前会话的 Token 消耗
- 层级二：自动摘要 — 当 Token 接近上限时，自动压缩旧消息为摘要
- 层级三：磁盘持久化 — 将压缩后的历史写入磁盘，确保跨会话恢复
文件依赖图
Claude Code 构建文件级别的任务依赖图，追踪文件之间的导入关系和变更影响，避免重复劳动和不必要的扫描。
阶段 3：异步执行与多代理团队
后台任务与通知
代理可以在后台执行长时间运行的任务，同时继续处理其他工作：
from concurrent.futures import ThreadPoolExecutor, as_completed
with ThreadPoolExecutor(max_workers=4) as executor:
futures = {executor.submit(process_file, f): f for f in files}
for future in as_completed(futures):
result = future.result()
print(f"Completed: {result}")
JSONL 邮箱持久通信
子代理之间通过 JSONL（JSON Lines）邮箱文件进行异步通信。每个代理拥有自己的收件箱文件，其他代理可以写入消息，目标代理在下次循环中读取处理。
FSM 团队通信协议
代理团队使用有限状态机（FSM）协议进行协调：
IDLE → TASK_ASSIGNED → WORKING → REVIEW → MERGE → COMPLETE
每个状态定义了代理可以执行的操作集合，以及状态转换的条件。
Git Worktree 任务隔离
每个任务在独立的 Git Worktree 中工作，确保分支隔离、避免冲突，并允许代码审查在合并前进行。
阶段 4：生产环境加固
实时 Token 流式输出
将 API 流式响应实时呈现给用户，避免等待整个响应完成，提升用户体验。
扩展工具集与文件快照
除了基本的 bash、读写文件外，还支持：
FileSurf— 快速浏览文件结构Glob— 模式匹配文件搜索Grep— 内容搜索- 文件快照 — 在每次工具调用前后自动保存文件状态，支持回滚
YAML 权限治理
Claude Code 使用三层权限评估：
| 级别 | 行为 | 说明 |
|---|---|---|
| 🔴 始终拒绝 | rm -rf /、生产数据库写入 | 静默拦截，无需用户干预 |
| 🟢 始终允许 | 读取文件、运行测试 | 自动放行 |
| 🟡 用户审查 | git push、包发布、文件删除 | 弹窗请求确认 |
事件总线与生命周期钩子
每步操作都触发事件，外部系统可以通过钩子监听并介入：
tool:before → 权限检查 → tool:execute → tool:after → log
阶段 5：高性能异步运行时
并行工具执行
使用 asyncio.gather 并行执行多个独立工具调用，如同时读取多个文件。
实时中断注入
用户随时可以中断正在执行的操作，插入新的指令或修正方向，代理会优雅处理中断。
提示缓存与 KV 缓存优化
系统提示、工具描述、常用代码片段被缓存，减少 API 调用成本。Claude Code 还会复用跨会话的 KV 缓存，加快推理速度。
MCP 运行时集成
原生支持 MCP（Model Context Protocol），允许通过外部 MCP 服务器动态扩展工具集，无需修改核心代码。
阶段 6：企业级升级
Redis Pub/Sub 生产级邮箱
将 JSONL 文件邮箱升级为 Redis Pub/Sub 通道，支持持久化、发布订阅和水平扩展。
高级 Worktree 生命周期管理
完整的 Worktree 生命周期：创建 → 同步 → 开发 → 审查 → 合并 → 清理，支持 CI/CD 流水线集成。
如何进一步改进这套架构
Fareed Khan 在文章末尾提出了几个改进方向：
- 强化学习微调 — 用 RLHF 优化工具调用选择策略
- 动态上下文窗口 — 根据任务复杂度自适应调整 Token 预算
- 分布式子代理 — 将子代理分布到不同机器上执行
- 用户行为学习 — 从用户反馈中学习偏好，自动调整权限和策略
总结
Claude Code 的成功不是靠更好的提示词，而是靠一套精心设计的 Harness 工程架构。从最基础的 while 循环开始，逐步构建出工具调度、上下文管理、多代理协作、权限治理和企业级扩展的完整体系。
这套架构完全可复现。理解它不仅能帮你更好地使用 Claude Code，更能为构建自己的 AI 编程代理提供清晰的路线图。
参考： 原文 Building Claude Code with Harness Engineering by Fareed Khan in Level Up Coding GitHub 仓库： FareedKhan-dev/claude-code-from-scratch