目录

• AI Agent 的"失明"困境
• 逐渐工程化的 AI 开发
• 文档介质与按需加载
• 约束粒度与分层设计
• 验证闭环与质量保障
• 上下文是最贵的资源
• AGENTS.md：给 Agent 的 README
• Harness 的本质：让 Agent 看得见

AI Agent 的"失明"困境

我们让 AI Agent 实现一个功能，它思考了一下开始写代码。200 行写完，运行 lint 直接失败。我们发现类型定义文件 import 了配置包，但违反了我们期望的架构分层约束——因为 Agent 不知道这个规则，当然我们也没告诉它。于是它开始修复：移动代码、调整依赖、重新组织。再跑 lint——又一个新问题。循环三次后，上下文窗口被错误日志和 diff 塞满，Agent 开始"忘记"最初的任务目标。

这不是 Agent 不够聪明，而是 Agent 看不见。

你可能在项目中遇到过类似场景：同一个项目，昨天的 AI 还记得你们的架构约定，今天开个新会话又全忘了。每次协作都要重新解释一遍背景、分层规则、命名规范。AI 生成的代码能跑，但完全不符合团队规范，code review 时才发现一堆问题。让它修 bug，结果引入了新 bug——没有自动验证，全靠人肉检查。

最近读了两篇关于 Harness 工程化的文章，给了我很大启发。第一篇从实践角度介绍了 Harness 的落地，包括 creator/executor 工作流、验证机制；第二篇系统拆解了 Harness 六大组件，理论层面解释了 “Agent = Model + Harness” 的核心公式。

作为一直关注 AI 技术的人，我越来越感觉到：Harness 不是什么新发明，而是对已有事物的有序重组，是一个典型的工程化产物。它把 AI 开发中的最佳实践系统化了，就像 Spring Boot 不是新发明，而是对 DI、AOP 等已有技术的有序重组一样。

逐渐工程化的 AI 开发

我最初的理解是：AI 开发就是 Prompt Engineering + RAG + 纠错。但这几年实践下来，Prompt Engineering 的问题越来越明显——上下文窗口有限，即使 200K token 也不够一个中等项目用。

Harness 让我意识到：Prompt 只是配置文件，而 Harness 是完整的框架。想想看，Spring Boot 通过自动配置、starter 依赖、约定优于配置这些机制，让开发者从繁琐的配置中解放出来。Harness 做的事情本质上是一样的——把 AI 开发中的工程实践系统化，让 Agent 从"需要手把手教"变成"在约束框架内自主工作"。

从后端程序员的视角看，这个转变非常自然。我们不会要求每个新人都记住项目的所有细节，而是提供清晰的文档、规范的目录结构、自动化的检查工具。Agent 也是一样——它需要的是一个"操作系统"，而不是一张写满规则的纸。

文档介质与按需加载

两篇文章都强调了一个核心观点：代码库是 Agent 的操作系统，知识必须放在 Git 中。这让我想起之前的项目经历——我们把架构决策写在钉钉里，编码规范在 Notion 上，结果新人来了根本找不到，AI 更是不可能读到。

500 行 AGENTS.md 的问题很明显——当一切都重要时，什么都不重要。AGENTS.md 应该作为索引，在检索阶段以小信息损失给出大价值。

层次化存放的设计很合理：根目录 AGENTS.md 存全局，子目录存局部，Agent 按需加载。这让我想起 Spring 的配置层次——父 context 提供公共配置，子 context 覆盖或扩展特定配置。Agent 同时加载全局和局部知识，既保证了上下文充足，又避免了上下文爆炸。

知识放在 Git 中的另一个好处是版本化。任何知识变更都有历史记录，可以回滚、审计、追踪。配合 MCP（Model Context Protocol），Agent 可以像调用 API 一样访问内部系统，知识真正变成可编程的资产。

约束粒度与分层设计

分层约束的设计最让我眼前一亮。层级编号从 Layer 0（类型定义）到 Layer 4+（HTTP handler 和 CLI），规则很简单——高层可以 import 低层，反过来不行。这让我想起 Java 的模块化系统（JPMS）或者 DDD 中的分层架构。

但 Harness 的设计更轻量。它不规定具体的设计模式或编码风格，只约束依赖方向。在这个边界之内怎么实现，随便。这

Bash + 沙箱实现了从"说"到"做"的质变，赋予 Agent 自我验证循环（写→跑→看→修→再来）。沙箱提供安全隔离：资源限制、网络隔离、文件系统隔离、超时机制。这让我想起 Docker 容器的隔离机制——给了开发者一个安全的实验环境，想怎么折腾都行，反正随时可以重建。

"这样做合法吗"的预验证机制很有价值，在写代码前就检查，避免修改变动代价大。错误信息质量决定修复效率——好的报错本身就是一次教学，好比后端的编译错误信息，应该清楚指出问题所在和如何修复。

验证闭环与质量保障

纠错验证闭环与"一锤子买卖"形成鲜明对比。错误信息决定修复质量，超过一定次数就人类介入。两篇文章提到：具备自我验证循环的 Agent 任务完成率比"一次性生成"高，这个提升不是来自更强的模型，完全来自 Harness 层的 Bash 能力。

这让我想起单元测试的价值——不是测试本身能发现所有 bug，而是测试驱动开发（TDD）让开发者在写代码时就思考边界条件。Harness 的验证机制本质上就是测试的延伸，把测试前置到代码生成之前。

Hooks 在关键节点插入确定性检查：Lint 检查、格式约束、安全过滤、成本控制。用确定性的规则约束概率性的模型输出。

交叉 review 机制用不同模型 review，避免"视而不见"，就像代码审查用不同视角发现问题。review 成本约是编码成本的 10%-20%，但能发现逻辑问题。整个机制就是"概率性生成+确定性校验"的组合，既利用模型的创造力，又通过工程手段兜住质量底线。

上下文是最贵的资源

Context Rot（上下文腐烂）是个很形象的概念。随着对话进行，上下文堆满冗余信息，信噪比下降、矛盾信息累积、推理质量退化。大约第 60 次 tool call 后，Agent 可能已经忘了最初的任务目标。

协调者不写代码的设计保证了上下文资源充足。完成子任务后压缩并丢弃详细上下文，每次从干净的上下文开始，拿到精确的 prompt，干完就释放。

分层上下文结构很合理：核心层（System Prompt、关键约束，始终保留）、工作层（当前任务相关信息，按需更新）、历史层（已完成任务的摘要，逐渐压缩）。这让我想起 JVM 的内存分代模型——新生代、老年代有不同的生命周期和回收策略，上下文也可以分层管理。

模型按需分配的策略也很有价值：协调者用中等模型，快速执行类用轻量模型如 Claude Haiku，深度推理类用 GPT-5.3 Codex 或 Claude Opus，代码检索类用 Gemini 3 Flash。总成本可以降低 60%-70%，质量不打折扣。

AGENTS.md：给 Agent 的 README

AGENTS.md 是给 AI coding agents 的 README，一个简洁、可预测的地方来提供 context 和 instructions，兼容多个 AI coding agents（OpenAI Codex、Cursor、Factory 等）。这与 README.md 有明确区分——README.md 给人类看的；AGENTS.md 给 Agent 看的。

常用内容也很实用：项目概览、构建和测试命令、代码风格指南、测试指令、安全考虑。这让我想起新人入职时的文档——需要快速上手，不需要知道所有细节，但要清楚"怎么跑"、“怎么测”、“什么不该做”。

嵌套使用的设计很灵活：大 monorepo 中每个子项目可以有独立的 AGENTS.md，Agent 自动读取最近的文件，最近的优先级最高。就像多模块项目的子配置，继承并覆盖父配置。根目录 AGENTS.md 存全局，子目录存局部，按需加载，避免上下文爆炸。

AGENTS.md 本质上就是配置中心+知识库，统一管理项目约定。由 Agentic AI Foundation（Linux Foundation 下的组织）管理，保证了标准的统一性和开放性。

Harness 的本质：让 Agent 看得见

读完这两篇文章，我最大的感触是：Harness 的本质不是让 Agent 更聪明，而是让 Agent 能看见更多。它是对已有 AI 技术的工程化整合，不是新发明。从 Prompt Engineering + RAG + 纠错，到系统化的六层架构，是工程思维的体现。

模型决定了 Agent 能力的下限，Harness 决定了 Agent 能力的上限。这套思路对任何需要与 AI 协作的项目都有参考价值，无论你是个人开发者还是团队负责人。

第二篇文章《一文讲透如何构建 Harness——六大组件全解析》对 Harness 的六层结构有更详细的讲解，建议深入阅读原文。但更重要的是——回到自己的项目中，思考如何构建一个让 Agent "看得见"的运行环境。

参考资料：

• 让 Agent 看得见——Harness 工程化实践
• 一文讲透如何构建 Harness——六大组件全解析
• AGENTS.md 官方规范