AI Coding's Real Bottleneck Is the Repository, Not the Model

最近在做 DocFlow，一个融合 Agent、RAG 和知识图谱的全栈实战项目，实测支持百人实时协同，支持 Word（DOCX）、PDF 导入，Agent 能检索资料、改写文档、操作表格，背后实现了 主 Agent 统筹、子 Agent 并行查证与结果复核，以及上下文自动压缩、长短期记忆和任务恢复，RAG 则涵盖 父子分块、BM25＋向量混合检索、RRF 融合、重排与原文引用溯源，适合想深入源码、动手做 AI 应用的同学

同时整理了 80 篇 Agent 开发、72 篇 RAG、70 篇知识图谱文章，共 222 篇学习资料，从基础原理到工程实践，可以结合源码边学边做，感兴趣可以加我微信 yunmz777，了解项目与配套资料，一起交流 AI 开发。

第一次用 Codex、Claude Code、Cursor Agent，最直接的感受通常是快。接口、类型、测试、文档都能迅速生成，一个人甚至可以同时开多个 Agent 往前推。

项目跑一段时间以后，瓶颈会换地方，代码越来越容易写出来，仓库却越来越难养。目录边界开始松，重复 helper 变多，测试数量涨了却没盖住关键路径，PR 往里涌，人的 Review 开始排队。更麻烦的是，坏写法一旦进主干，后面的 Agent 还会接着学。

这时候再换更强模型、把上下文加长，或者把 AGENTS.md 再堆厚一点，往往只能补局部，缺的是一套能接住高吞吐生成结果的工程环境。

OpenAI 的 Harness Engineering 讨论的，正是这种重心转移，人从亲手做完每一处实现，转向设计环境、把意图说清楚，并搭起反馈回路。Codex 的 AGENTS.md 文档 也写明，Codex 开工前会读 AGENTS.md，把它当仓库级工作指导。

所以 Harness Engineering 要解决的，不是再多挤出一点代码，而是让生成结果在真实仓库里长期可控、可验、可维护。

真正危险的不是写错一次，而是坏模式开始自我复制

传统开发里，一个坏写法进主干，扩散往往还比较慢。到了 AI Coding，速度会明显加快，因为 Agent 很擅长顺着当前仓库已有的写法继续生成。

分层清楚，它就学清楚的分层，到处是跨层依赖、万能 helper、随意 any 和过期文档，它也会把这些当成项目惯例。

这也是 Harness 为什么要盯仓库熵增。目标不是幻想某个 Agent 永不犯错，而是错误进了系统以后，尽量别再轻易获得继续复制自己的机会。

工程师的工作正在从直接实现，上移到设计工作环境

模型接手更多实现以后，工程师并没有退场，只是重心变了。

过去很多工程经验可以留在人脑里，靠带人、口头沟通和 Review 往下传。Agent 进来以后，这些隐性规则得逐渐落成仓库里的结构、导航、自动检查和验证路径，否则模型只能猜。

问题也随之从 "模型能不能帮我写" 变成 "项目能不能让 Agent 少反复踩同一类坑"，两句话听起来接近，工程解法却差得很远。

Harness 不是工具拼盘，而是一条能够纠错的工程闭环

把上下文、工具、记忆、权限和监控都接上，并不会自动变成可靠的 Harness，有没有价值，要看这些能力有没有串成闭环。

任务进来以后，要经过导航、实现、约束、验证和合并判断，失败了还要能定位原因，并把新知识写回仓库。

闭环一旦转起来，一次失败就不再只是返工，它可以沉淀成新的导航、规则、测试或清理任务。下一次任务再进来时，环境已经和上次不完全一样。

仓库要成为 Agent 能稳定读取的记录系统

很多团队不是没有规则，而是规则放错了地方。架构原则在群聊里，模块边界在老员工脑子里，事故经验留在会议纪要里，对人还能勉强运转，对 Agent 基本等于不存在。

Agent 更稳地能消费的，是仓库里的代码、Markdown、配置、测试、日志、命令结果和 CI 输出，仓库因此不能只存最终代码，还要留下足够的工程事实。

还有一点同样关键，不同知识别全塞进同一个文档。

以 NestJS 项目为例，与其给 Agent 一大段技术栈介绍，不如直接说清边界：api 不直接访问 Redis 或队列，common 不是工具函数垃圾桶，Service 不直接读 process.env，新接口必须补 DTO 和权限测试。真正影响实现的，是这些约束。

AGENTS.md 应该负责指路，而不是承担全部知识

AGENTS.md 很容易被写成越来越厚的百科全书。技术栈、项目历史、部署流程、所有目录、全部注意事项一股脑塞进去，表面信息很多，当前任务真正要紧的规则反而被冲淡，它更适合当入口地图。

写得好的 AGENTS.md，不会试图一次塞完仓库里所有知识，而是尽量缩短从任务到正确上下文、正确修改位置、正确验证命令之间的路径。

文档让边界可见，自动检查才能让边界真正生效

只告诉 Agent "不要跨层 import"、"不要直接读环境变量"、"新接口必须补权限测试"，本质上还是提醒，复杂任务里模型可能守住，也可能漏掉。

不可违反的规则，得进入确定性机制。Claude Code hooks 文档 对 hooks 的定位很直接，在生命周期指定节点跑确定性命令，而不是指望模型自己记得做。

机械化不是把 Agent 管死，而是把项目真正不能被破坏的不变量钉住。规则越确定，就越不该继续消耗模型推理和人的 Review 注意力。

"已经完成" 必须变成可以被观察的工程状态

有约束还不够，代码写完以后还得证明它能工作。

AI Harness Engineering 论文 把任务规格、上下文选择、工具访问、项目记忆、任务状态、观测、失败归因、验证、权限和熵管理等能力放在 harness 层讨论。落到工程里，有一条很硬，完成不能只靠模型自报。

不同类型的修改，需要的证据也不一样。

OpenAI 的 Harness Engineering 提到的 application legibility 和 agent legibility，落到项目里就是尽量看得懂、跑得动、验得清。Agent 需要改文件的权限，也需要受控执行命令、读日志，再根据结果继续修正。

长任务不能只活在聊天记录里

小改动可以靠一次对话撑住，跨模块重构、接口迁移、复杂工作流修改就不行。任务拖到几小时甚至更久以后，改过哪些文件、跑过哪些命令、哪里失败过、还剩什么风险，都不能再完全押在聊天上下文上。

这些进度也不该一股脑写进长期记忆，临时状态和长期知识要分开。

Claude Code memory 文档 也提醒，CLAUDE.md 和自动记忆本质上仍是上下文，不是强制配置。真正必须执行的规则，最后还得落进确定性检查。

多 Agent 提高吞吐以后，系统必须主动制造背压

一个人能同时驱动多个 Agent，不等于项目能无限吞下 PR。如果生成结果全直接进人工 Review，人的注意力很快会变成新队列，Agent 越多，队列往往越长，所以高吞吐环境里的背压得主动做出来。

Review 不会因为 Agent 出现就失去价值，它只是该少管机器已经能判定的问题，把人的注意力留给需求理解、架构边界、高风险取舍和最终合并责任。

Harness 最有价值的能力，是把错误写回系统

如果今天 Agent 写错了，人修完就收工，下次仍可能从头再犯。

更该追问的是，为什么这次错误能走到这么后面。是 AGENTS.md 指错了位置，文档没写清边界，lint 没覆盖，测试缺了，还是主干里本来就堆满了坏样本？不同根因，应写回不同位置。

持续清理在 AI Coding 里也会更重要。重复 helper、跨层依赖、过期文档、随意 any、绕过权限校验的接口，不只耽误今天的人，也会变成未来 Agent 的参考样本。

代码更容易生成以后，真正难复制的是工程环境

当 Coding Agent 能越来越稳地写出普通实现，代码本身并没有贬值，但团队难复用、难复制的资产会往另一层挪。

这里为什么不能跨层调用、什么改动必须人工批准、数据库迁移怎样才算安全、怎样证明任务真的结束、失败以后怎样恢复，这些东西不会因为模型更强就自动长出来。

AGENTS.md 模板、目录约束、lint、结构测试、CI 门禁、排查文档、失败样本和回归测试，会逐渐变成团队真正值钱的长期资产。

落地 Harness，不要一开始就造大平台

Harness Engineering 一旦展开，可以装进记忆、权限、评测、编排、观测、反馈等很多平台能力。团队刚开始用 Coding Agent 时，没必要一口吃成胖子，更现实的做法是先让最小闭环真正转起来。

这个阶段缺的不是功能清单，而是一条最小反馈回路，让 Agent 能找到正确上下文，在规则内改代码，跑固定验证，失败后还能留下新的工程能力。这条环一开始转，项目就从一次性的 AI Coding 迈进了 Harness Engineering。

Harness Engineering 也不是把提示词写得更复杂

提示词、上下文、技能包、Agent Framework 和 Harness 常被放在一起谈，但它们不在同一层。边界若不拆开，很容易把一份很长的 AGENTS.md，或一套复杂的 Agent 编排框架，误当成整套 Harness 已经就绪。

提示词工程更靠近当前输入，上下文工程决定当前任务该看到什么，技能包沉淀可复用的操作方式，Agent Framework 负责模型、工具、状态和多步执行的编排。Harness Engineering 站在更外层，关心这些能力进入真实仓库以后，怎样长期被边界、验证、反馈和清理约束住。

总结

Harness Engineering 要解决的，是项目能不能承受 Coding Agent 带来的高吞吐，而不是模型能不能再多写一点。

仓库要从只存代码，变成 Agent 能读到的工程记录系统。AGENTS.md 负责导航，不可违反的规则进入 lint、类型系统、hooks、结构测试和 CI。任务完成要拿出证据，长任务要区分临时状态、长期记忆和强制门禁，多 Agent 并行时还要用自动背压迫主干。

错误也不能只修当前补丁，每次失败都该追到导航、约束、验证或仓库熵增上的根因，再把规则、测试、文档和清理任务写回系统。

没有这套闭环，AI Coding 只会更快产出代码，也更快放大仓库原本的问题。有了 Harness，每一批生成结果才会受同一套工程环境约束，失败也会逐渐变成下一次任务的保护。

Agent 可以说 "已经完成"，但代码能不能进主干，最终还得看工程边界和验证证据。