5000 行复刻 Claude Code：一份能跑起来的架构教程，而不是另一个 demo
Build your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓
秒懂
- 它是什么？
- claude-code-from-scratch 用约 5000 行 TypeScript 或 Python 从零实现 coding agent 的核心架构，并以 13 章教程逐行讲解。它面向想理解 agent 内部机制、而非只想调用 API 的开发者，但它的定位是教学，不是生产工具。
- 适合谁用？
- 想搞懂 coding agent 内部机制、愿意亲手写几千行代码的开发者，这个项目值得花时间。它把 agent loop、工具调度、上下文压缩这些抽象概念拆成可运行的章节，每章都能用 mock 模型跑通，降低了理解门槛。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 69 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
为什么有人要手写一个 Claude Code
Claude Code 开源了几十万行代码，但代码量本身成了阅读障碍。你很难从几十万行里看出 agent 的核心逻辑在哪里，哪些机制是关键的，哪些是为了工程健壮性堆出来的。这个项目用约 5000 行 TypeScript 或 Python 分别实现一套可运行的 coding agent，并配了 13 章教程。它的目标读者不是想用 agent 的人，而是想理解 agent 工作原理的人。教程里每一章都对照 Claude Code 的公开可观察行为，讲清楚差异在哪。这不是一个让你日常写代码的工具，它是一份带可运行代码的教材。
十三章节里藏着哪些关键机制
教程分两个阶段。第一阶段构建一个可用的 coding agent，从 agent loop 开始，然后是工具系统、system prompt、CLI 与会话、流式输出、权限与安全、上下文管理。第二阶段加入进阶能力，包括记忆系统、技能系统、plan mode、多 agent、MCP 集成。每个章节都对应 Claude Code 里的具体模块，比如第 2 章工具系统对照的是 Claude Code 的 66 个工具，第 7 章上下文管理对照的是 compact 目录。第 14 章是功能测试，列了 22 项手动测试覆盖全部功能。这样的结构意味着你可以按顺序读，也可以跳到自己关心的机制。
每章都能跑，这是教程最实在的设计
读代码最怕读不懂又跑不起来。项目给每个代码章配了最小实现，一条命令就能跑，不需要 API key。本地用 mock 模型驱动，不联网。命令是 node steps/run.mjs 7，跑第 7 章会看到旧消息被压成摘要。加 --diff 参数，只显示这一章比上一章多写的代码。加 --py 换成 Python 版。README 里强调，每章的代码、文档贴的代码块、跑出来的输出，全部从同一份源码生成，不会出现文档和代码对不上的情况。想连真模型试，加 --live 就行。这个设计解决了教程类项目常见的痛点，代码和讲解脱节，读者照着敲却跑不出预期结果。
跑起来之后，它是个什么样的 agent
安装后有 TypeScript 和 Python 两个版本。TS 版需要 npm install && npm run build，Python 版需要 3.11+，用 pip install -e . 安装。两个版本都提供 mini-claude 或 mini-claude-py 命令行入口。启动后是交互式 REPL，支持 /clear、/cost、/compact、/memory、/skills 这些命令。参数设计模仿了 Claude Code 的常用选项，比如 --yolo 跳过安全确认，--plan 只分析不修改，--accept-edits 自动批准文件编辑，--dont-ask 用于 CI 模式自动拒绝需确认的操作，--max-cost 限制费用，--max-turns 限制轮次。模型默认是 claude-opus-4-6，可以通过环境变量 MINI_CLAUDE_MODEL 或命令行 --model 修改，命令行优先级更高。后端支持 Anthropic 格式和 OpenAI 兼容格式，通过环境变量自动识别，也支持自定义 base URL。
安全与权限：五模式设计是亮点，也是局限
第 6 章专门讲权限与安全，实现了 5 种模式加声明式规则和危险检测。对照的是 Claude Code 的 permissions 目录，那个目录有 52KB 代码。5 模式具体是哪五种，README 没有逐一列出，但从命令行参数能看出端倪：默认交互式确认，--yolo 跳过确认，--dont-ask 自动拒绝，--accept-edits 只自动批准编辑。这个设计把权限控制从简单的 yes/no 提升到了策略层面，你可以声明规则，让 agent 在规则内自主行动。但要注意，这是一个教学实现，它的危险检测逻辑远不如 Claude Code 完整。在真实项目上跑 --yolo 之前，你得清楚自己承担了全部风险。
上下文压缩与记忆：agent 长会话的命门
第 7 章讲上下文管理，实现了 4 层压缩和大结果持久化。第 8 章讲记忆系统，有 4 种记忆类型加语义召回和异步预取。这两章是 coding agent 区别于普通聊天机器人的核心。长对话里，上下文窗口很快会被工具输出填满，不压缩就得丢弃信息，压缩得不好又会丢失关键细节。项目用 4 层压缩来分层处理，把旧消息逐步压成摘要。记忆系统则让 agent 跨会话保留信息，比如记住你的代码风格或常用命令。这两块机制在教程里有对应的可运行代码，你可以实际观察压缩前后 token 的变化。但 README 没有给出压缩算法的具体实现细节，比如摘要用什么模型生成、语义召回用什么向量库，这些需要读代码或教程正文才能确认。
它和 Claude Code 的真实差距在哪里
项目在声明里明确说，这是照着 Claude Code 的公开可观察行为和通用 agent 写法来做，不保证和真实内部实现一致。这是个重要的诚实声明。Claude Code 有几十万行代码，这个项目用 5000 行复刻核心，意味着大量工程细节被省略。比如 Claude Code 有 66 个工具，这里只实现了 13 个。多 agent 架构、MCP 集成这些都有，但实现深度必然不同。教程的价值在于让你理解架构骨架，而不是让你掌握 Claude Code 的每一个实现细节。如果你需要的是和 Claude Code 完全一致的行为，这个项目会误导你。如果你需要的是理解 coding agent 的基本运作机制，它比读源码高效得多。
替代方案：直接读源码，还是看这个教程
想理解 Claude Code，你有三条路。一是直接读 Anthropic 开源的几十万行代码，信息最全但门槛最高。二是读这个项目的姊妹项目 How Claude Code Works，那是 12 篇专题共 33 万字的源码级解析，不写代码，纯文字讲解。三是用 claude-code-from-scratch，边写边学，每章动手跑代码。三条路的差异在于抽象层级和参与度。直接读源码是自底向上，容易被细节淹没。How Claude Code Works 是自顶向下，先有全局框架再深入细节。这个教程是中间路线，用最小实现让你建立直觉，再对照真实架构看差异。如果你已经读过 How Claude Code Works，觉得需要动手验证理解，这个项目是合适的下一步。如果只是想快速了解架构，直接读专题文章更省时间。
编辑结论
想搞懂 coding agent 内部机制、愿意亲手写几千行代码的开发者，这个项目值得花时间。它把 agent loop、工具调度、上下文压缩这些抽象概念拆成可运行的章节，每章都能用 mock 模型跑通，降低了理解门槛。不适合把 coding agent 当黑盒工具用的人，它的功能远不如 Claude Code 完整，也没有生产级的安全与稳定性保障。采用前先确认三件事：你的 Python 版本不低于 3.11，你愿意接受教程中明说的与真实 Claude Code 内部实现的差异，以及你需要的功能是否在 13 章覆盖范围内。项目以 MIT 协议发布，代码可自由使用，但注意 Claude Code 是 Anthropic 的商标，本项目与 Anthropic 无关，若商用需自行评估商标与命名风险。
社区笔记