先说一件让我沉默三分钟的事
某天晚上我在刷 GitHub Trending，看到一个仓库名叫 learn-claude-code，副标题写着：
"Bash is all you need — A nano claude code–like 「agent harness」, built from 0 to 1"
我瞄了一眼数据：54,600 Stars，9,000 Forks，69次提交。
然后我打开 README，开头第一段话直接给我整不会了：
"Agency — the ability to perceive, reason, and act — comes from model training, not from external code orchestration."
（智能来自模型训练，不来自外部代码编排。）
我盯着这句话看了三分钟。
这句话戳穿了过去两年 AI 圈里一个价值数十亿美元的集体幻觉——那些拖拽式"AI Agent 平台"、那些号称"无需懂 AI 就能搭 Agent"的 SaaS 产品，它们实际上在做什么？
把 LLM API 用 if-else 分支和节点图串起来，然后叫它"Agent"。
README 里的原话更毒：
"What they build is a Rube Goldberg machine — an over-engineered, brittle pipeline of procedural rules, with an LLM wedged in as a glorified text-completion node. That is not an agent. That is a shell script with delusions of grandeur."
（他们造的是鲁布·戈德堡机器——一堆过度工程化、极脆弱的程序规则管道，把 LLM 塞进去当个高配文字补全节点。那不是 Agent。那是一个自我感觉良好的 shell 脚本。）
好家伙，一个教学仓库，开口就对整个行业开炮。
我立刻 Fork 了。
这里说一下国内的朋友订购claude code确实有些困难，这里我们推荐一个靠谱的网站：claudemax.shop
这个项目是谁做的？做了什么？
项目作者是 shareAI-lab，中文社区活跃的 AI 工程研究团队，X 账号 @baicai003（白菜003，这名字挺接地气的）。
核心定位：一个从 0 开始、手把手拆解 Claude Code 架构的教学项目，用 12 个渐进式 Session，带你亲手实现一个迷你版的「AI Agent 引擎」。
技术栈：Python（39%）+ TypeScript（59.2%），配套 Next.js 互动学习平台。
截至 2026 年 5 月 1 日的数据：
| 指标 | 数值 |
|---|---|
| ⭐ Stars | 54,600 |
| 🍴 Forks | 9,000 |
| 📝 Commits | 69 |
| 👁️ Watching | 249 |
| 📄 支持语言 | 英文 / 中文 / 日文 |
| 📜 License | MIT |
Fork/Star 比值 = 9000/54600 ≈ 16.5%
这个比值相当健康，说明有大量人在本地跑代码、做实验，不只是随手收藏。
README 的哲学导言，值得单独讲
这个项目的 README 不是一般教程的那种"安装 → 运行 → 结束"流水线，它在前三分之一的篇幅里，系统性地讲了一件事：
什么是真正的 Agent，什么不是。
它用五个历史里程碑来证明"Intelligence comes from training, not coding"：
2013 年：DeepMind DQN 只靠原始像素和分数，学会了 7 款 Atari 游戏，打败人类专家，发表在 Nature。没有任何游戏规则硬编码，一个模型，从经验中学。
2019 年：OpenAI Five 打 Dota 2，5 个神经网络自我对弈 45,000 年，2:0 击败 TI8 世界冠军 OG，后续公开赛 42,729 场赢了 99.4%。没有脚本策略，没有元编程团队协调，模型在自我对弈中学到了一切。
2019 年：AlphaStar 打 StarCraft II，以 10:1 击败职业选手，后来在欧服排名进入前 0.15%（共 9 万玩家）。一个信息不完全、实时决策、动作空间远超围棋的游戏。Agent 是什么？是模型，训练出来的。
2019 年：腾讯觉悟打《王者荣耀》，在世界冠军杯 5v5 击败 KPL 职业选手，1v1 模式下职业选手 15 局只赢了 1 局，没撑过 8 分钟。训练强度：一天等于人类 440 年。
2024-2025 年：Claude、GPT、Gemini 等大语言模型作为编码 Agent 部署，读代码库，写实现，Debug，团队协作。架构和此前所有 Agent 完全一致：训练好的模型，放进环境，给它工具去感知和行动。
然后 README 给出结论：
"Agency — the ability to perceive, reason, and act — is trained, not coded."
这个铺垫是为了说一件事：你作为 Harness 工程师，你的工作不是给模型编写智能，而是给模型建造它能居住的世界。
模型是驾驶员，Harness 是车辆。这个比喻，我觉得是目前我看到过对"AI 工程师职责"最清晰的描述。
12 个 Session 的学习路径：我全部跑过了
项目分四个阶段，每个阶段一个核心概念，每个 Session 加一个 Harness 机制。我把自己跑完的体验说一下。
Phase 1：THE LOOP（基础循环）
s01 — The Agent Loop | 格言： "One loop & Bash is all you need"
这是整个项目的基础，也是最重要的十几行代码：
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 的核心循环。
模型决定什么时候调用工具，什么时候停止。代码只负责执行模型要求的操作。
这个设计的精妙之处在于：循环属于 Agent（模型），机制属于 Harness（代码） 。整个项目从头到尾都不打破这个原则——12 个 Session 加了 12 个机制，核心循环一行都没有改变。
s02 — Tool Use | 格言： "Adding a tool means adding one handler"
工具注册机制，把工具名映射到处理函数：
TOOL_HANDLERS = {
"bash": run_bash,
"read_file": read_file,
"write_file": write_file,
}
加新工具 = 加一个 handler。循环不变。这个设计的可扩展性让我想起金融系统里的事件驱动架构——新事件类型来了，加 handler，主循环不动。
Phase 2：PLANNING & KNOWLEDGE（规划与知识）
s03 — TodoWrite | 格言： "An agent without a plan drifts"
这里实现了 Claude Code 里大名鼎鼎的 TodoWrite 机制。Agent 在执行任务前先列出步骤，然后逐一执行，README 说完成率"doubles"（翻倍）。
这个结论有实验基础：没有计划的 Agent 容易在中途偏离目标，做着做着开始干别的，跟没有 TODO list 的人类程序员一样（我就是那个程序员）。
s04 — Subagents | 格言： "Break big tasks down; each subtask gets a clean context"
这是我个人认为学习价值最高的一个 Session。
子 Agent 的核心洞察：每个子任务用独立的 messages[]，保持主对话干净。
父 Agent 不把自己乱七八糟的上下文传给子 Agent，子 Agent 就一件事做到底。这跟微服务架构里的"单一职责原则"异曲同工，也跟金融系统里"隔离账户风险"的思路一致——上下文污染和风险传染，本质上是同一类工程问题。
s05 — Skills | 格言： "Load knowledge when you need it, not upfront"
Skills（技能文件）不是开场就注入系统提示词，而是通过 tool_result 按需加载。
这个设计的动机是省 Token：你不需要在每次会话里都告诉 Agent 所有可能用到的知识，让它自己判断什么时候需要什么知识，然后去拉取。
s06 — Context Compact | 格言： "Context will fill up; you need a way to make room"
三层上下文压缩策略，这部分我看了两遍。
- 热数据：最近的完整交互，保留原文
- 温数据：稍早的交互，AI 摘要压缩
- 冷数据：更早的历史，只保留关键事实
这个分层思路让我想到量化系统里的 Tick 数据存储——你不可能把所有高频数据都放内存里实时查，需要冷热分离，按查询频率决定存在哪里、压缩到什么粒度。
Phase 3：PERSISTENCE（持久化）
s07 — Tasks | 格言： "Break big goals into small tasks, order them, persist to disk"
文件驱动的任务图，有依赖关系管理。这是多 Agent 协作的基础——任务不在内存里，掉了还能恢复，还能跨 Agent 共享。
s08 — Background Tasks | 格言： "Run slow operations in the background; the agent keeps thinking"
后台 daemon 线程跑慢操作，完成后通过通知队列告知主 Agent。这让 Agent 不用傻等 I/O，可以继续思考下一步——跟异步编程的思想完全一致，只是在 Agent 语境里重新表达了一遍。
Phase 4：TEAMS（团队协作）
s09 — Agent Teams | 格言： "When the task is too big for one, delegate to teammates"
持久化 Teammate + 异步 JSONL 邮箱。这里是整个项目技术含量最高的部分。
每个 Teammate 是一个持久化的 Agent 实例，通过文件系统里的 JSONL 邮箱互相通信。主 Agent 发任务，Teammate 领取，完成后回报。
s10 — Team Protocols | 格言： "Teammates need shared communication rules"
统一的请求-响应协议，有关机握手、计划审批的有限状态机（FSM）。没有共同的通信协议，Agent 团队就是一盘散沙。
s11 — Autonomous Agents | 格言： "Teammates scan the board and claim tasks themselves"
Agent 主动扫任务板、自主认领任务，不需要主 Agent 一个个分配。这是从"指挥型"到"自治型"的关键跳跃。
s12 — Worktree Isolation | 格言： "Each works in its own directory, no interference"
每个 Agent 工作在独立的 Git worktree 里，任务 ID 绑定目录 ID，完全隔离，互不干扰。这是 Claude Code 实现并行执行的核心机制之一。
Capstone：s_full.py
把所有 12 个机制合成一个完整系统，没有任何新概念，只是验证：你是否真的理解了每一层叠加的含义。
我跑完 s_full.py 的时候，脑子里有一种清晰的满足感——不是"哇好厉害"，而是"哦，原来是这样，就这样"。
好的教程应该让你觉得"其实也不难嘛"，而不是让你觉得更加神秘。
这个项目做到了。
互动学习平台：意外的加分项
cd web && npm install && npm run dev
# http://localhost:3000
我本来以为这只是个摆设，打开来居然相当完整：
- Step-through 图解：每个 Session 的架构图，可以一步步点进去看数据流
- Source Viewer：直接在浏览器里看代码，对应的文档在旁边
- 三语文档：中/英/日，不是机器翻译的，读起来很顺
这个 Web 平台的存在让这个项目从"一个代码仓库"变成了"一套完整的课程体系"。
对于习惯看着图理解系统的人（比如我），这个视觉化的呈现方式大大降低了理解成本。
项目还连着两个实战工具
学完 12 个 Session 之后，作者还给了两条路让你把知识变成实际产品：
Kode Agent CLI
npm i -g @shareai-lab/kode
一个开源编码 Agent CLI，支持 Skills、LSP（Language Server Protocol），Windows 兼容，可接 GLM / MiniMax / DeepSeek 等开放模型。
这是 learn-claude-code 学到的架构思想的"直接产品化"——你在 12 个 Session 里理解的那些机制，直接在 Kode CLI 里运行着。
Kode Agent SDK
面向需要把 Agent 能力嵌进自己产品的开发者。
与官方 Claude Code Agent SDK 不同的是，Kode SDK 是纯库形式，没有每个用户一个进程的开销，可以嵌入后端、浏览器扩展、嵌入式设备、任何运行时。
这对于想在量化系统、金融 SaaS 里集成 AI 能力的人（我）来说，是一个非常务实的选择。
真实测评：亮点与槽点，逐一呈现
🌟 打动我的地方
1. README 的哲学层面是认真的，不是故弄玄虚
那段从 DeepMind DQN 到 LLM Agent 的历史溯源，写得相当扎实，每个引用都有论文或原始报道链接。
这不是为了凑字数——它是在帮你建立一个正确的心智模型：你做的是 Harness，不是 Intelligence。在正确定位自己工作边界之前，很多工程决策都会走偏。
2. 每个 Session 一个格言，精准到令人印象深刻
"An agent without a plan drifts" （没有计划的 Agent 会漂移） "Context will fill up; you need a way to make room" （上下文会被填满，你需要腾地方） "Each works in its own directory, no interference" （各自在自己目录里工作，互不干扰）
12 句格言，12 个机制，一一对应。这是教学设计的功夫，不是随手写的。
3. 代码量克制，只写必要的东西
整个项目 69 次提交。不是因为懒，是因为克制。
每个 Session 的参考实现都是最小化的——只演示一个机制，不带多余的工程包装。这让你能把注意力集中在"这个机制为什么重要、怎么工作"，而不是"这堆依赖是干嘛的"。
对比某些"学习项目"动辄几百个文件、十几层抽象，这种克制是一种教学美德。
4. 覆盖三语文档且质量有保证
中文文档不是机器翻译的，读起来很顺，概念描述准确。对于母语是中文的开发者，这省掉了很多阅读摩擦。
5. Fork/Star 比值 16.5%，说明用户在真实学习
这不是收藏型项目。16.5% 的 Fork 率意味着每 6 个 Star 里就有 1 个人在本地跑代码。
⚠️ 需要说清楚的地方
1. 这是教学项目，不是生产系统
README 自己也说了，项目有意简化或省略了几个生产机制：
- 完整的事件/Hook 总线（PreToolUse、SessionStart/End 等）
- 基于规则的权限治理和信任工作流
- 会话生命周期控制（恢复/分叉）和高级 Worktree 生命周期控制
- 完整的 MCP 运行时细节
如果你是来找可以直接部署的产品，这个项目不是。
如果你是来理解"Claude Code 底层是怎么运作的"，这个项目非常合适。
2. 69 次提交说明仓库相对年轻
相比 claude-mem 的 1,823 次提交、everything-claude-code 的 1,465 次提交，69 次提交意味着这是一个相对新且精炼的项目。
好处是：代码干净，没有历史债务。 需要注意的是：生态还在建立，边界情况可能没有全覆盖。
3. 配套的 Kode CLI 和 SDK 处于早期阶段
这两个配套工具本质上是把课程里的概念产品化，目前功能还在快速迭代，不建议用于对稳定性要求高的生产环境。把它们当作"学完课程之后的实验场"更合适。
4. Worktree 隔离部分文档稍薄
s12 是全项目最复杂的机制，但对应的文档篇幅比前几个 Session 稍短，细节讲解不够完整。需要结合代码本身才能完全理解。
54.6k Star：含金量分析
和同类项目横向比较
| 项目 | Stars | Fork/Star比 | 定位 | Commit数 |
|---|---|---|---|---|
| everything-claude-code | 167k | 15.5% | 生产级 Agent 操作系统 | 1,465 |
| claude-mem | 70.3k | 8.5% | Claude Code 记忆插件 | 1,823 |
| learn-claude-code | 54.6k | 16.5% | Agent Harness 教学课程 | 69 |
| mattpocock/skills | 23k | 8.2% | TypeScript 工程师 Skills 分享 | 34 |
learn-claude-code 有所有项目里最高的 Fork/Star 比值（16.5%） ，这跟它的教学定位高度吻合——学习项目就是要被 Fork 下来本地跑的。
Star 含金量有多实
54.6k 的增长主要来自两个来源：
- Claude Code 生态爆发的红利：2026 年 Claude Code 成为最热门的开发者工具之一，围绕它的教学内容需求巨大。
- 内容本身的质量：README 里的哲学导言 + 历史案例是有讨论价值的内容，在 X 和开发者社区里被多次转发讨论。
结论：54.6k Star 含金量实在，Fork 数据是最有力的证明——人们在真正学这门课。
和金融系统的隐性类比（来点我的独家视角）
我在金融行业干了很多年，在量化系统里有很多"Agent 化"的设计经验。
读完 learn-claude-code 之后，我发现一件有趣的事——Harness 工程的设计模式和金融系统的架构原则惊人地相似。
| Harness 概念 | 金融系统类比 |
|---|---|
| 子 Agent 独立 messages[] | 隔离账户/独立风控单元 |
| Context Compact 三层压缩 | Tick 数据冷热分层存储 |
| 异步 JSONL 邮箱 | 消息队列（Kafka/RocketMQ） |
| 任务依赖图 | 交易指令的 DAG 调度 |
| Worktree 隔离 | 沙箱账户/测试环境隔离 |
| 权限边界 | 交易权限审批链 |
这个类比让我有一个体感：Harness 工程不是一个 AI 特有的领域，它是软件系统设计的一般问题，只是发生在 AI 语境里。
懂金融系统的人，学 Harness 工程会比想象中容易——因为大量核心设计问题已经在别的领域解决过了。
快速上手：5 分钟跑完 s01
# 克隆仓库
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
# 开启 Web 学习平台
cd web && npm install && npm run dev
# 打开 http://localhost:3000
建议的学习节奏：每天一个 Session，不要贪多。每个 Session 的价值不在代码量，在思考那句格言和对应机制之间的关系。
总评打分
| 维度 | 评分 | 说明 |
|---|---|---|
| 内容深度 | ⭐⭐⭐⭐⭐ | 哲学导言 + 代码实现 + 格言提炼，三层叠加 |
| 代码质量 | ⭐⭐⭐⭐⭐ | 极度克制，每个 Session 只加一个机制 |
| 教学结构 | ⭐⭐⭐⭐⭐ | 12 个渐进 Session，每个有独立格言，学习路径清晰 |
| 文档完整性 | ⭐⭐⭐⭐☆ | 三语支持，但 s12 文档稍薄 |
| 生产就绪性 | ⭐⭐⭐☆☆ | 这是教学项目，不打算也不应该直接生产部署 |
| 配套工具 | ⭐⭐⭐⭐☆ | Kode CLI 和 SDK 有实际价值，但还在早期 |
| 综合 | ⭐⭐⭐⭐½ | Agent 工程入门必读，没有之一 |
适合谁，不适合谁
强烈推荐给：
- 想深入理解 Claude Code 等 AI 编程工具内部原理的开发者
- 想自己造一个简单 Agent 引擎而不是调包调 API 的工程师
- 对"什么是真正的 Agent"有困惑、被"no-code AI 平台"搞懵的人
- 有系统设计基础、想把这些概念迁移到其他领域（金融、医疗、制造）的人
不适合：
- 只想找一键部署的生产工具（看 everything-claude-code）
- 刚接触 AI、还没用过 Claude Code 的完全新手（先用用工具再来理解原理）
- 不想读英文技术文档的（中文版文档有，但项目整体还是英文为主）
写在最后：关于那句话
整个项目开头的那句话，我最后再重复一遍：
"Agency comes from the model. The harness makes agency real. Build great harnesses. The model will do the rest."
我做了这么多年金融系统，最近两年开始做 AI 相关的东西。
一开始我也是"提示词工程师"思维——觉得多加几个 if-else，搭个节点图，就能把 AI 用好。
这个项目帮我重新定位了自己的工作：我不是在给 AI 写智能，我是在给 AI 建造它能工作的世界。
这个认知转变，比我学会任何一个具体的 API 都有价值。
Bash is all you need。
