从零构建 Claude Code 式 AI Agent 执行框架教程

解决什么

当前 AI Agent 开发领域充斥着"无代码平台"和"可视化编排工具",它们宣称通过拖拽节点、串联 Prompt 就能"构建 Agent"。这个项目用一记重拳打破这种幻觉:Agent 的智能来自模型训练(如 GPT、Claude 的预训练和强化学习),而非外部代码编排。工程师的真正任务是构建"执行框架"(Harness)——让已有智能的模型能在特定环境(如代码编辑器、终端)中感知、推理和行动。

项目通过从零实现一个类 Claude Code 的微型 Agent 框架,教你理解 Agent 产品的本质:模型(驾驶员)+ 执行框架(车辆)。它用 Bash 和 Python 演示如何给模型提供工具(文件读写、Shell 执行)、知识(文档、API 规范)、观察接口(日志、Git diff)和权限控制(沙箱隔离),而不是试图用 if-else 逻辑"创造智能"。

为何火

7 万+ stars 背后是开发者对 Agent 底层原理的渴求。项目 README 开篇就用 DeepMind DQN(2013 年玩 Atari)、OpenAI Five(2019 年击败 Dota 2 世界冠军)、AlphaStar(2019 年达到星际争霸 2 宗师段位)等里程碑证明:所有 Agent 的智能都来自模型训练,而非周围的代码。这种"思维转变"击中了被 Prompt 编排工具误导的工程师痛点。

项目用"Bash is all you need"这句挑衅式口号,强调执行框架的本质是简单、原子化的工具组合,而非复杂的流程编排。它将 Agent 工程师的角色重新定义为"Harness Engineer"(执行框架工程师),明确职责边界:实现工具、管理上下文、控制权限,而非"创造智能"。这种清晰的定位让开发者从"Agent 炼金术"回归工程本质。

核心功能

项目是教学性质,核心内容包括:

1. 执行框架(Harness)设计模式:定义 Harness = 工具 + 知识 + 观察接口 + 行动接口 + 权限控制,用公式化方式拆解 Agent 产品的组成部分
2. 工具实现示例:演示如何用 Python 封装文件读写、Shell 执行、API 调用等原子化工具,强调"可组合、描述清晰"的设计原则
3. 上下文管理策略:展示如何按需加载领域知识(产品文档、架构决策记录),而非一次性塞满上下文窗口
4. 权限与安全边界:讲解沙箱隔离、审批流程、信任边界的实现思路,避免 Agent 失控
5. 思维框架纠偏:用历史案例(DQN、AlphaStar、OpenAI Five)和反面教材(无代码 Agent 平台)对比,强化"智能来自训练"的核心观念

安装

这是教学项目而非生产工具,使用方式是:

1. 克隆仓库:git clone https://github.com/shareAI-lab/learn-claude-code.git
2. 阅读 README 和代码示例,理解 Harness 设计模式
3. 根据示例代码(Python + Bash)自行实现或改造为生产环境的执行框架

项目未提供 Docker 或 pip 安装包,因为它是"教你造车"而非"给你一辆车"。开发者需要有 Python 基础和对 LLM API(如 Claude、GPT)的调用经验。

适合谁

• 被无代码 Agent 平台误导的开发者:想理解 Agent 底层原理,摆脱"拖拽节点就能造 Agent"的幻觉
• LLM 应用工程师:需要给 GPT/Claude 等模型构建生产级执行环境,学习工具设计、上下文管理、权限控制的最佳实践
• AI 产品经理:想理解"模型能力"与"工程实现"的边界,避免对 Agent 产品产生不切实际的期待
• 教学与培训场景:项目多语言 README(英文、中文、日文)和清晰的概念拆解适合作为 Agent 开发课程的教材

不适合:期待开箱即用工具的用户,或对 Python/Bash 完全陌生的初学者。

社区评价

HN 上有用户提问项目是否适合初学者,还是涵盖高级模式(如工具使用、Prompt 链)。从 README 内容看,项目更偏向思维框架纠偏而非具体技术实现细节——它用大量篇幅论证"智能来自模型训练"这一观点,但工具实现、Prompt 工程等细节需要开发者自行探索。

56 个 open issues 和 11,466 个 forks 显示社区参与度高,但也反映项目作为教学资源,用户在实际落地时遇到不少问题(如缺少完整示例代码、工具接口设计的具体实现等)。项目更像一篇"Agent 工程宣言"而非完整教程,需要读者有一定工程经验才能转化为生产代码。

选型对比

vs Claude Code(商业工具):Claude Code 是 Anthropic 的官方 Agent 产品,提供开箱即用的代码编辑、终端执行、浏览器控制能力。本项目是教你"如何从零实现类似功能",适合想理解底层原理或需要深度定制的团队,但不提供生产级稳定性和 UI。

vs LangChain/AutoGPT(开源框架):这些框架提供高层抽象(如 Chain、Agent Executor),但项目批评它们"过度工程化",用复杂的流程编排掩盖了 Agent 的本质。本项目主张"Bash is all you need",强调用简单、原子化的工具组合,而非庞大的抽象层。

vs 无代码 Agent 平台(如 Dify、Coze):项目直接将这类平台定义为"Rube Goldberg 机器"(过度设计的无用装置),认为它们只是"带 LLM 节点的 Shell 脚本",无法产生真正的自主行为。本项目适合想摆脱这类平台束缚、深入底层的开发者。

已知坑

1. 教学性质,非生产工具:项目未提供完整可运行的代码框架,更多是概念讲解和设计模式,需要开发者自行实现
2. 缺少具体实现细节:README 用大量篇幅论证"为什么",但"怎么做"(如工具接口设计、错误处理、并发控制)需要读者自行探索
3. 依赖外部 LLM API:项目假设你已有 Claude/GPT 等模型的 API 访问权限,中国大陆用户需要解决网络访问和 API Key 获取问题
4. 无沙箱实现示例:虽然强调权限控制的重要性,但未提供 Docker/虚拟机级别的沙箱隔离代码,生产环境需自行补充
5. 社区问题响应滞后:56 个 open issues 显示维护者可能无法及时回复所有问题,适合有自主解决能力的开发者

总结:这是一个"思维转变"项目而非"拿来即用"工具,适合有经验的开发者学习 Agent 底层设计哲学,但需要投入时间将概念转化为生产代码。