Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

参考：shareAI-lab/learn-claude-code

你有没有想过，为什么你跟 Claude Code 说“帮我改一下这个网页”，它就能自己打开文件、修改代码、运行测试，然后告诉你结果？

它看起来好聪明，像人一样会“动手”。但其实，它背后的原理并不神秘，甚至可以用几十行简单的代码讲清楚。

这篇文章是给新手的。不管你有没有学过编程，我都会尽量用生活中的例子来解释。读完之后，你会明白：

• Claude Code 最核心的部分是什么；
• 它是怎么“看懂”文件、“动手”改代码的；
• 它为什么能记住很多事情、做错事能重来；
• 以及如果你想自己做一个类似的 AI 助手，应该从哪里开始。

一、一句话讲清楚 Claude Code

如果把 Claude Code 拆开，你会发现它只有三个东西：

一个循环 + 一张工具表 + 一个会说话的 AI

这个“循环”非常重要。没有它，AI 就只能说一次话，没法连续做很多事。

flowchart LR
    subgraph 工具箱["🧰 工具箱（Harness）"]
        读文件["读文件"]
        写文件["写文件"]
        执行命令["执行命令"]
        搜索["搜索代码"]
        权限["权限检查"]
    end

    大脑["🧠 AI 大脑<br/>会思考、会推理"]
    电脑["💻 你的电脑"]

    大脑 -->|我想读文件| 读文件
    读文件 -->|文件内容| 大脑
    大脑 -->|我想运行测试| 执行命令
    执行命令 --> 电脑
    电脑 -->|测试结果| 大脑
    权限 -->|这个能做吗？| 执行命令

二、最核心的 30 行代码

Claude Code 的心脏，是一段很简单的代码。你可以把它理解成“机器人干活的主流程”：

def agent_loop(query):
    # 1. 先把用户的问题记下来
    messages = [{"role": "user", "content": query}]

    while True:
        # 2. 把对话历史发给 AI，告诉它有哪些工具可以用
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,
            messages=messages,
            tools=TOOLS,
            max_tokens=8000,
        )

        # 3. 把 AI 的回复存进历史
        messages.append({"role": "assistant", "content": response.content})

        # 4. 如果 AI 不再调用工具，就说明它说完了，结束循环
        if response.stop_reason != "tool_use":
            return

        # 5. 执行 AI 要求的工具，并把结果告诉它
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = run_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

人话解释

1. 你问了一个问题 → 比如“帮我修一下这个 bug”。
2. AI 看历史和工具表 → 它想：“我需要先读一下代码文件。”
3. AI 说“我要用读文件工具” → 程序真的去打开文件。
4. 把文件内容还给 AI → AI 再看，决定下一步。
5. 一直重复，直到 AI 说“我搞定了”。

flowchart TD
    开始([你输入任务]) --> 发给AI[把任务+历史发给 AI]
    发给AI --> AI思考[AI 思考]
    AI思考 --> 判断{AI 想调用工具吗？}
    判断 -->|想| 执行工具[程序执行工具]
    判断 -->|不想| 输出答案[输出最终答案]
    执行工具 --> 返回结果[把结果返回给 AI]
    返回结果 --> 发给AI
    输出答案 --> 结束([结束])

三、20 节课都在讲什么？一张总图看懂

Claude Code 的学习资料里有 20 节课，每节课加一个新能力。它们不是乱排的，而是像打游戏升级一样，一步一步变强。

flowchart LR
    subgraph 第一阶段["🌱 第一阶段：让 AI 动起来"]
        s01["s01 循环"]
        s02["s02 工具"]
        s03["s03 权限"]
        s04["s04 钩子"]
    end

    subgraph 第二阶段["🛠️ 第二阶段：做复杂任务"]
        s05["s05 计划"]
        s06["s06 子代理"]
        s07["s07 技能"]
        s08["s08 压缩记忆"]
    end

    subgraph 第三阶段["🧠 第三阶段：记得住、错得了"]
        s09["s09 记忆"]
        s10["s10 系统提示"]
        s11["s11 错误恢复"]
    end

    subgraph 第四阶段["⏳ 第四阶段：长时间运行"]
        s12["s12 任务图"]
        s13["s13 后台任务"]
        s14["s14 定时任务"]
    end

    subgraph 第五阶段["👥 第五阶段：团队协作"]
        s15["s15 队友"]
        s16["s16 团队协议"]
        s17["s17 自治"]
        s18["s18 目录隔离"]
    end

    subgraph 第六阶段["🔌 第六阶段：扩展组装"]
        s19["s19 MCP 插件"]
        s20["s20 完整系统"]
    end

    第一阶段 --> 第二阶段 --> 第三阶段 --> 第四阶段 --> 第五阶段 --> 第六阶段

下面拆解核心部分。

四、第一阶段：让 AI 动起来

s01 Agent Loop：一个循环就够了

这是所有东西的基础。就像你骑自行车，核心是“踩踏板 → 车轮转 → 车前进”这个循环。Claude Code 的核心就是：

AI 思考 → 调用工具 → 看结果 → 再思考 → 再调用工具 → …… → 完成

没有循环，AI 只能说一句话。有了循环，它就能连续做很多步。

s02 Tool Use：从一把螺丝刀到整套工具箱

最早的 AI 只有一个工具：执行终端命令（bash）。但这样很不方便，就像你修自行车只能用一个螺丝刀。

后来 Claude Code 给 AI 配了一整套工具：

• read_file：读文件
• write_file：写文件
• edit_file：改文件中的一部分
• glob：按名字找文件
• grep：在文件里搜索文字

这些工具是“分发表”管理的。程序不用写一堆 if/else，而是查一个字典：

TOOL_HANDLERS = {
    "read_file":  read_file_function,
    "write_file": write_file_function,
    "edit_file":  edit_file_function,
}

# AI 说想用 read_file，就找到对应的函数执行
handler = TOOL_HANDLERS["read_file"]
result = handler(path="main.py")

好处：加新工具就像往工具箱里多放一把扳手，不用改主流程。

s03 Permission：先问能不能做，再让它做

这是 Claude Code 很重要的一课：自由要有边界。

AI 能力很强，但它不能想删啥就删啥、想改啥就改啥。权限系统就像家长给孩子定规矩：

• 读文件可以；
• 修改重要文件要问一下；
• 删除整个文件夹？不行。

flowchart TD
    AI想做事[AI 想执行命令] --> 查权限{权限系统检查}
    查权限 -->|允许| 直接执行
    查权限 -->|需要确认| 问用户[弹窗问用户]
    查权限 -->|禁止| 拒绝[拒绝执行]
    问用户 -->|同意| 直接执行
    问用户 -->|不同意| 拒绝

这教会我们一个工程原则：先设边界，再给自由。

s04 Hooks：在循环边上挂“挂钩”

Hook 中文叫“钩子”。想象你在书包上挂很多小挂件：钥匙扣、饭卡、耳机。主书包不变，但你可以加东西。

Claude Code 的 Hook 系统也是这样：

• 工具执行前，可以检查一下（PreToolUse）；
• 工具执行后，可以记录日志（PostToolUse）；
• 会话开始/结束时，可以做初始化或清理。

flowchart LR
    AI决定[AI 决定调用工具] --> 前钩子["PreToolUse 钩子<br/>检查/拦截"]
    前钩子 --> 执行工具
    执行工具 --> 后钩子["PostToolUse 钩子<br/>记录/通知"]
    后钩子 --> 返回AI

核心思想：主循环不要改来改去，把扩展功能挂到钩子上。

五、第二阶段：做复杂任务

s05 TodoWrite：先做计划，再动手

如果你要写一篇大作文，你会先列提纲，对吧？Claude Code 也是这样。

做复杂任务前，AI 会先写一个待办清单（Todo）：

1. 读 README 了解项目      [待做]
2. 找到 bug 所在的文件     [进行中]
3. 修改代码                [待做]
4. 运行测试确认修好        [待做]

每完成一步，就更新状态。如果 AI 太久没更新，系统还会“唠叨”它：“喂，你忘了更新待办清单啦！”

这个机制让 AI 不容易“跑偏”。

s06 Subagent：雇一个小助手

有时候一个任务需要查很多东西。比如“这个项目的测试框架是什么？”AI 可能要读 10 个文件才能确定答案是 pytest。

如果让主 AI 自己读 10 个文件，它的“脑子”会塞满东西，又慢又贵。

解决办法是：雇一个临时小助手（子代理）。小助手用全新的对话去读那 10 个文件，最后只把答案“pytest”告诉主 AI。

flowchart LR
    主AI["主 AI"] -->|派任务| 子AI["子 AI<br/>新开一个对话"]
    子AI -->|读10个文件| 文件["项目文件"]
    文件 -->|内容| 子AI
    子AI -->|只返回结论：pytest| 主AI

主 AI 的脑子很干净，只记住了最重要的结论。

s07 Skill Loading：需要哪本字典，就翻哪本

想象你要学数学、物理、化学三科。你不会每次上课都把三本书全背上，而是上什么课带什么书。

Claude Code 也是这样。它有很多“技能书”（比如 git 用法、测试规范、API 文档），但不会一次性全塞给 AI。

它是两层加载：

1. 先给目录：告诉 AI 有哪些技能书；
2. 需要时再翻开：AI 说“我要查 git 那本书”，系统才把完整内容给它。

这样就省了很多“脑容量”。

s08 Context Compact：脑子塞不下时怎么办？

AI 一次能看的文字是有限的，就像你的作业本只有那么多页。如果写得太多，就要翻页或者撕掉旧的。

Claude Code 有三种“翻页”方法：

1. micro_compact：把很久以前的工具结果换成一句话摘要，比如“之前用过 read_file”；
2. auto_compact：当文字太多时，自动让 AI 写个总结，用总结替换原来的长对话；
3. compact 工具：AI 自己决定什么时候该“翻页”。

flowchart TD
    subgraph 第一层["第一层：micro_compact"]
        旧结果["旧工具结果"] --> 占位符["换成占位符<br/>[之前读过 main.py]"]
    end

    subgraph 第二层["第二层：auto_compact"]
        太多文字["对话太长"] --> 写总结["AI 写摘要"] --> 替换历史["用摘要替换历史"]
    end

    subgraph 第三层["第三层：compact 工具"]
        AI判断["AI 觉得该压缩了"] --> 手动触发["调用 compact 工具"]
    end

    第一层 --> 第二层 --> 第三层

六、第三阶段：记得住、错得了

s09 Memory：AI 也要记笔记

AI 没有真正的记忆。每次对话结束，它就忘了。如果想让它长期记住东西（比如你喜欢什么代码风格、项目有什么规矩），就需要一个“记忆系统”。

记忆系统通常分三步：

1. 选择：哪些东西值得记住？
2. 提取：把重要信息摘出来；
3. 固化：存到文件或数据库里，下次对话再读出来。

flowchart LR
    对话["一段对话"] --> 选择["选择重要信息"]
    选择 --> 提取["提取关键事实"]
    提取 --> 存储["存到记忆文件"]
    存储 --> 下次对话["下次启动时读取"]

比如 AI 记住了：“这个用户喜欢用 2 个空格缩进。”下次写代码时它就会自动用 2 个空格。

s10 System Prompt：提示词不是写死的

System Prompt 就是告诉 AI“你是谁、该怎么做事”的那段话。

Claude Code 的 System Prompt 不是一次性写死的，而是运行时拼接的：

• 基础身份部分；
• 当前项目规则；
• 加载的技能书；
• 用户的偏好记忆。

就像你写作文时，老师给的题目要求 + 你自己的提纲 + 参考资料，组合在一起。

s11 Error Recovery：做错事能重来

AI 也会犯错。比如它调用了一个不存在的文件，或者写的代码运行报错。这时候怎么办？

Claude Code 有几种“重来”策略：

• 重试：可能是网络抖动，再试一次就好了；
• 换条路：这个方法不行，换另一个工具试试；
• 清理空间：上下文太满导致看不清，先压缩一下再试；
• 换个小模型/大模型：简单任务用小模型省钱，复杂任务换大模型。

flowchart TD
    出错[工具执行出错] --> 重试{重试有用吗？}
    重试 -->|有用| 再试一次
    重试 -->|没用| 换方法[换工具/换思路]
    换方法 -->|还不行| 清空间[压缩上下文]
    清空间 -->|再试| 再试一次

重要道理：错误不是终点，而是调整的起点。

七、第四阶段：长时间运行

s12 Task System：把大目标拆成小任务

复杂项目不能靠一个简单的 Todo 清单。任务之间有依赖关系：

• A 做完了，B 才能开始；
• C 和 D 可以同时进行；
• E 要等 C 和 D 都做完。

Claude Code 用任务图来管理。每个任务存成一个文件，记录自己的状态、依赖谁、被谁依赖。

flowchart LR
    A["设计登录页面"] --> B["写前端代码"]
    A --> C["写后端接口"]
    B --> D["联调测试"]
    C --> D

s13 Background Tasks：慢活放后台

有些命令要跑很久，比如 npm install 可能要几分钟。如果 AI 停下来等，就太浪费了。

Claude Code 会开一个新的后台线程去跑这些慢命令，主 AI 继续思考别的事。等后台跑完了，再通知 AI。

s14 Cron Scheduler：定时任务

Cron 就是“定时器”。比如你可以让 AI 每天早上 8 点检查一遍代码仓库，看看有没有需要更新的依赖。

“到点了就干活，不用人喊。”

flowchart LR
    时间到[时间到了] --> Cron[Cron 触发器]
    Cron --> 任务[执行预设任务]
    任务 --> 结果[把结果发给 AI]

八、第五阶段：团队协作

s15 Agent Teams：多个 AI 一起干活

一个 AI 干不完的大项目，可以叫一群 AI 一起干。每个 AI 有自己的身份和“收件箱”（mailbox）。

它们通过 JSONL 文件收发消息：

{"from": "leader", "to": "alice", "content": "你去写登录页面"}
{"from": "alice", "to": "leader", "content": "我做好了"}

每行一条消息，追加写入，像写日记一样简单。

s16 Team Protocols：队友之间要讲规矩

多人协作不能乱说话。Claude Code 的团队协议规定：

• 每个重要请求都要带一个 request_id（像快递单号）；
• 回复时要引用同一个 request_id；
• 请求状态是 pending（等待中）、approved（同意）或 rejected（拒绝）。

这样就不会搞混谁同意了什么。

s17 Autonomous Agents：AI 自己会找活干

更高级的团队里，AI 不需要等领导分配任务。它会自己去看任务板，认领还没人做的、并且前置条件满足的任务。

如果 60 秒没活干，它就自动“下班关机”。

s18 Worktree Isolation：各干各的，不打架

两个 AI 同时改同一个文件，会互相覆盖。Claude Code 用 git worktree 给每个任务一个独立目录和独立分支：

任务 A → 目录 auth-refactor/ → 分支 wt/auth-refactor
任务 B → 目录 ui-login/     → 分支 wt/ui-login

大家互不干扰，最后再把代码合并。

九、第六阶段：扩展组装

s19 MCP Plugin：不够用时，插更多工具

MCP 是“模型上下文协议”。你可以把它理解成“USB 接口”：

• Claude Code 本身带了一些工具；
• 如果你需要连数据库、查浏览器、操作 Slack，可以通过 MCP 插进来；
• 这些外部工具和自带工具一样，AI 都能调用。

flowchart LR
    Claude["Claude Code"] --> MCP["MCP 接口"]
    MCP --> 数据库["数据库工具"]
    MCP --> 浏览器["浏览器工具"]
    MCP --> Slack["Slack 工具"]
    数据库 -->|结果| Claude
    浏览器 -->|结果| Claude
    Slack -->|结果| Claude

s20 Comprehensive Agent：把所有东西拼起来

最后一节课，就是把前面 19 节课的所有机制都装进同一个循环里：

一个循环 + 工具 + 权限 + 钩子 + 计划 + 子代理 + 技能 + 记忆 + 压缩 + 任务图 + 后台任务 + Cron + 团队 + 自治 + Worktree + MCP = 完整的 Claude Code

听起来很多，但你已经一个个看过了。它们都是围绕最初那个简单循环加上的“配件”。

十、给新手的 5 个开发小技巧

这些技巧来自 Claude Code 的源码，平时写程序也能用到。

1. 用“查表”代替一堆 if/else

# 不推荐
if name == "read": read_file()
elif name == "write": write_file()

# 推荐
HANDLERS = {"read": read_file, "write": write_file}
HANDLERS[name]()

加新功能只要加一行。

2. 修改列表要小心

如果你想在一个函数里修改外面的列表，要用切片赋值：

messages[:] = new_list  # 正确：改原来的列表
# messages = new_list   # 错误：只是让局部变量指向新列表

3. 用 **kwargs 接受任意参数

def handler(**kw):
    print(kw["path"])

handler(path="main.py", limit=10)

(**kw) 表示“不管什么参数名，都装进字典 kw 里”。

4. 守护线程做后台任务

import threading

t = threading.Thread(target=download_file, daemon=True)
t.start()

主程序退出时，守护线程会自动结束，不会卡住。

5. JSONL 比 JSON 更适合追加写入

# 写：每行一条
with open("inbox.jsonl", "a") as f:
    f.write(json.dumps(msg) + "\n")

# 读：逐行解析
for line in open("inbox.jsonl"):
    msg = json.loads(line)

追加写入很安全，不会因为同时写入而损坏文件。

十一、总结

Claude Code 看起来很厉害，但它的核心其实非常朴素：

一个 while 循环 + 一张工具表 + 一个会说话的 AI。

真正让它变强的，是围绕这个循环一层层加上的“配件”：权限、计划、子代理、技能、记忆、压缩、任务图、后台任务、团队、自治、目录隔离、MCP……

这些配件都是为了解决一个核心问题：

怎么让一个只会说话的 AI，真正能在现实世界里连续、安全、高效地干活。

理解了这个骨架之后，你再回头看 Claude Code，就不会觉得它是黑魔法了。它就是一个被精心设计的“机器人工作台”，而我们看到的聪明，来自那个会思考的大脑，加上一套会执行的 harness。

大脑负责想，工作台负责做。把工作台造好，大脑就能发挥全部实力。

本文是学习 shareAI-lab/learn-claude-code 的笔记整理。如果你想动手，可以从 s01_agent_loop/code.py 开始，一课一课跟着做。

• AI 工程

• Claude Code
• AI 编程
• Agent
• LLM
• 学习笔记
• 新手编程

方糖猫（大可）

18 年后端架构，现在独立做 AI 产品。这里记录 AI 视频、AI Agent 与工程实践。