26.7K 星标！Learn Claude Code 12 节课手搓 Cursor，AI 编程 Agent 原理全拆解

AI应用案例
1

用 Claude Code、Cursor 写代码时，你是否曾惊叹于 AI 自动改文件、debug、执行命令的神奇，却对其底层原理一无所知？这款 GitHub 标星 26.7K + 的开源教程Learn Claude Code，堪称 AI 编程 Agent 的 “解剖教科书”—— 用 12 节循序渐进的课程，从最小循环到多 Agent 协作，层层拆解 AI 编程助手的核心机制，每节课都配套可运行的 Python 代码，让你从零到一理解原理，甚至亲手打造属于自己的 AI 编程 Agent！

5073445c01b41e888fc230b4130b1f97
5073445c01b41e888fc230b4130b1f971200×816 69.3 KB

一、Learn Claude Code：不止会用，更要懂原理

Learn Claude Code 是 shareAI-lab 开源的 AI 编程 Agent 教学项目，核心目标是打破 AI 工具的 “黑盒魔咒”，让开发者从根本上理解 “AI 编程助手到底是怎么工作的”。它的爆红并非偶然，而是精准击中了开发者的核心痛点：只会用工具却不懂原理，就无法判断 AI 的能力边界，遇到问题也无从优化。

核心洞察：所有 AI 编程 Agent，底层都是同一个循环

项目最犀利的发现的是：无论 Claude Code、Cursor 这类工具多复杂，其底层核心都是一个极简循环 —— 用户发送消息→模型判断是否调用工具→调用工具执行任务→将结果回传给模型→循环直至任务完成。

bdb10e735cd9211e0b539a49bd092252
bdb10e735cd9211e0b539a49bd0922521112×696 24.3 KB

这个最小 Agent 内核仅需不到 30 行代码就能实现，而我们看到的规划、子任务拆分、上下文管理、多 Agent 协作等高级功能，都是在这个基础循环上层层叠加的 “增强机制”。12 节课就对应 12 层增强，从 “一个循环 + 一个工具” 的极简 Agent，逐步进化到能团队协作的复杂系统。

三大核心优势

  1. 循序渐进，逻辑清晰：每节课只新增一个机制，不贪多求全，从核心循环到多 Agent 协作，复杂度逐步提升，有 Python 基础就能跟上；

  2. 心智模型优先：先讲问题本质，再给解决方案，配 ASCII 图解和最小可运行代码，不死记硬背，真正理解 “为什么这么设计”；

  3. 多端适配，上手零门槛：配套交互式 Web 平台（支持中、英、日三国语言），提供步骤图解、源码查看器，还能本地运行代码，理论与实践结合；

  4. 落地性强：学完即可掌握 Agent 开发核心能力，还能直接使用作者配套的开源工具，快速落地实际项目。

二、12 节课完整路线：从单 Agent 到团队协作，层层递进

教程按 “核心基础→规划与知识→持久化→多 Agent 协作” 分为四个阶段，每节课都有明确的核心目标和一句 “灵魂 motto”，让学习方向更清晰：

第一阶段：核心循环（第 1-2 节）—— 搭建 Agent 的 “发动机”

聚焦 Agent 的最基础构成，搞定 “能运行” 的核心逻辑：

  1. s01：The Agent Loop

    • 核心 motto：“One loop & Bash is all you need”（一个循环 + 一个工具 = 一个智能体）

    • 核心内容：实现最极简的 Agent 循环 ——while 循环 + 工具调用，这是所有 AI 编程 Agent 的底层骨架。用户发送消息后，模型持续判断是否需要调用工具，执行后将结果回传，直到任务完成。

    • 关键代码：不到 30 行实现完整循环，理解 “模型 - 工具 - 用户” 的交互逻辑。

  2. s02：Tool Use

    • 核心 motto：“加一个工具，只加一个 handler”

    • 核心内容：设计工具调度系统，新增工具时无需修改核心循环，只需注册一个处理函数（handler），通过 dispatch map 实现工具的灵活扩展，比如新增文件操作、命令执行工具。

第二阶段：规划与知识（第 3-6 节）—— 让 Agent“会思考、不遗忘”

解决 Agent“无计划、易失忆” 的问题，提升任务完成率和稳定性：

3. s03：TodoWrite

  • 核心 motto：“没有计划的 agent 走哪算哪”

  • 核心内容：新增计划机制，Agent 执行任务前先列出步骤清单，避免盲目操作，让复杂任务的完成率直接翻倍，比如写代码前先规划 “需求分析→架构设计→编码→测试” 步骤。

  1. s04：Subagents

    • 核心 motto：“大任务拆小，每个小任务干净的上下文”

    • 核心内容：大任务拆分后，为每个子任务创建独立的子 Agent 和专属 messages ，避免不同任务的上下文相互污染，比如将 “开发 + 调试” 拆分为两个子 Agent。

  2. s05：Skills

    • 核心 motto：“用到什么知识，临时加载什么知识”

    • 核心内容：知识按需加载，通过 tool_result 将所需技能注入上下文，而非一开始就把所有知识塞进 system prompt，避免信息过载。结合实战验证的 “200 行规则”，技能入口点严格控制在 200 行内，确保模型高效处理。

  3. s06：Context Compact

    • 核心 motto：“上下文总会满，要有办法腾地方”

    • 核心内容：实现三层上下文压缩策略（元数据→技能入口→引用文件），移除冗余信息，保留关键逻辑，让会话可以无限延续，避免大项目开发时上下文溢出。

第三阶段：持久化（第 7-8 节）—— 让 Agent“记住进度、不卡顿”

解决 “任务中断丢失、慢操作阻塞” 的问题，适配长期项目：

7. s07：Tasks

  • 核心 motto：“大目标要拆成小任务，排好序，记在磁盘上”

  • 核心内容：将拆分后的小任务持久化到磁盘，形成任务图，即使 Agent 重启也能恢复进度，为多 Agent 协作打下基础。

  1. s08：Background Tasks

    • 核心 motto：“慢操作丢后台，agent 继续想下一步”

    • 核心内容：用守护线程运行慢操作（如大型文件编译、数据下载），完成后通过通知注入结果，Agent 无需等待，可继续处理其他任务，提升并发效率。

第四阶段：多 Agent 协作（第 9-12 节）—— 从 “单打独斗” 到 “团队作战”

实现多 Agent 分工协作，搞定复杂大型项目：

9. s09：Agent Teams

  • 核心 motto：“任务太大一个人干不完，要能分给队友”

  • 核心内容：创建持久化的 Agent 团队，每个 Agent 有明确分工（如前端、后端、测试），通过异步邮箱实现消息互通，比如让前端 Agent 负责界面开发，后端 Agent 负责接口实现。

  1. s10：Team Protocols

    • 核心 motto：“队友之间要有统一的沟通规矩”

    • 核心内容：定义 Agent 团队的通信协议，用 “请求 - 响应” 模式规范协作流程，避免沟通混乱，比如任务分配、结果同步的统一格式。

  2. s11：Autonomous Agents

    • 核心 motto：“队友自己看看板，有活就认领”

    • 核心内容：实现自组织协作，Agent 主动扫描任务看板，根据自身职责认领任务，无需人工分配，比如测试 Agent 发现 bug 后自动认领调试任务。

  3. s12：Worktree + Task Isolation

    • 核心 motto：“各干各的目录，互不干扰”

    • 核心内容：为每个 Agent 分配独立的工作目录（worktree），通过 ID 绑定任务与目录，避免多 Agent 操作同一文件导致冲突，比如前端 Agent 和后端 Agent 分别在各自目录开发。

三、快速上手：5 分钟跑通第一个 Agent

教程的本地运行流程极其简单，有 Python 基础就能快速启动：

  1. 克隆项目

    bash

    运行

    git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code

  2. 安装依赖

    bash

    运行

    pip install -r requirements.txt

  3. 配置 API Key

    bash

    运行

    cp .env.example .env
# 编辑.env文件，填入你的ANTHROPIC_API_KEY

  4. 开始学习

    从第一节课开始，逐步运行代码，观察每新增一个机制后的变化：

    bash

    运行

    # 运行第1节课：核心循环
python agents/s01_agent_loop.py
# 逐步推进到第12节课：多Agent目录隔离
python agents/s12_worktree_task_isolation.py
# 运行完整版（包含所有机制）
python agents/s_full.py

  5. 体验交互式 Web 平台

    想直观查看步骤图解和源码？启动 Web 端：

    bash

    运行

    cd web
npm install
npm run dev

    打开浏览器访问http://localhost:3000，选择中文界面，即可通过可视化方式学习每个机制的原理和代码。

四、从学习到落地：两款配套工具直接用

学完原理后，作者还提供了两款落地工具，无需从零开发即可享受 Agent 能力：

  1. Kode Agent CLI

    • 功能：开箱即用的开源编程助手 CLI，支持技能扩展和 LSP（语言服务器协议），Windows、Linux、macOS 全兼容。

    • 安装：npm i -g @shareai-lab/kode

    • 亮点：可接入 GLM、MiniMax、DeepSeek 等开源模型，摆脱对闭源模型的依赖。

  2. Kode Agent SDK

    • 功能：轻量级 Agent 开发库，无 “每个用户一个进程” 的开销，可嵌入后端、浏览器扩展、嵌入式设备等任何运行时。

    • 优势：相比官方 Claude Code SDK，更轻量化、兼容性更强，适合二次开发和集成到自有项目。

五、为什么值得学？—— 开发者的 “Agent 通透指南”

对开发者而言，Learn Claude Code 的价值远不止 “学会搭建 Agent”：

  • 打破黑盒认知：学完后能清晰判断 AI 编程助手的能力边界，遇到 “抽风” 问题时知道如何优化（比如调整上下文压缩策略、拆分任务）；

  • 通用底层逻辑：无论后续学习 OpenClaw、LangChain 还是其他 Agent 框架，核心原理都相通，一通百通；

  • 从 “使用者” 到 “创造者”：掌握 Agent 开发能力，可根据自身需求定制工具，比如为特定开发场景（如区块链、AI 绘图）打造专属 Agent；

  • 实战导向：每个机制都源于真实开发痛点，代码可直接复用，学习成本低、落地见效快。

项目开源地址

如果你不想只做 AI 工具的 “被动使用者”，想真正搞懂 AI 编程 Agent 的底层逻辑，甚至创造自己的工具，这款 26.7K 星标的教程绝对值得入手。12 节课层层递进，从极简循环到多 Agent 协作，让你彻底摆脱 “知其然不知其所以然” 的困境，成为懂原理、能落地的 Agent 开发者！

2

有点意思啊这教程

3

有点意思但先观察看看

4

看过这项目 确实讲得透