Executive Summary

learn-claude-code 是由 shareAI-lab 开源的 Agent Harness 工程教学项目，通过12个渐进式会话教授如何为 AI Agent 构建运行环境（Harness）。该项目以 “The model IS the Agent” 为核心理念，强调 Agent 的本质是神经网络本身，而非框架或提示链。

核心发现:

• 44k+ Stars，社区热度极高
• 12个渐进式会话，从简单循环到隔离自主执行
• Harness Engineering 理念：Tools + Knowledge + Observation + Action Interfaces + Permissions
• 双语/三语支持：英文、中文、日文文档
• 配套完整：Web 学习平台 + Kode Agent CLI/SDK + claw0 始终在线助手

---

1. 项目概况

1.1 基本信息

属性	详情
项目名称	learn-claude-code
GitHub 地址	https://github.com/shareAI-lab/learn-claude-code
项目描述	“Bash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1”
星标数 (Stars)	44k+ ⭐
Fork 数	6.7k
Watchers	217
Contributors	23
开源协议	MIT License
主要语言	TypeScript (59.2%) + Python (39.0%) + CSS (1.8%)
项目作者	shareAI-lab

1.2 关键词/标签

• Agent Harness
• AI Agent Engineering
• Claude Code
• LLM Agents
• Tool Use
• Multi-Agent Systems
• Context Management
• Agent Teams

1.3 项目定位

learn-claude-code 是一个教学性质的 Agent Harness 工程课程，目标是通过渐进式学习，让开发者理解如何构建真正的 AI Agent 运行环境。

核心理念:

"The model IS the Agent"
"Bash is all you need"
"The code is the harness. Build great harnesses."

目标用户群体:

• 希望深入理解 AI Agent 原理的开发者
• 想要构建自定义 Agent 框架的工程师
• 学习 Claude Code 内部机制的开发者
• 对 Agent Harness 工程感兴趣的技术团队

1.4 项目简介

该项目通过 12 个渐进式会话（sessions），从零开始构建一个类 Claude Code 的 Agent Harness。每个会话添加一个新的机制，最终形成一个功能完整的 Agent 运行环境。

核心特点:

• 渐进式学习：从最简单的循环开始，逐步添加复杂功能
• 实践导向：每个会话都有可运行的 Python 代码
• 理论结合：深入解释 “为什么” 而不仅仅是 “怎么做”
• 多语言支持：文档提供英文、中文、日文版本

---

2. 主要功能

2.1 核心功能

功能模块	功能描述	技术实现
Agent Loop	基础智能体循环	while + tool_use 判断
Tool Use	工具调用系统	工具注册表 + handler 映射
TodoWrite	任务规划	TodoManager + 步骤分解
Subagents	子智能体	独立 messages[] 上下文
Skills	技能系统	SKILL.md 按需加载
Context Compact	上下文压缩	三层压缩策略
Tasks	任务系统	文件 CRUD + 依赖图
Background Tasks	后台任务	守护线程 + 通知队列
Agent Teams	智能体团队	队友 + JSONL 邮箱
Team Protocols	团队协议	请求-响应协商 FSM
Autonomous Agents	自主智能体	空闲循环 + 自动认领
Worktree Isolation	工作区隔离	任务-目录绑定

2.2 12个会话详解

Phase 1: THE LOOP（循环基础）

s01 - The Agent Loop [1个工具]

• 核心理念: “One loop & Bash is all you need”
• 学习内容: 最基本的 Agent 循环结构
• 关键代码:

def agent_loop(messages):
    while True:
        response = client.messages.create(...)
        if response.stop_reason != "tool_use":
            return  # 模型决定停止
        # 执行工具调用，继续循环

s02 - Tool Use [4个工具]

• 核心理念: “Adding a tool means adding one handler”
• 学习内容: 如何扩展工具系统
• 关键机制: 循环不变，新工具注册到分发映射

Phase 2: PLANNING & KNOWLEDGE（规划与知识）

s03 - TodoWrite [5个工具]

• 核心理念: “An agent without a plan drifts”
• 学习内容: 任务规划的重要性
• 效果: 先列步骤再执行，完成率翻倍

s04 - Subagents [5个工具]

• 核心理念: “Break big tasks down; each subtask gets a clean context”
• 学习内容: 子智能体隔离
• 关键机制: 子 Agent 使用独立 messages[]，保持主对话清洁

s05 - Skills [5个工具]

• 核心理念: “Load knowledge when you need it, not upfront”
• 学习内容: 技能按需加载
• 关键机制: 通过 tool_result 注入，非 system prompt

s06 - Context Compact [5个工具]

• 核心理念: “Context will fill up; you need a way to make room”
• 学习内容: 上下文压缩
• 关键机制: 三层压缩策略实现无限会话

Phase 3: PERSISTENCE（持久化）

s07 - Tasks [8个工具]

• 核心理念: “Break big goals into small tasks, order them, persist to disk”
• 学习内容: 基于文件的任务系统
• 关键机制: 文件 CRUD + 依赖关系图

s08 - Background Tasks [6个工具]

• 核心理念: “Run slow operations in the background; the agent keeps thinking”
• 学习内容: 后台任务执行
• 关键机制: 守护线程运行命令，完成时注入通知

Phase 4: TEAMS（团队协作）

s09 - Agent Teams [9个工具]

• 核心理念: “When the task is too big for one, delegate to teammates”
• 学习内容: 多智能体团队
• 关键机制: 持久队友 + 异步 JSONL 邮箱

s10 - Team Protocols [12个工具]

• 核心理念: “Teammates need shared communication rules”
• 学习内容: 团队通信协议
• 关键机制: 单一请求-响应模式驱动所有协商

s11 - Autonomous Agents [14个工具]

• 核心理念: “Teammates scan the board and claim tasks themselves”
• 学习内容: 自主任务认领
• 关键机制: 无需领导分配，自动认领任务

s12 - Worktree Isolation [16个工具]

• 核心理念: “Each works in its own directory, no interference”
• 学习内容: 工作区隔离
• 关键机制: 任务管理目标，worktree 管理目录，通过 ID 绑定

2.3 应用场景

2.3.1 Agent Harness 学习

场景描述: 系统学习如何构建 AI Agent 运行环境

具体应用:

• 按顺序学习 12 个会话
• 每个会话运行对应代码，观察行为
• 修改代码，实验不同参数

典型用户: AI 工程师、技术负责人

2.3.2 自定义 Agent 开发

场景描述: 基于学习的内容构建自己的 Agent

具体应用:

• 复制 s_full.py 作为起点
• 根据需求增删功能模块
• 集成到现有项目中

典型用户: 需要定制 Agent 的开发者

2.3.3 团队培训

场景描述: 团队共同学习 Agent 工程

具体应用:

• 使用 Web 平台进行交互式学习
• 讨论每个 session 的设计决策
• 共同完成 s_full 综合项目

典型用户: 技术团队、学习小组

---

3. 技术信息

3.1 技术架构

learn-claude-code/
├── agents/              # Python 参考实现
│   ├── s01_agent_loop.py
│   ├── s02_tool_use.py
│   ├── s03_todo_write.py
│   ├── s04_subagents.py
│   ├── s05_skills.py
│   ├── s06_context_compact.py
│   ├── s07_tasks.py
│   ├── s08_background_tasks.py
│   ├── s09_agent_teams.py
│   ├── s10_team_protocols.py
│   ├── s11_autonomous_agents.py
│   ├── s12_worktree_task_isolation.py
│   └── s_full.py        # 综合所有机制
├── docs/
│   ├── en/              # 英文文档
│   ├── zh/              # 中文文档
│   └── ja/              # 日文文档
├── web/                 # Next.js 交互式学习平台
├── skills/              # s05 技能文件示例
└── .github/workflows/   # CI/CD

3.2 核心组件

3.2.1 Agent 核心循环

def agent_loop(messages, system, tools, tool_handlers):
    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  # Agent 决定停止
            
        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})

3.2.2 Harness 组成

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

Tools: 文件IO、Shell、API、浏览器控制
Knowledge: 按需加载的技能和上下文
Observation: 环境感知能力
Action Interfaces: 行动接口
Permissions: 权限控制（沙箱、审批）

3.3 技术亮点

3.3.1 “The model IS the Agent” 理念

区别于传统的 “Agent = 框架 + 提示 + 工作流”，该项目强调：

• Agent 是神经网络本身，通过数十亿次梯度更新训练
• 历史证明：DQN、OpenAI Five、AlphaStar、绝悟 —— 都是模型即 Agent
• 工程师的工作是构建 Harness（运行环境），而非编写智能

3.3.2 渐进式复杂度

从 1 个工具（s01）到 16 个工具（s12），每个 session 只增加必要的复杂度：

s01: 1 tool   → 基础循环
s02: 4 tools  → + 工具系统
s03: 5 tools  → + 任务规划
s04: 5 tools  → + 子智能体
s05: 5 tools  → + 技能加载
s06: 5 tools  → + 上下文压缩
s07: 8 tools  → + 任务系统
s08: 6 tools  → + 后台任务
s09: 9 tools  → + 智能体团队
s10: 12 tools → + 团队协议
s11: 14 tools → + 自主认领
s12: 16 tools → + 工作区隔离

3.3.3 三层上下文压缩

s06 实现的三层压缩策略：

1. Summarization: 摘要历史对话
2. Offloading: 将大内容卸载到文件
3. Selective Loading: 选择性加载相关上下文

3.4 核心技术栈

类别	技术/库	用途
后端语言	Python 3.x	Agent 实现
前端框架	Next.js	Web 学习平台
前端语言	TypeScript	Web 平台开发
AI 模型	Claude (Anthropic)	核心 LLM
API	Anthropic Messages API	模型交互
包管理	pip (Python) / npm (Node)	依赖管理

---

4. 如何使用

4.1 硬件要求

组件	最低配置	推荐配置
CPU	任意现代 CPU	多核处理器
内存	4 GB	8 GB+
硬盘	100 MB 可用空间	500 MB+
网络	互联网连接（调用 API）	稳定连接

4.2 软件要求

软件	版本要求	说明
操作系统	Linux/macOS/Windows	全平台支持
Python	3.8+	运行 Agent
Node.js	18+	运行 Web 平台
API Key	Anthropic API Key	调用 Claude 模型

4.3 使用方法

4.3.1 基础使用

# 克隆仓库
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code

# 安装依赖
pip install -r requirements.txt

# 配置 API Key
cp .env.example .env
# 编辑 .env，添加 ANTHROPIC_API_KEY

# 运行会话
python agents/s01_agent_loop.py          # 起点
python agents/s12_worktree_task_isolation.py  # 完整进阶
python agents/s_full.py                  # 综合项目

4.3.2 Web 学习平台

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

4.4 上手难度评估

用户类型	难度	说明
Python 初学者	⭐⭐⭐	需要理解基础语法和 API 调用
有 LLM 经验的开发者	⭐⭐	概念熟悉，主要是学习 Harness 设计
AI 工程师	⭐	快速理解，可作为参考实现
技术团队	⭐⭐	适合作为团队学习材料

---

5. 竞品分析

5.1 相关项目对比

项目	类型	特点	与 learn-claude-code 对比
Claude Code	商业产品	Anthropic 官方 Agent CLI	learn-claude-code 是教学实现
DeerFlow	开源框架	超级 Agent Harness	更完整的生产框架
HiCLAW	开源框架	多智能体协作 OS	更复杂的企业级功能
OpenSpec	开源框架	规范驱动开发	不同维度（规范 vs Harness）
Aider	开源工具	AI 结对编程	更成熟的生产工具
Kode Agent	配套项目	生产级 Agent CLI	基于 learn-claude-code 构建

5.2 优劣势分析

5.2.1 竞争优势

1. 教学导向: 渐进式设计，适合系统学习
2. 理念清晰: “The model IS the Agent” 深入人心
3. 代码简洁: 每个 session 都保持可读性
4. 多语言文档: 中英日三语支持
5. 社区活跃: 44k+ stars，持续更新
6. 配套完整: Web 平台 + Kode Agent + claw0

5.2.2 竞争劣势

1. 教学性质: 不是生产级框架
2. 功能有限: 相比 DeerFlow/HiCLAW 功能较少
3. 依赖 Claude: 主要面向 Anthropic API
4. 需要自己扩展: 学完需要自己动手构建生产系统

5.3 学习路径对比

资源类型	代表	适合人群	学习曲线
官方文档	Anthropic Docs	快速上手	平缓
教学项目	learn-claude-code	深入理解	渐进
生产框架	DeerFlow/HiCLAW	直接使用	陡峭
视频课程	各种教程	视觉学习者	平缓

---

6. 附录信息

6.1 参考资料

1. GitHub 仓库: https://github.com/shareAI-lab/learn-claude-code
2. 英文文档: docs/en/
3. 中文文档: docs/zh/
4. 日文文档: docs/ja/

6.2 配套项目

项目	说明	状态
Kode Agent CLI	开源编码 Agent CLI，支持 Skill & LSP	已发布
Kode Agent SDK	独立库，可嵌入后端/浏览器扩展	已发布
claw0	始终在线助手（心跳 + Cron + IM + 记忆）	姊妹仓库

6.3 社区资源

• Issues: https://github.com/shareAI-lab/learn-claude-code/issues
• Pull Requests: 5 open
• Contributors: 23

6.4 版本历史

版本	说明
Current	63 commits，持续更新
Web Platform	Next.js 交互式学习

---

7. 总结与建议

7.1 项目评估

优势:

• 教学价值极高，渐进式设计合理
• 核心理念清晰，“The model IS the Agent” 有深度
• 代码质量高，可读性强
• 多语言支持，社区活跃
• 配套项目完整，形成生态

劣势:

• 不是生产级框架，需要用户自己扩展
• 主要面向 Claude API，其他模型支持有限
• 功能相对简单，复杂场景需要自行实现

7.2 使用建议

推荐使用:

• 希望深入理解 Agent 原理的开发者
• 想要构建自定义 Agent 的团队
• 技术团队集体学习 Agent 工程
• 作为 DeerFlow/HiCLAW 等框架的学习前置

学习路径建议:

1. 按顺序学习 s01-s12
2. 每个 session 运行代码，观察输出
3. 修改参数，实验不同行为
4. 学习 s_full 综合项目
5. 参考 Kode Agent 生产实现

7.3 与其他项目的关系

learn-claude-code (教学基础)
    ↓
Kode Agent CLI/SDK (生产实现)
    ↓
claw0 (始终在线助手)

与其他框架的关系：
- DeerFlow: 更完整的生产级 Harness
- HiCLAW: 更复杂的多智能体系统
- OpenSpec: 规范层，可与 Harness 配合使用

7.4 风险提示

⚠️ 学习曲线: 需要一定的 Python 和 LLM 基础

⚠️ API 成本: 运行示例需要 Anthropic API Key，产生费用

⚠️ 生产转换: 学完需要自己动手构建生产系统

⚠️ 模型依赖: 示例主要针对 Claude，其他模型可能需要调整

---

核心金句:

“The model is the agent. The code is the harness. Build great harnesses. The agent will do the rest.”

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