harness-engineering

Harness：以 Agent 为先的工程脚手架

Harness 是让编码 Agent 能在代码仓库中有效工作的脚手架。 它将 Agent 直接根据仓库本身理解完整业务领域所需的知识、边界和规则编码其中。

其理念是：Agent 执行，人类引导。工程师的工作不是编写代码，而是设计环境、明确意图并建立反馈循环。 Harness 让这一切成为可能。

为什么重要

从 Agent 的角度来看，运行时无法在上下文中访问的内容，实际上就不存在。Slack 讨论、Google 文档、团队的隐性知识—— 这些都不可见。Harness 将这些知识编码为仓库本地、受版本控制的产物，使其清晰可见。

Harness 完善的代码仓库会为 Agent 提供：

• 地图（AGENTS.md）——指明去哪里查找，而不是要记住什么
• 边界（领域规范）——规定哪些内容可以相互依赖
• 规则（黄金原则）——将审美判断编码为可强制执行的不变量
• 质量基线（评分）——指出差距所在

没有这些脚手架，Agent 会照搬它们发现的各种模式——包括糟糕的模式。Harness 可以防止熵不断累积。

Harness 成熟度模型

Harness 是逐步构建的。每个级别都建立在前一个级别的基础上——不要试图一次性从 Level 0 跳到 Level 4。评估当前级别，并朝下一级迈进。

级别	名称	能实现什么	关键产物
0	无 Harness	Agent 对一切都只能猜测——没有地图，没有规则	无
1	地图	Agent 知道去哪里查找，也了解代码库的功能	AGENTS.md、ARCHITECTURE.md、docs/
2	规则	Agent 知道什么可以做、什么不可以做	.harness/principles.yml、enforcement.yml、domains.yml
3	反馈	Agent 通过质量信号和流程模式自我纠正	.harness/quality.yml、文档维护、GC 扫描
4	自主性	Agent 可在明确的升级处理边界内独立运行	Worktree 隔离、升级规则、Agent 间审查

各个级别的效果会层层叠加。一个达到 Level 2、但没有 Level 1 的代码仓库，其规则无人能找到。一个达到 Level 3、但没有 Level 2 的代码仓库，虽然有质量评级，却无从落实改进。先打好基础。

评估期间（Phase 1），确定当前成熟度级别。规划期间（Phase 2），以达到下一级为目标——不要一次性追求所有级别。重复执行 Harness 工作流，逐步提升。

关键例外：对于 Agent 正在积极编写代码的代码仓库（以 Agent 为先或由 Agent 辅助），架构边界（领域定义和依赖只能向前的规则）应与知识层一同创建，而不是推迟到单独的 Level 2 阶段。文章明确指出，严格的架构是由 Agent 驱动开发的第一天就必须具备的前提，而不是规模化后的考量。没有边界，Agent 生成代码的速度会快过控制熵的速度。

多轮工作流

构建 Harness 是一个交互过程。请按以下阶段推进，在每个阶段的交界处展示结果并等待用户确认。用户可能希望跳过、调整阶段顺序或扩展阶段——请遵循用户的安排。

Phase 1: Assess    → Analyze the repo, report agent readiness
Phase 2: Plan      → Propose a tailored harness, user confirms
Phase 3: Knowledge → AGENTS.md, docs/, ARCHITECTURE.md
Phase 4: Domains   → Identify domains, map layers, generate .harness/domains.yml
Phase 5: Enforce   → Golden principles, rules → .harness/principles.yml, enforcement.yml
Phase 6: Quality   → Grade domains → .harness/quality.yml
Phase 7: Process   → Doc-gardening, GC, review patterns
Phase 8: Verify    → Cross-check everything, report completeness

深度优先地构建引导层

应深度优先而非广度优先地构建工具链。早期构建工具链所需的时间比预期更长——并不是因为仓库有问题，而是因为环境信息不够完善。每个阶段都会为下一阶段铺路：

• AGENTS.md 为 docs/ 铺路（Agent 知道更深入的内容该放在哪里）
• docs/ 为理解架构铺路（Agent 可以阅读领域背景）
• 架构规范为正确识别领域铺路
• 领域规范为制定有意义的执行规则铺路
• 执行规则为质量评分铺路（无法检查的内容就无法评分）

遇到问题时，解决办法几乎从来不是“再努力一点”。不妨问问：缺少什么能力或上下文？ 然后先补齐这部分。

对于现有工具链的更新，同样适用这些阶段；但评估时会将差异与当前的 .harness/ 规范进行对比，只更新发生偏差的部分。

阶段 1：评估

检查仓库的所有工具链层。目标是了解现有内容、缺失内容和不一致之处，而不是立即修复问题。

检查内容：

领域	检查内容
结构	目录、语言、包清单、单体仓库还是单包
技术栈	框架、构建系统、部署目标、依赖管理器
Agent 配置	AGENTS.md、CLAUDE.md、.cursor/、.github/copilot/，以及任何现有的 Agent 指令
文档	README、docs/、架构文档、ADR、代码中的文档注释
代码组织	领域结构、模块边界、导入模式、依赖关系图
测试	框架、覆盖率、CI 门禁、测试组织方式
可观测性	日志模式（是否为结构化日志？）、指标、错误处理、跟踪
流程	PR 模板、评审工作流、CI/CD 配置
团队配置	Agent 优先（Agent 编写 90% 以上的代码）、Agent 辅助（混合模式），还是 Agent 就绪（为未来使用 Agent 做准备）
依赖项	外部库是否便于 Agent 理解？API 是否稳定、文档是否完善、训练数据中的表示是否充分？

阅读 references/assessment.md，查看详细检查清单和评分标准。

团队配置决定工具链的形态：Agent 优先型仓库从一开始就需要强有力的执行机制和垃圾回收（GC）。Agent 辅助型仓库需要明确的边界，但可以更多依赖人工评审。Agent 就绪型仓库主要需要知识层。

输出： 一份 Agent 就绪度报告——按层整理的当前状态摘要、关键发现，以及按优先级排列的建议工具链组件。

提交报告，并等待用户确认或调整后再进行规划。

阶段 2：规划

针对这个特定仓库提出工具链计划。并非每个仓库都需要所有组件——应根据评估结果合理确定范围。

按成熟度等级确定规模：

当前等级	目标	要构建的内容
0 → 1	绘制地图	AGENTS.md、ARCHITECTURE.md、核心 docs/ 结构
1 → 2	制定规则	.harness/domains.yml、principles.yml、enforcement.yml
2 → 3	提供反馈	.harness/quality.yml、文档维护、GC 模式
3 → 4	实现自治	Worktree 隔离、升级边界、Agent 评审

还要考虑仓库规模——小型仓库（< 5k LOC）可能只需要等级 1–2，而大型代码库（50k+ LOC）则适合采用全部四个等级。

计划应按阶段列出所有要创建或更新的产物，并简要说明每项产物的作用。将计划整理成清单，供用户批准、修改或删减。

开始实施前请等待确认。

阶段 3：知识层

构建能为 Agent 提供代码库地图的产物。

AGENTS.md（约 100 行）

这是最重要的单个文件。它是一张路由表，不是百科全书。

其中应包含：

• 3–5 条不可妥协的规则（违反后造成的损害最大的规则）
• 指向更深入文档的链接：ARCHITECTURE.md、docs/、当前计划
• 如何验证工作（构建／测试命令）
• 仓库是什么以及它的结构（2–3 句话）

其他内容都应放在 docs/ 中。如果 AGENTS.md 超过约 100 行，就太长了， 应将内容拆分到 docs/，并添加指向这些文档的链接。

docs/ 目录

docs/
├── design-docs/
│   ├── index.md              # Catalogue with verification status
│   └── core-beliefs.md       # Agent-first operating principles
├── exec-plans/
│   ├── active/               # In-flight work
│   ├── completed/            # Done work (context for future agents)
│   └── tech-debt-tracker.md  # Known debt with priority
├── generated/                # Auto-generated (DB schema, API specs)
├── product-specs/
│   ├── index.md              # Feature catalogue
│   └── <feature>.md
├── references/               # External docs in agent-friendly format
├── PRODUCT_SENSE.md          # Product principles, personas, domain sensitivity
└── <DOMAIN>.md               # Domain guides (only those relevant to the repo)

docs/ 中的每个文件都应采用渐进式披露结构：

1. 摘要（2–3 句话）——足以让 Agent 判断此文件是否相关
2. 关键决策——最重要的 3–5 项内容，放在前面
3. 详情——供需要深入了解的 Agent 阅读的完整内容
4. 指引——链接到相关文档，以获取更多背景信息

这样可以防止“一个庞大的 AGENTS.md”问题在文件层面再次发生。 Agent 应能够只阅读每份文档的摘要，然后找到合适的文档，而不是将所有文件都加载到上下文中。

只创建仓库实际需要的内容。每个文件都应包含基于评估得出的实际内容， 而不是模板套话。

ARCHITECTURE.md

顶层领域地图，应回答：有哪些领域、它们之间有何关系、依赖规则是什么、新代码应放在哪里。

阅读 references/knowledge-layer.md，了解模板和写作指南。 阅读 references/core-beliefs.md，了解核心信念模板和内容指南。

阶段 4：架构层

将领域边界和依赖规则定义为机器可读规范。

领域识别

领域是一个纵向切片——一颗贯穿所有集成层的追踪弹，从数据结构一直到面向用户的输出。它不是一个横向技术层。

判断标准：能否追踪用户操作从 UI 到运行时、服务、仓库和类型的完整路径，并且这条路径始终围绕一个连贯的业务概念？如果可以，这就是一个领域。

CORRECT (vertical slices):        WRONG (horizontal layers):
┌─────────┐ ┌──────────┐         ┌──────────────────────────┐
│ Billing  │ │ Onboard  │         │ controllers/             │ ← NOT a domain
│ ┌─────┐  │ │ ┌─────┐  │         │ models/                  │ ← NOT a domain
│ │Types│  │ │ │Types│  │         │ services/                │ ← NOT a domain
│ │Confg│  │ │ │Confg│  │         │ utils/                   │ ← NOT a domain
│ │Repo │  │ │ │Svc  │  │         └──────────────────────────┘
│ │Svc  │  │ │ │UI   │  │
│ │UI   │  │ │ └─────┘  │
│ └─────┘  │ └──────────┘
└─────────┘

寻找业务概念，而不是技术功能：

• “计费”“引导”“搜索”＝领域（纵向，拥有完整技术栈）
• “控制器”“工具函数”“测试”“工具链”＝层或关注点（横向）

阅读 references/architecture-layer.md，了解详细的识别启发式方法和追踪弹测试。

层结构

每个领域内部的代码按层组织：

Types → Config → Repo → Service → Runtime → UI

关键规则：依赖只能向前流动。 types 模块绝不导入 service。横切关注点（身份验证、遥测、功能标志）通过一个名为 Providers 的显式接口接入。

并非每个领域都包含所有层。CLI 工具可能只有 Types → Config → Service → Runtime。库可能只有 Types → Service。按实际情况梳理。

生成 .harness/domains.yml

创建领域规范。阅读 references/yml-schemas.md 了解架构， 并阅读 references/architecture-layer.md 了解识别启发式方法。

阶段 5：强制执行层

将架构方面的偏好编码为机器可读规则。目标是：集中执行边界，允许局部自主。

黄金原则（.harness/principles.yml）

识别 5–10 条针对本仓库的明确规则。每条原则都需要：

• 内容：规则本身
• 原因：为何重要（不遵守会出什么问题）
• 检查方法：Lint、结构测试、审查或人工检查
• 示例：来自此代码库的具体正／反面代码片段

从评估中发现的原则入手——已经造成问题的模式，或目前依靠人工维护、但应加以强制执行的不变量。

机械规则（.harness/enforcement.yml）

工具可以检查的具体规则：

• 文件、类型、函数的命名约定
• 文件大小限制
• 结构化日志要求
• 导入边界检查
• 测试覆盖率要求

面向 Agent 的错误消息

这是整个工具链中杠杆效应最高的模式之一。每条强制执行规则都必须包含一个 violation_message 模板，并包含以下四个部分：

1. 问题所在 — 具体的违规行为
2. 重要性 — 与某项原则相关联的理由
3. 修复方法 — 具体的修复步骤
4. 参考位置 — 文件路径或文档指引

Lint 错误消息是一种传递机制，可在 Agent 恰好需要时，将修复说明注入其上下文中。笼统的消息（“X 中存在边界违规”）几乎毫无用处。详细的消息（“X 从 Y 导入内容，违反了只能向前依赖的规则。修复方法：通过 Providers 注入。参见：ARCHITECTURE.md#cross-cutting”）能让 Agent 立即自我纠正。

生成强制执行代码

.harness/*.yml 规范描述了规则。但没有任何检查的规范只是会逐渐失效的文档——这正是工具链旨在防止的问题。

对于每条强制执行规则，至少还要生成一个具体产物：

• Lint 配置：强制执行命名、导入或结构规则的 ESLint/Ruff/Clippy 配置，并提供面向 Agent 的错误消息
• CI 工作流：用于验证 AGENTS.md 链接、docs/ 交叉引用或知识时效性的 GitHub Actions / CI 任务
• 结构测试：用于验证架构不变量（例如导入方向、领域边界合规性）的测试文件
• 脚本：用于检查文件大小限制、禁止模式或命名约定的验证脚本

即使是存根实现，也胜过什么都没有。带有 TODO 函数体的 lint 规则，比一份文档完善却无人读取的 YAML 规范更有价值。

阅读 references/enforcement-layer.md，了解原则目录和模式。 阅读 references/yml-schemas.md，了解架构。

阶段 6：质量评分

按照标准化维度为每个领域评分。

**维度：**代码质量、测试覆盖率、文档、可观测性、可靠性、安全性。

**等级：**A（优秀）到 F（缺失／损坏）。

初始评分是基线。后续工具链更新会将当前状态与这些等级进行比较，以跟踪改进或检测偏离。

生成 .harness/quality.yml，其中包含评分、差距说明和审核日期。 阅读 references/quality-scoring.md，了解评分标准。

阶段 6.5：运行环境可理解性（如适用）

对于有正在运行的应用（Web 应用、API、服务）的代码库，评估 Agent 是否能观察应用，而不仅仅是代码。文章中的团队让 Agent 能够直接理解正在运行的应用，这使持续 6 小时以上的自主 Agent 会话成为可能。

评估并提出建议：

• 可在工作树中启动：应用能否按 Git 工作树启动，使每次 Agent 运行都能获得隔离实例？如果不能，将其列为高优先级差距。
• 浏览器自动化：对于 UI 应用，Agent 能否通过 Chrome DevTools Protocol 操控应用（截图、DOM 快照、导航）？
• 可观测性：Agent 能否从自己的实例查询日志（LogQL）、指标（PromQL）和链路追踪（TraceQL）？
• 临时状态：Agent 的任务完成后，日志、指标和应用状态是否会被清理？

此阶段仅适用于有可运行应用的代码库。库、命令行工具和基础设施代码库可以跳过此阶段。

阶段 7：流程模式

记录让由 harness 驱动的代码库长期保持健康的模式。 将这些内容写入相应的 docs/ 指南文件。

• 文档维护：定期检查过时或不准确的文档
• 垃圾回收：识别并清理模式偏移、重复的辅助工具，或累积的“AI 垃圾”——这项工作刻不容缓，不是可选项。缺少自动化垃圾回收时，Agent 生成的代码库会迅速退化，导致 20% 的工程时间消耗在手动清理上
• Agent 审查：在成熟度达到 3 级及以上时，Agent 对 Agent 的审查应成为主要质量关卡，而非人工审查的补充。人工只审查需要判断的事项（业务逻辑、产品决策、架构方向）。 演进过程：1—2 级时人工审查所有内容 → 3 级时由 Agent 预审，人工抽查 → 4 级时由 Agent 对 Agent 进行审查，人工只处理升级事项。
• 合并理念：PR 生命周期短，优先后续修复，而不是无限期阻塞。 前提条件：只有在已落实自动化强制检查（成熟度达到 2 级及以上）、测试覆盖率能够捕捉回归问题，且 Agent 能生成后续修复时，才适合采用此做法。缺少这些条件时，放宽合并关卡是不负责任的。
• 反馈编码：说明如何将审查评论和缺陷转化为文档更新或规则
• 升级边界：明确哪些决策需要人工判断，哪些可由 Agent 自主解决，避免问题问得过多（导致进度缓慢）或过少（存在风险）

模板请参阅 references/process-patterns.md。

阶段 8：验证

实施后，验证 harness 是否一致：

• AGENTS.md 中引用的每个路径都存在
• docs/ 中的所有交叉链接都能正常解析
• .harness/*.yml 文件的结构有效
• domains.yml 中的领域与实际代码目录相对应
• ARCHITECTURE.md 反映真实的模块结构
• 已为所有已识别领域填写质量评分
• 知识库结构与 knowledge.yml 配置相符

报告检查结果。在标记 harness 为完成之前，先修复问题。

更新流程

更新现有 harness 时：

1. 检测偏移：将 .harness/ 规范与实际代码库进行比较
   • domains.yml 中未列出的新目录/模块
   • 文档引用了已删除或已移动的文件
   • 质量评分早于配置的审查周期
   • 最近新增的代码违反了原则
2. 提出有针对性的更新：不要重建，只更新发生偏移的部分
3. 实施更改：使用相同的阶段结构，但仅针对发生偏移的部分
4. 重新验证：运行完整的验证清单

.harness/ 目录

所有机器可读的 harness 配置都存放在仓库根目录的 .harness/ 中。

.harness/
├── config.yml         # Harness metadata, version, tech stack summary
├── domains.yml        # Business domain definitions + layer rules
├── principles.yml     # Golden principles with rationale + examples
├── enforcement.yml    # Mechanical rules (naming, limits, logging, imports)
├── quality.yml        # Per-domain quality grades + gap tracking
└── knowledge.yml      # Knowledge base structure configuration

完整的架构定义及示例请参阅 references/yml-schemas.md。

根据技术栈调整

harness 与技术栈无关，但具体实现需相应调整：

• 命名约定：JS/TS 使用 camelCase，Python/Rust 使用 snake_case
• 分层名称：可能有所不同——“repo”也可能是“repository”或“data-access”
• 构建命令：因技术栈而异——在 AGENTS.md 中记录
• 依赖强制检查：不同模块系统的导入风格各不相同
• 日志记录：不同生态系统使用不同的结构化日志库

在评估期间识别技术栈，并据此调整所有模板。 不要将某个生态系统的约定强加给另一个生态系统。