从零开始写 Agent，我在 Prompt、Context 和 Harness 三层工程上踩过的坑

2026-06-10 从零开始写 Agent，我在 Prompt、Context 和 Harness 三层工程上踩过的坑

这篇博客聊聊我这一年多接触 AI 辅助编程和 Agent 编写的真实经历。从去年中旬偶然发现 Cursor 官网，到十月份之后接触 TraeCN，再到后来尝试 Cursor、OpenCode、Codex、OpenClaw，最后自己动手写 Agent。整个过程走了不少弯路，也推翻了很多最初想当然的认识。

在写这篇文章时，我也翻了一些资料——从 Anthropic 的官方工程博客，到 TMLR（Transactions on Machine Learning Research）正在评审的《Agent Harness Engineering: A Survey》综述论文，再到 harn.app 上整理的实践框架和掘金社区的讨论。这些资料让我把之前零散的经验串联成了一条更清晰的线，也补充了一些我自己实践中还没有注意到的维度。

起点，一次偶然的发现

去年中旬，我偶然点进了 Cursor 的官方网站。当时正在准备竞赛培训，时间很紧，只是大概看了下产品介绍，知道这是个 AI 编程助手，能做代码补全和生成。心里想着挺有意思，但手头事情太多，没空深入了解，就这么搁下了。

竞赛培训结束后，时间空出来一些。去年十月份之后，我开始接触 TraeCN。那时候我的用法很初级，主要是让它帮忙写一些简单的函数，或者解释看不懂的代码片段。TraeCN 确实能省不少时间，尤其是一些 boilerplate 代码，再也不用自己手敲了。

但用了一段时间后，我开始不满足于这种浅层辅助。我想让 AI 做更复杂的事，比如理解整个项目的结构，或者帮我做跨文件的改动。这时候我开始尝试 Cursor、OpenCode、Codex、OpenClaw 这些工具。（顺便提一嘴，Codex 是真好用）

工具尝试阶段，各家有各家的脾气

Cursor 给我的第一印象是快。代码补全几乎没有延迟，而且它能理解我当前打开的文件上下文，生成的代码和项目风格比较一致。但 Cursor 的问题也很明显，它更像是一个超级加强版的 IDE 插件，擅长单文件或者邻近文件的改动。一旦涉及复杂的跨模块重构，它就有点力不从心了。

OpenCode 和 Codex 的集成度很高，尤其是在特定生态里。Codex 配合 GitHub 用很方便，能直接读取仓库信息。但它们的自由度相对较低，很多时候只能按照预设的套路来，遇到非常规需求就卡住了。

OpenClaw 是我用过的工具里自主性最强的。它能执行 shell 命令、读写文件、甚至自己规划任务步骤。刚开始用的时候很惊艳，感觉像雇了一个真正的程序员。但很快我就发现了问题，它太自由了，经常在一些边界条件上出错，而且错误会连锁传播，越到后面越难收拾。

这一轮工具尝试让我明白一件事。现有的 AI 编程工具，要么太死板，要么太放任。它们解决的是特定场景的问题，但没有一个能真正按照我的想法去工作。于是我萌生了自己写 Agent 的念头。

自己写 Agent，推翻了一个想当然的认识

刚开始写 Agent 的时候，我走了最直观的一条路。把 Prompt 写得尽可能详细，给 Agent 规定死每一步该干什么，能调什么工具，不能干什么，输出格式必须怎样。甚至在代码里写了一大套硬编码的门禁逻辑，Agent 每做一步都要过一遍检查清单。

最开始的效果似乎还不错。Agent 按照我规定的步骤走，输出也很规范。但我很快发现了问题。

第一个问题是僵化。Prompt 写得越细，Agent 的应变能力越差。遇到我预设之外的情况，它完全不知道怎么处理，要么报错退出，要么机械地套用不合适的步骤。

第二个问题更隐蔽。当我换一个更强的模型时，效果反而下降了。因为 Prompt 里那些为了约束弱模型而写的详细规则，对强模型来说变成了多余的束缚。强模型本可以做出更合理的判断，却被我的硬编码规则限制住了。

这其实就是后来我在 Anthropic 的工程博客里看到的"高度"问题（Right Altitude）：系统提示词存在一个 Goldilocks Zone（黄金区）——**太规定（Too Prescriptive）**会写出像流程图一样僵硬的 if-else 逻辑，难以适应真实情况的变化；**太模糊（Too Vague）**又会缺少具体的信号，让 Agent 误以为存在共享上下文而偏离任务。**恰到好处（Just Right）**的提示词应该具体到足以有效引导行为，但又足够灵活以提供强大的启发式判断，用最小的信息集完整描述预期行为。

这个发现让我挺意外的。我原以为提示词越清晰越多越好，结果在实践中恰恰相反。过于详细的指令不仅没帮助，还可能成为 Agent 能力的上限。

Anthropic 的一篇文章，让我换了思路

就在我纠结怎么改进 Agent 的时候，我读到了 Anthropic 的一篇关于 Agent 工程的文章。里面有一个观点直接击中了我。

好的 Agent 工程，重点不在于指导 Agent 该干什么，也不在于用一套硬编码的门禁去限制它。重点在于给 Agent 提供一个可运行的环境，让它在这个环境里有足够的信息和工具去自主决策。

这句话把我之前的做法完全推翻了。我原来在做的是 micromanagement，每一步都要管。而正确的做法应该是提供土壤和工具，让 Agent 自己长。

文章里提到的思路和我之前的经验也对得上。OpenClaw 之所以容易失控，不是因为它的模型不够强，而是因为它的运行环境缺乏有效的约束和反馈机制。Cursor 之所以安全但死板，也是因为它把环境限制得太死了。

从这时候开始，我的关注点从 Prompt 本身转移到了 Prompt 背后的整个系统。

从 Prompt Engineering 到 Context Engineering

理解了 Anthropic 的思路后，我做的第一个改变是精简 Prompt。把那些为了约束弱模型而写的详细规则大量删除，只保留最核心的目标描述和边界条件。Prompt 从原来的几百字压缩到了几十字。

但光精简 Prompt 不够，因为 Agent 做决策需要信息。如果信息给少了，Agent 就会瞎猜。如果信息给多了，Agent 就会在噪声里迷路。

这就是 Context Engineering 要解决的问题。用 Andrej Karpathy 的话说："上下文工程是一门微妙的艺术与科学——在正确的时间，用正确的信息填充上下文窗口。" 它和 Prompt Engineering 的区别在于：Prompt Engineering 问的是"什么是正确的词？"，而 Context Engineering 问的是"模型在执行的每个节点上应该拥有的最优信息集是什么？"

我开始认真对待这件事。每次调用模型之前，我会根据当前任务筛选出最相关的信息。Agent 在处理 bug 修复时，只给它看相关模块的代码和最近的提交记录，其他无关信息一律不放入上下文。同时，我把信息按结构化方式组织，用清晰的标题分隔不同来源的内容。

在翻资料的时候，我发现关于上下文工程有几种成熟的技术，值得单独记录一下：

1. Just-In-Time 上下文检索（即时检索）

这是最推荐给 Agent 使用的策略。Agent 不预先加载所有可能相关的信息，而是维护轻量级的标识符（文件路径、存储的查询等），在需要时通过工具动态加载数据。这样做的好处是让 Agent 的工作记忆中只保留当前真正需要的内容，避免了"上下文腐烂"（Context Rot）——即随着上下文窗口中 token 数量增加，模型准确回忆和推理信息的能力会下降的现象。由于 Transformer 架构中每个 token 都要关注其他所有 token，token 数 n 意味着 n² 对关系，上下文越长，模型的注意力焦点被拉伸得越稀薄。

2. 上下文压缩（Compaction）

当对话接近上下文窗口限制时，让模型总结当前对话内容，然后用摘要重新开启一个新的上下文窗口。这个过程的关键是先最大化召回率（确保捕获所有相关信息），再迭代消除冗余内容（清理重复的工具调用和中间输出），保留关键的架构决策、bug 定位和实现细节。

3. 结构化笔记（Agentic Memory）

Agent 定期将中间笔记写入持久化存储（位于上下文窗口之外），在后续需要时再将其拉回上下文窗口。这相当于给 Agent 配备了一个"外置硬盘"，用来记录 ID、过滤器、早期决策和已验证的事实。

4. 子代理架构（Sub-agent Architectures）

使用专业化的子代理处理特定焦点任务，每个子代理使用干净的上下文窗口进行深入探索，然后只返回一个精炼、浓缩的摘要给主代理。这在处理长任务时特别有效，因为它防止了工具调用的噪声在主上下文中积累。LangChain 的 LangGraph 框架就是围绕这个思想设计的——它通过一个状态对象来隔离不同来源的上下文，LLM 只在需要时才能访问特定上下文字段。

这些技术背后有一个共同的核心原则：找到最小的高信号 token 集合，以最大限度提高期望结果的可能性。 效果提升很明显，Agent 的决策准确率提高了，响应速度也更快了，因为上下文变精简了。这个经历让我体会到，给模型喂多少信息不重要，喂什么信息、怎么组织信息才重要。

Harness Engineering，把认知再升一级

今年我读到一份关于 Harness Engineering 的调研报告，里面有个公式让我印象很深。Agent = Model + Harness。 Model 是模型本身，Harness 是模型之外的一切——系统提示词、工具接口、沙箱环境、编排逻辑、反馈循环、观测体系等等。

报告里提到了一组数据让我非常震撼。同一模型，仅改变 Harness 设计，编码基准测试分数可以从 6.7% 跃升到 68.3%。另一个例子是，通过系统提示词重构、中间件上下文注入和自我验证钩子，有人把一个固定的 GPT-5.2-Codex Agent 在 Terminal-Bench 2.0 上从 52.8% 提升到了 66.5%——13.7 个百分点的增益完全通过基础设施改变实现。还有一个 Meta-Harness 的工作通过自动化 Harness 优化达到了 76.4%，超过了所有手工设计的方案，但没有修改任何模型权重。这些 Harness 层面带来的改进，每一项都超过了同一基准上模型代际进步通常报告的 2 到 4 个百分点。这个差距太惊人了，它直接说明了一件事：模型能力的提升往往不是 Agent 表现不佳的瓶颈，Harness 的设计质量才是决定性因素。

TMLR 的综述论文把这个现象称为"绑定约束命题"（Binding Constraint Thesis）：对于跨可比前沿模型评估的长时任务，基准测试的方差可能由执行 Harness 和模型本身共同驱动。

这让我回顾自己写过的 Agent，发现很多稳定性问题确实出在 Harness 层，而不是模型层。比如 Agent 在两个文件之间来回修改，改完 A 发现 B 有问题，改完 B 发现 A 又不对，陷入死循环。这不是模型不够聪明，而是 Harness 缺少断路器机制。后来我给 Agent 加了最大迭代次数和超时检测，这个问题就彻底消失了。

再比如 Agent 把一段合法的解构赋值改成了错误的形式。这也不是模型的问题，而是 Harness 缺少验证步骤。后来我在写入文件前强制运行测试，失败就回滚，准确率立刻上去了。

Harness Engineering 把 Prompt Engineering 和 Context Engineering 当成基础层，在此基础上搭建执行环境、工具管理、状态记忆、观测评估和故障恢复。它的核心思想是：Agent 的可靠性取决于整个系统的设计，而不是单次模型调用的质量。

关于 Harness 的系统分层，不同资料有不同的归纳方式，放在一起看反而更容易理解全貌：

harn.app 提出的 CAR 框架（三层）：

• Control（控制层）：约束与规范。不要让 Agent 写好代码，而是机械地强制执行好代码的样子——通过 AGENTS.md、linters、类型检查、测试即契约、架构规则来实现。语言约束是建议，代码约束是法律。 Prompt 里写"请不要修改数据库 schema"并不可靠，因为当上下文过长时上下文腐烂几乎不可避免；但把规则写入 CI 检查、pre-commit hooks 或策略守卫，模型就无法绕过。
• Agency（工具层）：工具与接口。定义模型被允许如何行动——限定工具范围，而不只是限定知识。MCP 服务器、子代理委托、浏览器/GUI 访问、权限边界都属于这一层。
• Runtime（运行层）：执行与恢复。管控工作随时间的展开方式——生命周期钩子、重试与回滚、上下文压缩、追踪收集作为"反射弧"自动触发安全检查或格式化操作，不需要 AI 干预。

juejin 上一篇文章归纳的七层架构，更偏实践视角：

1. 认知层（Context Layer）
2. 工具层（Tool Layer）
3. 契约层（Contract Layer）
4. 编排层（Orchestration Layer）
5. 记忆与状态（Memory & State）
6. 评估层（Evaluation Layer）
7. 约束与恢复（Constraint & Recovery）

TMLR 综述论文提出的 ETCLOVG 七层分类法，更学术系统化：

1. Execution environment（执行环境）：sandbox、workspace、container、隔离执行
2. Tool interface（工具接口）：文件系统、git、浏览器、数据库、API
3. Context management（上下文管理）：检索、压缩、动态注入、token 预算
4. Lifecycle/Orchestration（生命周期/编排）：多步骤任务串联、状态流转
5. Observability（可观测性）：日志、追踪、中间结果审计
6. Verification（验证）：测试、静态分析、自我检查、行为验证
7. Governance（治理）：权限层级、安全边界、人工介入点

不管用哪种分类法，核心信息都是一致的：早期系统把能力集中在单个模型循环里，而后期系统越来越把可靠性视为跨层的基础设施问题。

我现在把 Harness 拆成几块来设计。信息边界层，定义 Agent 该知道什么、不该知道什么。工具系统层，控制 Agent 如何与外部交互。执行编排层，把多步任务串起来。记忆与状态层，管理中间结果。评估与观测层，让 Agent 能自我检查。约束与恢复层，出错时怎么拦截和回滚。

这样拆分之后，调试 Agent 变得清晰多了。出问题的时候，我能快速定位是哪一层的问题，而不是对着模型的输出发呆。

工具设计要克制

我犯过的另一个错误是给 Agent 塞了太多工具。有一次写项目管理 Agent，集成了十几种工具。查代码、改代码、查文档、发邮件、创建任务、搜索知识库、读取数据库。结果 Agent 表现很糟糕，经常在不该调用工具的时候调用，或者连续调用多个无关工具，把简单问题搞得复杂无比。

后来我砍掉了大部分工具，只保留最核心的三个。读取文件、写入文件、执行命令。效果反而更好了。Agent 的决策路径变清晰了，出错率也大幅下降。

这个教训让我对工具设计有了新的认识。工具数量和控制精度之间存在权衡。工具越多，Agent 的选择空间越大，但也越容易迷失。对于特定场景的 Agent，工具集应该保持精简，每个工具都要有明确的职责边界。

另外，工具的命名也很关键。我早期有个工具叫 file_processor，Agent 经常搞不清楚什么时候该用它。改成 read_file 和 write_file 之后，调用准确率明显提升。命名原则很简单，动词加名词，一看就知道干什么。

关于这一点我在资料里看到一条很实用的规则：如果一个人类工程师都不能明确地说出在某个情境下该用哪个工具，就不能指望一个 AI Agent 能做到。 工具应该自包含（single purpose）、对错误健壮（handle edge cases gracefully）、极度清晰（intended use is unambiguous）、token 高效（returns relevant info without bloat），并且参数命名具有描述性（例如 user_id 而非 user）。

一个实际的重构案例

今年三月份，我接手了一个遗留项目的维护工作。代码库里充斥着各种过时写法，手动重构估计要花两周。我决定写个 Agent 来辅助完成。

这个 Agent 的逻辑很简单。遍历项目目录找出目标文件，逐个读取内容，让模型按照预设规则重构，比如把 var 改成 const 和 let，把回调函数改成 async 和 await，然后把重构后的代码写回文件，最后运行测试验证结果。

整个过程分成两个阶段。第一阶段是探索，Agent 先扫描项目结构，生成待修改文件清单，让我确认。第二阶段是执行，Agent 按清单逐个处理，每处理完一个就运行一次测试。

实际运行中遇到了不少问题。有一次 Agent 把一段合法的解构赋值改成了错误的形式，测试立刻失败了。好在我在设计阶段就加入了测试检查点，Agent 发现测试失败后会回滚代码，然后跳过这个文件继续处理下一个。最终在三天的间歇性运行后，Agent 帮我重构了大概百分之七十的代码，剩下的百分之三十因为逻辑过于复杂，还是需要人工处理。

这个案例让我体会到 Agent 的现实定位。它擅长处理大量重复、模式化的工作，但在涉及复杂业务逻辑的时候，人的判断依然不可替代。把 Agent 当成一个不知疲倦的初级程序员来用，期望设定合理了，反而更容易获得满意的结果。

调试 Agent 的一些经验

写 Agent 最痛苦的部分不是写代码，而是调试。Agent 的执行流程涉及多个步骤，每个步骤都可能出错，而且错误会连锁传播。

我总结了几条经验。

日志要详尽。Agent 的每一步决策、每一次工具调用、每一个中间结果都应该记录下来。出了问题之后，翻日志是最快的方式。TMLR 综述把可观测性（Observability）列为独立的架构关注点，强调中间步骤必须可读——计划、追踪、差异、失败记录都应该存在 Agent 和人类可以审计的文件中。

设置断路器。给 Agent 设置最大迭代次数和超时时间，防止陷入死循环。加了迭代上限之后，至少能保证程序不会跑飞。

保留人工介入点。在关键节点暂停执行，让人确认后再继续。比如文件写入操作前弹出确认框，显示变更内容摘要。这在处理重要代码库的时候尤其必要。harn.app 称之为 Governed（治理）——自主性必须有边界，不可逆操作受到权限层级、沙箱、验证门和人工审查的约束。

反馈要闭环。Agent 完成任务后，系统需要自动判断它是否做对了，并把结果反馈给 Agent，驱动它自我修复。这在 juejin 的文章里被称为反馈层——功能验证（代码能跑吗？逻辑对吗？）和行为验证（Agent 的行为本身符合预期吗？）都是这个循环的一部分。行为验证甚至可以写成测试，比如"变更行数不应超过 50 行"、"不应引入新依赖"，这些断言能防止 Agent 过度工程化。

写在最后

从最初偶然发现 Cursor 官网，到接触 TraeCN，再到尝试各种工具，最后自己动手写 Agent，这一路的认知升级挺明显的。最开始我以为重点是写好 Prompt，后来发现 Context 更重要，再后来意识到整个 Harness 的设计才是根本。

这段时间我翻资料时发现，整个社区的认知演进也是按同样的顺序：2022-2023 年是 Prompt Engineering，大家关心的是措辞；2024 年是 Context Engineering，大家开始意识到信息选择和组织的重要性；从 2025 年开始，随着 Agent 开始真正修改代码库、调试系统、连续运行数小时，Harness Engineering 成为了新的焦点——构建一个让 AI Agent 可以安全、可预期、可审计地运行的系统。这个三代演进的脉络和我自己踩坑的顺序高度吻合，也让我对自己当前的方向更有信心。

最大的感触是 Agent 没有魔法。它的本质依然是大语言模型加循环加工具调用。那些看起来很炫酷的 Agent 应用，背后都是大量的工程细节和边界情况处理。

但写到这里我想多说一句。Agent 并不是 LLM 应用的最终形态，它只是一个过渡态。

当前的 Agent 本质上是在用工程手段弥补模型能力的不足。Harness 越复杂、钩子越多、约束越严密，恰恰说明模型本身还不够可靠——我们需要一个庞大的外部脚手架来防止它犯错。而理想的方向，应该是模型自身就能更稳定地理解任务、管理状态、处理边界，从而让 Harness 简化，而不是无限膨胀。

再往深看一层，Prompt Engineering 是在教模型"怎么说"，Context Engineering 是在教模型"看什么"，Harness Engineering 是在教系统"怎么管"。这三层工程加起来，其实是在回答同一个问题：当模型还不够聪明的时候，我们怎么让它把事情做对？ 但如果未来模型本身具备了更强的长期规划、工具理解、状态记忆和错误恢复能力——这些能力从外部 Harness 内建到模型内部——那么今天我们精心设计的 Agent 框架就可能变得多余，就像当初详细的 Prompt 规则在更强的模型面前失去意义一样。

另一个角度是应用范式本身。当前的 Agent 仍然是"有人指挥的自动化"——人定义任务、人确认结果、人兜底异常。真正的下一代 LLM 应用可能不是"Agent"这个词暗示的"代理执行"，而是模型作为系统的一个原生组件嵌入到应用逻辑里，和传统代码、数据库、用户界面无缝协作，不需要显式的工具调用循环和人工检查点。那时我们写的不再是 Agent，而是具备原生理解和推理能力的新型应用。

所以我对自己的定位很清楚：今天用心写好 Agent，不是因为我相信 Agent 是终点，而是因为在通往终点的路上，这是最有价值的练兵场。理解 Agent 的痛点，就是在理解下一代 LLM 应用需要解决什么问题。

如果你也想在日常工作中引入 Agent，建议从一个具体的小问题开始。不要想着一步到位搭建全能助手，先解决一个实际的痛点。等这个小 Agent 跑顺了，再逐步扩展能力范围。同时保持一份清醒——你在做的可能不是未来，而是通往未来必经的一段路。

技术本身并不复杂，复杂的是把技术落地到真实场景中的过程。希望这篇博客能给正在尝试写 Agent 的你一些参考。