1. 从“打开 Claude Code”到“根本不用打开”一个团队工作流的真实演变一年前我们团队几乎所有人的日常都长一个样早上到工位第一件事打开终端敲claude回车然后开始跟它对话。写代码、改 bug、查文档、生成测试全靠这个入口。那时候谁要是说自己一天没打开过 Claude Code基本等于说自己今天没干活。一年后情况完全反过来了。我们内部做过一次粗略统计团队里大约70% 的日常工作根本不需要打开 Claude Code 这个交互界面。代码照样在写任务照样在推进Agent 照样在跑但那个曾经作为唯一入口的终端窗口反而变成了一个“偶尔才去瞄一眼”的地方。这个变化不是因为我们不用 Claude 了恰恰相反我们用得比以前更狠。变的只是使用方式——从“人主动去找 Agent 对话”变成了“Agent 在后台自己跑人只在关键节点介入”。而推动这个转变的核心就是围绕Harness这套编排思路的持续迭代以及它带来的一个有点反直觉的结果Harness 越成熟它自己就越不需要被显式使用最终走向“自我淘汰”。这篇文章我想把这套演变过程完整拆开讲。包括我们一开始怎么用 Claude Code、后来为什么觉得不对劲、Harness 到底解决了什么问题、orchestration 层是怎么设计的、Agent 和 Skill 的分工怎么划、以及最后那个“70% 不需要打开”的状态是怎么自然形成的。如果你正在做agent 开发、在折腾agent 框架、或者单纯想把claude code 使用这件事从“手动挡”升级到“自动挡”这篇应该能给你省不少弯路。需要先说明一点下面讲的所有方案、参数、目录结构都是我们团队在真实项目里跑出来的不是理论推演。但每个团队的技术栈和协作习惯不一样你完全可以只抄思路不抄细节。2. 为什么“一直开着 Claude Code”这件事本身就是个问题2.1 交互式 Agent 的隐形天花板刚开始用 Claude Code 的时候所有人都觉得效率起飞。你描述需求它给方案你确认它执行。一个下午能干掉以前两天的活。但用了三四个月之后我慢慢发现几个不对劲的地方。第一个问题是注意力被切碎。每次跟 Agent 对话你都得重新加载上下文这个任务之前做到哪了、上次改的文件是什么、为什么那么改。Claude Code 本身有上下文管理但人的脑子没有。你一天在十个任务之间来回切换每个任务都要重新“进入状态”这个切换成本累积起来非常吓人。第二个问题是人变成了瓶颈。Agent 干活很快但它每次做完一步都要等你确认。你不在电脑前它就停在那。你去开个会回来发现它卡在一个“是否继续”的确认框上等了四十分钟。这四十分钟里它本可以继续往下跑。第三个问题更隐蔽重复性任务无法沉淀。今天你教它怎么处理某类报错明天换个任务同样的报错它还是从头问一遍。你没法把“这类事情就该这么办”固化下来每次都得重新对话。这三个问题指向同一个结论交互式对话适合探索性任务但不适合流程化、重复性、需要长时间运行的任务。而一个团队日常干的活里后者占了大头。2.2 从“对话”到“编排”的思维转变想明白这一点之后我们的思路就变了。不再问“怎么让 Claude Code 更好用”而是问“怎么让 Agent 在没人盯着的时候也能把活干完”。这个问题的答案就是orchestration编排。编排的核心思想是把一个大任务拆成若干步骤每个步骤定义清楚输入、输出、执行者、失败处理方式然后让一个调度器按顺序或按依赖关系把这些步骤跑起来。人只在两种情况下介入一是任务开始前定义流程二是流程跑到需要决策的节点时被通知。在这个模型里Claude Code 从“主角”降级成了“演员之一”。它可能负责某个需要复杂推理的步骤但整个流程的推进不依赖它一直开着。真正的主角是那个调度器也就是我们说的Harness。这里要澄清一个常见混淆Harness 和 Agent 不是一回事。Agent 是干活的Harness 是管 Agent 怎么干活的。你可以把 Agent 理解成工人Harness 理解成工头加流水线。工人再厉害没有流水线也只能单件生产有了流水线工人才能批量产出。热词里经常出现的“harness 和 agent 区别”本质就是这个区别。3. Harness 到底是什么把 Agent 装进流水线的那层壳3.1 用生活类比理解 Harness如果上面那段还是有点抽象我换个说法。想象你要做一顿饭。Agent 是一个厨艺很好的厨师你让他做什么他都能做。但如果你每次做饭都要现场跟厨师说“先切菜、再热锅、油温七成热下葱姜、炒香后放肉……”那这个厨师的价值就被你的沟通成本吃掉了。Harness 就是那本菜谱加厨房管理制度。它规定了这道菜分几步、每步用什么工具、火候多少、哪步可以并行、哪步失败了要重来、哪步做完要尝一下味道再继续。有了它你不需要每次都在旁边指挥厨师照着流程走就行你只在“尝味道”这种需要判断的节点出现。技术上说Harness 是一层包裹在 Agent 外面的执行框架。它负责任务分解把用户的一个大需求拆成有序的子任务上下文传递把上一步的输出整理好喂给下一步工具调用管理决定每一步能用哪些工具、怎么调用错误处理与重试某步失败了是重试、跳过还是终止状态持久化整个流程跑到哪了断电重启后能接着跑人工介入点哪些节点需要人确认怎么通知人Claude Code 本身其实也带了一部分 Harness 能力但它是为“单次对话”设计的不是为“长流程编排”设计的。所以当任务变复杂、步骤变多、需要跨会话运行时你就需要一层更外部的 Harness。3.2 为什么说 Harness 会“自我淘汰”标题里那个“自我淘汰”听起来有点玄其实逻辑很朴素。Harness 刚做出来的时候你需要显式地去配置它、启动它、监控它。你会打开一个终端跑harness run task.yaml然后盯着日志看。这时候 Harness 是一个“需要被使用的工具”。但随着它越来越成熟会发生几件事第一触发方式变得无感。以前你要手动启动后来变成 git push 自动触发、定时任务自动触发、甚至某个监控告警自动触发。你不再“使用”Harness而是它在你没注意的时候自己跑了。第二配置变得声明式。以前你要写一堆脚本告诉它怎么做后来变成你只描述“我要什么结果”Harness 自己决定怎么拆步骤。你写的东西越来越少。第三异常处理变得自动化。以前失败了要你去看日志、判断原因、手动重跑。后来常见失败模式都被内置处理了你只在真正罕见的问题上被叫醒。这三件事叠加的结果就是Harness 从一个“你操作的对象”变成了一个“你几乎感觉不到的基础设施”。就像你现在用电你不会说“我在使用电网”你只是按开关。Harness 成熟到一定程度就“消失”在背景里了。这就是自我淘汰——不是它没用了而是它有用到你意识不到它的存在。我们团队那个“70% 不需要打开 Claude Code”的统计本质上就是这个过程的量化体现。不是我们不用 Agent 了是 Agent 和 Harness 已经融进了日常流程不再需要一个显式的“打开”动作。4. 我们团队的 Harness 架构从目录结构到执行链路4.1 整体分层设计先上一张我们实际在用的分层图用文字描述不画图最底层是执行层就是各种 Agent 和工具。Claude Code 在这里各种 shell 命令、文件操作、API 调用也在这里。这一层只关心“给我输入我干活给你输出”。往上一层是能力层也就是 Skill。Skill 是对执行层能力的封装比如“生成单元测试”是一个 Skill“修复 lint 错误”是一个 Skill“根据 schema 生成 API 代码”是一个 Skill。Skill 定义了输入输出格式、依赖哪些工具、成功标准是什么。再往上是编排层也就是 Harness 本体。它读取任务定义按依赖关系调度 Skill处理 Skill 之间的数据传递管理重试和超时。最上面是触发层包括手动触发、定时触发、事件触发比如 git hook、CI 事件、监控告警。这个分层的好处是每一层可以独立演进。换一个 Agent 实现不影响 Skill 定义改一个 Skill 逻辑不影响编排流程加一个新的触发方式不用动下面任何东西。4.2 目录结构长什么样我们仓库里跟 Harness 相关的部分大概长这样.harness/ tasks/ # 任务定义一个 yaml 一个任务 daily-lint.yaml pr-review.yaml doc-sync.yaml skills/ # Skill 定义 fix-lint/ skill.yaml prompt.md validate.sh gen-test/ skill.yaml prompt.md agents/ # Agent 配置 claude-code.yaml local-llm.yaml state/ # 运行时状态gitignore logs/ # 执行日志gitignoretasks/里每个 yaml 定义一个完整流程。比如pr-review.yaml大概是这样name: pr-review trigger: type: webhook event: pull_request.opened steps: - id: fetch-diff skill: git-diff params: base: main - id: lint-check skill: fix-lint depends_on: [fetch-diff] params: auto_fix: false - id: test-gen skill: gen-test depends_on: [fetch-diff] params: coverage_target: 0.8 - id: summarize skill: pr-summary depends_on: [lint-check, test-gen] human_review: true这个定义里fetch-diff和lint-check、test-gen有依赖关系lint-check和test-gen之间没有依赖可以并行。summarize需要等前两个都完成而且标记了human_review: true意思是这一步的结果要人确认后才继续。4.3 执行链路是怎么跑起来的当 PR 被打开webhook 触发 Harness。Harness 做这几件事读取pr-review.yaml解析出步骤和依赖关系构建一个有向无环图DAG确定哪些步骤可以并行从没有依赖的步骤开始执行每步调用对应的 SkillSkill 内部调用 Agent可能是 Claude Code也可能是别的拿到结果结果写入state/供下游步骤读取遇到human_review节点发通知我们用的是内部 IM等人确认全部完成后把汇总结果发回 PR 评论整个过程里人只在第 6 步出现。其他时候Harness 自己跑自己的。这就是为什么“不需要打开 Claude Code”——因为 Claude Code 只是第 4 步里被调用的一个工具它不需要一个可见的终端窗口。5. Skill 和 Agent 的分工别把两件事混在一起5.1 Skill 是“做什么”Agent 是“怎么做”热词里“skill 和 agent 的区别”被搜了很多次说明很多人在这块是懵的。我用一句话说清楚Skill 定义任务的目标和验收标准Agent 负责用它的能力去达成这个目标。举个例子。“修复 lint 错误”是一个 Skill。它定义了输入是代码文件输出是修复后的代码成功标准是 lint 检查通过。至于怎么修——是用 Claude Code 去理解错误然后改还是用一个规则引擎去自动替换那是 Agent 层的事。Skill 不关心。这个分离带来一个巨大的好处你可以换 Agent 而不改 Skill。今天用 Claude Code 修 lint明天觉得本地模型够用了换成local-llmSkill 定义一行不用改。反过来你也可以给同一个 Agent 挂不同的 Skill让它承担不同角色。5.2 一个 Skill 的完整定义拿fix-lint举例它的skill.yaml大概是这样name: fix-lint description: 修复代码中的 lint 错误 inputs: - name: files type: list[string] required: true - name: auto_fix type: bool default: true outputs: - name: fixed_files type: list[string] - name: remaining_errors type: list[object] agent: claude-code timeout: 300 retry: max: 2 on: [timeout, agent_error] validate: ./validate.shvalidate.sh是验收脚本跑一遍 lint如果还有错误就返回非零Harness 就知道这步没成功触发重试或标记失败。这里有个经验validate 脚本一定要写而且要和 prompt 分开。很多人偷懒让 Agent 自己说“我修好了”结果 Agent 经常过度自信。用一个独立的、确定性的脚本去验收能挡掉大量假成功。5.3 Agent 配置的抽象agents/claude-code.yaml大概是这样name: claude-code type: cli command: claude args: - --print - --output-format - json env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} working_dir: ${TASK_WORKDIR}注意--print和--output-format json。这两个参数是关键--print让 Claude Code 以非交互模式运行执行完就退出不进入对话循环json输出让 Harness 能程序化解析结果。没有这两个参数Claude Code 就没法被编排因为它会一直等你输入。这也是很多人卡住的地方他们想用 Claude Code 做自动化但不知道怎么让它“干完就退”。答案就是非交互模式加结构化输出。6. 实操从零搭一个最小可用的 Harness6.1 环境准备与依赖假设你在 Ubuntu 上先把基础环境弄好。Claude Code 的安装按官方文档走就行装完之后确认claude --version能正常输出。Harness 我们用的是自己写的一个轻量调度器核心依赖就几个Python 3.10、PyYAML、一个任务队列我们用的 Redis小规模用文件锁也行。如果你不想自己写市面上也有一些开源的 agent 框架可以参考但我们的经验是自己写一个 200 行的调度器比配置一个重型框架更快因为你的需求往往没那么复杂。pip install pyyaml redis6.2 写第一个 Skill从最简单的开始一个“总结 git diff”的 Skill。skills/summarize-diff/skill.yamlname: summarize-diff description: 总结代码变更 inputs: - name: diff_text type: string required: true outputs: - name: summary type: string agent: claude-code timeout: 120skills/summarize-diff/prompt.md你是一个代码审查助手。下面是一段 git diff请用中文总结这次变更做了什么 不超过 200 字重点说清楚改了哪些功能、有没有风险点。 diff: {{diff_text}}注意{{diff_text}}是占位符Harness 在执行时会把上一步的输出填进去。这个模板机制是 Skill 复用的关键。6.3 写第一个 Tasktasks/summarize-commit.yamlname: summarize-commit trigger: type: manual steps: - id: get-diff skill: shell params: command: git diff HEAD~1 HEAD - id: summarize skill: summarize-diff depends_on: [get-diff] params: diff_text: ${get-diff.stdout}跑起来harness run tasks/summarize-commit.yamlHarness 会先执行git diff把输出存到get-diff.stdout然后调用summarize-diffSkill把 diff 填进 prompt调 Claude Code 非交互模式拿到总结打印出来。这就是最小闭环。你会发现整个过程你没有打开 Claude Code 的交互界面但 Claude 确实干活了。6.4 加上触发和通知手动跑通之后把它挂到 git hook 上。在.git/hooks/post-commit里加一行harness run tasks/summarize-commit.yaml .harness/logs/commit.log 21 这样每次 commit 之后Harness 在后台跑总结写进日志。你不需要做任何事。这就是“无感触发”的第一步。再进一步把结果推到 IM- id: notify skill: im-notify depends_on: [summarize] params: channel: dev-team message: ${summarize.summary}到这一步你已经能体会到那个“自我淘汰”的感觉了Harness 在跑但你没有“使用”它的动作。7. 踩过的坑那些文档里不会写的问题7.1 上下文爆炸最开始我们让每个 Skill 都把完整的上一步输出塞进 prompt结果跑到第三步的时候prompt 已经几万 token 了又慢又贵还经常超限。解决办法是在 Skill 之间做上下文裁剪。每个 Skill 的skill.yaml里加一个context_budget字段Harness 在传递数据时按预算截断。比如summarize-diff只需要 diff 文本不需要上一步的完整日志那就只传 diff。context_budget: max_tokens: 4000 strategy: truncate_middletruncate_middle是保留头尾、砍中间因为 diff 的关键信息往往在开头和结尾。7.2 Agent 假成功前面提过Agent 经常说“我修好了”但其实没修好。除了 validate 脚本我们还加了一个二次确认机制对于关键 Skill跑完 validate 之后再让一个独立的 Agent 检查一遍结果。两个都通过才算成功。这个机制增加了成本但在关键路径上非常值。我们统计过加了二次确认之后下游因为上游假成功而失败的比例下降了大概 60%。7.3 重试风暴有一次一个 Skill 因为网络问题失败Harness 按配置重试结果重试的时候又失败又重试短时间内打了几百次请求把 API 配额打爆了。后来我们加了指数退避加熔断重试间隔按 2 的幂次增长连续失败超过阈值就熔断标记任务失败并通知人。配置大概是这样retry: max: 3 backoff: exponential base_delay: 5 circuit_breaker: threshold: 5 window: 3007.4 状态不一致Harness 跑到一半机器重启了状态丢了重跑的时候有些步骤重复执行了。这在有副作用的步骤上比如发通知、改数据库会出问题。解决办法是幂等设计加状态持久化。每个 Skill 执行前先检查state/里有没有这个步骤的完成记录有就跳过。状态写到磁盘或 Redis重启后能恢复。这个改动不大但让整个系统从“玩具”变成了“能上生产”。8. 常见问题速查问题可能原因排查方向Claude Code 卡住不退出没加--print参数检查 agent 配置确认非交互模式Skill 输出解析失败输出不是合法 JSON加--output-format json或在 validate 里做格式校验任务跑一半停了依赖步骤失败或超时看logs/里对应步骤的日志检查 timeout 配置重试次数异常多没有熔断机制加 circuit_breaker 配置上下文超限步骤间传递数据太多加 context_budget做裁剪重复执行有副作用的步骤状态没持久化检查 state 目录确认幂等检查逻辑通知没发出去IM skill 配置错误单独跑 notify skill 测试并行步骤互相干扰共享了工作目录每个并行步骤用独立 workdir9. 一年下来我最大的几个体会第一个体会是自动化的终点是“感觉不到自动化”。刚开始你会为“我能自动跑任务了”兴奋后来你会发现真正好的状态是你根本想不起来还有自动化这回事它就像呼吸一样自然。我们那个 70% 的数字不是刻意追求的目标是自然演化的结果。第二个体会是Harness 的价值不在“能跑”在“跑挂了能自己恢复”。能跑通的 demo 一天就能写出来但让它稳定跑一年需要处理的是各种边界情况网络抖动、API 限流、磁盘满、进程被杀、状态不一致。这些才是真正花时间的地方。第三个体会是别过度设计。我们一开始想搞一个很复杂的 DAG 引擎支持条件分支、循环、子流程嵌套。后来发现 80% 的任务就是线性的几步偶尔有个并行。把线性流程做扎实比支持一堆花哨特性有用得多。第四个体会是Agent 的能力在涨Harness 的复杂度在降。一年前很多步骤需要人写详细的 prompt 和 validate现在模型自己就能判断得八九不离十。这意味着 Harness 里越来越多的逻辑可以交给 AgentHarness 本身越来越薄。这大概就是“自我淘汰”的另一个层面——不是 Harness 消失了是它把越来越多的决策权交还给了 Agent自己只保留最核心的调度和状态管理。如果你现在还在手动开 Claude Code 一个个任务地跑我建议你先挑一个最重复、最流程化的任务把它拆成 Skill写个最简单的 Harness 跑起来。不用追求完美先跑通一个闭环。跑通之后你会发现那个“打开 Claude Code”的动作慢慢就变得多余了。
