shareAI-lab/learn-claude-code · 上手攻略

仓库：shareAI-lab/learn-claude-code
链接：https://github.com/shareAI-lab/learn-claude-code
分类：agent · llm-infra · 教程
作者：Tom
更新：2026-07-06

这是什么

learn-claude-code 是一个从 0 到 1 构建类 Claude Code 的 Agent Harness（智能体操控层）的完整学习项目。Stars 69,893，MIT 许可，Python 语言。

它的核心哲学一句话概括：「Bash is all you need」—— 一个 Bash 工具、一个 Agent Loop、一个模型，就是一个完整 Agent。

这个仓库不教你调 API 拼装工作流，而是教你理解 Agent 的本质，然后手写每一个关键机制：工具系统、Subagent、Context Compaction、Skill 加载、Task 图、权限管理等20个章节。

解决什么问题

市场上充斥着一类误区：以为把 LLM API 用 if-else 和工作流图串起来就是「Agent」。这个仓库的作者认为这是把 Agent 的核心能力归结到了错误的层级——Agency 来自模型训练，而非编排代码。

它解决的根本问题是：大多数人不清楚 Agent 产品中「模型」和「操控层（harness）」的边界在哪里，以及 harness 该怎么从零构建。

学习路径从最简 Loop 开始，逐步叠加复杂度，最终覆盖完整的多 Agent 团队、Worktree 隔离、异步任务、MCP 协议等生产级机制。

快速安装

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

# 查看课程结构（当前 track 为 s01–s20）
ls s*_*/

无依赖安装要求——每个章节的 code.py 是自包含的单文件实现，使用 Python 标准库 + 少量三方依赖（anthropic SDK 等），可按需安装。

核心内容结构

双轨并行（注意别混用）

旧版（legacy）	新版（current）
`docs/` + `agents/` + `web/`	根目录 `s01_` … `s20_`
12 章节	20 章节
旧链接/旧学员仍在用	现在入学的默认读这个

现在入学请只读新版根目录 s01_* 到 s20_* 章节，切勿混用新旧章节编号。

新版 20 章节一览

章节	主题	核心观点
s01	Agent Loop	One loop + Bash = one agent
s02	工具注册	加新工具只需注册 handler，不改 loop
s03	权限控制	先划边界，再授权
s04	Hook 系统	在 loop 周围挂载扩展，不改 loop 本身
s05	TodoWrite	执行前先列步骤，完成率翻倍
s06	Subagent	大任务拆分，子任务得干净上下文
s07	Skill 加载	按需加载 skill，不要 upfront 全加载
s08	Context Compaction	多层压缩策略支撑无限长会话
s09	Memory	选择→抽取→巩固，三子系统记忆管理
s10	System Prompt	prompt 在运行时组装，非硬编码
s11	错误恢复	出错重试、腾空间、换路径
s12	Task System	文件后端任务图，多 Agent 协作基础
s13	后台任务	慢操作放后台，Agent 继续推理
s14	Cron 触发	定时任务，无需人工触发
s15	Agent Teams	多 Agent 持久协作 + 异步 mailbox
s16	Team Protocols	团队间共享通信协议
s17	自主 Agent	完全自主决策，不需要人工干预
s18	Worktree 隔离	git worktree 提供真正干净的工作空间
s19	MCP 协议	Model Context Protocol 路由外部能力
s20	综合实战	整合所有机制构建完整系统

核心概念解析

Agent = Model + Harness

Agent = Model (LLM) + generalized operational environment (Harness)
Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Model 负责决定（推理、判断）
Harness 负责执行（文件 I/O、Shell、API、浏览器、数据库）
Model 决定何时停（stop_reason == "tool_use" vs. text response）
代码只执行，不替代模型做决策

最简 Agent Loop（s01）

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})

一个 loop + 一个 Bash 工具 = 一个完整 Agent。其余19个章节都在此基础上叠加机制。

典型适用场景

学习 Agent 架构：想系统理解 Agent 产品中 harness 工程的具体职责和实现方式
构建企业级 Agent 产品：需要 Task 系统、权限治理、多 Agent 协作等生产机制
参考 Claude Code 架构：Claude Code 被认为是目前最优雅的 harness 实现，本仓库以其为范本做教学解析
Agent 教学/分享：用这个仓库作为课程或工作坊的配套教材

坑与注意

新旧轨道切勿混用：章节编号不对应，混读会导致理解混乱。新学员从 s01_* 根目录章节开始。
生产省略项：仓库在序言中明确列出了故意简化的部分（完整事件总线、Session resume/fork、完整 MCP 运行时细节等），需要生产级实现的读者请自行补充。
JSONL mailbox 协议是教学实现：不是任何特定生产系统的内部实现，不应直接拿来作为某商业产品的实现依据。
Agent Teams（s15-s16）需要异步基础设施：这部分代码涉及 mailbox 协议，需要读者有 Python 异步编程（asyncio）基础。
Model 不是本仓库教的：仓库明确说 Agency 来自训练，调参 fine-tuning 在本仓库范围之外。

与同类对比

项目	定位	特点
learn-claude-code	Agent harness 工程教学	从 loop 到完整系统，20章递进，含代码
LangChain/LlamaIndex	Agent 应用编排	侧重 RAG 和工具链，非 harness 底层
Claude Code 官方	产品级 harness	不开源，只知道「有什么」不知道「怎么建」
AutoGPT / GPT-Engineer	Agent 应用	偏端到端产品，架构教学少

本仓库独特价值：它是目前唯一一个完整解析 Claude Code 架构思路、且提供可运行代码的开放学习项目。

一句话结论

想真正理解 Agent 产品里 harness 层的架构逻辑，并从零亲手实现它？读这个仓库的 20 章——它是目前最好的开源 Agent 工程教科书。

数据来源：GitHub README（英文/中文，2026-06-26），仓库最新提交（2026-06-26）。章节内容以仓库根目录最新 README 为准。