learn-claude-code：拆解 agent harness 的最小内核

它要解决的不是「怎么做 agent」，而是「你做的到底是什么」

这个仓库的名字里有一个容易被忽略的词：harness。它没有叫「learn-agent」，也没有叫「build-claude-code-clone」，而是把教学对象锁定在 harness 上。

README 开头就摆出一个立场：agency 来自模型训练，不来自外部代码编排。也就是说，你写再多的 if-else、节点图、prompt 链，也制造不出智能。你能做的是给已经具备智能的模型一个可以操作的环境。

这个立场决定了整个仓库的气质。它不教你怎么调 API 拼 workflow，而是教你写一个极简的 agent loop，然后在 17 个章节里逐步往这个 loop 周围加机制。

Bash 作为唯一工具接口，是一种刻意的减法

仓库自述写的是「Bash is all you need」。s01 的座右铭更直白："One loop & Bash is all you need"。

这句话的代价是显而易见的：只给模型一个 Bash 工具，意味着放弃结构化 API、放弃浏览器控制、放弃数据库查询这些常见工具。但换来的是教学上的清晰。任何读者都能看懂 TOOL_HANDLERS[block.name] 这行代码在做什么，不需要先理解复杂工具注册体系。

core pattern 的代码非常短，核心循环只有十几行。模型返回 tool_use block，代码执行对应 handler，把 tool_result 追加回 messages，再循环。没有重试策略，没有并发控制，没有权限检查。

这些缺失不是缺陷，而是教学策略。s01 先把最小的闭环跑起来，后续每个章节再往里面塞一个机制。这种「先裸奔、再穿衣服」的顺序，比一上来就给完整实现更容易让人理解每个机制存在的理由。

17 课的设计逻辑：每个机制只回答一个问题

仓库目前有两条学习路径：根目录的 s01 到 s17 是现行版本，docs/ 和 agents/ 保留旧版 12 课。映射表显示旧版内容被重新编排，比如旧版的 agent teams、team protocols、autonomous task claiming、task-bound worktrees 被合并进了新的 s13。

新版的 17 课可以分成几组。s01 到 s04 处理 loop 本身及其边界：最小循环、工具注册、权限检查、hooks。s05 到 s08 处理上下文：计划、子代理、按需加载知识、上下文压缩。s09 到 s12 处理时间维度的机制：记忆、任务系统、后台任务、定时触发。s13 之后进入多代理协调和综合运行时。

每课只加一个机制，座右铭直接点出设计判断。比如 s03 的「先设边界，再给自由」，讲的是权限检查要在工具执行前发生。s08 的「上下文总会满，要有腾挪办法」，讲的是压缩时先压缩工具结果、再压缩历史。

这种节奏的好处是，读者不会被一次性抛入完整系统的复杂度。坏处也很明显：章节之间存在依赖，跳过中间章节直接看 s15 的集成运行时，会缺失很多上下文。

它对「agent 是什么」的拒斥，比它的代码更值得读

README 里有一段专门写「What an Agent Is NOT」。它点名批评拖拽式 workflow 构建器、无代码 AI agent 平台、prompt 链编排库，称这些是「Rube Goldberg machines」——过度工程化、脆弱、把 LLM 当文本补全节点塞进流程里。

这段话的攻击性很强，但它划出了一条清晰的边界：如果你在做的是把 API 调用串起来，你做的不是 agent，你做的只是带 LLM 的 shell 脚本。

这个判断有争议，因为很多生产系统确实用 workflow 编排解决实际问题。但作为教学立场，它逼着读者先回答一个更基础的问题：你写的代码里，哪部分是模型在决策，哪部分是你在替模型决策。

仓库给出的答案是 harness 的五个组成：Tools、Knowledge、Observation、Action Interfaces、Permissions。这个划分并不新颖，但把「观察」和「动作」分开列出来，比很多框架把一切都塞进 tools 的表述更准确。

边界与判断

这个仓库最大的价值不在代码本身，而在它迫使读者面对一个常被回避的问题：你写的 orchestration 代码，到底是在帮模型，还是在替模型做决定。

它的局限也同样明确。单 Bash 工具的设计适合教学，不适合直接用于生产。17 课的机制覆盖了 harness 的主要方面，但每个机制都只实现了最小版本。README 自己也在 course boundary 里说，s17 是机制示例，不是另一个综合运行时。

如果你已经写过完整的 agent 系统，这个仓库的很多内容会显得过于基础。但如果你正在用 LangChain 或类似框架搭 agent，却说不清楚 agent loop 里每一步发生了什么，它值得从头读一遍。

我的判断是：这不是一个拿来用的框架，而是一份帮你建立 harness 心智模型的教材。建议先读 README 前半部分的论述，再按 s01 到 s08 顺序动手跑代码，不要跳到 s15 想看「完整版」——那会错过这个仓库真正想教的东西。