当AI Agent编写代码时，常因不了解项目架构规范而违反分层约束。它反复尝试修复：移动代码、调整依赖、重新组织，但lint检查又引发新问题。数次循环后，上下文窗口被错误日志填满，Agent逐渐"遗忘"最初任务目标。
问题核心并非AI能力不足，而是它"看不见"团队的隐式规则。同一项目中，昨日记得架构约定的AI，新会话中又全然遗忘。Prompt再详细也无法覆盖代码库所有规则，上下文窗口再大也装不下全部架构决策。规范文档存于钉钉或Notion上，AI无法读取。
Harness工程提出新思路：不依赖AI"直觉"，而是通过机械化检查确保正确性。如同CI/CD在合并前拦截问题，Harness将验证提前至编码阶段。
仓库是 Agent 的操作系统
LLM如同高性能CPU，缺少操作系统指引则无法理解仓库架构。Harness将仓库转化为Agent的"操作系统"，核心原则有四：
落地：从搭建到执行
Harness由两大引擎协作：harness-creator生成基础设施（文档/lint脚本），harness-executor执行开发任务。工作流为：检测环境→加载上下文→制定计划→人工审批→执行→验证→完成。executor启动时若缺少AGENTS.md，自动调用creator构建环境。
creator首次运行会对项目评分（0-100分）：0-20分为裸奔状态需从零搭建；21-70分有基础但存缺口；71分以上仅需微调。
典型项目结构如下：
my-project/
├── AGENTS.md ← 导航地图（~100行）
├── docs/
│ ├── ARCHITECTURE.md ← 架构与依赖规则
│ ├── DEVELOPMENT.md ← 构建/测试命令
│ └── design-docs/ ← 组件设计文档
├── scripts/
│ ├── lint-deps.* ← 层级依赖检查
│ └── validate.py ← 统一验证管道
└── harness/ ← 状态管理目录
├── tasks/ ← 任务状态
└── trace/ ← 执行轨迹核心在于scripts/的机械执法层，将团队规范转化为"不遵守即报错"的硬性规则。
在动手之前先问"能不能做"
验证分三层：编译检查→架构合规（lint-arch）→单元测试→端到端功能验证（verify）。关键创新是预验证机制：
python3 scripts/verify_action.py --action "create file internal/types/user.go"
# ✓ VALID: 符合命名规范
python3 scripts/verify_action.py --action "import internal/core from internal/handler"
# ✗ INVALID: L4不能import L3对新文件创建或跨包import等操作预验证，可避免50+行代码重构的成本。优质报错应包含：违规规则、原因、修复建议，本质是实时教学。
verify环节验证用户实际路径（如"创建用户→登录→查看资料"），补足测试覆盖盲区。creator会自动生成verify脚本骨架，开发者填充断言逻辑即可。
上下文是最贵的资源
中等以上任务必须拆解为协调者与执行者：协调者（Coordinator）专注规划与汇总，绝不触碰代码；执行者（子代理）从纯净上下文启动，任务完成后释放上下文，仅保留摘要。
模型需按任务性质差异化调用：简单任务（改typo）用Claude Haiku等轻量模型；复杂重构用GPT-5.3 Codex；代码检索用Gemini Flash。交叉review环节使用不同架构的模型进行代码审查，有效发现逻辑隐患。
检查点机制记录关键架构决策，确保中断后恢复时的决策一致性。避免协调者"顺手改代码"——这将快速消耗上下文资源，引发恶性循环。
让 Harness 自己长大
Harness通过闭环实现自我进化：Agent失败→验证捕获问题→Critic分析根因→Refiner更新规则。例如某包被多次违规import时，系统自动补充层级映射。
Harness维护三类记忆：情景记忆（具体失败教训）、程序记忆（成功操作流程）、失败记忆（供Critic分析）。当同类任务成功执行三次以上，可"编译"为确定性脚本（如make add-endpoint），释放Agent处理创新工作。
从今天开始实践
最小实施路径：创建AGENTS.md（https://agents.md/）作为Agent指南：
# 项目名 Agent Guide
## 架构总览
Layer 0: types/ → 纯类型定义
Layer 1: utils/ → 工具函数
Layer 3: core/services/ → 业务逻辑
Layer 4: api/ → 接口层
## 质量标准
- 单文件≤500行
- 禁止console.log/print()
- PascalCase命名类型
- 执行：make lint-arch新项目直接用creator搭建，旧项目由creator扫描生成基础设施。建议步骤：当日建立AGENTS.md；本周添加lint脚本；本月完善验证管道；后续启动Critic→Refiner反馈循环。半年后，仓库将成为高度适配团队的Agent运行环境，竞争优势体现于可复用的"轨迹"而非临时Prompt。
环境设计的价值远超Prompt调优。Harness使普通模型产出可靠代码，缺失该系统的顶级模型仍会在基础问题上反复失误。前期半日构建基础规则，将收获随时间复利增长的协作效能。