harness-engineering

Harness 工程

Harness 工程将编码 Agent 反复犯下的错误转化为持久的 仓库产物：

Harness = Instructions + Constraints + Feedback + Memory + Evaluation + Governance

当用户要求以下事项时，使用此技能：

• 让仓库对 GitHub Copilot 或其他编码 Agent 更可靠
• 添加持久的 Agent 指令、仓库规则或护栏
• 防止 AI 编码 Agent 反复犯错
• 记录已知的失败路径以及防止复发的检查
• 为项目规则添加轻量级漂移检查
• 审查、刷新或更新现有的 Agent harness

不要将此技能用于普通的功能实现，除非用户要求 改善仓库的 Agent 运行环境。

核心原则

• 将目标仓库视为事实来源。
• 先检查再编辑。保留现有的技术栈、包管理器、CI、 文档、命名和架构。
• 添加最小可用的 harness。优先更新现有文件，而不是添加 重复的指导。
• 在可行的情况下，通过测试、linter、 类型检查、CI、pre-commit 钩子或漂移脚本让重要规则可强制执行。
• 仅当自动化会变得脆弱或误导时，才使用人工审查点。
• 记录不应复发的高风险失败，并指明能捕获复发的 检查或审查点。
• 不要盲目复制通用模板。让每个产物适应目标仓库中的 真实证据。

发现

在提议或进行 harness 更改之前，检查仓库中现有的 规则和证据。

当以下文件和文件夹存在时，阅读它们：

• README.md
• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/
• .github/workflows/
• CONTRIBUTING.md
• 包清单，例如 package.json、pyproject.toml、go.mod、 Cargo.toml、pom.xml 或 build.gradle
• docs/ 下现有的文档
• scripts/ 下现有的脚本
• 现有的测试和 CI 检查

然后总结：

• 技术栈、包管理器和入口点
• 现有的开发和验证命令
• 当前的 Agent 指令或仓库约定
• 已知的失败、事件、易波动路径或反复出现的审查评论
• 项目规则未得到执行的缺口

采用工作流

遵循以下顺序：

1. 选择适合目标仓库的 harness 表面。
2. 编写针对目标的 Agent 指令。
3. 为高价值规则添加可强制执行的检查。
4. 为高风险或反复出现的失败记录失败记忆。
5. 为可能悄然过时的指导添加漂移检查。
6. 报告采用情况，附上证据、假设和后续事项。

1. 选择 Harness 表面

只选择适合目标仓库的表面：

需求	首选产物
始终开启的 Agent 行为	AGENTS.md 或 .github/copilot-instructions.md
文件范围的指导	.github/instructions/*.instructions.md
反复进行的项目检查	scripts/check_*.py、shell 脚本或包脚本
CI 强制执行	现有的工作流文件或一个小的新工作流
已知失败	docs/failures/*.md
架构或流程决策	docs/decisions/*.md
采用证据	docs/harness/adoption-report.md 或类似文件

如果仓库已经有等效位置，请更新它，而不是 创建一套并行系统。

2. 编写 Agent 指令

Agent 指令应具体且可操作。包括：

• 项目目的和主要归属边界
• 设置、测试、lint、构建和验证命令
• 包管理器和依赖规则
• 安全编辑规则、生成文件规则和禁止路径
• 对更改代码的测试期望
• PR 和提交约定（如果仓库有的话）
• 如何记录新的失败或决策

避免宽泛的个性指导、通用最佳实践以及无法 检查或审查的规则。

3. 添加可强制执行的检查

将高价值的规则转换为检查。良好的 harness 检查应：

• 范围足够窄，以避免误报
• 速度足够快，可在本地和 CI 中运行
• 命名清晰，以便 Agent 在完成前运行它们
• 配有文档，说明它们保护的规则

示例：

Rule: Do not edit generated API clients.
Check: script scans diffs for generated paths and fails with a clear message.

Rule: Every failure memory note names a regression check.
Check: script validates docs/failures/*.md for a "Detection" section.

Rule: Profile docs and templates must stay aligned.
Check: test compares profile README files to expected template files.

4. 记录失败记忆

当失败对用户可见、高风险或可能再次发生时，记录这些失败。 除非已有笔记涵盖相同的根本原因，否则在 docs/failures/ 下新建文件。

推荐结构：

# Short Failure Title

## Summary

What failed, who saw it, and why it matters.

## Root Cause

The technical or process cause. Avoid blame.

## Prevention

Instruction, test, drift check, CI gate, fixture, or manual review point that
prevents or detects recurrence.

## Evidence

Links to issue, PR, test, log, command output, or file paths.

如果没有可行的自动化检查，记录人工审查点，并说明为什么自动化会不安全或具有误导性。

5. 添加漂移检查

对可能悄然过时的指导使用漂移检查。常见示例：

• 文档提及已不存在的命令
• 配置片段与生成的示例出现分歧
• 失败笔记遗漏回归检查
• 结构性变更缺少决策记录
• CI 引用了过时的脚本或包命令

优先使用仓库现有语言编写小型脚本。如果仓库没有脚本约定，仅使用标准库的 Python 是一个可移植的默认选择。

6. 报告采用情况

以采用报告结束实质性的 harness 工作，报告包括：

• 更改的文件
• 添加或更新的规则
• 添加或复用的检查
• 运行的命令及结果
• 假设和人工后续跟进
• 创建或有意跳过的失败记忆
• 将如何衡量有效性

审查工作流

当被要求审查 harness 变更时，采取对立视角。寻找：

• 未经目标仓库证据支持而照搬的通用规则
• 重复或冲突的指令文件
• 可能在有效变更上失败的大范围检查
• 未强制执行的高风险规则
• 对反复出现的错误或运行时失败缺少失败记忆
• 源文件变更后未刷新的生成文档
• 未运行相关检查的 CI 门禁
• 目标仓库约定被 harness 默认值覆盖

首先报告发现，按严重程度排序，并在可用时附上文件和行号引用。除非用户明确要求修复，否则审查期间不要修改文件。

输出契约

在完成 harness 采用工作之前，请核实：

• 编辑前已检查目标仓库
• 新指导特定于目标仓库
• 更改的检查可在本地运行，或有记录在案的人工替代方案
• 在需要时记录了失败记忆，或最终回复说明了跳过的原因
• 生成文档或索引已刷新
• 最终报告列出了运行的每条命令及其结果

可选参考

https://github.com/baskduf/harness-starter-kit 中的提示词优先工作流是这些理念的参考实现。仅在用户要求或仓库已包含它时，将其用作参考材料。目标仓库仍是事实来源。