从零手写 Claude Code：理解 Coding Agent 的最佳教程

Claude Code From Scratch 是一个从零手写 Claude Code 的分步教程项目，用约 5000 行代码（TypeScript + Python 双版本）完整实现了 Claude Code 的核心功能：Agent Loop、工具系统、上下文压缩、记忆系统、技能系统、多 Agent 和 MCP 集成。

---

痛点背景：Claude Code 的代码太难读了

2024 年底，Anthropic 宣布 Claude Code 开源，代码量超过 50 万行。这个消息让开发者社区兴奋不已，但真正去读源码的人却发现门槛极高：

• 体量巨大：50 万行代码，涵盖 Agent、权限、CLI、UI、MCP、记忆、技能系统等多个子系统；
• 深度耦合：各模块之间相互引用，新手很难找到切入点；
• 工程化完善但学习不友好：TypeScript 类型嵌套、中间件层层包裹，理解核心逻辑需要大量时间；
• 黑盒行为多：Claude Code 有大量"公开不可观察"的行为——即无法从外部调用推断内部实现。

有没有一种方式，能让人用几千行代码就理解 Claude Code 的核心架构？

这个项目正是答案。

---

核心价值：为什么这是一个独特的学习资源？

不是 demo，是分步教程

市面上有很多"仿 Claude Code"的玩具项目，但大多只实现了基础的 Agent Loop，无法真正让人理解 Claude Code 的深度设计。

这个项目的定位是教程，13+ 章内容，每章都对应 Claude Code 的一个核心模块：

阶段	章节	内容	Claude Code 对照
Phase 1	1. Agent Loop	核心循环：LLM → 工具执行 → 循环	agent.ts ↔ query.ts
Phase 1	2. 工具系统	13 个工具 + mtime 防护 + 延迟加载	tools.ts ↔ Tool.ts (66个)
Phase 1	3. System Prompt	提示词工程 + @include 语法	prompt.ts ↔ prompts.ts
Phase 1	4. CLI 与会话	REPL、Ctrl+C、会话持久化	cli.ts ↔ cli.tsx
Phase 1	5. 流式输出	双后端 + 流式工具执行 + 并行执行	agent.ts ↔ api/claude.ts
Phase 1	6. 权限与安全	5 模式 + 声明式规则 + 危险检测	tools.ts ↔ permissions/ (52KB)
Phase 1	7. 上下文管理	4 层压缩 + 大结果持久化	agent.ts ↔ compact/
Phase 2	8. 记忆系统	4 类型记忆 + 语义召回 + 异步预取	memory.ts
Phase 2	9. 技能系统	技能发现 + inline/fork 双模式	skills.ts ↔ SkillTool/
Phase 2	10. Plan Mode	只读规划 + 4 选项审批工作流	agent.ts ↔ EnterPlanMode
Phase 2	11. 多 Agent	Sub-Agent fork-return 多 Agent 架构	subagent.ts ↔ AgentTool/
Phase 2	12. MCP 集成	JSON-RPC over stdio 连接外部工具	mcp.ts ↔ mcpClient.ts
Phase 2	13. 架构对比	完整对比 + 扩展方向	全局
Phase 2	14. 功能测试	22 项手动测试覆盖全部功能	test/

每章代码都能跑

这是项目最用心的设计：每个代码章都配有可单独运行的最小实现。

node steps/run.mjs --list     # 列出所有能跑的章节
node steps/run.mjs 7          # 跑第 7 章：对话变长时触发上下文压缩
node steps/run.mjs 7 --diff   # 只看这一章比上一章多写的代码
node steps/run.mjs 7 --py     # 换成 Python 版
node steps/run.mjs 7 --live   # 连真实 API 测试

所有输出都是真实运行出来的——不存在"文档和代码不一致"的问题。

双语言实现

每个功能都提供了 TypeScript 和 Python 两个版本，适合不同背景的学习者：

• TypeScript 版本：适合前端/全栈开发者，直接复用 Node.js 生态；
• Python 版本：适合 AI/ML 工程师，可与 LangChain、LlamaIndex 等框架结合。

---

核心架构解析

Agent Loop：最小可运行的循环

Claude Code 的核心是一个"LLM → 工具 → LLM"的循环。教程第一章就给出了一个最精简的实现：

while (true) {
  const response = await llm.chat(messages);
  if (response.content.type === 'text') {
    messages.push(response); // 继续对话
  } else if (response.content.type === 'tool_use') {
    const result = await executeTool(response.content);
    messages.push({ type: 'tool_result', content: result });
  }
}

上下文管理：4 层压缩机制

Claude Code 处理长对话的核心是上下文压缩。教程第七章详细拆解了 4 层压缩策略：

1. 摘要压缩：对话轮次过多时，将历史消息压缩成摘要；
2. 大结果截断：工具返回的大结果（文件列表、目录树）截断后持久化到磁盘；
3. 重要信息提取：从工具结果中提取关键信息，替换原始输出；
4. 选择性保留：保留最近的 N 轮对话 + 关键上下文，其余压缩。

记忆系统：让 Agent "记住"之前学到的

Phase 2 第八章实现了类似人类记忆的 4 类型系统：

• 工作记忆：当前会话内的短期信息；
• 语义记忆：跨会话的持久化知识（代码规范、技术偏好）；
• 情景记忆：之前处理过的类似任务；
• 前瞻记忆：未完成的任务和计划。

---

快速上手

TypeScript 版本

git clone https://github.com/Windy3f3f3f3f/claude-code-from-scratch.git
cd claude-code-from-scratch
npm install && npm run build
npm start                    # 交互式 REPL 模式
npm start -- --resume       # 恢复上次会话

Python 版本

cd python
pip install -e .
mini-claude-py              # 交互式 REPL

配置 API

export ANTHROPIC_API_KEY="sk-ant-xxx"
# 或 OpenAI 兼容格式
export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"

---

姊妹项目：How Claude Code Works

如果 5000 行还不够，作者还提供了姊妹项目 How Claude Code Works，12 篇专题、33 万字，从源码级别深度解析 Claude Code 的内部实现。两个项目配合使用，学习效果最佳。

---

总结

维度	评分
教育价值	⭐⭐⭐⭐⭐ 从 50 万行到 5000 行，文档 + 代码 + 可运行示例三位一体
实用性	⭐⭐⭐⭐ 教程级项目，但每章代码均可运行，可作为开发基础
代码质量	⭐⭐⭐⭐ 双语言版本，架构对照清晰
文档质量	⭐⭐⭐⭐⭐ GitHub Pages 在线教程 + 每章独立文档 + 视频演示
维护状态	⭐⭐⭐⭐⭐ 持续更新，与 Claude Code 开源版本同步跟进

适合人群：想深入理解 Coding Agent 架构的前端/后端开发者、AI 爱好者、想从零构建自己 Agent 工具的工程师。