Github高赞项目50K learn-claude-code 的学习笔记总结

这篇文章主要整理自 GitHub 上一个近期比较火的 Claude Code 原理学习项目，是我在学习过程中整理的一份学习笔记。

文章会按照课程内容，从 S01 到 S12 逐章进行总结，梳理每一章的核心知识点、关键概念以及我自己的理解，帮助大家系统了解 Claude Code 的工作原理与使用思路。

S01 基础骨架

这是整个系列最核心的最小骨架。后面所有内容，本质上都在这个结构上加东西。

python 复制代码

def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,
            messages=messages,
            tools=TOOLS,
            max_tokens=8000,
        )

        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 = run_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": str(output),
                })

        messages.append({
            "role": "user",
            "content": results,
        })

这个基础骨架的核心只有 4 步：

调模型
看模型是否要工具
执行工具
把结果塞回去，再继续下一轮

也就是说本质就是一个无限的循环一直到LLM输出停止为止。

S02 相比 S01 新增了什么

S01 只有一个"硬编码工具"

S01 更像这样：

python 复制代码

output = run_bash(block.input["command"])

也就是说，工具调用几乎写死了。

S02 新增：工具分发表

新增了：

python 复制代码

TOOL_HANDLERS = {
    "bash": run_bash,
    "read_file": run_read,
    "write_file": run_write,
    "edit_file": run_edit,
}

循环里改成：

python 复制代码

handler = TOOL_HANDLERS.get(block.name)
output = handler(**block.input)

本质变化

从"只会跑 bash 的 loop"变成"可扩展工具系统"。

S03 相比 S01 新增了什么

新增 1：TodoManager

新增一个内存中的待办状态：

python 复制代码

class TodoManager:
    def __init__(self):
        self.items = []

新增 2：`todo` 工具

在 TOOLS 和 TOOL_HANDLERS 里加：

python 复制代码

"todo": lambda **kw: TODO.update(kw["items"])

本质变化

在基础 loop 上加了"规划状态"。

也就是：

S01：模型只是在做事
S03：模型开始在内存层级"维护任务计划"

S04 相比 S01 新增了什么

新增 1：子 agent 执行函数

新增一个子循环：

python 复制代码

def run_subagent(prompt):
    sub_messages = [{"role": "user", "content": prompt}]
    ...

这个函数内部其实又跑了一遍基础 loop。

新增 2：父 agent 新工具 `task`

父 agent 可以调用：

python 复制代码

task(prompt="...")

然后 runtime 去执行：

python 复制代码

output = run_subagent(...)

本质变化

在基础 loop 上加了"递归的、context隔离的子 loop"。

也就是说：

S01：只有一个 loop
S04：一个主 loop可以临时拉起另一个独立的上下文干净的 loop 然后结束子loop 将结果重新塞回主loop中去

S05 相比 S01 新增了什么

新增 1：SkillLoader

新增一个技能加载器，扫描 skills/*/SKILL.md

python 复制代码

class SkillLoader:
    def get_descriptions(self): ...
    def get_content(self, name): ...

新增 2：system prompt 不再是固定文本

而是变成：

python 复制代码

SYSTEM = f"""
You are a coding agent.
Skills available:
{SKILL_LOADER.get_descriptions()}
"""

新增 3：`load_skill` 工具

模型可以按需加载完整 skill 内容：

python 复制代码

"load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"])

本质变化

在基础 loop 上加了"按需知识注入机制"。

不是直接改 loop 结构，而是新增了一个按需加载skill的模块其实你就可以理解为当下很多的skill机制

S06 相比 S01 新增了什么

新增 1：每轮调用前先做 `micro_compact`

loop 顶部多了一步：

python 复制代码

micro_compact(messages)

新增 2：token 超阈值时自动压缩

又多了一步：

python 复制代码

if estimate_tokens(messages) > THRESHOLD:
    messages[:] = auto_compact(messages)

新增 3：手动 `compact` 工具

多了一个控制型工具：

python 复制代码

"compact": ...

本质变化

在基础 loop 上加了"上下文管理层+压缩机制"。

S01 的 loop 是无限增长的。

S06 的 loop 开始会"整理记忆"。

S07 相比 S01 新增了什么

新增 1：TaskManager

把任务状态落盘到 .tasks/*.json

python 复制代码

class TaskManager:
    def create(...)
    def update(...)
    def list_all(...)

新增 2：任务工具

在基础工具集上新增：

python 复制代码

task_create
task_update
task_list
task_get

本质变化

在基础 loop 上加了"外部持久化任务状态"。

S01 只有 messages。

S01 只有 内存级别的无任务依赖的TODO任务表。

S07 开始有了一个独立于对话之外的任务数据库。

把扁平清单升级为持久化到磁盘的任务图 。每个任务是一个 JSON 文件, 有状态、前置依赖 (blockedBy)。任务图随时回答三个问题:

什么可以做? -- 状态为 pending 且 blockedBy 为空的任务。
什么被卡住? -- 等待前置任务完成的任务。
什么做完了? -- 状态为 completed 的任务, 完成时自动解锁后续任务。

S08 相比 S01 新增了什么

新增 1：BackgroundManager

新增后台线程执行器：

python 复制代码

class BackgroundManager:
    def run(...)
    def check(...)
    def drain_notifications(...)

新增 2：新工具

加了：

python 复制代码

background_run
check_background

新增 3：每轮模型调用前先 drain 队列

基础 loop 顶部改成：

python 复制代码

notifs = BG.drain_notifications()
if notifs:
    messages.append(...)

本质变化

在基础 loop 上加了"异步执行 + 通知注入"。

S01 所有工具都是同步阻塞。

S08 允许" 后台线程跑命令, 完成后注入通知。"。

S09 相比 S01 新增了什么

新增 1：MessageBus

新增文件邮箱系统：

python 复制代码

class MessageBus:
    def send(...)
    def read_inbox(...)

新增 2：TeammateManager

新增队友线程系统：

python 复制代码

class TeammateManager:
    def spawn(...)
    def _teammate_loop(...)

新增 3：主 agent 多了团队工具

新增：

python 复制代码

spawn_teammate
list_teammates
send_message
read_inbox
broadcast

新增 4：每个 teammate 自己也跑 loop

也就是说，S09 不再只是一个 agent_loop，而是多个线程里各自有 loop。

本质变化

在基础 loop 上加了"多实例 loop + 邮箱通信"。

S10 相比 S01 新增了什么

新增 1：request tracker

新增两个全局状态表：

python 复制代码

shutdown_requests = {}
plan_requests = {}

新增 2：协议型工具

lead 和 teammate 多了协议工具：

python 复制代码

shutdown_request
shutdown_response
plan_approval

新增 3：`request_id` 关联逻辑

请求和响应不再只是普通消息，而是：

python 复制代码

{"request_id": "...", "approve": True}

本质变化

在基础 loop 上加了"结构化协议状态机"。

S01 的工具调用是"调用就完"。

S10 开始出现"发起请求 -> 等待响应 -> 更新状态"的流程。

S11 相比 S01 新增了什么

新增 1：task board 扫描

新增：

python 复制代码

scan_unclaimed_tasks()
claim_task()

新增 2：teammate loop 变成双阶段

原来只是一个普通 loop。

现在变成：

WORK PHASE
IDLE PHASE

也就是一个更大的外层循环：

python 复制代码

while True:
    work_phase()
    idle_phase()

新增 3：`idle` 工具

模型可以主动要求进入空闲轮询阶段：

python 复制代码

"idle"

新增 4：identity re-injection

上下文短了以后补身份块：

python 复制代码

make_identity_block(...)

本质变化

在基础 loop 上加了"空闲态 + 自主找活"。

S01 是用户驱动。

S11 开始变成部分"系统自己驱动"。

S12 相比 S01 新增了什么

新增 1：repo root 检测

先确定 git 仓库根目录：

python 复制代码

detect_repo_root(...)

新增 2：EventBus

新增 lifecycle event log：

python 复制代码

class EventBus:
    def emit(...)
    def list_recent(...)

新增 3：TaskManager 增强字段

task 多了：

python 复制代码

worktree
created_at
updated_at

新增 4：WorktreeManager

新增最核心的隔离执行器：

python 复制代码

class WorktreeManager:
    def create(...)
    def list_all(...)
    def status(...)
    def run(...)
    def keep(...)
    def remove(...)

新增 5：一批 worktree 工具

新增：

python 复制代码

worktree_create
worktree_list
worktree_status
worktree_run
worktree_keep
worktree_remove
worktree_events
task_bind_worktree

本质变化

在基础 loop 上加了"任务执行目录隔离"。

S01 所有命令都在一个工作目录里跑。

S12 开始允许：

从而避免并行修改互相污染。

最后给你一个最直观的总结

S01 是地基

只有这个：

python 复制代码

LLM -> tool -> tool_result -> LLM

后面每一章，本质上都是在这个地基上加一个"层"

S02：加 更多工具
S03：加 内存级别的计划
S04：加 子 loop
S05：加 按需知识
S06：加 上下文压缩
S07：加 带依赖状态的持久化任务计划
S08：加 异步线程执行任务
S09：加 朴素的没有协议控制的多个 agent loop
S10：加 带有协议控制的多个 agent loop
S11：加 轮训机制的多 agent loop
S12：加 worktree 隔离机制

总结

S01 给出了 Agent 的最小闭环；S02-S12 则是在这个闭环上，逐层叠加工具扩展、规划、上下文管理、任务持久化、异步执行、多 Agent 协作、自主性和执行隔离，最终把"模型调用"演进成"Agent Runtime"。

Github高赞项目50K learn-claude-code 的学习笔记总结