🤖 learn-claude-code：从零搭建你自己的AI编程助手，3个代码块就能上手
你有没有遇到过这种情况：想用AI帮你写代码，但每次都要手动复制粘贴文件内容、反复描述项目结构、在终端和聊天窗口之间来回切换？更糟的是，AI经常忘记上下文，刚聊完的代码逻辑，下一轮对话就断片了。
这不是你的问题，是工具设计的问题。市面上大多数“AI编程助手”本质上只是个带界面的聊天框——它们没有真正理解你的项目环境，无法操作文件、执行命令、查看错误日志。而真正能干活的那个东西，叫Agent。
这个项目解决了什么
learn-claude-code 是一个教你手搓AI编程Agent的教程仓库。它不卖课、不卖API，而是把Claude Code这个顶级Agent框架的底层设计模式，拆成你能直接用的代码和思路。
项目上线后迅速登上GitHub趋势榜（Trendshift），社区贡献者超过30人。核心作者明确说了一句话：
智能来自模型训练，Agent产品 = 模型 + 外部框架。
翻译成大白话：模型是大脑，框架是身体。你不需要重新训练一个大脑，但你需要给它装一双手、一双眼睛和一个能干活的环境。这个项目教的就是这个。
核心功能拆解：一个Agent框架到底长什么样
先看一段最核心的代码，这是Agent的“工具箱”定义：
# 摘自 learn-claude-code 核心示例
class Harness:
def __init__(self):
self.tools = {
"read_file": self.read_file,
"write_file": self.write_file,
"run_shell": self.run_shell,
"search_code": self.search_code
}
self.knowledge = []
self.permissions = {"sandbox": True, "need_approval": ["delete", "overwrite"]}
就这么简单？对。一个Agent的核心骨架就是：工具集 + 知识库 + 权限控制。模型通过工具感知环境，通过知识库理解领域，通过权限边界保障安全。
再看一个实际的工具实现——文件读写：
def read_file(self, path: str) -> str:
"""读取文件内容，返回文本。路径自动做沙箱检查。"""
if not self._in_sandbox(path):
return "Error: path outside sandbox"
with open(path, 'r') as f:
return f.read()
def write_file(self, path: str, content: str) -> str:
"""写入文件内容。需要用户确认才能覆盖已有文件。"""
if os.path.exists(path):
if not self._get_approval(f"Overwrite {path}?"):
return "Cancelled: overwrite not approved"
with open(path, 'w') as f:
f.write(content)
return f"Written {len(content)} bytes to {path}"
每个工具都遵循三个原则：原子性（一次只做一件事）、可组合（工具之间能串联）、描述清晰（模型能理解工具用途）。
实操步骤：3分钟跑起来
第一步，克隆项目：
git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
第二步，安装依赖并配置你的Agent：
# config.py - 你的Agent配置文件
AGENT_CONFIG = {
"model": "claude-3-5-sonnet-20241022",
"tools": ["file_io", "shell", "search"],
"knowledge_dirs": ["./docs", "./api_specs"],
"max_context_tokens": 32000,
"approval_mode": "interactive" # 危险操作需要你点头
}
第三步，启动Agent并让它干活：
python run_agent.py --task "修复 src/main.py 中所有未处理的异常"
Agent会自己读取代码、分析异常类型、生成修复方案、询问你是否执行修改。你只需要在关键步骤点个“确认”按钮。
避坑指南：别踩这3个雷
1. 别给Agent太多上下文。 很多人一股脑把整个项目塞进去，结果模型被无关代码淹没了判断力。正确做法是按需加载——只给当前任务相关的文件。项目里有个 context_compaction 模块就是干这个的。
2. 别跳过权限控制。 Agent跑 rm -rf / 这种事不是没有发生过。永远给文件操作加沙箱，给危险命令加审批。代码里已经写好了 sandbox 和 approval 两个基类，直接用。
3. 别指望一次对话搞定一切。 Agent会遗忘，这是模型本身的天花板。解决方案是“任务持久化”——把长期目标存成文件，每次对话开始前重新加载。项目里的 task_system.py 就是干这个的：
class TaskSystem:
def __init__(self):
self.tasks = []
self.persist_path = "./agent_tasks.json"
def add_task(self, description: str, priority: int):
self.tasks.append({"desc": description, "priority": priority, "status": "open"})
self._save()
def get_active_tasks(self):
return [t for t in self.tasks if t["status"] == "open"]
要点总结
- Agent的核心不是代码，是模型训练出来的智能。 你能做的是给它一个高质量的执行环境。
- 一个合格的Agent框架 = 工具 + 知识 + 上下文管理 + 权限控制。 缺任何一个，你的Agent都会变成智障。
- 从模仿开始。 learn-claude-code 已经把Claude Code的架构拆成可复用的模块，你直接改改就能用在自己的项目里。
- 别过度工程化。 很多人给Agent套了十几层if-else、节点图、流程编排，结果模型被规则卡死，反而不会干活了。框架要轻，模型要重。
最后一句：你写的是车，不是司机。车造好了，司机自然会上路。