把 Claude Code 源码蒸馏成 Agent Skill — Harness Engineering 实践

前段时间 Claude Code 源码泄露了51.2 万行 TypeScript。看到消息后的第一反应是趁热把 harness 层的设计模式系统性地蒸馏一遍 — 这大概是目前能拿到的最成熟的生产级 Agent harness 实现。没想到有朝一日能让 Claude Code 蒸馏自己热乎乎的代码变成冷冰冰的 Skill。最终产出的是一个可以直接npx skills add安装的 Agent Skill — agentic-harness-patterns-skill[1]。它从 Claude Code 的实现中提炼了六个 harness 层的设计原则覆盖了从 Agent 如何管理记忆和上下文到多 Agent 如何协调分工再到工具权限和生命周期如何设计。关注的是背后的 why 而非 Claude Code 的 how以期可以直接迁移到其他 Agent 框架或者用于指导个人一些 agent harness 开发与设计的最佳实践。agent-harness-patterns但 51.2 万行代码显然不是一个 Agent 在一个 session 里能处理的。蒸馏过程本身就变成了一次 Harness Engineering 的实践 — 我设计了一套多 Agent 协调流程让 CodexGPT 5.4 xhigh负责 reviewClaude CodeOpus 4.6 max负责执行每轮 review action 都在新 session 中进行通过文件系统协调。我的设计原则主要来自几篇经典的 lab 博客• Anthropic - Effective harnesses for long-running agents[2]• OpenAI - Harness engineering: leveraging Codex in an agent-first world[3]• OpenAI - How we used Codex to build Sora for Android in 28 days[4]如果让我总结这几篇博客传达的最有价值的 insights•Anthropic我个人觉得是维护多 Agent 的 Role 并善于利用文件系统作为上下文。A 社在多 Agent 领域理解很深 同时 FileSystem first 和 Just-in-Time Context 也是它的偏爱•OpenAI在 Codex 不断迭代的过程中逐步对齐了文件系统作为上下文的理念另外一个比较有意思的是OpenAI 的博客给我的感觉是在强调 Harness Engineering 需要注入人的品味后文会提到。回过头看蒸馏的过程有点像做 PCA主成分分析式的降维。我通过注入自己的博客和偏好构建了一组基向量然后让 Agent 从复杂的代码空间中做投影提取出几个最主要的 principle。代码是高维的但有价值的设计模式其实是低秩的我蒸馏的本质就是找到这些主成分。古老的数模记忆攻击了我本文从三个层面展开Harness 协作架构设计、我在其中做了什么Human-in-the-loop、以及实践过程中的一些反思。1. Harness Design: Split by Role, Coordinate via Filesystem核心是将 review 与 execution 分离到两个不同的模型家族且每轮 review-action 循环都在全新的 session 中进行。这样设计的原因是我日常使用时感觉 GPT 5.4 xhigh 在 review 和 design 方面不会偷懒角色Agent职责审查与架构CodexGPT 5.4 xhigh对照源码核查事实、判断方向和抽象层级、从用户视角审查可用性构建与执行Claude CodeOpus 4.6 max阅读源码、起草参考文档、协调子 Agent 并行工作、执行修改至于为什么要分离 Agent Role和你不让实现者审查自己代码的逻辑一样。Codex 以全新视角对照源码审查Claude Code 带着对先前决策的完整理解执行修改。两个 Agent 互不可见对方的 session。Anthropic 在 Building multi-agent systems: When and how to use them[5] 中也提到过类似思路*One multi-agent pattern that consistently works well across domains is theverification subagent. This is a dedicated agent whose sole responsibility is testing or validating the main agent’s work.那它们靠什么协调文件系统。通过文件名 简单的 Read Tool低成本且不会丢信息。这个设计可以参考 Anthropic 的 How we built our multi-agent research system[6] 中的原则Subagent output to a filesystem to minimize the ‘game of telephone.’感兴趣的可以阅读 Multi-Agent System一篇就够了。[7]。由于是文档型任务而非 Coding 任务顶层的编排让两个 Agent 交互还是由我来控制。在正式开工前我让 Codex 一次性生成了整套 harness 基础设施。这套文件的设计目标是让一个没有当前对话上下文的 clean agent 也能直接接手知道去哪读、先做什么、做完写到哪里、怎么 review。fig1-harness-filesystem文件按职能分为三组角色定义Role Briefs告诉 Agent “你是谁规则是什么”文件作用clean-agent-brief.mdBuilder Agent 的入场说明操作规则、最低输出要求、什么情况下应该停下来问人review-agent-brief.mdReviewer Agent 的入场说明审查优先级、输出模板、问题严重度的分级标准协调层Coordination— Agent 之间的共享状态文件作用context-map.md源码上下文地图50 源文件按 harness 层分组标注每个文件为什么重要pattern-notes.md探索笔记前几轮扫描的关键发现供后续 Agent 直接读取而非重新探索task-board.md共享任务队列35 个任务含依赖关系和退出标准progress-log.md只追加的活动日志 决策日志最终记录了 13 项关键决策handoff_v0_*.mdReview 与 execution 之间的行动简报codex_review_v0_*.mdCodex 的审查输出含严重度分级、源码引用、推荐修复方向质量门控Quality Gates— 定义什么算完成文件作用review-checklist.md阻塞性问题事实错误、无源码依据的声明vs. 质量检查跨运行时可移植性、触发词准确性execution-strategy.md多 Agent 执行策略谁做什么、并行度、子 Agent 的 brief 模板output-format.md产出物的格式规范文件结构、元数据字段、长度限制这套文件本身就体现了 harness engineering 的一个核心理念先建协调机制再开始干活。如果直接让 Agent 开始提取模式没有 task-board 追踪进度、没有 review-checklist 定义质量标准后面的多 Agent 协作就无从协调。Handoff 文档是 Agent 之间的 API。每份 handoff 恰好包含下一个 Agent 执行所需的信息一般来说是索引告诉一个新的 agent 需要的 contexts 所在的大致范围。接收方在全新 session 中启动读取最新的 handoff例如xxx_handoff_xx.md然后执行。因此对于每次 review or executionagent 都会有三类 contexts• agent role• agent task handofftask specific对于 codex 则是 progress-log.md 中的 diff• repo filesystem一些 insight 来自 openai 的博客We made repository knowledge the system of record, …give Codex a map, not a 1,000-page instruction manual.中的渐进式披露是同一个理念 — handoff 做的就是粗索引让 Agent 只在需要时获得恰好足够的上下文。这里的设计灵感就主要来自Anthropic - Effective harnesses for long-running agents[2]使用两个不同的 Agent在博客中是每个 coding agent 都会在新的空白 session 中选择一个 feature 进行实现。我这里则更进一步让 reviewercodex和 executorclaude都在新的 session 中进行每轮都拿到完整的 token 预算不会被前几轮的上下文污染 token usage scaling以期得到更好的结果在设计良好的情况下我的经验表明效果会很不错并且可以 scaling 到相当规模的产品上。再补充说明由于是文档生成所以 Harness 工程的好坏可能对性能的影响不明显因为文本的 evaluation 比较难做但在 coding 任务上好的 Harness 设计可以轻松的让 Agent 运行 3060 分钟并得到非常高质量的产出。2. Human-in-the-Loop: Taste Injection这套流程的设计目标是在最少 human effort 的情况下完成大规模蒸馏。但最少不等于零。实践中发现有些环节人的作用不可或缺。2.1 品味注入博客作为 InstructionExampleOpenAI — Harness engineering[3]Enforcing architecture and taste— 贯彻架构与品味智能体在具有严格边界和可预测结构的环境中效率最高。这可能是整个过程中最有意思的部分。我把之前写的几篇关于 Context Engineering 的博客作为 instruction / taste 喂给了 Claude Code让它在提炼模式时参考我自己的分析框架。因此Agent 不是从零开始提取Agent 最佳实践的它带着我对 select / write / compress / isolate Context Engineering 四轴框架的理解带着我对 “Do the simple thing that works” 的偏好以及我对抽象层级的判断标准。蒸馏出来的东西不是 Claude Code 源码的客观映射最开始生成的都是这种而是经过我的偏好基向量投影后的结果。回到 PCA 式降维的类比博客就是那组基向量。它们定义了什么方向是重要的然后 Agent 沿着这些方向做投影。没有这些基向量Agent 可能会提取出完全不同的主成分也许更偏向实现细节也许更偏向 API 设计但不一定是我想要的 harness 设计原则。最初提取的东西简直没眼看fig2-pca-projectionTip这其实我对于 Agent 完成任务的感受同样这点也在 OpenAI 中的博客被反映。如果你给 Agent 一个近乎无限的 Action SpaceAgent 会直接失败。你需要先 Laying the foundation by hand 亲手奠定基础源自另一篇有意思的博客OpenAI - How we used Codex to build Sora for Android in 28 days[4]这是为了帮它归约 Action space在你亲手确定方向后agent 会越做越好至少符合你的需求2.2 架构决策几个关键时刻虽然具体的 review 和 edit 都由 Agent 完成但有几个节点是我主动介入的定位选择。Codex 的第一轮 review 指出 skill 在回答错误的问题 Claude Code 有哪些子系统“而不是构建者正在解决什么问题”。这个重新定位的决策是 Codex 建议的但选择接受它并让 Claude Code 按此执行是我做的判断。让它从解释代码变成抽取最佳实践抽象边界。“去掉 Claude Code 这个名字这条原则是否仍然有价值”这个判断标准是在多轮 review 中逐渐确定的。最初 Codex 和 Claude Code 对什么算可移植原则的理解并不一致是我在 handoff 中明确了这条规则。用户视角的补位。5 轮专注于内容准确性的 review 之后我意识到还缺少用户视角的审查由于我写博客的经验我最后总会从读者/使用者的角度去思考我 hardcode 了这个 rule 要求它们均要引入这个思考角度理论上应该被我沉淀为 skill 哈哈哈3. 过程概览fig3-fanout-convergencePhase 0搭脚手架在任何 Agent 动手之前我先和 Codex 对齐了项目范围和命名然后让它生成了 §1 中的全套 harness 文件。我给的 prompt 大意是给 Codex 的 Prompt“我们需要一个完整的 guidance用于 clean agent 领取任务和快速了解 contexts和对应的 progress tracking方便 clean agent 了解已经做了什么的 Harness。能否帮我生成这个 necessary harness set”比起 coding 任务这类文档任务的 harness 设计可以更轻量。Phase 1-2探索与并行起草4 个并行 Explore Agent 各负责不同的源码区域扫描约 1,900 个文件产出一份上下文地图。然后 7 个并行子 Agent 各领取一个 harness 层写一篇对应的深度分析最终产物中的references/*.md。Phase 3-4核验 → 纠错 → 转向Codex 第一轮 review 发现了 6 个事实错误记忆系统未覆盖、并发分类搞错字段、权限来源数量写错等。Claude Code 在新 session 中修正。随后 Codex 指出方向有问题 — 应该提取设计原则而不是解释代码。Phase 5模板标准化 — 8 个 Agent 并行重写确定原则优先后8 个子 Agent 同时按统一模板重写所有文档基本源自我的人工反馈。。问题通用→ 黄金法则可移植→ 适用场景 → 权衡 → 实现模式无代码→ 踩坑指南 → Claude Code 实证最后一个 section 用自然语言描述 Claude Code 的实现决策不出现源码路径、函数名或代码片段。Phase 6Review 收敛P1 必须修才能发布的错误P3 措辞级别的优化。Review 轮次发现关键问题v0.41P1 6P2 1P3记忆模型仍然描述错误v0.53P3通过仅措辞级别的调整UX 审计1P1 2P2 2P3skill 运行时的技能列表有 250 字符硬限精心调的触发词全被截掉了严重度在下降说明收敛在发生。但 UX 审计又引入了一个新的 P1 — 内容层面已经收敛了展示层面还有关键问题没人发现。Phase 7最终优化缩短技能描述248 → 116 字符让触发词重新出现在列表中。为每个章节添加 “从这里开始” 的操作指引声明目标读者。Reflection前面的章节已经覆盖了大部分具体的经验这里只补充几点更一般性的思考。4.1 关于客观提取§2.1 讲了 PCA 类比这里简单补充一点一个客观的模式提取可能反而是最没用的因为它没有视角也就没有优先级无法归约 agent action space。好的“蒸馏”需要一个明确的立场然后诚实地标注这个立场是什么怎么感觉和 《Principle》里面的概念比较接近推荐阅读 瑞·达利欧 的这本书我最近也在基于这本书构建个人 Principle Skill 笑死。4.2 关于 Roadmap后续对 Codex CLI 和 Gemini CLI 的分析会用同一组基向量。如果一个模式在三套独立实现中都沿着同一个方向出现那它反映的大概率不是某个团队的设计偏好也不只是我的偏好而是构建 Agent 这件事本身的规律。这或许是最值得继续做的事情。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】