learn-claude-code
shareAI-lab/learn-claude-code加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下，你拿到了一辆顶级跑车的钥匙——那是 Claude/GPT/Gemini 等大语言模型，拥有强大的推理和行动能力。但问题是：没有一辆合适的「载具」，再强的模型也只能在原地打转。这个仓库教你的，就是如何从零打造那辆载具——也就是 Agent Harness（智能体框架）。
这不是一门教你「如何使用 AI」 的课程，而是一门教你「如何构建让 AI 真正发挥作用的基础设施」的工程课。作者在 README 开篇就抛出了一个反直觉但极其重要的观点：Agency 来自模型训练，而非外部代码编排。这句话点出了整个项目的核心立场——Agent 的核心能力（感知、推理、行动）是模型在训练中学到的，代码的作用是给它一个舞台。
图1：shareAI-lab 项目头像
要理解这个项目的价值，必须先理解 Agent 的历史。README 中详细梳理了一条从 2013 年到 2024 年的技术进化线：
2013 年 DeepMind DQN 突破 Atari — 一个只接收原始像素和游戏分数的神经网络，在没有人工设计游戏规则的前提下，在 7 款 Atari 游戏中超越了所有此前算法。这是有记录以来最早引起广泛关注的通用 AI Agent 案例。
2019 年 OpenAI Five 征服 Dota 2 — 五个神经网络通过 10 个月内与自己对战了相当于 45,000 年的 Dota 2，最终在直播赛中 2-0 击败了世界冠军战队 OG，在后续公开竞技中胜率达到 99.4%。
2019 年 DeepMind AlphaStar 制霸星际争霸 II — 在信息不完全、实时决策的复杂环境中，AlphaStar 达到了玩家中的前 0.15%（宗师段位）。
2024-2025 年 LLM Agent 重塑软件工程 — Claude、GPT、Gemini 等大语言模型作为编程 Agent，阅读代码库、编写实现、调试故障、团队协作。其架构与前述所有 Agent 完全一致：一个经过训练的模型，放入一个环境，赋予感知和行动的工具。
作者用这条时间线要说明的核心结论是：Agency 是训练出来的，不是编出来的。这是理解整个项目定位的关键前提。
项目标题「Bash is all you need」本身就是一种宣言——它告诉你，这个仓库不需要复杂的容器编排，不需要 Kubernetes，甚至不需要 Docker。它用最少的工程基础设施，演示了 Agent 的核心工作原理。
用生活化的比喻：如果把 Agent 想象成一个有超能力的助手，模型是这个助手的大脑（经过训练），而 Harness 是这个助手的手和眼——它让大脑能够与环境交互：读取文件、执行命令、浏览网页、处理结果。
README 中用 Agent Loop 图示清晰展示了这一架构：
图2：Agent Loop 架构 — LLM 调用 → 工具执行 → 结果回传 → 循环
核心循环只有一行伪代码：
while stop_reason == "tool_use":
response = LLM(messages, tools)
execute tools
append results
这行代码道出了整个 Agent 工作流程的本质：将工具执行结果反馈给模型，直到模型决定停下来。
项目采用分主题（session）目录结构，共有 10 个递进的学习模块，每个模块对应一个核心 Agent 开发主题：
| 模块 | 主题 | 核心内容 |
|---|---|---|
| s01 | Agent Loop | 最基础的「提问→LLM→执行→结果→再提问」循环 |
| s02 | Tool Use | 让 Agent 调用外部工具（bash 命令、文件读取等） |
| s03 | Permission | Agent 执行敏感操作前的权限控制机制 |
| s04 | Hooks | 在关键节点注入自定义逻辑（生命周期钩子） |
| s05 | Todo Write | Agent 自主维护任务列表并持续推进 |
| s06 | Subagent | 主 Agent 调度子 Agent 实现并行/分层任务 |
| s07 | Skill Loading | 动态加载外部技能模块扩展 Agent 能力 |
| s08 | Context Compact | 长对话上下文压缩与摘要技术 |
| s09 | Memory | Agent 跨会话记忆持久化机制 |
| s10 | System Prompt | 系统提示词工程与角色设定 |
每个模块都包含 code.py（可运行的实现代码）和多语言 README 文档（含中文、英文、日文三个版本）。这种「代码 + 文档」的双轨结构，使它既是一个可运行的示例库，也是一本可以系统学习的教材。
从 agents/ 目录的结构来看，实际代码库分为 9 个 Python 模块：s01_agent_loop.py（Agent 循环）、s02_tool_use.py（工具调用）、s03_todo_write.py（任务列表管理）、s04_subagent.py（子代理）、s05_skill_loading.py（技能加载）、s06_context_compact.py（上下文压缩）、s07_task_system.py（任务系统）、s08_background_tasks.py（后台任务）和 s09_agent_teams.py（多 Agent 协作）。
项目选用 Python + Bash 作为主要技术栈，极简但不简陋。这两个工具的组合恰好覆盖了 AI 开发的两个核心场景：Python 处理模型调用、API 通信和复杂逻辑，Bash 处理系统级操作（文件 I/O、进程管理、命令行工具调用）。
核心依赖只有三个：anthropic（Anthropic 官方 SDK）、python-dotenv（环境变量管理）和 pyyaml（配置文件解析）。这种极简依赖策略使项目易于理解、安装和调试。
代码中大量使用注释和 ASCII 架构图来解释原理，降低了理解门槛。例如 s01_agent_loop.py 开头的图示清晰展示了 LLM → 工具执行 → 结果回传的循环关系。这种「代码即文档」的理念贯穿整个项目。
这个项目的目标用户是想要深入理解 Agent 内部工作原理的开发者，而非只想快速调用 API 的使用者。
入门要求：
不适合：
作为一个教学项目，它有明确的边界，不回避这些边界本身就是一个优点。
它不做容器化 — 没有 Dockerfile，没有 docker-compose，纯 Python 环境运行。对教学来说这是优点（减少复杂度），但对团队协作和生产部署来说是明显的短板。不同的开发环境可能遇到依赖冲突。
它不涉及模型训练 — 正如作者在 README 中强调的，Agent 的核心能力来自模型训练。这个项目只关注 Harness 层的工程实现，不涉及模型训练、微调或评测。
它不提供生产级错误处理 — 示例代码追求简洁明了，生产环境需要的重试机制、熔断器、监控告警等都不在讨论范围内。
学习曲线陡峭 — 虽然代码本身简洁，但背后的 Agent 设计理念、工具调用协议、上下文管理策略都需要一定的 AI 开发经验才能真正吸收。零基础用户可能会在初期感到「看懂了但不知道怎么用」。
这个项目目前 GitHub Star 数超过 62,000（截至 2026 年 5 月），Forks 超过 10,000，在 GitHub trending 上持续活跃。这种规模的关注度本身就说明了一件事：市场对「如何从零构建 Agent」的需求极其旺盛。
从更宏观的视角看，这个项目代表了一种趋势：AI 开发正在从「调 API 拼应用」向「搭框架做系统」演进。随着 Claude Code、GitHub Copilot 等 AI 编程工具的成熟，开发者越来越意识到：真正的壁垒不在于模型本身，而在于如何围绕模型构建可靠、可维护的工作流系统。
这类项目（如 LangChain、AutoGPT、 crews、Flowise 等）的共同特点是：它们都在尝试回答同一个问题——如何让 AI 模型从「能聊天」变成「能干活」。Learn Claude Code 的独特价值在于：它用最少的工程复杂度，展示了这一转变的核心机制，给学习者提供了最直接的路线图。
git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
pip install -r requirements.txt
# 配置 API Key
cp .env.example .env
# 编辑 .env，填入 ANTHROPIC_API_KEY=sk-ant-...
# 运行第一个 Agent 示例
python agents/s01_agent_loop.py
整个流程从安装到跑通第一个示例，熟练开发者通常不超过 10 分钟。