【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文以 learn-harness-engineering 课程第 4 讲的anti-patterns.md反模式清单为主线系统拆解把仓库知识塞进一个巨型指令文件的五种典型失败方式——知识全堆一文件、同规则多处重复、无人审计的过时规则、过于具体的条件指令、把工具手册塞进启动上下文。你将理解这些反模式背后的上下文预算、Lost in the Middle、指令信噪比SNR等机制并掌握短入口文件 专题文档按需加载的拆分方案配合仓库内可运行的split-vs-monolithic.ts模拟与真实AGENTS.md案例获得可直接落地的重构方法。一、从反模式清单说起五个最常见的指令文件陷阱anti-patterns.md是第 4 讲的配套反模式速查清单它列出的五个问题正是所有把AGENTS.md越写越长的团队都会踩中的坑把所有仓库知识放进一个文件Putting all repository knowledge into one file在多个地方重复同一条规则Repeating the same rule in multiple places编码了无人审计的过时规则Encoding obsolete rules that nobody audits写出具体到极少适用的条件指令Writing conditional instructions so specific that they rarely apply把冗长的工具手册嵌入启动上下文Embedding long tool manuals into the startup context这五条并非并列的建议而是一整套失效机制的不同侧面。第 4 讲正文index.md描述了它们的共同源头——一个自然但灾难性的恶性循环agent 犯错 → 你加一条规则防止这个 → 暂时管用 → agent 又犯另一个错 → 再加一条 → 重复到文件失控。单看每次加规则都很合理但累积效应是灾难性的。600 行的AGENTS.md里真正与当前任务相关的可能只有三分之一。二、反模式一把所有仓库知识放进一个文件这是五个反模式的总根源。它直接触发三组连锁故障上下文预算被吃光。agent 的上下文窗口是有限的。以 200K token 窗口为例一个膨胀的指令文件可能占掉 10–20K token。看似还有余量但复杂任务需要读取几十个源文件、工具执行输出也占上下文、对话历史还在累积——等到真正需要理解代码时预算已经耗尽。Lost in the Middle中间迷失。Liu 等人 2023 年的研究清楚证明LLM 对长文本中间部分的信息利用效率显著低于两端。600 行的文件第 300 行写着所有数据库查询必须用参数化查询这样的安全硬约束但它埋在中间agent 几乎一定会忽略它。优先级冲突。文件混排了不可违反的硬约束不得使用eval()、重要的设计指导优先函数式风格和某个具体历史教训上周修过 WebSocket 内存泄漏。三者重要性完全不同但在文件里格式一模一样agent 没有可靠信号区分哪条是红线、哪条只是建议。三、反模式二在多个地方重复同一条规则重复有两种形态都值得警惕文件内重复同一规则以不同措辞出现在文件多处随着时间推移必然走向矛盾累积——一条说用 TypeScript 严格模式另一条说某些遗留文件允许用any。agent 每次随机选一条遵循行为不可预测。与代码重复类型定义、接口注释、配置文件里的说明agent 读代码时自然能看到。第 4 讲明确指出这类信息直接放在代码里更合适无需在指令里再抄一遍。重复意味着两处都要维护一处更新一处不更新就产生漂移。第 4 讲给出的判断标准很干脆如果去掉某条规则不影响 agent 的决策质量这条规则就不该存在这也是第 3 讲minimal but complete原则的延伸见 Lecture 03。四、反模式三编码了无人审计的过时规则**维护衰减Maintenance decay**是大型指令文件最难治愈的病过时指令极少被删因为删除的后果不确定也许别处依赖这条规则而新增指令感觉零成本。结果文件只增不减信噪比持续下降——这和软件技术债的积累是同一个问题。第 4 讲给出的根治方案是像管理代码依赖一样管理指令每条指令都必须标注三要素来源为什么加这条规则适用条件这条规则在什么时候需要过期条件什么情况下可以删掉这条规则定期审计删除过时、冗余、矛盾的条目。用不上的依赖就该删掉否则它们只会拖慢系统。五、反模式四写出具体到极少适用的条件指令WebSocket 内存泄漏后注意类似模式这类规则的问题在于它针对的是一个特定历史场景对绝大多数任务都是噪声。第 4 讲用**指令信噪比Instruction SNR**来量化这个问题SNR 文件中与当前任务相关的指令比例。修一个 bug 时被迫读 50 行部署指令SNR 就很低。反模式四的本质是把偶尔需要的条件知识放进了每次启动都全量加载的位置。正确做法是给这类条件指令一个家放进对应主题的专题文档并在入口文件里用一行描述 适用条件的形式提供路由例如- API 设计规范 (docs/api-patterns.md) — 添加新端点时必读 - 数据库操作约束 (docs/database-rules.md) — 涉及数据库修改时必读 - 测试标准 (docs/testing-standards.md) — 编写测试时参考规则仍在但只有在适用时才进入上下文。六、反模式五把冗长的工具手册嵌入启动上下文启动上下文startup context是 agent 每次会话最先、最完整看到的内容成本最高。把工具手册、API 参考、长历史教训一股脑塞进这里是对预算最浪费的用法。第 4 讲给出的设计原则是Reveal on Demand按需展开先给概要信息需要时再给详细信息。好的 harness 设计与好的 UI 设计同理——不把所有选项一次性砸到用户脸上。这与仓库中 context-engineering-pattern.md 描述的三层渐进式加载完全一致Tier 1: 元数据始终存在、廉价——功能清单、记忆索引、会话状态 Tier 2: 指令激活时加载——AGENTS.md、技能正文、风格指南 Tier 3: 资源按需加载——架构文档、API 参考、示例七、两种指令架构的对比第 4 讲用两张 mermaid 图直观对比了两种架构的走向两条路径的差别就是上下文预算的分配方式巨型文件让每次任务都背负全部指令短入口文件则把预算留给当前任务真正需要的东西。八、拆分方案入口文件是路由器不是百科全书第 4 讲给出了可复制的具体拆法入口文件AGENTS.md50–200 行只放四类内容项目概览一两句话、首次运行命令、全局硬约束不超过 15 条不可违反的规则、指向专题文档的链接一行描述 适用条件。完整示例# AGENTS.md ## Project Overview Python 3.11 FastAPI backend, PostgreSQL 15 database. ## Quick Start - Install: make setup - Test: make test - Full verification: make check ## Hard Constraints - All APIs must use OAuth 2.0 authentication - All database queries must use SQLAlchemy 2.0 syntax - All PRs must pass pytest mypy --strict ruff check ## Topic Docs - API Design Patterns (docs/api-patterns.md) — Required reading when adding endpoints - Database Rules (docs/database-rules.md) — Required when modifying database operations - Testing Standards (docs/testing-standards.md) — Reference when writing tests专题文档每份 50–150 行按主题放在docs/目录或对应模块旁边agent 只在需要时读取。比喻很形象就像收纳袋整理行李内衣一个袋、洗漱一个袋、充电器一个袋找东西不用翻整个箱子。如果某条指令必须在入口文件里放顶部或底部绝不放中间——中间迷失效应决定了极端位置被利用得更好。但更优解始终是把指令移到专题文档按需加载。九、仓库源码佐证模拟实验与真实 AGENTS.md 案例1. 可运行的对比模拟split-vs-monolithic.ts仓库提供了可直接运行的实验脚本split-vs-monolithic.ts它构造一个 200 行的单体指令文件4 个分区各 50 行模拟 agent 搜索规则时读取的行数单体方案searchMonolithic从第一行开始顺序扫描找到规则需要读取的行数等于规则所在行号拆分方案searchSplit根据查询所属分区只读取对应那一个约 50 行的专题文件。按脚本逻辑推算的四组查询结果行号来自代码中埋入的规则位置查询单体读取行拆分读取行节省找显式返回类型规则第 72 行7222约 69%找部署窗口规则第 175 行17525约 86%找集成测试规则第 120 行12020约 83%找测试文件结构规则第 135 行13535约 74%平均约 126约 26约 79%脚本的运行方式见 CLAUDE.md 的命令约定npx tsx docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts。脚本结尾的结论点明了收益单体文件下每次查询都要扫描最多 200 行拆分后只需读取相关的约 50 行文件——更少的上下文窗口占用、更少的幻觉、更快的执行。2. 真实案例同一个仓库里的两种 AGENTS.md仓库本身就是一个拆分前后的活教材projects/project-01/solution/AGENTS.md约 60 行已经具备短入口文件的形态启动规则按序执行、四个 Electron 层边界、约定、完成定义、功能清单工作方式全部是当前项目必须知道的内容。projects/project-02/solution/AGENTS.md进一步示范了路由式入口Startup Rules中按顺序引导读取docs/ARCHITECTURE.md与docs/PRODUCT.md并明确docs/ 目录按 agent 可读性组织配合session-handoff.md记录上次会话的完成项、剩余项、决策与改动文件——这就是第 4 讲所说把偶尔用的信息收起来的实际落地。3. 官方模板的印证仓库的多处模板文件都把入口文件 路由层写成了明文docs/en/resources/templates/AGENTS.md开头即声明本仓库为长时运行 coding-agent 设计……优先用持久的仓库工件而非聊天摘要并引导读取feature_list.json、claude-progress.md、init.sh。docs/en/resources/openai-advanced/repo-template/AGENTS.md更明确地写道保持本文件简短把它当作进入 system-of-record 文档的路由层而不是巨型指令转储并用Routing Map一节一行一条地列出ARCHITECTURE.md、docs/design-docs/、docs/product-specs/、docs/PLANS.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md、docs/SECURITY.md、docs/FRONTEND.md各自管什么。skills/harness-creator/templates/agents.mdharness-creator 技能的官方模板同样保持精简结构——启动工作流、工作规则、必需工件、完成定义、结束会话流程、验证命令。这些文件相互印证了同一结论入口文件负责路由深度内容由专题文档和代码承载。4. 与反模式的对照把仓库真实文件放回反模式清单里检查会发现拆分后的入口文件恰好避开了全部五条知识分散到docs/专题文档反模式一、规则只写一处反模式二、session-handoff.md与feature_list.json这类工件让过时条目有据可查反模式三、条件指令带适用条件路由反模式四、工具命令只留一行反模式五。十、业界实践参考与边界说明第 4 讲还梳理了公开的工程实践需要注意这些描述都来自讲座所引用的公开资料且原文对这些数据都有明确边界说明OpenAI报告称单一巨型 AGENTS.md 挤占任务上下文、混淆优先级、积累过时规则且难以检查团队改用约 100 行的入口文件作为地图把详细知识放进结构化的 docs 目录并用专门的 lint 与 CI 检查维护知识库。原文并未报告这次调整前后的任务成功率或安全约束遵循率。ETH Zurich的评估研究发现在其评测设置中仓库上下文文件并未普遍提升任务成功率却使推理成本增加超过 20%建议人工编写的需求保持精简——文件变短不等于效果必然变好需要在目标任务上实测验证。Lulla 等人的配对研究gpt-5.2-codex、10 个仓库、124 个 PR 派生任务报告有 AGENTS.md 时中位耗时从 98.57s 降到 70.34s低 28.64%、中位输出 token 从 2,925 降到 2,440低 16.58%。但这测量的是效率而非拆分巨型文件的效果功能正确性不在研究范围内。这些资料的完整链接见 第 4 讲正文 的延伸阅读部分。更关键的工程结论是短文件不是银弹指令体系必须在它要支撑的真实任务上做前后对比验证。十一、关键要点与动手练习关键要点加条规则是短期止痛药、长期毒药。加规则之前先想这条规则放专题文档是不是更合适入口文件是路由器不是百科全书50–200 行只放概览、硬约束、链接。利用中间迷失效应重要信息放文件顶部或底部次要内容移入专题文档。像管理技术债一样管理指令膨胀定期审计每条指令有来源、适用条件和过期条件。拆分之后 SNR 提升agent 把更多上下文预算花在实际任务上而不是处理无关指令。练习源自第 4 讲SNR 审计列出当前入口指令文件的全部条目选 5 种常见任务类型逐一标记每条指令是否与该任务相关计算每种任务的 SNR。对大多数任务都是噪声的条目移到专题文档。按需展开重构如果指令文件超过 300 行拆成 (a) 不超过 100 行的入口文件 (b) 3–5 个专题文档。重构前后各跑同一组任务至少 5 个对比成功率。中间迷失验证在长指令文件中把一条关键约束分别放在顶部、中间、底部各跑一组任务每组至少 5 次对比遵循率差异——你可能会惊讶于位置效应有多强。这三个练习配合仓库的split-vs-monolithic.ts模拟与 Project 02 的实践项目即可完成从认识反模式到掌握拆分方法论再到亲自动手重构的完整闭环。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐AGENTS.md 巨型指令文件为何失败用 Progressive Disclosure 拆分指令路由learn-harness-engineering 实战AGENTS.md 巨型指令文件为何失败用 Progressive Disclosure 拆分指令路由learn harness engineering 实巨型指令文件为何让 Agent 失效learn-harness-engineering 中的指令反模式与按需拆分实战巨型指令文件为何让 Agent 失效learn harness engineering 中的指令反模式与按需拆分实战 本篇技术指南围绕 learn harne拆散巨型指令文件Learn Harness Engineering 第 4 讲「AGENTS.md 越写越长、Agent 反而越用越差」的根因与拆分方案拆散巨型指令文件Learn Harness Engineering 第 4 讲「AGENTS.md 越写越长、Agent 反而越用越差」的根因与拆分方案 导读上一篇如何快速构建企业级浏览器串口调试平台5大核心能力解析下一篇Legado-Harmony免费开源阅读器打造个性化电子书库终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考