深入理解 Claude Code：真正的 Agent Harness 工程

本文是对 learn-claude-code 项目的深度解读。这个开源项目通过逆向工程 Claude Code，教你如何为 AI Agent 构建高质量的 Harness。

核心观点：模型就是 Agent

在讨论代码之前，先把一件事彻底说清楚：Agent 是模型，不是框架，不是提示词链，不是拖拽式工作流。

Agent 是一个神经网络——Transformer、RNN、一个被训练出来的函数——经过数十亿次梯度更新，在行动序列数据上学会了感知环境、推理目标、采取行动。

历史已经写好了铁证

2013 年 — DeepMind DQN 玩 Atari，一个神经网络从零学会 49 款游戏

2019 年 — OpenAI Five 在 Dota 2 击败世界冠军 OG，胜率 99.4%

2019 年 — AlphaStar 在星际争霸 II 达到宗师段位

2019 年 — 腾讯绝悟在王者荣耀击败 KPL 职业选手

2024-2025 年 — Claude、GPT、Gemini 作为编程 Agent 重塑软件工程

每一个里程碑都共享同一个真理："Agent" 从来都不是外面那层代码，Agent 永远是模型本身。

Agent 不是什么

"Agent" 这个词已经被一整个提示词水管工产业劫持了。那些拖拽式工作流构建器、无代码 "AI Agent" 平台，做出来的东西是鲁布·戈德堡机械——一个过度工程化的、脆弱的过程式规则流水线。

提示词水管工式 "Agent" 是不做模型的程序员的意淫。 他们试图通过堆叠过程式逻辑来暴力模拟智能，但 Agency 是学出来的，不是编出来的。

心智转换：从 "开发 Agent" 到开发 Harness

当一个人说 "我在开发 Agent" 时，他只可能是两个意思之一：

1. 训练模型 — 通过强化学习、微调、RLHF 调整权重

2. 构建 Harness — 为模型提供一个可操作的环境

Harness 是 Agent 在特定领域工作所需要的一切：

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

    Tools:          文件读写、Shell、网络、数据库、浏览器
    Knowledge:      产品文档、领域资料、API 规范、风格指南
    Observation:    git diff、错误日志、浏览器状态、传感器数据
    Action:         CLI 命令、API 调用、UI 交互
    Permissions:    沙箱隔离、审批流程、信任边界

模型做决策，Harness 执行。模型做推理，Harness 提供上下文。模型是驾驶者，Harness 是载具。

为什么是 Claude Code

Claude Code 是我们所见过的最优雅、最完整的 Agent Harness 实现。它没有试图成为 Agent 本身，没有强加僵化的工作流，没有用精心设计的决策树去替模型做判断。

把 Claude Code 剥到本质来看：

Claude Code = 一个 agent loop
            + 工具 (bash, read, write, edit, glob, grep, browser...)
            + 按需 skill 加载
            + 上下文压缩
            + 子 agent 派生
            + 带依赖图的任务系统
            + 异步邮箱的团队协调
            + worktree 隔离的并行执行
            + 权限治理

这就是全部架构。每一个组件都是 Harness 机制。

核心模式：Agent Loop

def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant",
                         "content": response.content})

        if response.stop_reason != "tool_use":
            return

        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

这是最小循环。每个 AI Agent 都需要这个循环。模型决定何时调用工具、何时停止，代码只是执行模型的要求。

12 个递进式课程

learn-claude-code 项目通过 12 个课程，从简单循环到隔离化的自治执行，每个课程添加一个 Harness 机制：

课程	主题	格言

|------|------|------|

s01	Agent Loop	One loop & Bash is all you need
s02	Tool Use	加一个工具，只加一个 handler
s03	TodoWrite	没有计划的 agent 走哪算哪
s04	Subagent	大任务拆小，每个小任务干净的上下文
s05	Skills	用到什么知识，临时加载什么知识
s06	Context Compact	上下文总会满，要有办法腾地方
s07	Task System	大目标要拆成小任务，排好序，记在磁盘上
s08	Background Tasks	慢操作丢后台，agent 继续想下一步
s09	Agent Teams	任务太大一个人干不完，要能分给队友
s10	Team Protocols	队友之间要有统一的沟通规矩
s11	Autonomous Agents	队友自己看看板，有活就认领
s12	Worktree Isolation	各干各的目录，互不干扰

Harness 工程师到底在做什么

如果你在读这个项目，你很可能是一名 Harness 工程师：

实现工具 — 给 Agent 一双手：文件读写、Shell 执行、API 调用

策划知识 — 给 Agent 领域专长：产品文档、架构决策记录、风格指南

管理上下文 — 给 Agent 干净的记忆：子 Agent 隔离、上下文压缩

控制权限 — 给 Agent 边界：沙箱化文件访问、审批流程

收集任务过程数据 — Agent 执行的每一条行动序列都是训练信号

你不是在编写智能，你是在构建智能栖居的世界。

愿景：用真正的 Agent 铺满宇宙

这不只关乎编程 Agent。每一个人类从事复杂、多步骤、需要判断力的工作的领域，都是 Agent 可以运作的领域——只要有对的 Harness：

庄园管理 agent  = 模型 + 物业传感器 + 维护工具 + 租户通信
农业 agent      = 模型 + 土壤/气象数据 + 灌溉控制 + 作物知识
酒店运营 agent  = 模型 + 预订系统 + 客户渠道 + 设施 API
医学研究 agent  = 模型 + 文献检索 + 实验仪器 + 协议文档

循环永远不变，工具在变，知识在变，权限在变。Agent——那个模型——泛化一切。

快速开始

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env   # 填入你的 ANTHROPIC_API_KEY

python agents/s01_agent_loop.py       # 从这里开始
python agents/s12_worktree_task_isolation.py  # 完整递进终点

总结

模型就是 Agent。代码是 Harness。造好 Harness，Agent 会完成剩下的。

Bash is all you need. Real agents are all the universe needs.

如果你对 AI Agent 开发感兴趣，推荐去 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) 仓库亲自体验这 12 个课程。这是目前最好的 Harness 工程学习资源之一。