5000行手写一个Claude Code：claude-code-from-scratch项目全景解读（15章Coding Agent教程路线图）
【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch
Claude Code 的源码有 50 万行，读不动？claude-code-from-scratch 是一个从零复现 Claude Code 核心架构的开源学习项目：用约 5000 行 TypeScript / Python 代码，配合 15 章分步教程，带你亲手写出一个 Coding Agent——Agent 循环、13 个工具、权限系统、记忆召回、多 Agent、MCP 集成全部覆盖。本文带你走一遍这张教程路线图，看看它怎么把"几十万行"拆成"几千行"。
🚀 项目是什么：用一台卡丁车理解汽车
先说清楚这个项目不是 demo，而是一份分步教程：
真实的 Claude Code 把核心循环包在 50 万行 TypeScript 里——66 个工具、React/Ink 终端界面、MCP 协议、OAuth、多代理系统。直接翻这些代码，很容易淹死在边界情况里，读完还是说不清那个循环长什么样。
claude-code-from-scratch 反过来做：把那个循环单独拎出来，用最小代码重造一遍，一块一块搭。起点是十几行只会聊天的循环，每一章补一块能力，每一块都能单独跑起来。就像用一台卡丁车理解汽车——引擎、方向盘、刹车都在，空调音响先不装，但每一颗关键的螺丝都拧得清清楚楚。
| 关键数字 | 说明 |
|---|---|
| ~5000 行 | Python 版代码量（TypeScript 版 ~5500 行），互为镜像 |
| 15 章 | 从「只会聊天」一路造到「自主干活」 |
| 13 个工具 | 文件读写编辑、Shell、搜索、WebFetch、技能、子 Agent、Plan Mode |
| 0 个 API Key | 每章代码用本地 mock 模型就能跑，改一行立刻知道对不对 |
| MIT 协议 | 学习项目，与 Anthropic 无关联，仅参照公开可观察行为 |
核心一句话：传统程序里下一步做什么由程序员用if/else写死；Coding Agent 反了过来——下一步由模型决定，代码只负责把循环转起来、把工具递过去。这一个反转，就是 coding agent 和普通聊天机器人的全部区别。
📖 15 章教程路线图：三个 Phase 逐级点亮能力
完整章节列表见 docs/00-introduction.md。教程分三个阶段：
Phase 1：构建一个可用的 Coding Agent（第 1–7 章）
| 章节 | 这一章之后，agent 能…… | 对应源码 |
|---|---|---|
| 1. Agent Loop | 调用工具、把结果喂回自己，不再只是聊天 | src/agent.ts |
| 2. 工具系统 | 读写文件、跑 Shell、搜代码，真正动手改项目 | src/tools.ts |
| 3. System Prompt | 知道自己在什么系统、什么目录、什么 Git 状态下干活 | src/prompt.ts |
| 4. CLI 与会话 | 有交互命令行，对话能存盘、--resume接着聊 | src/cli.ts |
| 5. 流式输出 | 一边生成一边显示，还能接 OpenAI 兼容模型 | src/agent.ts |
| 6. 权限与安全 | 危险操作先问一句，deny 规则拦得住越界 | src/tools.ts |
| 7. 上下文管理 | 对话太长自动 4 层压缩，跑几十轮不撑爆窗口 | src/agent.ts |
Phase 2：进阶能力（第 8–12 章）
| 章节 | 这一章之后，agent 能…… | 对应源码 |
|---|---|---|
| 8. 记忆系统 | 跨会话记住偏好和项目事实，用得上时自己捞出来 | src/memory.ts |
| 9. 技能系统 | 常用操作打包成可复用技能，/commit随用随调 | src/skills.ts |
| 10. Plan Mode | 先只读地拿出方案，批准了再动手 | src/agent.ts |
| 11. 多 Agent | 任务太大就 fork 一个子 Agent 去啃，啃完带回结果 | src/subagent.ts |
| 12. MCP 集成 | 接上外部工具服务器，工具集能往外扩 | src/mcp.ts |
Phase 3：验收与自主运行（第 13–15 章）
| 章节 | 这一章之后，agent 能…… | 对应源码 |
|---|---|---|
| 13. 架构对比 | 和真实 Claude Code 逐项对照，看清最小实现差在哪 | 全局 |
| 14. 功能测试 | 22 个手动场景 + 自动化集成测试逐项验收 | test/ |
| 15. 自治与续跑 | /goal追目标、/loop定时重投、Auto Mode 分类器逐动作裁决 | src/autonomy.ts |
🏗️ 核心架构全景：一个主循环 + 12 个模块
搭到最后，各部件是这样接的：用户输入 → CLI 交给 Agent Loop → 模型决定调哪个工具 → 代码执行完把结果喂回去 → 循环到模型说「做完了」。
agent.ts是整台发动机的引擎（约 2169 行），组装消息、调 API、编排工具、压缩上下文、控制预算全在这儿；其余 11 个文件各管一摊，规模都不大：
| 模块 | 行数 | 管什么 |
|---|---|---|
| agent.ts | ~2169 | Agent 主循环：流式执行、4 层压缩、预算、Plan Mode、自治三件套 |
| tools.ts | ~884 | 13 个工具 + 权限门禁 + mtime 防护 + 延迟加载 |
| autonomy.ts | ~464 | /goal评估器、/loop调度、Auto Mode 分类器 |
| cli.ts | ~416 | CLI 入口、参数解析、REPL 交互 |
| memory.ts | ~392 | 4 类型记忆 + 语义召回 + 异步预取 |
| 其余 7 个模块 | 41–277 | mcp.ts、prompt.ts、ui.ts、subagent.ts、skills.ts、session.ts、frontmatter.ts |
Python 版是同一套结构的完整镜像，放在 python/mini_claude/ 包里，文件一一对应（agent.py、tools.py……），学哪门语言都能跟。
⚡ 最大亮点：每一章的代码都能跑，且不用 API Key
读代码最怕读不懂又跑不起来。这个项目的解法很巧妙——steps/ 目录下为每个代码章节都留了一份能单独运行的最小实现快照：
node steps/run.mjs --list # 列出所有能跑的章节 node steps/run.mjs 7 # 跑第 7 章：对话变长后自动把旧消息压成摘要 node steps/run.mjs 7 --diff # 只看这一章比上一章多写的那几行 node steps/run.mjs 7 --py # 换成 Python 版输出是本地 mock 模型真跑出来的（不联网、不用 key）；想拿自己的 prompt 连真实模型，加个--live就行。而且每章的代码、文档里的代码块、跑出来的输出，全部从 steps/canonical/ 同一份源码生成——不会出现"文档说的和代码对不上"。
🚀 快速开始：五分钟跑起一个迷你 Claude Code
git clone https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch cd claude-code-from-scratch npm install && npm run build export ANTHROPIC_API_KEY="sk-ant-xxx" # 也支持 OpenAI 兼容格式 npm start # 交互式 REPL 模式Python 版则是在 python/ 目录执行pip install -e .后运行mini-claude-py。启动后可以试一句read src/agent.ts and explain the main loop，看它自己读文件、自己讲。
命令行还有丰富的开关：--yolo跳过确认、--plan只分析不修改、--auto分类器自动裁决权限、--max-cost 0.50 --max-turns 20预算控制——每个开关背后都对应教程里的一章。
⚖️ 和真正的 Claude Code 差在哪？
对比表见 docs/13-whats-next.md 与 README.md。简化版：
| 维度 | Claude Code | mini-claude |
|---|---|---|
| 代码量 | 50 万+ 行 | ~5500 行（TS）/ ~5000 行（Python） |
| 工具数量 | 66+ 内置工具 | 13 个工具 |
| 权限系统 | 7 层 + AST 分析 | 5 种模式 + 声明式规则 + 正则检测 |
| 多 Agent | Sub-Agent + Coordinator + Swarm | Sub-Agent fork-return |
项目刻意没实现 Hooks 钩子系统、Coordinator/Swarm 模式和 LSP 集成——第 13 章解释了每一项"为什么不做"：它们更多是 prompt engineering 或协议工程问题，对理解 agent 原理帮助不大。读完 15 章，你手里拿的不只是几千行代码，而是一张能直接对照生产级实现的架构地图。
💬 加入社区，一起从零造轮子
项目由 Windy3f3f3f3f 等人贡献（MIT 协议），配套 QQ 交流群「AI Agent 工坊」（群号 1090526244），适合边学边交流。如果你正被"Coding Agent 到底怎么工作"这个问题困扰，这张 15 章的路线图，可能是目前成本最低的一条路：每章几百行，跑起来只需要一条命令。
【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
