Qoder Harness Engineering 指南：仓库是 Agent 操作系统 + 100 行 AGENTS.md + 层级约束（泮圣伟）

来源类型： 工程实践深度
日期： 2026-06-17
标签： #Qoder #HarnessEngineering #AGENTSmd #层级约束 #泮圣伟

核心痛点

"当我们让 AI Agent 实现一个功能，它思考了一下，开始写代码。200 行写完，运行 lint 直接失败。"

"循环三次后，上下文窗口被错误日志和 diff 塞满，Agent 开始'忘记'最初的任务目标。"

"这不是 Agent 不够聪明。这是 Agent 看不见。"

核心问题

"Prompt 写得再好，也没法穷尽代码库的所有隐式规则。上下文窗口再大，也装不下整个仓库的架构决策。"

"'教得更好'这条路有天花板——写更详细的 system prompt，提供更多示例，规则会随代码演进变化，你永远追不上。"

Harness 核心思路

"Harness 工程的思路不一样：与其教 Agent 怎么做，不如让它自己验证做得对不对。靠代码、linter、测试来保证正确性，而不是靠 LLM 的'直觉'。"

仓库是 Agent 的操作系统

"CPU 很强大，但没有操作系统它就是一块高速却无方向的芯片。"

"Harness 就是给它装的'操作系统'。"

四大原则

1. 仓库是唯一事实来源

"Aone 里的讨论、钉钉会议上的口头约定、架构师脑子里的蓝图，这些对 Agent 来说都不存在。"

"第一步是把一切编码到仓库中：架构决策、层级约束、命名规范。不是写在 Wiki 里，不是发在群里，而是作为版本化的文件提交到 Git。"

2. AGENTS.md 是地图不是手册

"很多团队的第一反应是写一份巨大的 AGENTS.md，500 行，什么都有。问题是：当一切都重要时，什么都不重要。"

"AGENTS.md 应该是地图，不是手册——控制在 ~100 行，只做索引和指路，详细内容放在 docs/ 目录里按需加载。"

3. 约束的粒度

"Harness 不规定'你必须用这个设计模式'或'函数必须这样写'，它只管架构边界。"

层级编号

Layer 0：类型定义（不 import 任何内部包）
Layer 1-2：工具函数和配置（只依赖更低层）
Layer 3：业务逻辑
Layer 4+：HTTP handler 和 CLI 命令

"规则就一条：高层可以 import 低层，反过来不行。"

4. 人的角色

"以前是人写代码、AI 辅助补全；现在反过来了——人设计系统（架构、约束、验证规则），Agent 在系统内执行。"

"人的价值从'写出正确的代码'变成了'设计出让 Agent 能可靠产出正确代码的环境'。"

关键洞察

1. 仓库 = OS

Agent 操作系统
CPU 强大但无方向

2. AGENTS.md ~100 行

地图不是手册
不腐烂

3. 层级约束

0-4 层
高层 import 低层

4. 自动化验证

替代 LLM 直觉
CI/CD 提前拦截

5. 人 = 系统设计者

不再拧螺丝
确保流水线对

与已有知识的关联

wiki/entities/qoder — Qoder
wiki/entities/agents-md — AGENTS.md
wiki/concepts/harness-engineering — Harness Engineering
wiki/concepts/layer-architecture — 层级架构
wiki/entities/pan-shengwei — 泮圣伟（作者）
wiki/entities/aone — Aone
wiki/concepts/auto-verify — 自动化验证

资料来源

原文：https://mp.weixin.qq.com/s/Et3WwNtEXEgxjaQHrQFDyQ
原始文件：raw/articles/微信文章/Qoder 工程实践：Harness Engineering 指南.md
作者：泮圣伟

我的判断（高置信度）

这是 2026 年 Harness Engineering 最深度的工程实践——仓库是 OS + AGENTS.md 100 行 + 层级约束 + 自动化验证。

关键洞察：
1. "仓库 = OS" —— 是核心类比
2. "AGENTS.md ~100 行" —— 是平衡
3. "层级约束" —— 是架构边界
4. "自动化验证" —— 是替代 LLM 直觉
5. "人 = 系统设计者" —— 是角色转变

预测：
- 2026 H2：可能形成 Harness 标准
- 2027：可能立法"AI 编程规范"
- 2028：可能涌现"Harness 工程师"职业

对 AI 工程师的建议：
"Harness Engineering" 是新方向
- 仓库是 OS
- AGENTS.md 是地图
- 自动化验证是关键

对企业 IT 的启示：
"AGENTS.md 100 行" 是新规范
- 不臃肿
- 按需加载
- 长期演进

对创业者的启示：
"Qoder 模式" 是新方向
- 人 + Agent 协作
- 系统设计是核心
- 长期价值是关键