learn-claude-code：17 章课拆解 Claude Code 式 Agent 外壳，从 0 到 1 理解 Harness 机制

一句话结论：learn-claude-code 是 shareAI-lab 开源的 17 章渐进式课程，用一句话贯穿全程——「智能体产品 = 模型 + 外壳」，每章拆一个 Harness 机制，帮你从零复刻一个 Claude Code 式的编码智能体外壳。

AI 摘要

• 项目用途：17 章渐进式课程，拆解 Claude Code 式 Agent 的每个机制，每章配可运行的 code.py。
• 适合人群：想理解 Agent 底层原理的中级 Python 开发者、想自建编码智能体的团队。
• 上手门槛：低，依赖只有 anthropic、python-dotenv、pyyaml 三个包。
• 智盒结论：它不教你「怎么用 Claude Code」，而是教你「Claude Code 为什么这么设计」，是理解 Agent 外壳工程的最佳入门路径之一。

项目信息

• 项目名：shareAI-lab/learn-claude-code
• GitHub URL：https://github.com/shareAI-lab/learn-claude-code
• License：MIT
• 版本状态：当前 17 课轨道（s 01–s 17）+ 遗留 12 课轨道（docs/）
• 目标栏目：资源

它解决什么问题

市面上的 Agent 教程大多教你「用」现成框架——LangChain、LangGraph、Dify。但当你真的想自己做一个编码智能体时，会发现一个尴尬的问题：模型只是大脑，真正决定「好不好用」的是那个「外壳」（Harness）——它怎么循环、怎么调工具、怎么管权限、怎么在长任务里不跑偏。

learn-claude-code 的核心命题就是一句：智能体产品 = 模型 + 外壳（Agent Product = Model + Harness）。它选 Claude Code 当样本，不是因为「最火」，而是因为它展示了一个「完整且优雅的外壳」该长什么样——它不替模型做判断，不给模型套僵化的工作流，而是给模型工具、知识、上下文管理和权限边界，然后退到一边。

核心功能

为什么它值得认真读

很多 Agent 教程的问题在于「给你结论，不给你过程」。learn-claude-code 反过来了：每章只隔离一个机制，配一个能直接运行的 code.py，让你看到这个机制单独长什么样。到 s 15，再把前面积累的机制重新接回同一个运行时；s 17 用「目标门禁」收尾——一个独立的评估器审视每次「想停」的判断，把没完成的工作送回同一个 agent loop。

这种「循环不变，机制生长」的讲法，把 Agent 外壳从一个黑盒变成了可以逐层拆解、逐层复现的东西。它甚至内置了防御性工程细节：比如 s 17 里 DEFAULT_STOP_HOOK_BLOCK_CAP = 8（停止拦截上限）和命令 DENY_LIST，这些才是生产环境里真正让人头疼的地方。

上手路径

1. 克隆 + 装依赖：git clone 后 pip install -r requirements.txt，依赖只有 anthropic、python-dotenv、pyyaml 三项。
2. 配一个 API Key：配置 ANTHROPIC_API_KEY 和 MODEL_ID（默认示例是 claude-sonnet-4-6）。
3. 从 s 01 跑起：python s01_agent_loop/code.py 看一个最小 agent loop，然后逐章往下走。

值得特别提的是它的模型接入方式：所有 code.py 都通过 Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL")) 初始化，.env.example 里内置了 MiniMax、GLM/智谱、Kimi/Moonshot、DeepSeek 的 Model ID 和 Base URL 对照表。这意味着你可以在国内网络环境下，用国产模型来跑这套课程，不用非得用 Anthropic 官方 API。如果你对「Agent 技能（Skill）」这个配套概念还不熟，可以先看我们之前整理的 Datawhale 开源 AI Skill 库，它讲的是不会写代码的人怎么用现成 Skill，正好和这套「自己造」的课程形成互补。

适合谁

• 想真正理解 Agent 底层的中级 Python 开发者：学过 LangChain 但卡在「Agent 到底怎么动起来」。
• 想自建编码智能体的小团队：17 课就是一张现成的架构地图。
• 对 Claude Code 设计好奇的人：它拆的就是 Claude Code 的机制。

不适合谁

• 只想快速用现成 Agent 的人：这套是「造轮子」教程，不是「用轮子」教程。
• 零 Python 基础：虽然依赖精简，但需要能读懂 code.py 里的异步和工具分发逻辑。

替代项目或工具

风险与限制

• License：MIT，商用友好。
• 项目活跃度：17 课轨道是当前规范版本，但仓库有遗留 12 课轨道（docs/），阅读时要注意别跨轨道混用章节编号。
• 技术门槛：理解 s 13 团队协作、s 17 目标循环需要一定的 Agent 工程基础。
• 模型依赖：虽然支持国产模型接入，但部分机制（如 s 17 的评估器）对模型能力有要求，弱模型跑起来效果可能打折。

FAQ

这个项目可以商用吗？

可以，MIT 协议。学完还可以走它指出的产品化路径——用 npm i -g @shareai-lab/kode 装它的 Kode Agent CLI，或用 Kode Agent SDK 嵌入自己的应用。

新手能不能直接使用？

能，门槛很低。依赖只有三个 Python 包，配一个 API Key 就能从 s 01 跑起。但要有 Python 基础，能读懂异步和工具分发的代码。

它和直接用 Claude Code 有什么区别？

Claude Code 是「用」的成品，learn-claude-code 是「拆解」它的教学仓库。前者让你快速干活，后者让你理解它为什么这么设计——适合想自己造一个类似 Agent 的人。

参考来源

• GitHub: shareAI-lab/learn-claude-code（README、各章 README）
• GitCode 博客《learn-claude-code 实战解读：从 0 到 1 构建 Claude Code 式 Agent 外壳的 17 个 Harness 机制》2026-09-05