深入理解 Claude Code：从 0 到 1 构建 AI 智能体工作台
一、写在前面
作为一名常年和开发团队打交道的项目负责人，我对"AI 智能体"这个词，经历过三个阶段：
**第一阶段：将信将疑**
「不就是个高级点的聊天机器人吗？」
**第二阶段：浅尝辄止**
试了几个"AI Agent 平台"，拖拖拽拽搭个工作流，跑起来还行，但稍微复杂一点就各种报错，调整起来非常痛苦。
**第三阶段：醍醐灌顶**
直到我读到了 shareAI-lab 开源的 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) 仓库，才真正理解：**智能体的自主性来自模型训练，不是来自你画的流程图。**
这篇文章，我把这个仓库的核心内容，用项目经理能理解的语言讲清楚，并给出实操步骤。
二、一个反直觉的核心观点
2.1 我们之前对"智能体"的理解，可能都错了
市面上大量"智能体平台"，本质是**提示词编排工具**------把一系列提示词串成流程，用 if-else 控制分支，美其名曰"AI Agent"。
但真正的智能体（Agent）长这样：
```
感知环境 → 推理决策 → 采取行动 → 观察结果 → 再决策
```
这个循环的能力，**是模型在训练过程中学到的**，不是你用代码编排出来的。
> DeepMind 的 DQN（2013）玩 Atari 游戏，OpenAI Five（2018）打 Dota2 击败世界冠军，AlphaStar（2019）达到星际争霸 II 大师级------这些 Agent 的自主性，全部来自模型训练，而不是外部编排代码。
2.2 那我们这些"非算法人员"能做什么？
做 **Harness（智能体载具）**。
一个能工作的 AI 产品 = **模型**（驾驶者）+ **Harness**（汽车）
-
模型提供：感知、推理、决策能力（来自训练）
-
Harness 提供：工具、知识、观测、行动接口、权限管控（来自工程实现）
**Claude Code 是目前开源界能看到的、最优雅的 Harness 实现之一。** 这也是 learn-claude-code 这个仓库存在的意义------通过逆向拆解 Claude Code 的 Harness 设计，学会如何为 LLM 构建高效、可扩展的运行环境。
三、learn-claude-code 仓库速览
3.1 仓库基本信息
```
仓库地址：https://github.com/shareAI-lab/learn-claude-code
星标：57.7k+
Fork：9.5k+
语言：TypeScript 59.2% / Python 39% / CSS 1.8%
```
3.2 仓库结构
```
learn-claude-code/
├── agents/ # Python 参考实现（s01～s12 + s_full 终极示例）
├── docs/{en,zh,ja}/ # 以思维模型为核心的文档（3 种语言）
├── web/ # 交互式学习平台（Next.js）
├── skills/ # s05 会话所需的技能文件
└── .github/workflows/ # CI 配置
```
3.3 12 个渐进式会话
这是整个仓库的精华------**从最简单的 Agent Loop 开始，每个会话新增一个 Harness 机制**，最终拼成一个完整的生产级 Harness。
| 会话 | 核心口号 | 新增机制 | 难度 |
|------|---------|---------|:----:|
| s01 | One loop & Bash is all you need | 最小 Agent 循环 | ⭐ |
| s02 | 加工具，只加 handler | 工具调度映射 | ⭐ |
| s03 | 没计划的 Agent 走哪算哪 | TodoWrite 规划 | ⭐⭐ |
| s04 | 大任务拆小，干净上下文 | 子 Agent 隔离 | ⭐⭐ |
| s05 | 用到什么知识，加载什么知识 | 技能系统（按需注入）| ⭐⭐ |
| s06 | 上下文总会满，要有办法腾地方 | 三层上下文压缩 | ⭐⭐⭐ |
| s07 | 大目标拆成小任务，记在磁盘上 | 任务系统 + 依赖图 | ⭐⭐⭐ |
| s08 | 慢操作丢后台，Agent 继续想 | 后台任务 + 通知 | ⭐⭐⭐ |
| s09 | 任务太大，分给队友 | 多 Agent + JSONL 邮箱 | ⭐⭐⭐⭐ |
| s10 | 队友之间要有统一的沟通规矩 | 协议状态机 | ⭐⭐⭐⭐ |
| s11 | 队友自己看板子，有活就认领 | 自治 Agent（无中心协调）| ⭐⭐⭐⭐ |
| s12 | 各干各的目录，互不干扰 | Worktree + 任务隔离 | ⭐⭐⭐⭐⭐ |
四、实操：从零启动 learn-claude-code
4.1 环境准备
```bash
1. 克隆仓库
git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
2. 安装 Python 依赖
pip install -r requirements.txt
3. 配置 API Key
cp .env.example .env
编辑 .env 文件，填入你的 ANTHROPIC_API_KEY
```
> **没有 Anthropic API Key？**
> 仓库的衍生项目 [Kode Agent CLI](https://github.com/shareAI-lab/Kode-cli) 支持接入 GLM / MiniMax / DeepSeek 等开放模型，可以用来替代。
4.2 运行第一个会话（s01）
```bash
python agents/s01_agent_loop.py
```
**你会看到什么：**
一个只有 Bash 工具的最简 Agent，你输入任务，它调用 Bash 命令完成任务，然后汇报结果。
核心代码（简化版）：
```python
def agent_loop(messages):
while True:
response = client.messages.create(
model=MODEL,
system=SYSTEM,
messages=messages,
tools=TOOLS,
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
return # 模型认为任务完成，返回文本
执行工具，把结果追加到消息列表
results = []
for block in response.content:
if block.type == "tool_use":
output = TOOL_HANDLERS[block.name](**block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})
```
**一句话总结 s01：** 一个 while 循环 + 一个 Bash 工具 = 一个能干活的最简 Agent。
4.3 交互式学习平台（推荐）
```bash
cd web
npm install
npm run dev
浏览器打开 http://localhost:3000
```
这个 Web 平台提供：
-
每个会话的分步动画演示
-
可直接查看的源码
-
配套文档（中/英/日三语）
五、精读笔记：s01～s06 核心要点
s01：One loop & Bash is all you need
**Harness 工程师最基础的工作：**
写一个循环，把模型的输出和工具的执行串联起来。
**关键认知：**
模型决定「要不要调用工具」「调用哪个工具」「传入什么参数」------代码只是执行者，不做决策。
s02：加工具，只加 handler
**s01 只有一个 Bash 工具，能干的事很有限。**
s02 教你在 `TOOL_HANDLERS` 字典里注册新工具：
```python
TOOL_HANDLERS = {
"bash": bash_handler,
"read_file": read_file_handler, # 新增
"write_file": write_file_handler, # 新增
"list_files": list_files_handler, # 新增
}
```
**关键认知：**
工具是 Agent 的「手」。工具越多，Agent 能完成的任务越复杂。但工具的**描述必须清晰**（模型通过描述决定怎么用工具）。
s03：没计划的 Agent 走哪算哪
**问题：** s01/s02 的 Agent 拿到任务就直接动手，做到一半发现方向错了，已经浪费了很多步骤。
**解法：** 给 Agent 一个 `TodoWrite` 工具，让它先列执行计划，再按计划动手。
```
无计划：用户说"帮我整理这个项目的代码"→ Agent 直接开始改文件→ 改到一半发现依赖关系没搞清楚→ 白干
有计划：用户说同样的话 → Agent 先列出步骤 → 用户确认 → 再执行 → 可控可纠偏
```
**关键认知：**
让模型「先想后做」，比「边做边想」成功率高得多。这不是编排，是给模型一个更好的思考框架。
s04：大任务拆小，干净上下文
**问题：** 一个复杂任务，Agent 和模型的对话会越来越长，后来模型开始「健忘」，前面说过的话后面就忽略了。
**解法：** 派生子 Agent（Subagent），每个子 Agent 有独立的 `messages[]`，互不干扰。
```
主 Agent：负责任务拆解和结果汇总（上下文始终保持精简）
├── 子 Agent A：负责模块 A 的重构（独立上下文）
├── 子 Agent B：负责模块 B 的测试（独立上下文）
└── 子 Agent C：负责文档更新（独立上下文）
```
**关键认知：**
子 Agent 隔离是控制上下文长度的核心手段，也是生产级 Agent 的标配能力。
s05：用到什么知识，加载什么知识
**问题：** 如果把所有领域知识都塞进 System Prompt，上下文会被迅速填满，而且大量内容和当前任务无关。
**解法：** Skill 系统------把知识拆成独立的 `SKILL.md` 文件，Agent 根据需要**临时加载**。
```
用户：帮我用 Python 写一个数据清洗脚本
Agent：检测到需要 Python 知识 → 加载 python_best_practices.md → 生成代码
```
**关键认知：**
「按需加载」比「提前注入」高效得多。这也是为什么 Claude Code 能支持那么多功能，但每次对话都不会让上下文爆炸。
s06：上下文总会满，要有办法腾地方
**问题：** 再大的上下文窗口，也总会有用完的时候。
**解法：** 三层上下文压缩策略：
```
第一层：对话摘要（把前面 N 轮对话压缩成一段摘要）
第二层：删除非必要内容（中间版本的代码草稿、过时的调试信息等）
第三层：存档到外部存储（把重要结论写入文件，上下文只保留「结论索引」）
```
**关键认知：**
上下文管理是 Harness 工程师的核心能力之一。会压缩，Agent 才能跑长跑。
六、对项目经理/产品经理的实际启发
读到这里，你可能会想：「这些是技术实现，跟我做项目管理/产品设计有什么关系？」
关系很大。以下是我个人的三点启发：
启发一：别再迷信"拖拽式 Agent 搭建平台"
如果你在评估是否要给团队引入某个"AI Agent 平台"，先问自己一个问题：
> **这个平台是让模型做决策，还是让我的流程图做决策？**
如果是后者，它本质上是一个「高级版的决策树」，不是真正的智能体。
启发二：AI 辅助项目管理的核心，是设计好「工具」和「知识」
用 Claude Code 辅助项目管理工作，最有效的方式是：
-
**定义好工具**：让 AI 能读 WBS、能更新进度、能查依赖关系
-
**整理好知识**：把公司的项目管理规范、模板、检查清单整理成 Skill 文件，按需加载
这比「写一个超长的 System Prompt 告诉 AI 怎么管项目」有效 10 倍。
启发三：让 AI 「先计划再执行」，不要「边做边想」
s03 的教训，直接适用于我们给 AI 下指令的方式：
```
❌ 错误方式：
「帮我分析一下这个项目的延期风险」
（AI 直接开始输出，可能漏掉关键维度）
✅ 正确方式：
「请先列出分析这个项目延期风险的步骤，
我确认后再开始」
（AI 先输出分析框架，你补充/删减，再执行）
```
七、仓库生态：学完之后能用什么
learn-claude-code 的作者还维护了几个衍生项目，可以直接用于生产：
| 项目 | 用途 | 地址 |
|------|------|------|
| **Kode Agent CLI** | 生产级编码 Agent CLI，支持多模型 | [github.com/shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli) |
| **Kode Agent SDK** | 将 Agent 能力嵌入应用（无独立进程开销）| [github.com/shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk) |
| **claw0** | 常驻 Agent（心跳 + 定时任务 + IM 接入）| [github.com/shareAI-lab/claw0](https://github.com/shareAI-lab/claw0) |
八、总结
**三个核心结论：**
- **智能体的自主性来自模型训练，不是编排代码**
别再试图用流程图「编出」一个智能体。
- **Harness 是智能体产品的基础设施**
工具、知识、观测、行动接口、权限------这五个部分做好了，模型自然能跑起来。
- **Claude Code 的 Harness 设计是目前最好的学习样本**
12 个渐进式会话，从 0 到 1 拆解每个机制，值得每一个和 AI 打交道的产品/项目人员细读。
**仓库地址：**
https://github.com/shareAI-lab/learn-claude-code
**推荐学习路径：**
先把 s01～s06 跑通（约需 2～3 小时），理解核心机制后，再按需深入后面更进阶的内容。
延伸阅读
-
项目经理用AI的第一步，从这3件事开始\](https://blog.csdn.net/sky_810613/article/details/159648582)
-
用AI写需求文档，我的提示词模板与踩坑记录\](https://blog.csdn.net/sky_810613/article/details/159837108)
**关注我**，每周分享 AI + 项目管理的实操经验。
如有疑问，欢迎在评论区交流。
*作者：静姐，20年IT老兵，现为某软件公司项目负责人，专注于AI与项目管理实践。*