【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本文是 learn-harness-engineering 课程第四讲的完整技术指南核心回答一个问题为什么把项目所有规则塞进一个 600 行的AGENTS.md反而会让 Agent 的表现越来越差。文章从指令膨胀的恶性循环出发梳理 Lost in the Middle、指令信噪比SNR、入口文件Entry File与按需展开Reveal on Demand等核心概念并结合本仓库docs/pt-BR/lectures/lecture-04-why-one-giant-instruction-file-fails/code/下的可运行示例与 Project 02 的 starter/solution 双版本对照给出可直接落地的短入口文件 专题文档拆分方案。读完你不仅能诊断自家指令文件的膨胀程度还能亲手完成一次可量化的拆分重构并复现split-vs-monolithic.ts中单文件 200 行 vs 四文件各 50 行的上下文节省对比实验。一、问题的根源一条规则引发的恶性循环你开始认真对待 harness建了一个AGENTS.md把能想到的所有规则、约束、历史教训都塞了进去。一个月后文件膨胀到 300 行两个月 450 行三个月 600 行。然后你发现 Agent 的表现反而变差了改一个小 bugAgent 花大量上下文处理无关的部署指令关键的安全约束埋在第 300 行被直接忽略文件里有三条互相矛盾的代码风格规则Agent 每次随机选一条。这就是巨型指令文件陷阱——觉得什么都有用什么都往里装结果想找一条具体规则得把整个文件翻一遍。写了 600 行但真正跟当前任务相关的可能只有三分之一。最常见的恶性循环是这样运转的Agent 犯了一个错 → 你说加条规则防止这个加到AGENTS.md暂时管用Agent 又犯了另一个错 → 再加一条重复下去文件膨胀到不可控。每次出问题就加条规则是再自然不过的反应但累积效应是灾难性的。具体来说巨型指令文件会在五个层面拖垮 Agent。1. 上下文预算被吃掉Agent 的上下文窗口是有限的。假设你的 Agent 有 200K tokens 的窗口Claude 的标准配置一个膨胀的指令文件可能占掉 10-20K tokens。看起来还有不少余量但一个复杂任务往往需要读取几十个源文件工具执行的输出同样占用上下文对话历史还在持续累积。等 Agent 真正需要理解代码的时候预算已经不够了。2. 中间迷失Lost in the MiddleLost in the Middle论文Liu et al., 2023清楚地证明LLM 对长文本中间部分信息的利用效率显著低于开头和结尾。你的AGENTS.md有 600 行第 300 行写的是所有数据库查询必须用参数化查询——这是安全硬约束但它被埋在文件中间Agent 几乎一定会忽略它。位置效应不是玄学而是可以被复现实验验证的行为规律见下文练习中的第三项验证实验。3. 优先级冲突文件里混合了三种性质完全不同的内容类型示例重要性不可违反的硬约束不得使用eval()红线重要的设计指导优先使用函数式风格强建议特定场景的历史教训上周修了 WebSocket 内存泄漏注意类似模式弱参考这三条规则的重要性完全不同但在文件里看起来一模一样。Agent 没有可靠的信号来区分哪条是红线、哪条只是建议——这就是下文要讲的核心概念Cant Tell What Matters。4. 维护衰减大文件天生难维护。指令过时了没人删因为删除的后果不确定也许别的地方依赖这条规则而加新指令看起来没有成本。结果文件只增不减信噪比持续下降。这和软件里的技术债务积累是同一个问题。5. 矛盾累积不同时期加入的指令之间开始互相矛盾一条说用 TypeScript 严格模式另一条说某些遗留文件允许用any。Agent 每次随机选择一条遵循——行为不可预测返工率上升。二、六个核心概念指令膨胀Instruction Bloat指令文件一旦占到上下文窗口的 10-15%就开始挤占代码阅读和任务推理的预算。一个 600 行的AGENTS.md可能占用 10,000-20,000 tokens对 128K 的窗口来说就是 8-15%。中间迷失Lost in the MiddleLLM 对长文本中间部分信息的利用效率明显低于两端。埋在 600 行文件第 300 行的关键约束被忽略的概率非常高。指令信噪比Instruction SNR文件中与当前任务相关的指令占总指令的比例。做 bug 修复时被要求读 50 行部署指令SNR 就很低。入口文件Entry File短小的入口文件作用是引导 Agent 去读更详细的专题文档而不是自己包含所有内容。50-200 行就够了。按需展开Reveal on Demand先给概要信息需要的时候再给详细信息。好的 harness 设计和好的 UI 设计一样不把所有选项一次性砸到用户脸上。这与交互设计中的渐进披露Progressive Disclosure是同一个思想。分不清轻重Cant Tell What Matters当所有指令以相同格式和位置呈现时Agent 无法区分哪些是不可违反的硬约束哪些只是建议性的软约束。三、指令文件架构从百科全书到路由器巨型单文件的读取路径是灾难性的——哪怕只改一个小 bugAgent 也必须把部署说明和历史备注全部扫一遍而埋在中间的规则又大概率被漏掉位置效应本身也是可以预测的。一个 600 行文件顶部与底部的信息有很高的概率被记住而中间部分大概率被稀释或忽略两条图的结论是一致的入口文件应当是路由器而不是百科全书把高频信息放在两端把低频细节移到按需加载的专题文档。四、如何拆分短入口文件 专题文档拆分原则可以概括为三句话常用的信息放手边偶尔用的收起来用不上的别带。4.1 入口文件AGENTS.md50-200 行只放四类内容入口文件只保留最必需的信息超过 200 行就要开始警惕项目概览一两句话说清楚这个项目是什么首次运行命令如make setup make test让 Agent 能快速自证环境可用全局硬约束不超过 15 条不可违反的规则专题文档链接每条一行描述加适用条件让 Agent 判断何时该去读。课程文档给出的入口文件模板如下完整可复制# AGENTS.md ## 项目概览 Python 3.11 FastAPI 后端PostgreSQL 15 数据库。 ## 快速开始 - 安装make setup - 测试make test - 完整验证make check ## 硬约束 - 所有 API 必须走 OAuth 2.0 认证 - 所有数据库查询必须用 SQLAlchemy 2.0 语法 - 所有 PR 必须通过 pytest mypy --strict ruff check ## 专题文档 - API 设计规范 (docs/api-patterns.md) — 添加新端点时必读 - 数据库操作约束 (docs/database-rules.md) — 涉及数据库修改时必读 - 测试标准 (docs/testing-standards.md) — 编写测试时参考注意硬约束部分的格式设计每条规则都是技术栈 具体动作的精确陈述而不是请写出高质量代码这类无法验证的空话。mypy --strict、ruff check这类可执行命令本身就是可验证的完成定义。4.2 专题文档50-150 行按主题就近存放每个专题文档控制在 50-150 行按主题放在docs/目录下或放在对应模块目录旁边。Agent 只在任务确实涉及该主题时才去读。这就像收纳袋整理行李的思路内衣一个袋、洗漱一个袋、充电器一个袋找东西不需要把整个箱子翻空。4.3 有些信息直接放在代码里更合适类型定义、接口注释、配置文件里的说明Agent 读代码时自然会看到不需要在指令里重复一遍。重复只会稀释 SNR并不会提升遵守率。4.4 每条指令都要有三条件元数据来源为什么加这条规则适用条件这条规则在什么时候需要过期条件什么情况下可以删掉这条规则定期审计删掉过时、冗余、矛盾的条目。管理指令要像管理代码依赖一样用不上的依赖就该删掉否则它们只会拖慢系统。4.5 位置原则顶部或底部永远不要中间如果某条指令确实必须留在入口文件里放在顶部或底部不要放中间。中间迷失效应告诉我们LLM 对长文本两端的信息利用效率显著高于中间。但更优的做法始终是把指令移到专题文档让 Agent 按需加载。4.6 行业共识OpenAI 与 Anthropic 都隐性支持这种拆分做法OpenAI 官方 Harness Engineering 文档主张入口文件应短小且以路由为导向Anthropic 关于长运行 Agent 的 harness 工程文章则强调控制信息应简洁且高优先级。两家说的是同一件事别把什么都塞进一个文件。五、仓库内的落地证据从课程代码到 Project 02这一讲在仓库里不只是理论还配套了可运行代码与一个完整的实战项目可以在docs/pt-BR/lectures/lecture-04-why-one-giant-instruction-file-fails/code/和projects/project-02/下直接查看。5.1 反模式清单一眼识别该拆的信号code/anti-patterns.md 给出了五条典型的指令文件反模式可以当作自查清单把整个仓库的知识都放进一个文件同一条规则在多个地方重复出现保留无人审查的过时规则写条件过于具体、几乎用不上的指令在初始上下文里内嵌冗长的工具使用手册。只要命中其中任意一条就说明文件正在向巨型指令文件退化。5.2 仓库自带的简短入口文件范本code/AGENTS-short.md 是课程提供的正确示范整个文件只有三部分——从这里开始读哪些文档、用什么命令启动、完成前跑什么检查、强制性规则不越层、不跳过验证、给下个会话留干净状态。它没有试图解释项目架构而是把解释责任交给了docs/ARCHITECTURE.md它也没有罗列所有开发规范而是用链接把 Agent 引导到对应文档。这就是路由器型入口文件的最小可行形态。5.3 可复现实验split-vs-monolithic.ts 如何量化节省code/split-vs-monolithic.ts 是一个可直接运行的 TypeScript 模拟脚本用数据说明拆分带来的上下文节省。运行方式npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts脚本的逻辑从源码结构可以完整还原构造单文件场景模拟一个 200 行的单体指令文件分成项目概览1-50 行、代码风格51-100 行、测试101-150 行、部署151-200 行四段并在第 72、78、120、135、175 行埋入五条关键规则见 L16-L65构造拆分场景按主题把 200 行拆成四个文件每个约 50 行见 L71-L76模拟四次查询分别查找返回类型规则部署窗口规则集成测试规则测试文件结构规则见 L88-L109对比读取行数单文件场景下 Agent 只能从顶部逐行扫描searchMonolithic见 L115-L130最坏要读满 200 行拆分场景下 Agent 根据查询主题直接定位到对应文件searchSplit见 L132-L156最多只读约 50 行输出对比报表逐条打印两种方案的读取行数与节省百分比最后打印平均节省与核心结论run 函数见 L166-L207。脚本头注释给出的核心洞察是单文件方案每次查询都要扫描最多 200 行而拆分方案只读相关文件的约 50 行——这意味着更小的上下文窗口占用、更少的幻觉、更快的执行。这个实验把指令膨胀从模糊的感觉变成了可测量的数字建议在自己的项目里用同样方法做一次基准测试。5.4 Project 02同一个项目弱 harness 与完整 harness 的对照Project 02Agent-Readable Workspace 是这一讲的配套实战项目其starter/与solution/两个版本恰好构成巨型/弱指令与分层指令的天然对照组项目 README 对两个目录的定位有明确说明starter 版的 AGENTS.md 是典型的最小但扁平文件只有 Quick Start、四层目录说明与三条 Conventions没有文档层级、没有完成定义、没有会话交接。README 明确指出其 harness 是弱的The harness is weak: AGENTS.md is minimal and there is no session handoffsolution 版的 AGENTS.md 则完整实践了本讲的所有原则启动规则Startup Rules按顺序列出先读本文件 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 跑npm install npm run check→ 读feature_list.json这就是入口文件的路由行为——只给顺序不给细节文档层级Docs Hierarchy明确docs/ARCHITECTURE.mdElectron 分层、数据流、导入管线与docs/PRODUCT.md功能需求的分工并在新增功能前先更新对应文档——专题文档与代码同步演进分层边界Electron Layer Boundaries把 main/preload/renderer/services 四层各自的职责、允许的依赖方向如 renderer 永不 import Node 模块写清楚这是全局硬约束的典型完成定义Definition of Done5 条可验证标准编译通过、窗口可见、feature_list.json标记 pass、遵守分层边界、文档已更新会话交接Session Handoff要求收尾时更新session-handoff.md记录已完成、待办、阻塞项与改动文件。solution 还配套了一份真实的 session-handoff.md可以看到上一条会话做了哪些决策如何被结构化记录如新增GET_DOCUMENT_CONTENTIPC 通道而非把内容捆绑进GET_DOCUMENT以减小列表视图的载荷这正是 Lecture 03仓库必须成为事实源与 Lecture 04指令按需展开的交叉点交接信息存在于独立文件而非堆积在AGENTS.md里。值得一提的细节是solution 版AGENTS.md只有约 60 行却通过docs/目录 session-handoff.md承载了远超 600 行单文件的信息量——这就是入口文件路由 专题文档按需加载的直接证据。六、真实世界案例SaaS 团队的拆分重构课程文档记录了一个典型的真实案例以下数据均来自课程文档一个 SaaS 团队的AGENTS.md从最初的 50 行膨胀到 600 行内容混合了技术栈版本、编码规范、历史 bug 修复笔记、API 使用说明、部署流程和团队成员的个人偏好——什么都有但很难快速找到跟当前任务相关的部分。Agent 表现开始明显下降简单 bug 修复任务中Agent 花大量上下文处理无关的部署指令安全约束所有数据库查询必须用参数化查询埋在第 300 行经常被忽略三条矛盾的代码风格规则导致 Agent 随机选择。团队做了一次拆分重构AGENTS.md裁剪到 80 行只保留项目概览、运行命令、15 条全局硬约束创建专题文档docs/api-patterns.md120 行、docs/database-rules.md60 行、docs/testing-standards.md80 行入口文件添加指向专题文档的链接历史笔记要么转成测试用例要么删除。重构后数据出自课程文档同一任务集的成功率从 45% 提升到 72%安全约束遵循率从 60% 提升到 95%——因为规则从文件中间移到了入口文件顶部不再被中间迷失效应吞掉。这个案例印证了本讲的三个杠杆缩短入口600 → 80 行、按主题拆分3 个专题文档、把历史知识固化成测试而非叙述消除只增不减的维护负担。七、核心要点加条规则是短期的止痛药、长期的毒药。每次加规则前先问这条规则放专题文档是不是更合适入口文件是路由器不是百科全书。50-200 行只放概览、硬约束和链接。利用中间迷失效应重要信息放文件顶部或底部不重要的移到专题文档。像管理技术债一样管理指令膨胀。定期审计每条指令要有来源、适用条件和过期条件。拆分之后信噪比提升Agent 把更多上下文预算花在实际任务上而不是处理无关指令。历史教训的最优归宿是测试用例而不是指令叙述能自动验证的规则就不要依赖 Agent 的记忆。八、延伸阅读以下资料与本讲主题直接相关可在公开渠道检索阅读OpenAI 官方博客Harness Engineering主张入口文件短小、面向路由Anthropic 工程博客Effective Harnesses for Long-Running Agents主张长运行 Agent 的控制信息简洁且高优先级Liu 等人 2023 年论文Lost in the Middle: How Language Models Use Long ContextsarXiv 编号 2307.03172长文本中间信息利用效率的原始实验HumanLayer 博客Harness Engineering for Coding AgentsNielsen Norman GroupProgressive Disclosure按需展开思想的交互设计源头。同时推荐继续学习本仓库的相邻章节关于仓库作为事实源的背景可看 Lecture 03关于初始化阶段与入口文件的关系可看 Lecture 06而 Lecture 08 则解释了feature_list.json这类特性清单为什么是 harness 的基础原语Project 02 的 Definition of Done 已经在用它。九、练习信噪比审计拿你当前的入口指令文件列出所有指令条目。选 5 个不同的常见任务类型标注每条指令是否跟该任务相关计算每个任务类型的 SNR。那些对大多数任务都是噪声的指令移到专题文档里。按需展开重构如果你有一个超过 300 行的指令文件把它拆成(a) 不超过 100 行的入口文件(b) 3-5 个专题文档。重构前后各跑同一组任务至少 5 个对比成功率——可以参照code/split-vs-monolithic.ts的做法把读取行数/成功率量化记录。中间迷失验证在一个长指令文件里把一条关键约束分别放在顶部、中间、底部各跑一组任务每组至少 5 次观察遵循率差异。你可能会惊讶于位置效应有多强——这也是为什么本讲反复强调顶部或底部不要中间。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐巨型指令文件为何失败learn-harness-engineering 中的指令拆分与按需加载实践巨型指令文件为何失败learn harness engineering 中的指令拆分与按需加载实践 本技术指南围绕 learn harness engineeWezTerm 窗口最大化详解window:maximize() 与 window:restore() 的用法及跨平台实现WezTerm 窗口最大化详解 window:maximize 与 window:restore 的用法及跨平台实现 导读 window:maximize 是为什么巨型 AGENTS.md 会让 Agent 失效learn-harness-engineering 中的指令文件拆分工程为什么巨型 AGENTS.md 会让 Agent 失效learn harness engineering 中的指令文件拆分工程 本文是 learn harne上一篇eCapture 最小权限运行指南用 Linux Capabilities 替代 root 运行 eBPF 抓包工具下一篇Flux项目贡献指南如何参与Rust精化类型工具的开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考