harness-engineering

Harness Engineering

核心原则

仓库就是 harness。Agent 失败意味着 harness 失败。Agent 违反规则时，应修复 harness，而不是 Agent。

支柱	解决的问题
上下文工程	Agent 幻觉、工具使用错误、文档过时
架构约束	越界、静默回归、错误原因不明确
垃圾回收	熵累积、死代码、文档漂移

何时应用

情况	操作
为 AI 开发新建仓库	从第一天起应用全部三个支柱
Agent 反复对工具/API 产生幻觉	支柱 1：在 AGENTS.md 中添加工具声明
Agent 跨越模块边界	支柱 2：添加用于强制边界的结构测试
Agent 生成的代码通过 CI，却违反约定	支柱 2：将约定转化为 lint 规则或结构测试
文档与实现不一致	支柱 1：添加 CI 交叉链接验证
代码库不断增长，Agent 质量下降	支柱 3：安排 GC Agent 清理死代码和未使用的导出
Agent 忽略 AGENTS.md 中的指导	检查：指导是泛泛而谈，还是针对具体失败的经验教训？将其改写为失败记录条目
Agent 生成的代码发生事故后	将失败记录到 AGENTS.md 中，并添加约束以防止问题重现

支柱 1：上下文工程

目标： 让仓库成为 Agent 能够使用、且不会产生幻觉的知识产品。

1.1 将 AGENTS.md 用作失败记录

AGENTS.md 中的每一行都应对应一次真实失败，而非通用最佳实践。

# Pattern
BAD:  "Follow clean code principles"
BAD:  "Use meaningful variable names"
GOOD: "Never import from packages/internal — agent imported shared/db directly on 2025-12-03, broke build"
GOOD: "Always use OrderService.create(), not Order.new — direct instantiation skips validation (incident #247)"

失败记录条目格式：

rule: Never call PaymentGateway directly from controllers
context: Agent bypassed service layer, sent duplicate charges (2025-11-15)
fix: Use PaymentService.charge() which handles idempotency

编写或更新 AGENTS.md 时：

• 如果规则没有引用具体失败或明确约束 → 删除
• 如果规则使用了“应该” → 改写为带有后果说明的“必须”
• 如果规则没有执行机制 → 为其配套一项支柱 2 约束

1.2 工具声明要求

未声明的工具对 Agent 来说并不存在。明确列出可用的工具、命令和脚本。

## Available Tools
- `bin/test` — Run test suite (prefer over raw pytest/rspec)
- `bin/lint` — Run linters with auto-fix
- `bin/db-reset` — Reset dev database
- `make deploy-staging` — Deploy to staging (requires approval)

## DO NOT USE
- `rm -rf` on any directory
- Direct database queries in production
- `curl` to external APIs without going through ApiClient

如果 Agent 使用了此列表中没有的工具 → 若有效，则将其添加到列表中；若有危险，则将其添加到“禁止使用”列表中。

1.3 以文档作为事实来源

RULE: docs/ is canonical truth
ENFORCEMENT: CI validates cross-links between docs/ and source code
MECHANISM:
  - Every public API must have a corresponding docs/ entry
  - CI script checks: for each @api-doc tag in source → matching file in docs/
  - Broken link = CI failure, not warning

过时的文档比没有文档更糟——Agent 会相信自己读到的内容。

1.4 为每项任务隔离可观测性

每项 Agent 任务都应有自己的日志上下文，而不是共用监控流。

PATTERN:
  - Assign task_id to each agent invocation
  - Route logs to task-specific output (file, log group, trace)
  - Post-task: review task log for failures, add to AGENTS.md if new pattern

共用监控会让单个 Agent 的失败淹没在噪声中。

支柱 2：架构约束

目标： 通过确定性的强制机制，让违规变得不可能，或能立即被发现。

2.1 提示型 Linter 错误

失败消息必须包含修复方法，而不只是指出违规。

# BAD linter output
ERROR: Import violation in src/api/handler.ts

# GOOD linter output
ERROR: Import violation in src/api/handler.ts
  ↳ Cannot import from 'packages/db' in 'src/api/'
  ↳ Use 'packages/db-client' instead (facade pattern)
  ↳ See: docs/architecture/data-access.md

Agent 会按字面理解错误消息。提供指导的错误消息能避免 Agent 在下一次尝试时重犯同样的错误。

2.2 结构测试

通过 CI 强制架构边界，而非依靠文档。

# Pseudocode structural tests
test "no cross-boundary imports":
  For each FILE in src/api/**:
    IMPORTS = parse_imports(FILE)
    FORBIDDEN = ["packages/internal", "src/admin", "src/worker"]
    assert IMPORTS intersection FORBIDDEN == empty

test "dependency direction":
  LAYERS = [presentation, application, domain, infrastructure]
  For each LAYER in LAYERS:
    For each IMPORT in LAYER.imports:
      assert IMPORT.layer_index >= LAYER.index  # only import same or lower

test "API contract stability":
  CURRENT = parse_openapi("api/openapi.yml")
  PREVIOUS = parse_openapi("api/openapi.yml", ref="main")
  assert no_breaking_changes(CURRENT, PREVIOUS)

2.3 数值化 CI 门槛

每项检查都必须有明确的通过/失败结果。Agent 看不到建议性警告。

检查类型	门槛实现
测试覆盖率	coverage >= 80%，否则失败
包体积	size <= 250KB，否则失败
Lint 错误	errors == 0，否则失败
类型错误	errors == 0，否则失败
安全漏洞	critical == 0，否则失败

规则： 重要事项就应设为门槛。如果只是警告，Agent 就会忽略。

2.4 依赖分层

明确规定并强制依赖方向。

# .dependency-layers.yml (or equivalent config)
layers:
  - name: presentation
    paths: ["src/ui/**", "src/api/routes/**"]
    can_import: [application, domain]

  - name: application
    paths: ["src/services/**", "src/use-cases/**"]
    can_import: [domain, infrastructure]

  - name: domain
    paths: ["src/models/**", "src/entities/**"]
    can_import: []  # domain has no dependencies

  - name: infrastructure
    paths: ["src/db/**", "src/external/**"]
    can_import: [domain]

如果没有明确的分层，Agent 就会创建循环依赖。

支柱 3：垃圾回收

目标： 主动对抗熵，而不是任由技术债累积。

3.1 后台 GC Agent

定期安排扫描，生成小型且可自动合并的 PR。

GC_TASKS:
  - dead_code: find unused exports, unreachable functions → remove
  - stale_docs: find docs/ entries with no matching source → flag
  - unused_deps: find package.json/Gemfile entries with no imports → remove
  - orphan_tests: find test files with no matching source file → flag
  - config_drift: diff .env.example vs actual config usage → reconcile

FREQUENCY: weekly for active repos, monthly for stable repos
OUTPUT: one small PR per GC task (not one mega-PR)
MERGE: auto-merge if CI passes, otherwise flag for review

3.2 自定义验证工具

构建针对仓库的快速反馈工具，而不是依赖通用 Linter。

PRINCIPLE: fast feedback > comprehensive analysis

Examples:
  - bin/check-api-contracts → validates OpenAPI spec matches routes (5s)
  - bin/check-imports → validates dependency layers (2s)
  - bin/check-docs → validates doc cross-links (3s)

RULE: if a custom check takes > 30s, it's too slow for agent feedback loops

3.3 反馈循环规范

Agent 生成不佳内容时，按以下顺序进行诊断：

1. Check AGENTS.md — is the constraint documented?
   If NO → add it (Pillar 1 fix)
   If YES → is it enforced in CI?

2. Check CI — does a gate catch this failure?
   If NO → add structural test or linter rule (Pillar 2 fix)
   If YES → is the error message teaching?

3. Check error message — does it include remediation?
   If NO → improve the error message (Pillar 2.1 fix)
   If YES → the harness is correct, investigate agent-specific issue

NEVER: Skip to "the agent is broken" without completing steps 1-3

Harness 评估清单

评估现有仓库的 harness 成熟度：

上下文工程

• 仓库根目录存在 AGENTS.md
• AGENTS.md 中的条目针对具体故障，而非泛泛而谈
• 明确列出可用工具和脚本
• 明确列出禁止的操作
• docs/ 与源代码之间的交叉链接由 CI 强制检查

架构约束

• Linter 错误包含修复说明
• 至少有一项结构测试用于强制执行模块边界
• 所有 CI 检查均为明确的通过/失败（不提供建议性警告）
• 依赖方向有文档说明并得到强制执行

垃圾回收

• 按计划清理死代码（而非临时清理）
• 自动检测过时文档
• 存在针对仓库特定不变量的自定义验证工具
• 故障后的诊断遵循 harness 优先顺序（3.3）

评分： 按支柱统计通过项。任一支柱低于 3/5 = harness 存在缺口。

交叉引用

• hierarchical-agents — AGENTS.md 结构、生成流程、JIT 索引
• tdd-workflow — 通过红-绿-重构实现结构测试
• structured-logging — 用于任务级隔离的可观测性模式
• quality-gate 智能体 — CI 门禁执行机制
• references/patterns-catalog.md — 拓扑模板、AGENTS.md 模式、结构测试示例、GC 智能体模板