一个面向工程实现者的中文项目：系统拆解 Claude Code 的架构、运行机制与产品设计，并把这些内容整理成一套可落地的构建教程。
这个项目的目标不是机械搬运源码，也不是做零散的逆向笔记，而是回答一个更有价值的问题：
如果你要从零做一个真正可用的 Claude Code 风格 agentic CLI，你应该如何设计它、拆解它、实现它。
这个仓库聚焦三件事：
- 基于真实源码证据，梳理 Claude Code 的核心系统结构
- 产出一套中文优先、工程导向的系列教程
- 为实现一个严肃的 Claude Code-like 产品提供设计参考与实现路线
项目覆盖的主题包括：
agent loop与模型调用主循环- 上下文管理与消息拼装
- 工具系统、tool-call 契约与执行编排
- 权限控制与命令执行边界
- 记忆系统、持久化与状态回流
- subagent、task、session 等多阶段工作流
- React/Ink 终端 UI
- MCP、插件、IDE bridge 与外部系统集成
这个项目主要写给以下读者：
- 想做 AI Coding Agent、Agent CLI、终端助手的工程师
- 想理解 Claude Code 为什么“像一个真正的软件系统”而不是“一个聊天壳”的读者
- 想基于真实架构线索而不是二手总结来设计产品的人
如果你的目标只是快速拼一个 demo，这个项目会显得偏重。
推荐按下面顺序阅读：
- 总览：先建立对 Claude Code 整体结构的全局地图
agent loop：理解系统最核心的运行主线- 上下文、工具、权限、记忆、subagent：沿着主循环逐步展开关键模块
- CLI 入口、终端 UI、MCP、插件、持久化：补齐外围系统
- 最小克隆与产品化：把理解转成实现路线
当前教程总纲见：
tutorial/how-to-build-a-claude-code.md
如果你想直接开始阅读正文，请先看：
tutorial/01-overview.mdtutorial/02-agent-loop.mdtutorial/05-prompt-cache.md
当前研究路线图见：
notes/00-roadmap.md
整套教程不按源码目录机械展开，而按系统运行主线展开：
- 先给读者一个整体 overview
- 再从
agent loop切入 - 再顺着主循环拆出上下文管理、工具系统、权限、记忆、subagent、任务系统
- 最后再覆盖终端 UI、MCP、插件、持久化与工程化问题
这样组织的原因很简单：只有先建立全局地图，再抓住主循环，后面的模块解释才不会散。
本项目对不同信息源做明确分层：
- 主要源码参考：
../claude-code-sourcemap/restored-src/src - 运行时验证材料：
../extracts/
使用原则：
- 默认以 restored source 作为源码级参考
- 只有在验证本机安装版本行为、确认能力存在与否、排查版本差异时，才使用
extracts/ - 做结论时尽量引用具体源码路径、字符串、控制流或命令行为
- 明确区分“源码确认”“运行时确认”“合理推断”
tutorial/: 面向读者的教程正文与结构化章节notes/: 源码阅读笔记、架构拆解、控制流记录、开放问题README.md: 项目入口、阅读指南、方法论与导航
当前阶段，所有文档以 Markdown 为主。
这不是临时凑合，而是一个有意选择：
- Markdown 最适合快速迭代教程内容
- 便于直接版本控制、review 与交叉引用
- 等内容成熟后，再决定是否迁移到静态站点或文档站
换句话说，当前的 .md 文档就是正式内容，不是草稿容器。
- 中文优先，必要时保留英文术语并给出中文解释
- 以架构、控制流、实现取舍为主线
- 面向严肃工程实现，而不是玩具 demo
- 不平铺源码目录，优先解释真正驱动系统运转的关键链路
- 每篇文章尽量同时回答两个问题：
- Claude Code 这一部分看起来是怎么工作的
- 如果你自己实现，应该怎么做得更干净
项目目前处于内容框架建立阶段，已经明确：
- 中文优先的教程方向
- overview ->
agent loop-> 模块展开 的文章主线 - 源码参考与运行时验证的证据边界
接下来会优先补齐：
- overview 章节
agent loop主线章节- 围绕主循环的核心模块章节
- 不神化产品，也不低估工程复杂度
- 不把零散源码观察误写成系统性结论
- 不把运行时提取物当成主源码来阅读
- 不为了“像教程”而牺牲技术准确性
如果你也在研究 AI Coding Agent、Agent Runtime 或 CLI Agent 架构，这个项目的目标是成为一个足够扎实、可引用、可实现的中文参考入口。