12课拆解Claude Code架构：从零掌握Agent Harness工程

一句话说清楚这个项目是什么

Learn Claude Code 是一个逆向工程 Claude Code 架构的开源教学仓库，用 12 个递进式 Python 课程，从最小 Agent 循环出发，逐步叠加工具注册、计划系统、子 Agent、技能加载、上下文压缩、任务持久化、后台执行、多 Agent 团队、自治协作，一直到 Worktree 隔离执行——覆盖了一个生产级 Agent Harness 的全部核心机制。

GitHub 地址：shareAI-lab/learn-claude-code（⭐ 49K+ Stars）

为什么你应该学这个

在上一篇文章《Harness Engineering：开发者的下一个必修课》中，我们聊过一个核心观点：

Agent = Model + Harness

模型是大脑，Harness 是身体。大脑由 Anthropic、OpenAI 训练，你控制不了。但身体——Agent 能看到什么、能操作什么、怎么记忆、怎么协作——这完全是你的工程问题。

问题是：Harness 怎么造？

市面上的教程要么停留在 "用 LangChain 串几个 API 调用" 的水平，要么直接跳到生产级系统让你望而却步。中间缺一个从 0 到 1、每一步都可以跑起来验证的递进式学习路径。

Learn Claude Code 正好填了这个空缺。

核心理念：Agent 是模型，不是框架

这个仓库的 README 开篇就掷地有声：

Agent 是模型。不是框架。不是提示词链。不是拖拽式工作流。

从 2013 年 DeepMind DQN 玩 Atari，到 2019 年 OpenAI Five 击败 Dota 2 世界冠军，到腾讯绝悟制霸王者荣耀——每一个 AI 里程碑都是同一件事：一个训练好的模型，放入一个环境，给予感知和行动的工具。

2024-2025 年的 LLM Agent 也一样。Claude、GPT、Gemini 被部署为编程 Agent，架构与之前每一个 Agent 完全相同。唯一不同的是规模和通用性。

所以当你说 "我在开发 Agent" 时，你实际在做的是构建 Harness——为模型搭建运行环境。这个仓库教的就是这件事。

12 个课程全景：每课一个 Harness 机制

整个课程分四个阶段，从最简单的循环到完整的团队自治：

阶段一：循环（The Loop）

s01 — Agent Loop

"One loop & Bash is all you need"

一切的起点。一个 while True 循环 + 一个 Bash 工具 = 一个能操作真实世界的 Agent。

while True:
    response = client.messages.create(model=MODEL, messages=messages, tools=TOOLS)
    if response.stop_reason != "tool_use":
        return  # 模型决定停止
    # 执行工具，追加结果，继续循环

这 20 行代码就是所有 AI Agent 的骨架。后面 11 个课程，循环本身一行不改——只在循环之外叠加 Harness 机制。

s02 — Tool Use

"加一个工具，只加一个 handler"

从 1 个工具扩展到多个。核心模式：一个 dispatch map，工具名映射到处理函数。新增工具只需注册，循环不用碰。

阶段二：规划与知识（Planning & Knowledge）

s03 — TodoWrite

"没有计划的 Agent 走哪算哪"

给 Agent 一个 TodoManager：先列步骤再动手，循环里加一个 nag reminder 催促 Agent 按计划推进。完成率直接翻倍。

s04 — Subagent

"大任务拆小，每个小任务干净的上下文"

子 Agent 用独立的 messages[]，不污染主对话。主 Agent 把大任务拆分，每个子任务在干净的上下文中执行完毕后汇报结果。

s05 — Skills

"用到什么知识，临时加载什么知识"

通过 tool_result 按需注入领域知识（Markdown 文件），而不是塞进 system prompt。这就是 Claude Code 的 Skill 加载机制。

s06 — Context Compact

"上下文总会满，要有办法腾地方"

三层压缩策略：保留关键信息、压缩历史对话、丢弃冗余内容。换来无限长度的会话能力。

阶段三：持久化（Persistence）

s07 — Task System

"大目标拆成小任务，排好序，记在磁盘上"

从内存清单升级为持久化到磁盘的任务图（DAG）。每个任务一个 JSON 文件，有状态、有依赖。任务图回答三个问题：什么可以做？什么被卡住？什么做完了？

task 1 (completed) → task 2 (pending) ─┐
                   → task 3 (pending) ─┤→ task 4 (blocked)

这个任务图是后面所有机制的协调骨架。

s08 — Background Tasks

"慢操作丢后台，Agent 继续想下一步"

后台线程跑耗时命令（构建、测试），完成后通过通知队列注入结果。Agent 不用干等。

阶段四：团队（Teams）

s09 — Agent Teams

"任务太大一个人干不完，要能分给队友"

持久化的队友 + 异步 JSONL 邮箱。主 Agent 可以创建队友、分配任务、通过邮箱异步通信。

s10 — Team Protocols

"队友之间要有统一的沟通规矩"

一个 request-response 模式驱动所有协商。定义了关机协议、计划审批状态机等团队协作规范。

s11 — Autonomous Agents

"队友自己看看板，有活就认领"

不需要领导逐个分配。Agent 自己扫描任务板，找到可做的任务就认领执行。真正的自组织。

s12 — Worktree Isolation

"各干各的目录，互不干扰"

终极课程。每个任务绑定一个独立的 git worktree 目录，两个 Agent 同时改代码也不会互相污染。任务管目标，worktree 管目录，按 ID 绑定。

学习路径图

Phase 1: THE LOOP                    Phase 2: PLANNING & KNOWLEDGE
==================                   ==============================
s01  The Agent Loop                  s03  TodoWrite
     while + stop_reason                  TodoManager + nag reminder
     |                                    |
     └─> s02  Tool Use                    s04  Subagents
              dispatch map                     fresh messages[] per child
                                               |
                                          s05  Skills
                                               SKILL.md via tool_result
                                               |
                                          s06  Context Compact
                                               3-layer compression

Phase 3: PERSISTENCE                 Phase 4: TEAMS
==================                   =====================
s07  Tasks                           s09  Agent Teams
     file-based CRUD + deps graph         teammates + JSONL mailboxes
     |                                    |
s08  Background Tasks                s10  Team Protocols
     daemon threads + notify queue        shutdown + plan approval FSM
                                          |
                                     s11  Autonomous Agents
                                          idle cycle + auto-claim
                                          |
                                     s12  Worktree Isolation
                                          task + worktree binding

五分钟跑起来

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/s_full.py

仓库还提供了一个交互式 Web 平台，包含分步动画、源码查看器和每个课程的文档：

cd web && npm install && npm run dev   # http://localhost:3000

和上次介绍的项目是什么关系

上篇文章我们介绍了 Everything Claude Code（ECC）——一个生产级的 Claude Code 配置集合（38 个代理 + 156 个技能）。

两者的关系是理论与实践的互补：

建议的学习顺序：先用 ECC 体验 "什么是好的 Harness"，再用 Learn Claude Code 理解 "为什么好"。

后续计划：每课一篇实操文章

这篇是总览。接下来，我们会为每个课程写一篇独立的深度实操文章：

1. s01 实操：用 20 行 Python 造出你的第一个 Agent
2. s02 实操：给 Agent 加工具——dispatch map 模式详解
3. s03 实操：让 Agent 先想后做——TodoWrite 规划系统
4. s04 实操：拆解大任务——Subagent 的上下文隔离
5. s05 实操：按需加载领域知识——Skill 机制
6. s06 实操：无限对话——上下文压缩三层策略
7. s07 实操：任务持久化——文件级 DAG 任务图
8. s08 实操：后台执行——异步任务与通知队列
9. s09 实操：多 Agent 协作——团队与邮箱系统
10. s10 实操：团队协议——状态机驱动的协商
11. s11 实操：自治 Agent——自组织任务认领
12. s12 实操：终极隔离——Worktree 并行执行

每篇都会包含完整的代码演练、运行截图和常见问题排查。关注Claw开发者，不错过更新。

写在最后

这个仓库最打动我的一句话是：

你不是在编写智能。你是在构建智能运转的世界。

模型的能力是 Anthropic 的事。但 Agent 能看得多清楚、行动得多精准、可用知识有多丰富——这些取决于你造的 Harness。

造好 Harness，Agent 会完成剩下的。

关注Claw开发者，获取 AI 工程实践分享。如果这篇文章对你有帮助，欢迎转发给你的技术团队。