1. Ralph循环

Ralph循环（Ralph Loop / Ralph Wiggum Loop） 是2025年底兴起的一种AI编程方法论，核心是用一个简单的循环让AI“不完成不许下班”，直到任务真正完成为止。它的故事既有趣又震撼。

1.1. 起源：澳洲放羊大叔的5行代码

2025年底，澳大利亚开发者Geoffrey Huntley在“铲羊粪的间隙”写出了下面这段仅含5行代码的Bash脚本：

bash

while :; do 
    cat PROMPT.md | claude-code；
done

这段代码的逻辑简单：

无限循环读取同一个任务文件（PROMPT.md）

反复交给Claude Code执行

不管Claude说“做完了”还是“出错了”，都继续同一个任务

Huntley发现，当AI看到自己上一轮留下的代码、测试结果和错误日志时，它会自动修正，哪怕第一次写错，反复几轮后最终能完成任务。他把这个循环命名为：Ralph Wiggum。Ralph Wiggum是《辛普森一家》中的角色，一个天真的小学生，经常说傻话、做傻事，但异常执着。剧中他有一句经典台词：

“I’m in danger!”

这句台词和“屡败屡战”的精神完美契合Ralph循环的设计哲学：哪怕在困境中，只要持续迭代、永不放弃，最终就能成功

1.2. Ralph循环的解决方案

Ralph 循环的工作原理可以用一句话概括：把“一次性提示”变成“持续迭代直到成功”

大多数AI编程工具采用 一次提示 → 结束 模式。AI在主观认为“足够好”时就停止，但实际可能测试没通过、功能不完整。

通过Stop Hook（停止钩子）机制，当AI试图退出时，系统会拦截并检查输出中是否包含预定义的“完成承诺”（如DONE或COMPLETE）来决定是否退出循环。
这样AI就能根据客观的执行结果来修正自己，而不是靠“感觉”

• Ralph 循环流程
  

• 流程图说明

  • 核心流程：AI 尝试退出 → Hook 拦截 → 校验完成承诺 → 分支判断
  • 循环逻辑：未检测到完成关键词 → 回传任务 + 历史信息 → AI 继续迭代改进
  • 终止逻辑：检测到关键词 → 任务结束，退出循环
  • 迭代信息：明确标注每一轮 AI 可获取的三类上下文数据

• ralph shell脚本
  

1.3. Claude Code之父亲自验证

这5行代码很快火出圈，因为效果惊人。

Anthropic的Claude Code负责人Boris Cherny在社交媒体上分享了自己的数据：

他公开承认自己用了Ralph Wiggum插件（Anthropic官方收编后的版本），让AI持续运行数小时甚至数天。

“过去30天，我提交了259个PR——497次提交，增加4万行代码，删除3.8万行代码。每一行都是Claude Code + Opus 4.5写的。”

Cherny的分享在开发者圈引发“大地震”，许多人惊呼“软件工程正在剧变”。

1.4. 发展

Ralph循环从最初的Bash脚本，迅速演化成完整生态：

Ralph循环被开发者教育者Matt Pocock形容为AI编程的"范式转变"——从瀑布式开发进化为AI敏捷开发。它与传统AI交互模式的对比：

2. Harness Engineering 的演进

• Harness 解读：

  • 马： AI 模型是一匹强大、快速奔跑的马，但它不知道自己该往哪走。

  • 骑手：人类工程师为 AI 指引奔跑的方向，而不是亲自奔跑。

  • 马具（Harness） ：是AI运行的基础设施，它包括：约束、护栏、反馈回路，它们将模型的力量转化为生产力。

2.1. 演进

1. EleutherAI (2020)：Evaluation Harness 奠基者
   2020年，EleutherAI(非营利性研究组织) 推出了 Language Model Evaluation Harness，首次以大模型评估为核心，构建了统一的任务接口与评测框架。该框架强调可复现、可扩展的评估流程，不仅服务于开源模型的研究，更在架构层面为后续各类“Harness”工具提供了原型基础。成为Harness工程思想在模型评测领域的先行实践。

2. LangChain（2022–2023）: 框架普及，抽象先行
   LangChain 构建了首个面向大模型应用开发的通用框架，将“链（Chain）”、“智能体（Agent）”、“工具（Tool）”等抽象为可组合的原语，极大降低了构建复杂AI系统的门槛。其倡导的模块化、可编排架构，直接启发了后续Harness工程对“外部环境—模型—工具”三者协同方式的系统化设计，使Harness从评估工具扩展为智能体运行的基础设施。

3. OpenAI（2023）: Function Calling 让智能体“动手”
   OpenAI 在GPT模型中引入 Function Calling 能力，使得模型不再局限于文本输出，而是能够结构化调用外部函数与API。这一突破将智能体从“对话系统”演化为“行动系统”，为Harness工程提供了关键的执行接口与闭环基础。Harness得以在此基础上实现感知-决策-执行的完整链路。

4. Anthropic（2025.11）: 概念确立与协议标准化
   Anthropic 在官方工程博客中[系统阐述了 agent harness 概念]，明确其作为连接模型能力与外部环境的中间层，涵盖工具调用、状态管理、错误恢复等核心模块。与此同时，Anthropic 推动的 Model Context Protocol（MCP） 成为智能体与工具交互的标准化协议，为Harness工程提供了统一接口规范，推动生态走向可互操作、可组合。

5. Mitchell Hashimoto （2026.1）：方法论升华, 命名“Harness Engineering”
   作为 HashiCorp 联合创始人及资深基础设施工程师，Mitchell Hashimoto 首次将“Harness Engineering”明确为独立工程领域。他从基础设施工程视角出发，系统阐述了Harness在可观测性、可测试性、可复现性方面的设计原则，强调其作为模型与外部世界之间的“工程层”核心地位，标志着该领域从实践模式走向系统化工程方法论。

6. OpenAI（2026.3）: 实证研究，规模验证
   OpenAI 发布基于百万行代码真实开发场景的实证研究，系统展示了Harness工程在大型智能体任务中的显著收益：任务完成率提升、错误传播降低、可审计性增强。该研究为Harness工程提供了迄今最大规模的实证支撑，推动其成为构建可靠、可扩展智能体系统的标准范式。

3. OpenAI 打造 Codex 管控框架

OpenAI 的工程文章[《工程技术：在智能体优先的世界中利用 Codex》]记录了该领域最具启发性的案例之一。在五个月里，他们的团队没有手工编写了一行应用程序代码。相反，他们构建了基础设施层的架构，让Agent通过它生成超过 100 万行代码。

从文章中我们可以看到他们的一些非常有启发的实践：

3.1. 重新定义软件工程师的工作方式

在项目实践过程中，由于环境规范不明确，智能体缺少实现高级目标所必需的工具、抽象层与内部结构，导致开发工作难以推进。此时工程团队的核心任务，转变为辅助智能体高效完成有效工作。

人类的工作模式主要通过提示词与系统交互：工程师仅需描述任务、启动智能体，并由智能体自动提交 Pull Request。为推进 PR 合流，工程师会指令 Codex 先在本地审核自身代码变更，再在本地与云端请求其他专用智能体进行审查，并对所有人工或智能体的反馈做出响应，如此循环迭代直至所有智能体审核人员均认可（该过程本质为 Ralph Wiggum 循环）。

Codex 直接复用工程师的标准开发工具（如 gh、本地脚本及代码仓库内置技能）获取上下文信息。在整个流程中，唯一有效的推进方式是由 Codex 执行实际工作，而人类工程师则持续介入并追问核心问题：究竟还需要哪些能力，以及如何让这些能力对智能体做到清晰可读、可强制执行？

通过该循环持续优化迭代，最终实现几乎全部审核工作由智能体之间自主完成的目标。

可以将这个过程总结成：
「工程师发起任务 → AI 编码 → PR 推进循环 → 能力迭代升级 → 目标达成」 的完整闭环，是AI 自动化开发 + 人机协同 + 能力持续进化的流程模型。

用人类少量引导，让 AI 智能体实现「编码 - 审核 - 迭代能力」的全自动闭环，最终达成无人工干预的 AI 自动化开发。

• 关键亮点：

  • 流程以工程师描述任务为起点，AI 自动完成编码并提交 PR；
  • 人机分工明确：工程师只做任务描述、规则定义，编码 / 测试 / 审核全由 AI 完成；
  • PR 推进，循环持续进化：AI 自检 → 多智能体审查 → 人类补全规则 → AI 能力升级；AI 每次迭代都会获得新能力，越来越自动化；
  • 终极目标：单次PR 完成、长期AI 自动化开发目标达成；从「人审 AI」变成「AI 审 AI」，实现完全自动化开发。

• 全程体现AI 能力持续迭代、人机高效协同的智能化开发模式。
  

3.2. 将智能体的“可读性”作为首要优化目标

传统工程中，团队会通过良好的代码结构和文档，帮助新入职的人类工程师快速上手。将这一概念迁移到了 AI 身上：人类工程师的目标是让智能体能够直接从代码仓库推理出完整的业务领域。

一个由智能体生成的代码仓库不再是“人写给人看”的传统项目，而是由 AI 智能体（Codex 自身）生成的，并且会有多个智能体参与协作。这样代码库不仅是可执行的程序，更是智能体赖以理解业务逻辑、约束和架构的唯一“知识库”。智能体需要像一名资深开发者一样，在代码库中直接找到“上下文”和“设计决策的依据”。

• 项目的约束：

  • 运行时边界：智能体在运行时，只能访问当前上下文（Context）中的内容。任何在上下文之外的信息，对智能体来说都是不存在的。

  • 不可见的知识：Google Docs、Slack 聊天记录、工程师头脑中的隐性知识（如架构决策的理由、团队规范）——这些对人类来说可查阅的信息，智能体无法访问。

• 解决方案：必须将这些“隐性的、外部的”知识，显式地、以结构化（如 Markdown、代码模式、可执行计划）的形式“推入”代码仓库。

3.2.1. 将日志、指标和追踪记录构建成一个本地可观测性堆栈

• AI编程/代码生成系统构建的可观测性（Observability）栈的设计方案

可以将上面的图简化为：

                    ┌─────────────────────────────────────────┐
                    │           可观测性栈（数据采集）           │
                    │  APP ──┬── LOGS (HTTP)                  │
                    │        ├── OTLP METRICS                 │
                    │        └── OTLP TRACES                  │
                    │                │                        │
                    │              VECTOR                     │
                    │         Fan out (local)                 │
                    └────────────────┬────────────────────────┘
                                     ↓
                    ┌─────────────────────────────────────────┐
                    │             存储与查询层                 │
                    │         Victoria Logs                   │
                    │    PromQL API / TraceQL API             │
                    └────────────────┬────────────────────────┘
                                     ↓
                    ┌─────────────────────────────────────────┐
                    │          查询关联与推理层                │
                    │      Query Correlate Reason             │
                    └────────────────┬────────────────────────┘
                                     ↓
┌───────────────────────────────────────────────────────────────────┐
│                        CODEX 闭环反馈                             │
│                                                                  │
│   ┌─────────┐    ┌─────────────────┐    ┌─────────────────┐     │
│   │ CODEX   │ → │ Implement change │ → │ Restart app     │     │
│   │ 分析    │    │ + PR            │    │                 │     │
│   └─────────┘    └─────────────────┘    └─────────────────┘     │
│        ↑                                       ↓                │
│   ┌─────────────────────────────────────────────────────┐       │
│   │                   Feedback loop                     │       │
│   │            Re-run workload / UI Journey             │       │
│   └─────────────────────────────────────────────────────┘       │
└───────────────────────────────────────────────────────────────────┘

3.2.1.1. 数据采集与存储架层

• 数据流转说明

• 采集层：APP 通过 HTTP 推送日志，通过 OTLP 协议上报指标和追踪数据

• 转发层：Vector 作为轻量级数据管道，扮演 扇出（Fan out） 组件，负责将接收到的数据分发到下游多个存储系统

• 存储与查询层：三类数据分别存入对应的专用存储，通过各自的查询接口（原生日志查询、PromQL API、TraceQL API）对外提供服务

3.2.1.2. 执行层：查询关联与闭环反馈

Codex 作为智能体，消费观测数据，自主修改代码并触发重新部署

Codex
  ↓
实施变更（PR）+ 重启应用
  ↓
重新运行工作负载
  ↓
（观测数据被采集、存储）
  ↓
查询、关联、分析
  ↓
Codex ← 接收反馈

整个系统的核心通过循环闭环：

1. CODEX（AI编程系统）通过查询关联（Query Correlate）来理解问题原因（Reason）
2. CODEX 执行动作：

• 实施代码变更 + 创建 PR
• 重启应用

3. 进入反馈循环（Feedback loop）
4. 重新运行工作负载
5. UI Journey 可能代表前端用户旅程数据，与后端观测数据形成端到端的关联

这里不再是“人看仪表盘然后改代码”，而是AI直接消费可观测性数据、自主决策并修改代码——这已经超越了传统“可观测性”，进入了 “可观测性驱动的自动修复” 阶段。

3.2.1.3. 架构特点

• 实现了可观测性三大支柱

日志（Logs）、指标（Metrics）、追踪（Traces）三者关联查询的融合，为后续的问题定位提供完整的上下文信息。当 AI 或开发者需要排查问题时，可以从指标发现异常，从追踪定位链路，从日志查看细节，三者相互印证，形成完整的可观测性闭环。

• 本架构是 Ralph 循环在生产环境、性能调优场景下的工程化实现

• 潜在的应用场景

1. 性能优化：Codex 分析 PromQL 指标发现某接口 P99 延迟高 → 自动优化代码 → 重新部署 → 验证效果
2. 故障自愈：TraceQL 定位到某服务异常 → Codex 分析根因 → 生成修复 PR → 自动合并部署
3. 成本优化：分析 Metrics 发现资源浪费 → Codex 调整配置或代码结构

这本质上是 可观测性 的典型架构：从“人看数据做决策”进化到“AI 看数据做决策”。

3.3. 代码仓设为记录系统

上下文管理是使智能体在大型和复杂任务中有效发挥作用的最大挑战之一。

要给 Codex 的是一张地图，而不是一本 1,000 页的说明书。， 不能将 AGENTS.md 视为百科全书，而是将其视为内容目录。

代码仓库的知识库位于一个结构化了的 docs 目录中，此目录被当作记录系统来使用。一份简短的 AGENTS.md（大约 100 行）被注入到情境中，主要用作地图，并指向其他地方更深层次的真实信息来源。

• 代码仓结构
  

这实现了渐进式披露：智能体从一个小而稳定的切入点开始，并被指导下一步该去哪里查看，而不是一开始就被淹没。

这个和Skills的渐进式披露的设计思想是一致的。

就像团队会努力提升代码对新入职工程师的可导航性一样，人类工程师的目标也是让智能体能够直接从代码仓库推理出完整的业务领域。

从智能体的角度来看，它在运行时无法在上下文中访问的任何内容都是不存在的。存储在 Google Docs、聊天记录或人们头脑中的知识都无法被系统访问。代码仓库本地的、已版本化的工件（例如，代码、Markdown、模式、可执行计划）就是它所能看到的全部。

因此将系统的更多部分转化为智能体可以检查、验证并直接修改的形式，可以直接提高杠杆效应。

3.4. 遵守规则、强制约束

仅靠文档本身，是没法保持完全由智能体生成的代码库的可持续性。

这里有三个规则：

3.4.1. 边界强约束，内部无杂质

“边界强约束，内部无杂质” 的设计哲学：

• 在系统边界（用户输入、API 响应、文件读取）做最严格的解析
• 一旦进入核心逻辑，所有数据已经是“不可能非法”的强类型
• 后续代码无需再防御，只需专注业务

这种思想在智能体工程中，让智能体在“运行时”处理的数据类型，从一开始就尽可能排除无效状态，能显著提升它在长任务中的可靠性和可预测性。

3.4.2. 100%代码覆盖率

• 测试覆盖率与价值关系的曲线图，展示了随着测试覆盖率提升，其带来的价值如何变化。
  

每个人听到这些都会持怀疑态度，因为100%覆盖率也是一直被认为是否值得的问题。

在 AI 时代，在100%覆盖率下，测试带来的杠杆效应会增加。当覆盖率足够高时，覆盖率报告的作用发生了质变, 它不再是“我们测了多少代码”的统计数字，而是：

• 完整的增量检测器：任何未被测试覆盖的代码变更都会立刻暴露
  • 当覆盖率足够高时，覆盖率报告的核心价值从 “质量度量” 转变为 “变更管理工具”；
  • 每次 PR 可以看到哪些新增/修改代码未被测试覆盖
  • 强制要求新代码必须有对应测试
  • 防止覆盖率随时间“腐烂”
• 未知缺口 → 已知缺口：将测试盲区从“不知道哪里没测”变为“精确知道哪里没测”
• 完全可问责：每一行新代码的测试状态都清晰可见

当模型添加或更改代码时，它不能止步于“这看起来正确”，它必须用可执行的示例来支持。。其他好处是：无法访问的代码会被删除。边缘情况会被明确化。代码审查也变得更容易，因为你能看到系统每个方面预期如何表现或变化的具体示例。

3.4.3. 明确边界的分层架构设计

• 分层架构
  

1. 配置层
   定义“是什么”和“数据从哪来”——为上层提供稳定的类型契约和数据访问能力。包括：

• Types：类型定义，包括领域模型、实体、值对象等
• Config：业务相关的配置
• Repo：数据仓库层，负责数据访问和持久化

2. 执行层
   实现“做什么”——执行层是系统的核心，负责业务逻辑的运行和用户交互。包含：

• Service：业务服务层，封装核心业务逻辑
• Runtime：运行时环境，可能指业务逻辑的执行上下文
• UI：运行界面

3. 支持层
   提供“工具”和运行反馈。包含：

• Utilities：通用工具函数、辅助类、基础设施能力
• App Wiring + UI：应用装配（依赖注入、组件组装）和用户界面

在每个业务领域内（例如应用设置），代码只能“向前”依赖于一组固定的层（Types → Config → Repo → Service → Runtime → UI）。横切关注点（认证、连接器、遥测、功能标志）通过一个单一的显式接口进入：Providers。其他任何内容都不被允许，并将通过自动化方式强制执行。

清晰的分层架构和依赖，可以降低AI的认知负担，只需理解当前层的职责和接口。可以有效的减低模型上下文窗口的需求。

3.5. 熵管理 (Entropy Management / “垃圾回收”)

这是最容易被忽视的组件。随着时间的推移，AI 生成的代码库会积累熵——文档与现实脱节、命名约定发生偏离、死代码堆积。

Harness 工程通过定期清理智能体来解决这个问题：

• 文档一致性智能体：验证文档是否与当前代码匹配
• 约束违规扫描器：寻找溜过早期检查的代码
• 模式强化智能体：识别并修复偏离既定模式的情况
• 依赖审计员：追踪并解决循环依赖或不必要的依赖

这些智能体按计划运行（每天、每周或由特定事件触发），保持代码库对人类审查者和未来的 AI 智能体都是健康的。

4. Langchain的变更

LangChain 编程智能体在 Terminal Bench 2.0 上的表现从 52.8% 提升到了 66.5% —— 排名从 前 30 跃升至前 5 —— 而他们没有对模型做任何改动。

5. 智能体管控工程（Harness Engineering）

智能体管控工程（Harness Engineering）是一种基于自动化、可扩展和可审计的智能体构建方法。该方法基于基于真实场景的实证研究，通过基于真实场景的测试和基于真实场景的验证来提高智能体的性能。

5.1. Langchain 给出的定义

Agent = Model + Harness

If you're not the model, you're the harness.
如果你不是模型，你就是管控。

• Langchain管控的图表示

• 智能体管控工程划分为：

  • HARNESS（框架/控制层）
    位于顶层，代表智能体的“大脑”或运行时的控制器，负责协调所有子模块。

  • Context Injection（上下文注入）
    包括提示词（prompts）、记忆（memory）、技能（skills）和对话（conversation）。这些是智能体在执行每一步时能获得的“背景信息”和“能力说明”。

  • Control（控制逻辑）
    包括压缩（compaction，即对上下文的精简）、编排（orchestration）以及“Ralph loops”，让智能体能够反复检查自己的输出、修正错误。

  • Model（模型）
    模型在这里“reasons → decides”，即根据注入的上下文进行推理并决定下一步行动。

    • 模型有两种输出方式：
      • writes：可能指生成内容、写文件、输出消息
      • reads：可能指读取输入、理解用户请求或环境反馈

  • Action（行动）
    执行具体的操作，包括调用 bash 命令、使用各种工具（tools）或通过 MCPs（可能是 Model Context Protocol 的缩写，一种标准化的工具调用接口）。执行结果会返回到上下文（results back to context），形成闭环。

  • Observer & Verify（观察与验证）
    负责获取外部反馈来确认行动是否成功。这包括：浏览器截图、测试结果、日志等。 这些信息也会被注入到上下文中，供模型在下一轮决策时使用。

  • Persist（持久化）
    用于保存状态，保证智能体的工作可以中断后恢复。包括文件系统（filesystem）、Git 版本控制、以及进度文件（progress files），便于跟踪任务的进展。

• 设计思想：
  这个架构体现了一种 “感知-推理-行动-验证-持久化” 的循环，是一个高度工程化的 AI Agent 系统。它强调：

  • 闭环反馈：行动的结果和观察到的环境变化都会重新进入上下文，影响后续决策。
  • 可控性：通过 ralph loops、压缩机制和编排，避免上下文爆炸或无限循环。
  • 可扩展性：通过 MCPs、bash、工具等方式，让 Agent 能调用外部能力。
  • 可恢复性：通过持久化模块，支持长时间运行的任务。

5.1.1. 从期望推导智能体管控工程架构

Harness 的每一项能力，都源于模型自身无法实现的行为。

从需求中可以得到智能体管控工程架构：

• 由需求得来的智能体管控工程的架构

5.2 智能体管控工程涵盖的内容

智能体管控工程（Harness Engineering）目前涵盖的内容，这里参考：The Complete Guide to Agent Harness: What It Is and Why It Matters。

由于内容很多，这里只对**静默失败(Silent Failures)**做些讨论。

5.2.1. 静默失败(Silent Failures)

“静默失败”指系统或某一步骤实际已出错，但未抛出异常、未中断流程，导致错误在后续步骤中累积，最终引发整体任务失败。例如：

• 某一步骤执行后，模型或工具返回了“成功”的信号，但实际上并未达成预期效果；
• 或者发生了错误，但系统没有抛出异常、没有记录、没有重试，而是“默默”继续往下执行；
• 这类失败不会立刻中断流程，却会让后续步骤基于错误的状态继续推进，最终导致整个任务失败。

在 AI Agent 的场景中，常见例子包括：

• 模型调用一个工具，工具返回了格式正确的空结果，模型误以为操作成功，实际数据并未更新；
• 上下文过长导致模型“遗忘”关键指令，后续步骤执行偏离目标，但系统并未感知；
• 子任务超时，但进程没有崩溃，Agent 仍在尝试推进，浪费了计算资源。

5.2.1.1. 在长任务中, 静默失败(Silent Failures)尤其致命

一个经典的数学说明：

20 步任务，单步成功率 95%，无 Harness 时整体成功率仅 36%。

这背后隐含的假设是：每一步的失败（即使是 silent failure）都会导致整个任务失败。
在没有 Harness 的原始环境中：

• 缺少状态持久化 → 失败后无法从正确检查点恢复；
• 缺少工具调用的验证 → 工具返回错误但模型继续；
• 缺少健康监控 → 进程卡死或资源耗尽时无自动恢复；
• 缺少人工介入与任务完成验证 → 无法在早期发现偏离。

这些缺失恰好是 Silent Failures 滋生的土壤。

5.2.1.2. 智能体框架如何消除 静默失败(Silent Failures)？

智能体框架将“静默失败”转化为“可观测、可恢复”的显式失败：

6. 工程师的工作内容正在改变

智能体管控框架工程（Harness Enigineering）代表了软件工程师职责的一次真正演变。

工作内容的改变，也对软件工程师技能提出了新的要求。

• 软件工程师技能：
  • 系统思维：理解约束、反馈回路和文档如何相互作用
  • 架构设计：定义可执行且高效的边界
  • 规范编写：精确表达意图，以便智能体执行
  • 可观测性：构建能揭示智能体行为模式的监控
  • 迭代速度：快速测试和改进 Harness 配置

7. 参考

• 工程技术：在智能体优先的世界中利用 Codex
• The importance of Agent Harness in 2026
• The Complete Guide to Agent Harness: What It Is and Why It Matters
• Effective harnesses for long-running agents
• The Anatomy of an Agent Harness