Appearance
2小时速通Harness工程：从零搭建Claude Code智能体系统
开发智能体不是写一堆 if-else。智能体就是大模型本身，你要做的是给它搭一个干活的环境——Harness。这个项目 12 节课，从零开始造这辆车。
什么是 Harness 工程？
Harness = 工具 + 知识 + 上下文管理 + 权限边界
打个比方：模型是司机，Harness 是车。你不需要教司机怎么开车，只需要造一辆好车。
12 章节总结
| 阶段 | 课节 | 干了什么 | 解决的问题 |
|---|---|---|---|
| 让它跑起来 | S01 | 一个循环 | 智能体能运转了 |
| S02 | 工具箱 + 围栏 | 能干活，有边界了 | |
| 让它干得好 | S03 | Todo 清单 | 不跑偏了 |
| S04 | 子智能体 | 能分工，上下文不臃肿 | |
| S05 | 技能文件夹 | 有知识储备，按需取用 | |
| S06 | 三层压缩 | 聊多久都不爆 | |
| 让它记得住 | S07 | 任务图 | 关机了任务还在 |
| S08 | 后台线程 | 不傻等了 | |
| 让它带团队 | S09 | 队友 + 收件箱 | 一个人忙不过来，招人 |
| S10 | 通信规矩 | 关机要握手，大事要审批 | |
| S11 | 自动认领 | 不用老板盯着，自己找活 | |
| S12 | 独立目录 | 各写各的，别打架 |
S01：最小智能体 — 一个循环就够了
核心就是一个循环：让智能体不断调用工具，直到它自己判断不再需要调用为止。
整个 Agent：把用户问题丢给大模型 → 大模型觉得需要用工具就用 → 用完把结果喂回去 → 大模型继续想 → 要么继续用工具，要么直接给答案。
什么时候停：大模型自己决定，不需要你写任何判断逻辑。
S02：工具箱 — 能用什么、不能碰什么
两件事：
- 建工具箱，把所有允许用的工具注册进去（读文件、写文件、编辑文件、跑命令），没注册的根本看不见
- 给文件工具加围栏，只能操作项目目录里的文件，防止越界访问系统文件
加新工具：往工具箱里多注册一条就行，循环代码一行不变。
S03：Todo 清单 — 防止注意力漂移
智能体干着干着容易跑偏，忘记最初目标，开始即兴发挥、重复做事、跳步。
解决办法：加 Todo 清单。接到任务后先列出步骤，然后一步一步打勾。
规则：同一时间只能有一个任务「进行中」。
兜底：连着 3 轮没更新 Todo，系统悄悄塞一条提醒进去。
S04：子智能体 — 上下文隔离与分工
所有工作产生的中间内容都堆在同一个上下文里，越来越臃肿。
解决方案：在工具箱里增加 task 工具。父 Agent 创建子 Agent，把子任务交出去。
子 Agent 拥有全新、干净的上下文，独立工作。最终传回给父 Agent 的只是一段简短摘要，所有中间过程直接丢弃。
防套娃：子 Agent 的工具箱里没有 task 工具。
S05：技能加载 — 按需加载的知识体系
Harness 有自己的文件系统结构。所有 Skill 以文件夹形式组织，每个文件夹里有 SKILL.md 文件。
两层加载：
| 层次 | 时机 | 内容 |
|---|---|---|
| 第一层 | 启动时 | 扫描所有 SKILL.md，把技能名称和简短描述注入系统提示，几十 token |
| 第二层 | 执行时 | 智能体确定需要某个技能时，调用 load_skill，完整 SKILL.md 内容注入上下文 |
核心思想：启动时只给菜单，点菜时才上完整食谱。
S06：上下文压缩 — 三层机制保证无限会话
上下文窗口有限，读几十个文件、跑几十条命令，轻松突破上限。
三道防线：
| 防线 | 说明 |
|---|---|
| 第一道 | 每轮自动把 3 轮以前的工具返回内容替换成标记 |
| 第二道 | token 总量超阈值时自动触发，存完整对话到磁盘，用摘要替换历史消息 |
| 第三道 | 智能体自己觉得太乱，可主动调用压缩工具 |
关键：历史信息存在磁盘上，没有真正丢失。
S07：任务系统 — 任务之间有依赖关系
任务之间不是单纯线性关系，更像一张图：任务 A 完成后才能执行 B，C 和 D 完成后才能执行 E。
核心设计：每个任务创建单独的 JSON 文件管理，分配唯一 ID 和三种状态（pending、in_progress、completed）。
依赖检查：执行时检查是否有前置依赖，有依赖就标记为待做；任务完成后自动查找其他任务的 blockedBy 列表，删掉依赖 ID，解锁任务。
四个工具：task_create、task_update、task_list、task_get。
S08：后台任务 — 别傻等
执行耗时较长的任务时，智能体只能干等，什么事都不干。
核心机制三步：
- 后台启动：background_run 把命令丢到后台线程，立即返回
- 结果进队列：后台命令跑完后，结果存进通知队列
- 每轮自动注入：调用模型前，Harness 自动检查队列，把完成的后台任务结果注入消息
S09：组建团队 — 一个人忙不过来，招人
大型任务一个人干不完，需要分工协作。
设计：默认对话的 Agent 为领导 Agent，只有领导才能创建队友。不同队友各自拥有独立线程，运行独立循环。
通信：每个 Agent 单独配置文件夹作为收件箱，每次调用模型前，将收件箱内容注入上下文，每个 Agent 都可以收发消息。
S10：团队规矩 — 不能想停就停
直接杀掉队友线程，可能正写到一半，留下烂摊子。重大操作也没有审批。
两个规矩（请求-响应 + 唯一 ID）：
| 规矩 | 流程 |
|---|---|
| 关机 | 领导发请求（带 ID），队友收到后收尾完毕再回复同意（引用同一个 ID） |
| 审批 | 队友提交方案（带 ID），领导审核后回复批准或拒绝（引用同一个 ID） |
S11：自治 — 别等老板分配，自己找活
让队友更有自主性：不需要领导逐个分配任务，队友自己找活干。
任务看板机制：
- 工作阶段每轮检查收件箱
- 空闲阶段每 5 秒轮询收件箱和任务看板
- 有新消息或可认领任务，自动领取并回到工作状态
- 持续 60 秒无新消息无任务，自动关机
防失忆：上下文压缩可能导致队友忘记自己是谁，系统检测到上下文过短时自动重新注入身份信息。
S12：Worktree 任务隔离 — 各干各的目录
多个智能体同时干活时，会互相干扰：智能体 A 在改一个文件，智能体 B 也在改同一个文件，未提交的改动互相污染。
解决方案：给每个任务划分独立工作空间，用 git worktree。每个目录都是独立的 git 分支：
- 各自改动在各自分支上，可以独立提交
- 完成后通过 git merge 合回主分支
- 出了问题可以干净地回滚整个分支
关联：每个 worktree 通过任务 ID 和任务系统绑定——任务管「做什么」，worktree 管「在哪做」。
总结
起点：30 行代码的循环。
终点：有工具、有记忆、有团队、能自治的完整系统。
核心：自始至终，循环那几行代码一行都没变过，变的全是 Harness。
这大概就是项目想说的：别去「开发」智能体，去给它造一个好用的工作环境。模型够聪明，你把环境搭好，剩下的它自己会搞定。
关键词：Harness工程, Claude Code智能体, Agent开发, 工具箱, 上下文压缩, git worktree
