学习 Claude Code —— 驾驭面向真实智能体的工程技术

真正的智能体能力（Agency）是通过训练植入深度学习模型中的，而不是通过程序代码或编排图构建出来的。要成为一个可运行的产品，智能模型需要一个强大的载体：一个管理工具、知识、上下文和权限的 Harness。本指南将探讨 Harness 工程，借鉴 Claude Code 极简且高效的架构，教你如何从零开始构建实用的智能体系统。

GitHub - shareAI-lab/learn-claude-code: Bash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1

可用语言： English | 中文 | 日本語

智能体能力（Agency）——即感知、推理和行动的能力——来自模型训练，而非外部的代码编排。模型是驾驶员；Harness 是车辆。

每个智能体的核心都是一个神经网络，它通过数以十亿计的关于感知、推理和行动序列的梯度更新塑造而成。人类是这一概念的生物学证明：我们通过感官感知，通过大脑推理，通过身体行动。当 AI 实验室提到“智能体（agent）”时，他们指的是在环境基础设施中运行的、经过训练的模型。

模型驱动智能体能力的历史记录是明确无误的：

• 2013 年（DeepMind DQN 玩转雅达利）： 一个单一的神经网络，仅接收原始像素和游戏分数，在没有任何特定游戏规则的情况下，掌握了 7 款雅达利 2600 游戏。到 2015 年，它扩展到了 49 款游戏并达到了专业水平，证明了模型可以通过经验进行学习。
• 2019 年（OpenAI Five 征服 Dota 2）： 五个神经网络在 10 个月内与自己进行了相当于 45,000 年的 Dota 2 游戏，并以 2-0 击败了 TI8 世界冠军。在没有预设脚本策略的情况下，他们在 42,729 场公开比赛中赢得了 99.4% 的胜利。
• 2019 年（DeepMind AlphaStar 掌控《星际争霸 II》）： AlphaStar 在闭门比赛中以 10-1 击败了职业选手，并在欧洲服务器上达到了宗师（Grandmaster）段位，克服了非完全信息和实时组合动作空间带来的挑战。
• 2019 年（腾讯“绝艺”称霸《王者荣耀》）： 腾讯 AI 实验室的“绝艺”系统在完整的 5v5 比赛中击败了 KPL 职业选手。在 1v1 对决中，职业选手在 15 场比赛中仅赢了 1 场。其训练强度达到了每天相当于人类训练 440 年的水平。
• 2024–2025 年（LLM 智能体重塑软件工程）： Claude、GPT 和 Gemini 等大语言模型被部署为编程智能体。它们阅读代码库、实现功能并调试错误。其架构保持完全相同：将一个经过训练的模型放入环境中，并赋予其用于感知和行动的工具。

每一个里程碑都指向同一个事实：智能体能力是训练出来的，而不是写代码写出来的。然而，模型仍然需要一个在其中运行的环境——无论是雅达利模拟器、游戏客户端，还是 IDE 和 Shell 终端。模型提供智能；Harness 提供行动空间。

“智能体（agent）”这一术语已被一个由拖拽式工作流构建器、无代码平台和提示词链编排库组成的“提示词管道（prompt-plumbing）”行业所绑架。这些系统运行在一个共同的幻想之上：即用 if-else 分支、节点图和硬编码的路由逻辑将 LLM API 调用串联起来，就构成了“构建智能体”。

这些都是鲁布·戈德堡机械（Rube Goldberg machines）——过度设计、脆弱的程序化规则管道，而 LLM 只是被强行塞入其中作为一个文本补全节点。你无法通过堆叠程序化规则树和提示词瀑布流来暴力破解出智能。

当你构建一个智能体产品时，你的工作属于以下两类之一：

1. 训练模型： 通过强化学习、微调或 RLHF 调整权重，以塑造行为轨迹。
2. 构建 Harness： 编写为模型提供运行环境的操作代码。

Harness 提供了智能体在特定领域工作所需的一切：

$ext{Harness} = ext{工具} + ext{知识} + ext{观察} + ext{行动接口} + ext{权限}$

Tools:          file I/O, shell, network, database, browser
Knowledge:      product docs, domain references, API specs, style guides
Observation:    git diff, error logs, browser state, sensor data
Action:         CLI commands, API calls, UI interactions
Permissions:    sandbox isolation, approval workflows, trust boundaries

Harness 的质量直接决定了模型智能的表达效果。作为一名 Harness 工程师，你的职责是：

• 实现工具： 给智能体装上手。设计原子化、可组合且描述清晰的工具，用于文件操作、Shell 执行、数据库查询和浏览器控制。
• 整理知识： 赋予智能体领域专业知识。按需加载文档、规范和样式指南，而不是预先加载全部。
• 管理上下文： 给智能体一个干净的记忆。使用子智能体隔离（subagent isolation）来防止噪声泄漏，使用上下文压缩（context compaction）来防止历史膨胀，使用任务系统来持久化目标。
• 控制权限： 建立边界。沙箱化文件访问，对破坏性操作要求明确的人工审批，并执行信任边界。
• 收集轨迹数据： 将执行序列视为训练信号。现实世界中的执行历史是微调下一代模型的原材料。

Claude Code 是一个优雅的智能体 Harness 实现，这源于它没有做的事情：它不试图去充当智能体。它不强加僵化的工作流，也不用手工设计的决策树来代替模型自身的判断。它只是提供工具、知识、上下文管理和权限边界，然后退到幕后。

将 Claude Code 剥离到其本质，会发现它包含：

• 一个智能体循环（agent loop）
• 核心工具（bash, read, write, edit, glob, grep, browser）
• 按需加载技能
• 上下文压缩
• 子智能体派生
• 带有依赖图的任务系统
• 异步邮箱团队协作
• 工作区（worktree）隔离的并行执行
• 权限治理
• 扩展钩子（hooks）系统
• 记忆持久化
• 模型上下文协议（MCP）外部能力路由

                    THE AGENT PATTERN
                    =================

    User --> messages[] --> LLM --> response
                                      |
                            stop_reason == "tool_use"?
                           /                          \
                         yes                           no
                          |                             |
                    execute tools                    return text
                    append results
                    loop back -----------------> messages[]

模型决定何时调用工具以及何时停止。Harness 代码只需执行模型请求的操作。

本项目中的每节课都是在这一基础循环之上，层层叠加一个 Harness 机制：

def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        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 = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

课程围绕 20 个核心课时展开，每个课时都会结合一个指导原则，引入一个关键的 Harness 机制：

• s01 "One loop & Bash is all you need" —— 一个工具 + 一个循环 = 一个智能体。
• s02 "Adding a tool means adding one handler" —— 保持循环不变；将新工具注册到分发映射中。
• s03 "Set boundaries first, then grant freedom" —— 先设定边界，再赋予自由。检查什么可以运行，什么必须停止，以及什么需要审批。
• s04 "Hook around the loop, never rewrite the loop" —— 围绕循环挂钩（hook），绝不重写循环。在不修改主循环的情况下添加扩展点。
• s05 "An agent without a plan drifts" —— 没有计划的智能体会随波逐流。执行前列出步骤，使完成率翻倍。
• s06 "Big tasks split small, each subtask gets clean context" —— 大任务拆小，每个子任务获得干净的上下文。运行子智能体处理旁支工作，只带回结果。
• s07 "Load knowledge on demand, not upfront" —— 按需加载知识，而非预先加载。先列出技能，仅在需要时展开。
• s08 "Context always fills up—have a way to make room" —— 上下文总会填满——要想办法腾出空间。为无限会话使用多层压缩策略。
• s09 "Remember what matters, forget what doesn't" —— 记住重要的，忘记不重要的。实现记忆选择、提取和巩固。
• s10 "Prompts are assembled at runtime, not hardcoded" —— 提示词在运行时组装，而非硬编码。使用按需加载的基于分段的拼接。
• s11 "Errors aren't the end, they're the start of a retry" —— 错误不是终点，而是重试的起点。当任务失败时重试、管理上下文空间，或尝试备用模型。
• s12 "Big goals break into small tasks, ordered, persisted to disk" —— 大目标分解为有序的小任务，并持久化到磁盘。构建一个基于文件的任务图，用于多智能体协作。
• s13 "Slow ops go background, agent keeps thinking" —— 慢操作转后台，智能体继续思考。运行后台线程，并在完成时注入通知。
• s14 "Fire on schedule, no human kick needed" —— 按计划触发，无需人工介入。触发基于时间的自主任务。
• s15 "Too big for one agent—delegate to teammates" —— 任务对一个智能体来说太大了——委托给队友。使用异步邮箱组织持久的队友。
• s16 "Teammates need shared communication rules" —— 队友之间需要共同的通信规则。强制执行严格的请求-回复格式以进行协调。
• s17 "Teammates check the board, claim work themselves" —— 队友查看任务板，自己认领工作。建立自组织的智能体团队。
• s18 "Each works in its own directory, no interference" —— 各自在独立的目录中工作，互不干扰。使用工作区（worktrees）将任务绑定到独立目录。
• s19 "Not enough capability? Plug in more via MCP" —— 能力不够？通过 MCP 插入更多。通过模型上下文协议（Model Context Protocol）将外部工具连接到统一的工具池中。
• s20 "Many mechanisms, one loop" —— 机制虽多，循环唯一。将所有组件整合到单一且全面的智能体 Harness 中。

为了保持学习路径清晰，本仓库对某些生产级架构采用了简化的教学实现：

• 使用极简的事件/钩子总线生命周期，而不是完整的企业级事件总线（如 PreToolUse、SessionStart 等）。
• 权限策略和信任工作流是基础性的，而非完全由企业规则治理。
• 工作区（worktree）生命周期和会话控制（恢复/派生）保持最简。
• MCP 运行时是直接实现（省略了复杂的 OAuth、轮询或传输路由）。
• 邮箱协议使用简单的 JSONL 文件结构。

课程进度从核心执行开始，依次过渡到任务管理、记忆处理、异步后台操作，最后是多智能体协作。

本项目包含一个旧版的 12 课时路线，以及一个全面的 20 课时路线。请确保你使用的是正确的文件夹，因为不同版本之间的章节编号有所不同。

每个章节都被结构化为一个独立的文件夹，其中包含说明文档、可运行的代码和可视化辅助工具：

s08_context_compact/
  README.md              # Core lesson with inline code
  README.en.md           # English translation
  README.ja.md           # Japanese translation
  code.py                # Standalone runnable implementation
  images/                # SVG diagrams 

开始探索代码库并运行课程：

# Clone the repository
git clone https://github.com/shareAI-lab/learn-claude-code

# Navigate to the workspace
cd learn-claude-code

# Install required packages
pip install -r requirements.txt

# Configure environmental variables
cp .env.example .env

• 智能是学习出来的，而非写出来的： AI 的智能体能力（Agency）是模型训练（梯度更新、强化学习、轨迹暴露）的产物，而不是脆弱的提示词链库或程序化规则引擎。
• Harness 是你的产品： 工程目标是构建一个可靠的载体——处理状态、工具输入、文件沙箱、上下文管理和权限——同时允许模型做出执行决策。
• 智能体循环的力量： 保持你的核心智能体循环绝对简单。通过添加工具处理器、挂钩行动、管理上下文状态和隔离的子智能体来扩展行为，而不是让核心循环变得复杂。
• 数据是终极资产： 设计一个强大的执行 Harness 允许你捕获实际的轨迹数据，这些数据可作为训练反馈循环，使未来的模型更聪明。

若要查看实现细节或在本地运行各章节，请访问 GitHub 仓库。