Agent 不是「写」出来的，是「装」出来的
你天天用 Claude Code、Codex、Cursor，但你有没有想过一个问题：这些工具里，到底哪部分是「智能」，哪部分是「代码」？
这个仓库的开篇就给了一个可能让你不舒服的答案：智能（agency）是模型训练出来的，不是代码编排出来的。DeepMind 的 DQN 打 Atari、OpenAI Five 打 Dota 2、AlphaStar 打星际——所有 agent 里程碑都是同一个架构：一个被训练过的模型 + 一个让它能感知和行动的环境。模型是驾驶员，代码是车。
所以作者说：别再说「我在构建 agent」了。你只可能在做两件事之一——训练一个模型，或者构建一个 harness（车架）。而 harness 的定义非常具体：
Harness = Tools + Knowledge + Observation + Action + Permissions
Tools: 文件读写、shell、网络、数据库、浏览器
Knowledge: 产品文档、领域参考、API 规范、风格指南
Observation: git diff、错误日志、浏览器状态
Action: CLI 命令、API 调用、UI 交互
Permissions: 沙箱隔离、审批流程、信任边界「模型决定，harness 执行」。这个仓库就是一门教你把这辆车从 0 造到 1 的课：learn-claude-code——「Harness Engineering for Real Agents」。73,986 Star、11,986 Fork、MIT，2025 年 6 月 29 日建仓，昨天（8 月 12 日）还在合并 PR #512，8 月 11 日刚把课程从 19 节重构到 17 节——这是一个还在快速迭代的活项目。
它到底是什么：17 节课，每节只加一个机制
一句话：一门 0→1 的 agent harness 工程课，17 个章节，每章一个机制、一句 motto、一份可独立运行的 code.py。根目录 s01_agent_loop/ 到 s17_goal_loop/ 是现行版；docs/ 和 agents/ 里是老的 12 节版（迁移期保留）。每章还带中英日三语 README 和 SVG 图解，复杂章节有 <details> 深潜折叠。
| 章节 | 机制 | Motto（一句话） |
|---|---|---|
| s01 Agent Loop | while 循环 + bash | One loop & Bash is all you need |
| s02 Tool Use | TOOL_HANDLERS 分发表 | 加一个工具 = 加一个 handler |
| s03 Permission | 三闸门权限管线 | 先设边界，再给自由 |
| s04 Hooks | PreToolUse / PostToolUse | 绕着循环挂钩子，别重写循环 |
| s05 TodoWrite | TodoItem 计划先行 | 没有计划的 agent 会漂移 |
| s06 Subagent | 全新 messages[] 隔离 | 子任务用新上下文，结论作为工具结果返回 |
| s07 Skill Loading | SkillLoader 按需注入 | 知识按需加载，不是开局全塞 |
| s08 Context Compact | 四级压缩管线 | 上下文总会满，要有腾地方的办法 |
| s09 Memory | 选择/提取/固化 | 记住重要的，忘掉不重要的 |
| s10 Task System | TaskRecord 落盘依赖图 | 大目标拆小任务，排序、持久化 |
| s11 Background Tasks | 线程执行 + 通知队列 | 慢操作丢后台，agent 继续思考 |
| s12 Cron Scheduler | 定时触发 | 到点自动干活，不用人踢 |
| s13 Agent Teams | 持久队友 + 原子认领 + worktree | 一个 agent 干不完，就让队友分工 |
| s14 MCP Plugin | 外部工具接入同一工具池 | 能力不够？MCP 插进来 |
| s15 Integrated Harness | 全部机制合一 | 机制再多，还是一个循环 |
| s16 Workflow Runtime | 脚本编排 + 日志断点续跑 | 编排形状固定了，就写进代码 |
| s17 Goal Loop | 独立评估器决定何时停 | 目标说了算，循环才能停 |
学习路径是递进的：先会动（s01-s04）→ 能干复杂活（s05-s08）→ 跨会话记忆（s09）→ 跑长任务（s10-s12）→ 多 agent 协作（s13）→ 扩展组装（s07/s14/s15）→ 编排与收尾（s16/s17）。每章 motto 都是可执行的原则，比如 s05 那句「An agent without a plan drifts——完成率翻倍」背后是有数据的。
三个最值得拆的设计
1. s01 的 137 行：整个 Agent 就是一个 while 循环
先看事实：s01 的 code.py 一共 137 行，其中核心循环长这样（原样摘自仓库）：
def agent_loop(messages: list):
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_bash(block.input["command"])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
# 把工具结果喂回去，继续循环
messages.append({"role": "user", "content": results})工具定义只有一个 bash，SYSTEM prompt 就一句：「You are a coding agent at {cwd}. Use bash to solve tasks. Act, don't explain.」——「Bash is all you need」不是口号，是字面意思。模型自己决定什么时候调工具、什么时候停；代码只负责执行模型要的东西。这个认知是整门课的锚点：后面的 16 节课，全是围着这个循环加机制，而且尽量不动循环本身。
2. s03 的三闸门权限管线：主循环只加了一行
权限系统是「先设边界再给自由」的完整演示，三闸门：硬拒绝名单 → 规则匹配 → 用户审批。关键设计是它接进主循环只花了一行——if not check_permission(block): continue。
我把这章克隆下来实测了（这部分是纯 Python 逻辑，不需要 API key）。check_deny_list 用子串匹配挡危险命令，check_rules 用 is_relative_to(WORKDIR) 挡路径逃逸、用关键词匹配挡破坏性命令，第三闸是 input() 阻塞式人工确认。真实输出：
=== Gate 1: deny list ===
'rm -rf /' -> Blocked: 'rm -rf /' is on the deny list
'sudo apt update' -> Blocked: 'sudo' is on the deny list
'ls -la' -> PASS
'echo hi' -> PASS
=== Gate 2: rules ===
write ../evil.txt -> Writing outside workspace # 路径逃逸被 is_relative_to 拦住
write notes.txt -> None # 工作区内，放行
bash 'rm foo' -> Potentially destructive command
bash 'ls' -> None
=== Gate 3: approval (auto-answer) ===
bash rm important.py -> DENIED (答 n)
bash rm important.py -> ALLOWED (答 y)三闸门全部按设计工作。注意一个细节：s01 里这份「危险命令名单」是直接硬编码在 run_bash 里的（["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]），到了 s03 才被抽出来做成正式管线——你能亲眼看到机制是怎么从「顺手写的 if」进化成「可扩展的系统」的，这正是 0→1 课程该有的样子。
3. s08 的四级上下文压缩：Claude Code 不「失忆」的真相
上下文管理是所有 Coding Agent 的命门，s08 给出一个教科书级的四级管线：
- tool_result_budget——超大的工具结果先落盘到
.task_outputs/tool-results/，对话里只留引用 - snip_compact——把旧对话中段归档到
.transcripts/，保持上下文「头尾完整、中段归档」 - micro_compact——进一步缩短旧工具结果
- compact_history——前三步做完还超限，才做真正的历史摘要
另外还有两条触发路径：模型主动调 compact 工具、或 API 报 prompt_too_long 时走 reactive_compact 压缩后重试一次。这解释了 Claude Code 为什么长会话不崩——不是模型上下文变大了，是 harness 在动手腾地方。我们之前写过的 headroom（压缩层）就是把这个机制产品化。
再往后 s13（Agent Teams，1794 行，全课最重的一章）讲持久队友 + 原子任务认领 + task-bound worktrees，s17（Goal Loop）让一个独立评估器读完整段对话来决定「这活到底干完没有」——python s17_goal_loop/code.py "/goal pytest tests exits with code 0" 就是它的用法。这两章已经够格当源码精读了。
跟「教 Agent 做事」的几个项目比一比
| 维度 | learn-claude-code（73.9K★） | Superpowers（271K★，6月28日） | ECC（239K★，8月10日） | opencode（196K★，7月13日） |
|---|---|---|---|---|
| 形态 | 17 节手写课程 + 可运行代码 + Web 平台 | Skills 框架 + 开发方法论 | harness 性能优化系统（技能/本能/记忆） | 生产级 Coding Agent（TS） |
| 核心主张 | Agency 来自模型，工程师的活是造 harness | 给 Agent 装工程纪律 | 优化 agent 的运行表现 | 直接给你一个能用的 agent |
| 产出 | 理解 + 能自己写的 0→1 harness | 一套可复用的 skills 库 | 一整套装进 harness 的能力包 | 一个产品 |
| 学习属性 | 教学优先，每章独立跑 | 偏实践配置 | 偏使用 | 偏使用 |
| 许可证 | MIT | MIT | MIT | MIT |
一句话：Superpowers 教你「让 Agent 守规矩」，ECC 教你「让 Agent 跑得快」，opencode 直接给你一辆车，而 learn-claude-code 教你「车是怎么造出来的」。前三个解决「怎么用」，它解决「为什么能work」——这也是 60 篇里唯一一篇站在「拆解」视角的。
上手：十分钟跑起来（实测）
# 1. 克隆（我实测 5MB 仓库，几秒完事）
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt # 只有 anthropic / python-dotenv / pyyaml
# 2. 配环境变量（API key 和模型 ID 都是必填）
cp .env.example .env
# ANTHROPIC_API_KEY=sk-... 必填
# MODEL_ID=claude-sonnet-4-6 必填，默认值已写好
# 想用国产模型？README 给了兼容表：
# MiniMax-M3 / glm-5.2 / kimi-k2.7-code / deepseek-v4-pro
# 配 ANTHROPIC_BASE_URL 即可走 Anthropic 兼容协议
# 3. 从第一课开始
python s01_agent_loop/code.py # 137 行：one loop + bash
python s03_permission/code.py # 三闸门权限
python s08_context_compact/code.py # 四级压缩（最复杂的一章之一）
python s17_goal_loop/code.py "/goal pytest tests exits with code 0" # 终点章
# 4. 不想配 key？两条路：
python -m pytest tests/ # 14 个测试文件，用 test double，不烧 API
cd web && npm install && npm run dev # Next.js 16 在线课程，localhost:3000我实测的体感：s01 从「读代码」到「看懂」不超过五分钟——137 行里一半还是注释和 README。s03 的权限管线我在没配 API key 的情况下直接 import 跑通了（就是上面那段输出）。仓库还带了 14 个测试文件（test_goal_loop.py、test_agent_teams_runtime.py、test_compaction_tool_pairs.py……），s17 的 docstring 明说「Test doubles belong in tests only」——想不花钱把机制跑一遍，跑测试就行。
实际体验的几个坑
- 没有 API key 连 import 都过不去——每章 code.py 都在模块级初始化
client = Anthropic(...)和MODEL = os.environ["MODEL_ID"]，不设环境变量直接 KeyError，连「看看它长啥样」都不行。想纯看机制：直接读代码，或跑 tests/（test double 不碰 API） - 课程刚重构完，新旧编号对不上——8 月 11 日刚把 19 节 streamline 成 17 节，而
docs/和agents/里还是老的 12 节版（老 s03=TodoWrite，新 s03=Permission，完全错位）。README 明确警告：别把新旧章节号混着读。看新编号一律以根目录s01_*～s17_*为准 - 章节体量差异巨大——s01 只有 137 行，s13（Agent Teams）有 1794 行，s17 也有 882 行。前 12 章适合通读，s13/s15/s16/s17 当源码精读更实际，硬啃完容易劝退
- deny list 是子串匹配，别当安全边界——名单里是
"sudo"、"rm -rf /"这种裸子串，任何含 sudo 的命令都会被挡（想改 sudoers 也一并误伤）。它只是「第一道闸」，s03 的定位是教学演示，真实产品的权限（比如 Claude Code 的 permission modes）要复杂得多 - 第三闸是阻塞式 input()——权限确认直接卡住等键盘输入，headless / CI 里跑会挂死。这恰好演示了为什么真实产品要把审批做成 hook 化、可脚本化的（s04 的内容）——先踩坑再理解设计，效果反而好
- readline 那段是给 macOS 修的——s01 开头 6 行 readline 绑定（#143 的 UTF-8 退格修复）是 macOS libedit 的补丁，Linux 上纯属摆设，看到别困惑
- Web 平台是静态生成——
web/是 Next.js 16，predev会先用 tsx 脚本从课程 markdown 抽取内容再渲染，本质是课程阅读器，别指望在浏览器里跑完整 agent
跟我们有关的一件事
这个工坊推过的项目，一半的底层机制都能在这门课里找到「最小实现」：hooks（s04，我们写过的 cc-switch / claude-mem 同款机制）、MCP（s14，工坊半壁江山）、subagent（s06，opencode / goose 的协作基础）、memory（s09，claude-mem 和 engram 的底层逻辑）、多 agent 协作（s13，multica / superset / orca 在做的事）、cron（s12——这个工坊自己就跑在 cron 上）。花一个下午把 17 章过一遍，等于把过去两个月推的项目串成了一条线，你会突然看懂那些「产品」到底在 harness 的哪一层加了料。
作者还留了「毕业作品」：npm i -g @shareai-lab/kode 的 Kode CLI（支持 GLM / MiniMax / DeepSeek 等开源模型，Windows 兼容）和 kode-agent-sdk（可嵌进后端/浏览器插件/嵌入式设备的无进程开销 SDK）。学完 17 节课直接上手自己造，路是通的。
要不要我帮你把 s01、s03、s08 三个章节的 code.py 拉到一个测试仓库里，配上 DeepSeek 的 Anthropic 兼容端点（README 里给了 deepseek-v4-pro 的配置），跑一个真实的「让 Agent 改代码 → 权限拦截 → 上下文压缩」完整链路，对比一下 token 消耗？
适合谁用
- 被「AI 编程工具是黑盒」困扰的人——读一遍 s01，黑盒就没了：137 行而已
- 想自己写 agent / harness 的工程师——这是目前最完整的 0→1 教程，还带可运行代码和测试
- Claude Code / Hermes / Codex 重度用户——理解底层机制后，调权限、写 hooks、配 MCP 都不再是「照着文档抄」
- 想用开源模型跑 CLI agent 的人——课程本身支持 Anthropic 兼容端点，毕业作品 Kode CLI 直接面向 DeepSeek / GLM / MiniMax
- 团队想统一 agent 工程认知——17 章每章一个机制，是绝佳的 onboard 教材
总结
learn-claude-code 14 个月 74K Star 不靠噱头：它把「Coding Agent 是怎么工作的」这个问题，拆成了 17 个你能亲手实现的机制。核心思想只有一句：别把智能写进代码——把世界（harness）建好，模型自己会行动。
MIT 协议、三语文档、可运行代码、带测试、昨天还在更新——对想真正理解 agent 而不是只会用 agent 的人来说，这是目前能找到的最好的起点。跑一下 python s01_agent_loop/code.py，你会看到「Bash is all you need」不是营销口号，是字面意思。
项目地址：github.com/shareAI-lab/learn-claude-code（Web 平台：learn.shareai.run · Kode CLI：github.com/shareAI-lab/Kode-CLI）