从零读懂 Claude Code：73k stars 的 learn-claude-code 教我们的事

发表于 分类于 ，
当 AI Coding 工具满天飞的时候，有一个仓库愿意把 Claude Code 的设计哲学用 20 节渐进式课程拆给你看——Agency 来自模型，Harness 才是工程师该做的事。

你有没有想过这样的问题：为什么 Anthropic 的 Claude Code 看起来比很多” 自研 AI 编程助手” 更顺手？为什么它能用一个命令行就跑完” 读代码、改代码、跑测试、修 bug” 这一整条链路，而有些产品把 LLM 套上十几个 if-else 分支之后就号称” 自主 Agent”？

最近 GitHub 上一个名叫 learn-claude-code 的项目悄悄爬到了 73k stars，73k 这个数字背后不是又一个” 快速上手 Claude Code” 的脚手架，而是一份从零开始讲清楚 Claude Code 内部设计的 20 节渐进式教程。它把整个系统拆解成” 模型 + Harness” 两部分，并且用一句非常挑衅的 slogan 把观点钉死：

Agency comes from the model. An agent product = Model + Harness.

今天我们就顺着这个仓库读一遍，看看一个真正优雅的 Agent Harness 是怎么搭出来的。

一、项目背景：它到底要解决什么问题

learn-claude-code 是 shareAI-lab 维护的一个 MIT 协议开源仓库，最初诞生于 2025 年 6 月，至今保持着非常密集的迭代节奏。它的官方 Slogan 是 “Bash is all you need” —— 也就是说，作者希望你读完整个教程之后相信一件事：只要给模型一个 Bash 工具，再加上一个循环，就已经有了一个 Agent 的雏形。

1.1 它不是另一个 “Agent 框架”

仓库的 README 一上来就先” 开炮”：

“The word ‘agent’ has been hijacked by an entire prompt-plumbing industry.”

拖拽式 workflow 构建器、零代码”AI Agent” 平台、prompt chain 编排库 —— 它们共享一个错觉：把 LLM API 调用串上 if-else、节点图和硬编码路由，就构成了” 构建一个 Agent”。

作者认为这些东西造出来的不是 Agent，而是 Rube Goldberg machines（鲁布・哥德堡机器）—— 一台台过度工程化、脆弱的、用 LLM 当文本补全节点的程序。它们不是 Agent，是” 伪装成 Agent 的 shell 脚本”。

1.2 一个澄清：什么是 “agency”

作者给了一个非常清晰的定义：

  • Agency = 感知 + 推理 + 行动 的能力。
  • 这种能力来自模型训练，不是来自外围代码。
  • DeepMind DQN 用一个神经网络打穿 7 款 Atari 游戏（2013），OpenAI Five 打了 45000 年的 Dota 2 之后击败 TI8 冠军 OG（2019），AlphaStar 在不完整信息的即时战略游戏里打到 Grandmaster—— 所有这些里程碑都指向同一个事实：Agency 是被训练出来的，不是被编码出来的。

所以如果我们这些普通工程师说” 我在构建一个 Agent”，我们实际能做的只有两件事中的一件：

  1. 训练模型：通过 RL、Fine-tune、RLHF 等梯度方法调整权重，DeepMind / OpenAI / Anthropic 在做的就是这个；
  2. 构建 Harness：写出代码给模型一个可操作的环境 —— 这是我们绝大多数人能做的事，也是这个仓库的核心。

1.3 一句话定义 Harness

1
2
3
4
5
6
Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
    Tools:          file I/O, shell, network, database, browser
    Knowledge:      product docs, domain references, API specs, style guides
    Observation:    git diff, error logs, browser state, sensor data
    Action:         CLI commands, API calls, UI interactions
    Permissions:    sandbox isolation, approval workflows, trust boundaries

模型决策，Harness 执行；模型推理，Harness 提供上下文；模型是驾驶员，Harness 是车。 这是整个仓库最重要的一个心智模型（mindshift）—— 工程师的工作不是写智能，而是给智能搭一个能充分发挥作用的世界。

二、核心功能亮点

整个仓库分了 20 节渐进式课程，每一节只加一个 Harness 机制，每一节都有自己的 motto。下面挑几个最能体现设计哲学的讲。

2.1 s01 Agent Loop：一个循环 + Bash = 一个 Agent

整个仓库最核心的代码，是 s01 里这个 15 行的 agent_loop：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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})

15 行代码，就是一个 Agent 的全部。模型决定何时调用工具、何时停止；代码只是按模型的要求去执行。 后续所有 19 节课程 ——Tools、Permissions、Hooks、Subagent、Context Compact、MCP—— 都是围着这个循环在加机制，循环本身一个字都不用改。

2.2 s03 Permission：先划边界，再给自由

“Set boundaries first, then grant freedom.”

这一节教你怎么在 Harness 里做权限治理：哪些操作可以直接放行、哪些必须 stop、哪些需要人工审批。一个典型的 PermissionRule 模式由三部分组成：

  • allow：白名单，比如读文件、grep、git status；
  • deny：黑名单，比如 rm -rf、git push --force；
  • ask：需要弹窗审批的操作，比如 git push、npm publish。

作者反复强调：自由和信任都是按层级授予的，Harness 必须把” 什么能跑、什么必须停、什么需要审批” 在工具调用前讲清楚，模型才能在一个可信的世界里发挥。

2.3 s06 Subagent：大任务拆小，每个子任务拿到干净上下文

“Big tasks split small, each subtask gets clean context.”

当一个 Agent 要处理的事情开始变大，主线程的 messages 数组就会被各种子任务的中间结果、错误日志、retry 信息塞满，最后模型自己也开始抓不到重点。s06 的解法是：开一个全新的 messages[] 给子任务，子任务跑完只把结果摘要塞回主线程。

1
2
3
4
def run_subagent(task: str) -> str:
    sub_messages = [{"role": "user", "content": task}]
    agent_loop(sub_messages)  # 子任务跑完一轮全新的循环
    return sub_messages[-1]["content"]  # 只回传结果

这个模式的关键不是” 并发”，而是” 隔离上下文 “—— 主线程不必看见子任务的所有探索过程。

2.4 s08 Context Compact：上下文总会撑爆，得学会腾地方

“Context always fills up – have a way to make room.”

任何长任务的 Agent 都会撞上 context window 这一关。s08 给出了多层 compact 策略：

  • snipCompact：直接截掉最旧的若干条消息；
  • microCompact：在一次工具调用之后把冗余日志折叠成摘要；
  • toolResultBudget：限制每个工具结果的体积；
  • autoCompact：当剩余 token 低于阈值时自动触发。

用这种分层策略，可以做到” 无限长 session”。这是任何想跑长任务（重构大型项目、跨多文件迁移）的 Agent 都必须解决的问题。

2.5 s15 Agent Teams + s17 自组织：人多了怎么协作

“Too big for one agent – delegate to teammates.”
“Teammates check the board, claim work themselves.”

到了 s15，仓库开始讲多 Agent 协作。核心模式是：

  • 持久化 teammates：每个 teammate 有独立的 identity、独立的 context、独立的能力标签；
  • 异步 mailbox：teammate 之间通过 JSONL 邮件协议通信，消息可以延迟、可以批量处理；
  • s17 的关键创新：没有 leader，队友们自己盯 board、自己 claim 工作。

s18 进一步把每个 task 绑定到自己的 worktree（独立目录），保证多 Agent 不会把彼此的文件搞乱。这一套机制组合起来，已经覆盖了 Claude Code 在生产里 90% 的多 Agent 协作模式。

2.6 s19 MCP Plugin：能力不够，外部工具来凑

“Not enough capability? Plug in more via MCP.”

最后一节扩展性课程讲的是 MCP（Model Context Protocol）：Harness 通过统一的 transport（stdio / SSE /streamableHTTP）把外部工具挂载进同一个工具池，模型调用起来就像调用内置工具一样自然。MCP 不是 learn-claude-code 发明的，但这一节帮你看清：MCP 本质上就是一个工具协议 —— 它的目的是让 Harness 能把外部能力当自己的” 手” 用。

2.7 s20 Comprehensive：所有机制回到一个循环

最后 s20 把前面 19 节所有机制组装回最初那个 15 行的 agent_loop。循环从来没变，变的是它周围那一圈工具、知识、权限、上下文、协作机制。 这是整个仓库最震撼的一个 moment—— 你意识到 Claude Code 这种工业级 Agent 的复杂度，是附加在简单核心上的，不是淹没它的。

三、实战示例：15 行跑一个 Agent

下面这段代码完全可以拷贝到你本地跑（需要 ANTHROPIC_API_KEY）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import os, anthropic

client = anthropic.Anthropic()
MODEL  = "claude-sonnet-4-5"
SYSTEM = "You are a coding agent. Use bash to solve the task."

TOOLS = [{
    "name": "bash",
    "description": "Run a shell command. Returns stdout/stderr.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

def bash(cmd: str) -> str:
    import subprocess
    r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=30)
    return (r.stdout + r.stderr).strip()[:5000]

def agent_loop(messages):
    while True:
        r = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant", "content": r.content})
        if r.stop_reason != "tool_use":
            return
        results = []
        for b in r.content:
            if b.type == "tool_use":
                out = bash(**b.input)
                results.append({"type": "tool_result",
                                "tool_use_id": b.id, "content": out})
        messages.append({"role": "user", "content": results})

# 用法
agent_loop([{
    "role": "user",
    "content": "列出当前目录下所有 .py 文件，并打印每个文件的行数",
}])

跑起来之后你会看到一个完整的工作循环：模型思考 → 决定调用 bash → Harness 执行 → 把结果塞回 messages → 模型继续思考 → 直到 stop_reason != "tool_use"。这就是一个 Agent 的最小可工作版本。

接下来你可以照着 s02–s20 的目录，把 Permission、Subagent、Context Compact、Task System 一个个叠上去，每加一个机制就跑一下，感受 messages 数组和工具池的扩张。

四、适用场景与限制

4.1 适合谁读

  • 想真正搞懂 Claude Code / Cursor Agent 内部机制的工程师 —— 这个仓库比任何博客都接近” 工业级 Agent Harness 的真实形态”；
  • 自己要做 Coding Agent / DevTool 的团队 —— 可以把 learn-claude-code 当参考实现，再根据自己的场景裁剪；
  • AI 工程师面试准备 ——s05–s12 几乎覆盖了所有主流 Agent 框架（LangGraph、CrewAI、AutoGen）的设计词汇；
  • 想理解 “Harness Engineering” 这门新学科的人 —— 作者把这个仓库定位成”harness engineering 的入门教材”，这是 2025–2026 年 Agent 生态里一个被严重低估的概念。

4.2 不适合什么场景

  • 想要一个开箱即用的 Coding Agent—— 你应该去看它的姐妹项目 shareAI-lab/Kode-CLI，而不是这个教程；
  • 只想调 prompt 不想写代码 —— 这个仓库几乎全是 Python 实现，每节都要求你跑 code.py；
  • 想找”Agent 评测基准”—— 它讲实现，不讲 benchmark；
  • 场景不是 coding—— 虽然”s01–s20” 的代码都围绕 shell 工具展开，但 Harness 的设计原则可以迁移到客服、销售、运维等领域，只是代码不能直接搬。

4.3 已知简化点（README 自己也写了）

为了让学习曲线平滑，作者明确砍掉了几个生产级机制：

  • 完整的 event / hook bus（如 PreToolUse、SessionStart/End、ConfigChange）；
  • 完整的 rule-based permission 治理与 trust workflow；
  • session lifecycle 控制（resume /fork）和完整的 worktree lifecycle；
  • 完整的 MCP runtime（transport、OAuth、resource subscription、polling）；
  • JSONL mailbox 是教学协议，不是某个生产系统的内部实现。

所以如果你想拿它做生产基线，必须自己补这些；但作为教学材料，它已经把最关键的 80% 讲透了。

五、总结

readme 末尾一句话总结得很到位：

Agency comes from the model. The harness gives agency a place to land. Build the harness well, and the model will do the rest.

learn-claude-code 这个仓库最大的价值，不是教你” 复制 Claude Code 的源代码”，而是帮你建立一种新的工程思维：我们写的不是 Agent，而是 Agent 的世界。

当所有”AI Agent 平台” 都在拼节点图、拼 workflow、拼 prompt chain 编排的时候，这个仓库告诉你：真正优雅的 Agent Harness 本质上就是一个 15 行的循环，外面套上一层又一层克制的、可解释的机制。每一层机制都有自己的 motto，每一层机制都在解决一个具体的问题，而不是堆砌复杂度。

如果你是工程师，强烈建议从 s01 开始，逐章跑 code.py，把 20 节课程过一遍。读完之后再看 Claude Code、Cursor、OpenHands 这些产品的 changelog，你会突然看懂它们每一个新 feature 是在 Harness 的哪一层加了东西。

写完这篇，我更确信一件事：2026 年最稀缺的不是会调 API 的 AI 工程师，而是懂 Harness Engineering 的工程师 —— 他们写的不是代码，而是代码与智能之间的合同。