HARNESS.md

HARNESS.md 格式规范

版本：1.0.0（本规范自身的版本号采用语义化版本）

HARNESS.md 是用于表示、存储和交换软件工程中 Agent harness 设计的文档格式。 它的核心作用是记录编码 Agent 在特定项目中如何运行、获取什么知识、调用哪些工具、 通过什么方式验证工作成果、受哪些确定性检查保护，以及在什么权限边界内自主行动。 本规范定义该文件的语法结构、元数据字段、推荐正文词汇表与格式校验契约。 本文是英文规范 spec.md 的中文表述； 两者在细节表述上若存在歧义，以英文规范为准。

1. 背景、定义与定位

在实际软件工程中，编码 Agent 具备读写文件和执行命令的基础能力， 并不意味着它能够直接、安全、高质量地承担具体项目中的开发任务。 一个 Agent 要在工程环境里独立完成工作，首先需要理解项目所处的客观条件与边界， 进而依赖一套相互配合的外部机制来获取上下文、调用工具、观察系统反馈、 拦截缺陷并遵守协作规范。

这些支撑条件中， 有相当一部分无法由 Agent 仅凭源代码分析或模型自带的通用知识可靠推断。 例如，团队的人工审查带宽、组织内部的分支与发布约定、 非公开的内部 API 与架构文档、故障发生后的业务代价、项目的预期维护周期， 以及团队在长期演进中形成的特定工程取舍。 如果缺乏明确的设计记录，Agent 要么在关键边界上反复试探甚至越权操作， 要么因缺乏足够信息而频繁中断任务请求人工介入。

围绕编码 Agent 建立的这套运行环境、信息渠道、验证手段与权限边界的集合， 称为 Agent harness（简称 harness）。 在具体仓库中，一个 harness 的实现通常分散在多个位置： 入口文件（如 AGENTS.md 或客户端专用指令文件）、领域知识文档、脚本与任务入口、 MCP 服务器或工具注册配置、凭证与沙箱策略、Git Hook、自动化测试以及 CI 流水线。 这些产物负责让 harness 实际运转， 但它们本身往往只体现“怎么做”的最终命令与配置， 而不记录“为什么这样设计”的前提与权衡。 同时，具体产物不可避免地会混入原项目的历史偶然性、脚本习惯和特定平台限制； 如果直接将某个仓库的配置文件原样复制到另一个项目， 极易把不匹配的依赖、过时的规则和无关的工程复杂度一并带入新环境。

HARNESS.md 旨在解决设计意图与具体实现分离的问题。 它对 Agent harness 所起的作用， 类似于 DESIGN.md 或架构设计文档对软件系统所起的作用： 以结构化元数据与自然语言正文承载 harness 的设计决定、适用前提、 取舍理由与预期机制。通过将设计抽象为独立于具体运行时配置的文件格式， HARNESS.md 成为一种可存储、可版本化、可跨项目交换的设计表示。 正如通用数据交换格式允许不同系统在不共享内部实现的前提下传递数据， HARNESS.md 允许不同团队和项目间传递 harness 设计， 并由接收方的人或 Agent 根据目标项目的实际技术栈与约束重新实现。

在项目文档体系中，不同文件面向各自的受众与使用时机，彼此互补而非替代：

  • README.md：主要面向人类开发者与使用者， 介绍项目功能、快速上手方式与日常开发流程。

  • AGENTS.md 或同类入口文件：主要面向正在仓库中执行日常编码任务的 Agent， 提供每次任务都需要加载的即时指令、常用命令和知识索引。

  • Skill、MCP 与客户端配置：属于具体的能力扩展或运行时控制手段， 用于在特定触发条件下向 Agent 注入操作步骤、工具接口或权限限制， 不适合用来长篇存放跨层级的整体设计理由。

  • HARNESS.md： 主要面向构建、迁移、审查和改进 Agent harness 的人或 Agent， 用于保存整体设计意图、背景假设与各机制之间的因果关系。

本规范仅定义 HARNESS.md 作为文档格式的最低结构、元数据契约、 推荐章节词汇与机械校验规则。本规范不规定“优秀的 harness 必须包含哪些组件”， 不强制任何工程技术选型，也不替代具体的 harness 设计方法论。

2. 格式目标与设计原则

本格式规范的核心目标只有一条：编写一份规范的 HARNESS.md 可以借助本规范； 但读懂一份 HARNESS.md，不应依赖本规范， 也不应依赖任何特定的 Skill、MCP、客户端或解析工具。

作者（无论是人类工程师还是编码 Agent）遵循本规范编写文档， 能够产出结构可预期、元数据一致的文件，便于工具检索、归档与校验。 而读者（无论是接手项目的开发者还是另一个环境中的 Agent）即使从未接触过本规范， 只要具备阅读普通 Markdown 技术文档的能力， 就能直接理解文件所描述的 harness 设计，并据此开展构建、评估或改造工作。

围绕这一核心目标，本格式确立了以下四项设计原则：

  1. 轻量约束。 规范仅对文件的外层结构、 五个顶层元数据字段以及标题的基础识别规则作出定义。 轻量是指规范本身的机械约束极少，而不是限制文档篇幅； 为了把设计交代清楚，文件正文可以写成任意长度。

  2. 正文自由。 harness 的设计内容全部采用自然语言在 Markdown 正文中书写。 规范不设任何必选的正文章节，不规定正文必须填写的表单项， 也不限制文档作者根据项目需要自由增加、删减或组合额外章节。

  3. 自解释性。 文件中的元数据键名、推荐章节标题以及正文中的设计叙述， 都应当依靠常识与上下文即可读懂。 文档作者应在正文中把特定术语、背景条件和设计理由解释清楚， 使读者无需翻阅外部格式手册即可理解设计全貌。

  4. 实现中立与可移植。 HARNESS.md 记录的是预期达成的工程机制与行为边界， 而非绑定某一款特定 Agent 客户端的私有配置语法。 即使文档中提到了具体的客户端、模型或脚本工具， 其重点也在于说明它们在整体设计中承担的角色与原因， 从而支持其他 Agent 在不同工具链或宿主环境中等价地重新实现该设计。

为了在保持正文自由的同时提升跨项目交流的效率， 本规范在第 5 章提供了一套推荐的二级章节词汇表及排列顺序。 这套词汇表并非封闭的语义分类体系，也不是衡量设计是否合格的核对清单， 而是一组共享的章节路标。 当不同文档使用相同的英文标题 （如 Context、Environment、Gates、Authority）来组织相近主题时， 人类读者和编码 Agent 都能更快地在长文档中定位关注的信息。 同时，推荐顺序按照从整体背景与约束、到代码与结构要求、 再到运行机制与长期演进的语义依赖关系排列， 使前文交代的前提能够自然支撑后文的具体设计。

正因为共享词汇表服务于可读性与可预期性，而非机器强制执行， 本规范严格区分了“格式符合性错误（Error）”与“建议性警告（Warning）”。 违反基础语法或元数据契约会导致格式不符合； 而偏离推荐标题结构或命名习惯仅会产生警告，用于提醒作者检查是否有意为之， 绝不会因此将一份内容合理的 HARNESS.md 判定为非法文件。

3. 使用方式与生命周期

在实际工程生命周期中， HARNESS.md 会经历创建、传递、展开实现、留存备查、漂移检查与迭代修订等阶段。 项目团队可以根据自身需求决定如何使用和处置这份文件， 本格式对不同的使用方式保持中立，不会在语法上偏向某一种模式。 最常见的两种基础用法是将其作为模板或作为锚定文档。

无论是哪种模式，在日常业务编码、修复缺陷或编写常规测试时， Agent 都不需要自动加载 HARNESS.md。它不是日常任务的入口文件。 通常只有在以下三类场景下，人或 Agent 才需要按需打开并阅读这份文件：

  1. 初次构建或重装 harness： 根据文档描述从头生成或补齐仓库中的各项配置、文档与脚本产物。

  2. 检查 harness 漂移：当项目经历多轮演进后， 核对仓库现有的入口文件、脚本、权限设置和门禁是否偏离了最初的设计意图， 或者是否存在设计要求了却从未落地的机制。

  3. 有意改进 harness： 当工程条件变化（如引入新工具、调整自治边界、发现反复出现的协作缺陷）时， 先评估并修订 HARNESS.md 中的设计，再同步更新仓库中的实现产物。

3.1 作为模板使用

当一个新项目启动，或现有项目首次引入编码 Agent 时， 团队可以从公共设计仓库（Hub）或组织内部的其他工程中获取一份现成的 HARNESS.md， 将其放入目标项目的根目录。 随后，开发者向编码 Agent 提供目标项目的具体业务背景与技术栈信息， 由 Agent 读取这份 HARNESS.md，理解其中阐述的设计结构与防护思路， 并将其转化为当前仓库的实际产物 （例如生成 AGENTS.md、配置检查脚本、设置权限规则与 CI 门禁）。 当整套 harness 构建完毕并验证可用后，如果团队不需要在仓库内长期维护设计文档， 可以将这份 HARNESS.md 删除。

3.2 作为锚定文档使用

第二种方式是将 HARNESS.md 长期保留在代码仓库根目录中， 作为项目 harness 设计的权威依据。在这种模式下， 文件平时像一份工程章程一样保持稳定，不随日常业务功能开发而频繁改动。

3.3 上下文成本与篇幅权衡

本格式不对 HARNESS.md 的文件长度或章节字数设置任何上限。 这一设计与文件的按需加载特性直接相关： 入口文件（如 AGENTS.md）在每个日常任务启动时都会被读入上下文， Skill 在每次触发时都会占用上下文窗口，因此它们必须高度精炼， 避免用冗长的背景论述挤占日常工作空间。 相比之下，HARNESS.md 在未被打开时不消耗任何上下文容量。

但这并不意味着按需读取没有成本。当 Agent 执行构建、审查或重构 harness 的任务时， 一旦打开 HARNESS.md， 其全部内容依然会占用当次任务的上下文窗口并影响信息检索效率。 不设格式长度上限，是为了允许作者把必要的工程前提、取舍原因和边界条件写透—— 适度增加清晰的因果说明，能够显著减少构建和演进过程中的错误揣测与返工。 良好的 HARNESS.md 应当追求信息密度与结构清晰度， 写到读者单凭这一份文件并结合项目代码就能理解并建出期望的 harness 为止， 而非堆砌无关的铺垫。

3.4 权威边界：以谁为准

当 HARNESS.md 作为锚定文档留在仓库中时， 它与项目代码及配置文件之间存在明确的职责与权威边界：

  • 设计意图以 HARNESS.md 为准。 仓库中用于实现 harness 的入口文件、知识文档、Hook、 脚本和门禁配置都是这份设计的产物。 当这些产物所表现出的结构或规则与 HARNESS.md 的记载不一致时， 说明系统发生了设计漂移：要么应当修复产物使其重新符合 HARNESS.md， 要么在确认新做法更合理后正式修订 HARNESS.md。

  • 系统状态以代码和实际配置为准。 一条命令当前究竟执行什么动作、某个目录或文件在仓库里是否真实存在、 CI 流水线此刻实际运行了哪些检查，只能由代码库、脚本和配置文件的当前状态回答。 任何人或 Agent 都不得在未核实仓库实况的前提下， 把 HARNESS.md 中的设计描述直接当作系统当前已经生效的运行时事实。

4. 文件格式与元数据

为了使一份设计文档既能被人类和 Agent 直接当作普通文本阅读， 又能被索引工具、代码仓库平台和设计 Hub 可靠地识别与分发， HARNESS.md 采用与 Agent Skills 规范中 SKILL.md 相同的双部分结构：

  1. YAML frontmatter：位于文件开头， 仅用于存放文件自身的身份标识与基础元数据。

  2. Markdown 正文：紧接在 frontmatter 之后， 用于承载全部具体的 harness 设计内容。

4.1 基础文件语法与存放位置

HARNESS.md 必须是 UTF-8 编码的纯文本文件。 YAML frontmatter 必须从文件的第一行开始； 起始分隔行与结束分隔行均为独立一行的三个连字符（---）。 在两个分隔行之间的内容必须解析为一个合法的 YAML 映射（键值对集合）。 结束分隔行之后的全部文本均属于 Markdown 正文。 校验器必须接受下列无害的差异：文件开头的 UTF-8 BOM， 分隔行行尾的空格和制表符，以及 CRLF 换行。 但编写文件时推荐使用不带 BOM 的 UTF-8 编码和干净的 --- 分隔行。

当 HARNESS.md 用于具体软件工程项目时，文件应当放置在仓库根目录下， 文件名固定为 HARNESS.md。 当一份设计作为独立的可复用条目存放在设计仓库（如公共或内部 Hub）中时， 它依然是完全相同的 HARNESS.md 格式文件，只是不依附于某个具体业务代码库； 其存放目录结构由所在平台自行组织。

4.2 Frontmatter 字段定义

frontmatter 的唯一职责是说明“这份设计文档是什么”， 不得用来承载关于目标项目或 harness 机制的具体设计陈述。 凡是涉及项目约束、环境工具、权限边界或工作流规则的内容， 都必须写在 Markdown 正文中。

本格式仅定义以下五个 frontmatter 顶层字段：

字段 必填 类型与取值要求 含义说明 格式层面的校验结果
name 是 非空字符串；推荐仅用 ASCII 小写字母、数字和不连续的连字符 这份 harness 设计的短名称（标识符） 缺失、为空或非字符串：Error；违反长度或字符命名规则：Warning
description 是 非空字符串；推荐不超过 1024 个字符 简要说明这份设计是什么，以及适合什么样的项目 缺失、为空或非字符串：Error；超过 1024 个字符：Warning
version 否 字符串；写法不受约束 这份设计自身的版本；写法和含义由作者决定，本格式不解释、不比较 存在但非字符串：Error
license 否 字符串 声明这份 HARNESS.md 文件本身的许可证名称，或指向随文件附带的许可证文件 存在但非字符串：Error
metadata 否 任意 YAML 数据结构 供特定平台、工具或组织使用的扩展附加信息 本格式不检查其内部结构与内容

上述字段中， license 和 metadata 直接沿用了 Agent Skills 规范里的同名字段设计， 以便于跨生态工具的复用。需要注意的是， license 描述的是这份 HARNESS.md 设计文档自身的许可条款， 未必等同于其所在软件项目的源代码许可证。

4.3 字段约束与扩展空间规则

各顶层字段的具体规则如下：

  • 必填与类型约束：name 和 description 是必填字段， 其值必须为非空字符串（仅包含空白字符的字符串视为空）。 version 和 license 为可选字段；一旦在文件中出现，其值必须为字符串类型。 违反上述必填或基础类型要求均属于格式错误（Error）。

  • 命名与长度的软性约束： 对 name 和 description 的格式限制借鉴自 Agent Skills 规范， 但在本格式中仅作为建议性约束（违反时给出 Warning，不算 Error）。 具体而言，name 的长度不应超过 64 个字符， 且应仅由 ASCII 小写字母（a-z）、数字（0-9）和连字符（-）组成， 不得以连字符开头或结尾，也不得包含连续的两个连字符（--）。 description 的长度不应超过 1024 个字符。 字符数按 Unicode 码点计。

  • 封闭的顶层键空间： frontmatter 仅允许出现上表列出的五个顶层键 （name、description、version、license、metadata）。 出现任何本规范未定义的其他顶层键均算作格式错误（Error）； 同一个顶层键在 frontmatter 中重复出现也算作格式错误（Error）。

  • metadata 的完全免检原则：如果作者或平台需要记录本规范未定义的附加属性， 必须将其放入 metadata 字段内部。 metadata 可以是映射、列表或标量等任意合法的 YAML 结构。 本格式既不定义也不约束 metadata 内部的键名与取值； 格式校验工具与通用读取工具应当完全忽略其内部内容——不读取其业务语义、 不执行结构校验、也不在格式层面对其进行比较。 哪个外部平台在 metadata 里约定了扩展键， 就由该平台自己在入库或发布环节负责检查。 例如，官方 Hub 可以约定在 metadata 中使用 tags 和 based-on 来标记分类与衍生关系；那属于 Hub 的平台规范， 与一份文件是否符合 HARNESS.md 格式规范无关。

5. 正文组织与推荐词汇表

HARNESS.md 的 Markdown 正文用于完整阐述项目的 harness 设计。 本格式对正文结构的基本原则是：正文完全自由，没有任何必选章节。

作者可以根据项目的实际复杂度、风险特征和表达习惯，自由决定正文的组织方式。 为了帮助作者起草文档， 并让不同背景的人类读者与编码 Agent 能够快速建立对文档结构的预期， 本规范提供了一套文档主标题约定和十三个推荐二级章节构成的共享词汇表。

5.1 文档主标题（H1）与总体导言

推荐在 Markdown 正文的开头使用一个一级 ATX 标题（例如 # 项目或 Harness 名称） 作为整篇文档的主标题。该一级标题的文字可以自由编写， 不要求与 frontmatter 中的 name 字段保持一致。 如果正文中没有任何一级标题，或者出现了多个一级标题， 校验器会给出警告（Warning），但这不影响文件的格式符合性。

在一级标题之后、第一个二级标题之前，推荐直接用自然语言段落编写总体导言。 这段导言承担整体概述的作用，通常用来交代： 这套 harness 为谁服务、核心要达成什么工程目标、明确不打算纳入管理的内容是什么， 以及哪些关键决策始终保留给人类完成。 本规范不强制要求导言段落存在，不规定其字数或格式， 校验器也不会对导言的有无或具体内容进行任何检查。

5.2 推荐二级章节词汇表

在总体导言之后，本规范定义以下十三个推荐的二级章节标题（H2）及其推荐排列顺序。 下表列出了每个推荐标题的准确英文名称及其通常可用于表达的设计内容提示：

推荐顺序 推荐二级标题（区分大小写） 章节语义提示（非强制填写内容要求）
1 Context 影响设计决定的项目客观事实、外部条件、业务风险、维护周期与协作前提
2 Invariants 期望跨任务始终维持的全局设计约束与不可突破的底线规则
3 Style 为便于 Agent 理解、修改和验证而确立的代码结构取向与工程风格偏好
4 File Structure 设计期望仓库具备的目录与关键文件布局，以及各路径所承担的职责
5 Environment Agent 所在的运行环境、可调用的工具/脚本/MCP，以及实际能够触及的系统范围
6 Knowledge Agent 在日常工作中需要查阅的项目知识、内部文档来源及其读取时机
7 Feedback Agent 通过运行什么命令、观察什么输出或状态来检验自身改动的正确性
8 Gates 在提交、合并或发布等环节以确定性方式自动拦截缺陷的门禁与检查机制
9 Authority 哪些操作 Agent 可以自主执行，哪些动作必须请求人类确认或由人类亲自完成
10 Completion 任务动手前如何对齐目标，以及满足什么条件才算一项工作真正完成并可交付
11 Entropy 在长期演进中如何识别并修复 harness 产物、文档与代码实现之间的偏差
12 Open Questions 当前设计中尚未定论、留待后续实践检验或团队裁决的事项
13 References 作者在制定本 HARNESS.md 设计时所参考或依据的外部资料与出处

上述顺序遵循从宏观前提到微观机制、再到生命周期演进的逻辑主线： 首先交代设计所处的客观背景（Context）以及对代码库本身的总体要求 （Invariants、Style、File Structure）； 随后依次展开支撑 Agent 自主工作的核心运行条件与控制机制 （Environment、Knowledge、Feedback、Gates、Authority）； 接着说明单次任务的收束标准与长期维护机制（Completion、Entropy）； 最后以未决问题与参考资料（Open Questions、References）收尾。 这种排列顺应了概念之间的前后依赖关系——例如， 只有先明确了项目的风险背景（Context）以及 Agent 所处的环境与可触及范围 （Environment），才能合理界定应当赋予它多大程度的自主行动权（Authority）。 但这一顺序旨在提供可预期的阅读与生成体验，并非规定 Agent 执行任务时的机械步骤。

5.3 章节识别、可选性与扩展规则

校验器与工具在识别正文章节时，遵循以下明确规则：

  • 精确匹配英文二级 ATX 标题： 推荐章节仅通过二级 ATX 标题（如 ## Context）进行识别， 且标题文本必须与 5.2 节表格中的英文名称完全一致（区分大小写）； 语法细则见 7.4 节。 虽然 HARNESS.md 的正文段落可以使用中文或任何其他自然语言书写， 但为了保证跨语言工具与不同 Agent 对章节骨架的一致识别， 建议二级标题本身保持英文、不翻译。

  • 非匹配标题视为普通自由内容： 如果文档将某个词条写成了三级标题（如 ### Context）、改变了拼写或大小写 （如 ## context）、翻译成了其他语言（如 ## 背景）， 或者该标题出现在围栏代码块（fenced code block）内部， 校验器均不会将其识别为对应的推荐二级章节。 它们只会被视为普通的自由正文或自定义标题，不参与推荐词汇表的顺序或重复检查。

  • 全部可选，按需采用：表中的十三个推荐章节全部是可选的。 文档作者只需挑选对当前设计有实际表达价值的章节撰写； 未采用的推荐章节直接省略即可，校验器对此不产生任何错误或警告。

  • 允许任意额外章节： 作者可以在正文的任意位置（包括推荐章节之间、之前或之后） 添加任意数量的自定义二级标题或更低层级的子标题，以表达项目特有的设计内容。

  • 顺序与重复的警告机制： 如果文档中实际采用的推荐二级章节没有按照 5.2 节表格中的相对先后顺序排列 （例如将 Authority 写在了 Environment 之前）， 或者同一个推荐二级章节在文档中出现了不止一次，校验器会发出警告（Warning）， 但这同样不破坏文件的格式符合性。

推荐词汇表不是一份待填表单。读者和 Agent 在阅读 HARNESS.md 时， 必须基于正文实际写出的自然语言内容来理解设计， 绝不能将推荐章节当作功能开关清单——不能仅仅因为文档没有写出某个推荐标题 （如没有单列 ## Gates 或 ## Entropy）， 就直接推断该项目禁止使用门禁或完全不关心长期维护； 相关设计意图完全可能已经融合在导言、其他推荐章节或自定义章节的叙述之中。

6. 自由正文中的设计信息表达

由于 HARNESS.md 的正文是自由文本且不设强制章节， 格式校验器不会替作者检查正文写得是否充实、逻辑是否自洽。 为了让一份 HARNESS.md 真正具备跨环境传递、指导构建和支撑长期维护的价值， 文档作者需要在自然语言叙述中有效地组织设计信息。本章阐述自由正文的信息表达原则； 这些原则是面向作者与读者的沟通指南， 不构成任何新的机器校验规则或必填字段契约。

6.1 携带因果上下文：决定、理由、前提与体现

一份可迁移、可维护的 harness 设计，其核心价值不在于罗列零散的命令， 而在于讲清楚设计背后的因果链条。无论是采用推荐章节还是自定义段落， 良好的设计叙述通常能让读者看清四个层面的关联： 作出了什么决定、为什么要这样做、这一决定依赖什么前提条件， 以及它预计通过怎样的机制或产物体现出来。

交代“为什么”和“依赖什么前提”，是支持设计跨项目演进的关键。 工程中的许多约束、组织内部的私域知识以及团队偏好的代码风格， 之所以需要写进 HARNESS.md，正是因为它们构成了具体机制的决策前提。例如：

  • 因为某个核心模块由外部合规团队共同维护且变更事故代价极高（前提）， 所以设计上要求所有涉及该目录的修改都必须通过专门的静态检查， 且禁止 Agent 直接合并分支（决定与机制）；

  • 因为项目只是一个预计存活两个月的内部原型，且全程有工程师实时结对监督（前提）， 所以设计上决定不配置复杂的预提交门禁与自动化回归套件， 仅依赖轻量级单测反馈（决定与理由）。

在写作时，作者既可以把全局性的客观条件集中写在 Context 一节中， 也可以在阐述具体机制（如 Gates 或 Authority）时就地说明其依赖的背景原因， 无需为了形式整齐而把同一事实在多个章节间机械重复， 更不必把各种背景维度当成必须在 Context 中逐项填满的固定表格。 只有当读者看懂了某项规则所依赖的前提，在将来项目条件变化或将设计迁移到新仓库时， 才能准确判断哪些设计需要保留、哪些应当调整或舍弃。

6.2 区分设计意图与偶然实现细节

在描述 harness 的各个机制时， 作者应当有意识地区分“架构层面的设计意图”与“当前环境下的偶然实现”。

当一份设计旨在跨项目复用或长期指导演进时， 说明“为什么需要某类知识入口、反馈手段或权限边界”， 通常比直接粘贴某一段特定语言的脚本代码更具可移植性。 例如， 说明“Agent 应当能够通过单一且幂等的命令在本地快速验证改动是否破坏现有契约”， 比仅仅写下一行特定框架的参数调用更能帮助接收方 Agent 在新环境中重建等价机制。

另一方面，保持实现中立并不意味着正文只能写抽象原则。 如果某些具体的目录路径、入口文件名、命令行接口、 工具名称或模型客户端特性本身就是该设计明确要求的目标状态， 作者完全可以在正文中写得具体而微。 关键在于让读者明白哪些具体细节是设计有意锁定的契约， 哪些只是为了说明意图而举出的当前实现方式。 当仓库的不同局部采取不同做法时（例如主应用目录要求严格的确定性门禁， 而 experiments/ 实验目录允许放宽检查）， 直接在相应机制的段落中说明这种局部差异及其理由即可。

6.3 词汇表的协同理解与边界弹性

推荐词汇表中的各个标题代表观察同一个 harness 的不同视角， 而不是彼此绝缘、非此即彼的分类格子。 在实际工程中，环境能力、知识读取、观察反馈、确定性门禁与行动授权往往紧密交织， 共同支撑起 Agent 的工作循环。

例如，同一个命令行工具或测试脚本， 既作为可用能力存在于运行环境中（Environment）， 又是 Agent 修改代码后用来观察行为是否符合预期的自检手段（Feedback）， 同时还可能被配置在提交流程里作为拦截缺陷的强制检查（Gates）， 而 Agent 能否带特定参数执行它则涉及权限边界（Authority）。 在组织正文时，作者应当以人类和 Agent 读起来最自然、最易懂为准： 可以把一个工具的存在与用途写在 Environment， 而在 Authority 和 Feedback 中直接引用它； 也可以在某一个核心章节里把紧密关联的机制一并讲透， 不必为了迎合标题分类而把完整的逻辑拆得支离破碎。

在日常写作与阅读中，以下几组常见概念的区分有助于保持条理清晰， 但它们同样属于辅助理解的经验提示，而非排他性的格式禁令：

  • 工具能力与使用授权： 在介绍工具 （包括注册到客户端的 MCP 服务器、预装的平台 CLI、项目自带的任务脚本等）时， 说明“环境里提供了哪些工具、它们能触及什么外部系统或凭证、 以及有意不提供什么工具”，通常属于对运行环境（Environment）的刻画； 而规定“Agent 在什么条件下可以不经询问直接调用它们执行有副作用的动作、 什么时候必须停下来由人决定”，则侧重于行动权限（Authority）； 至于“如何利用这些工具启动、驱动并观察正在开发的系统”， 则服务于工作验证（Feedback）。

  • Knowledge 与 References：两者都会提及文档或外部资料，但服务对象不同。 Knowledge 描述的是 Agent 在项目里执行日常开发任务时需要查阅的信息源 （如入口文件、架构说明、API 手册及查阅时机）； 而 References 列出的是作者在编写这份 HARNESS.md 设计文档时 所参考的外部文章、标准或上游设计出处，相当于论文末尾的参考文献， Agent 在日常编码工作中通常不需要去读取它们。

  • File Structure 与实际目录状态： File Structure 无论是用目录树、表格还是文字描述， 表达的都是这份设计要求仓库应当具备的目标布局与职责划分， 因此它可以包含尚未创建但计划由 Agent 生成的路径； 而仓库当前实际存在哪些文件，则由文件系统本身回答。

6.4 对缺省与未声明事项的审慎解释

由于正文是自由的，任何一份 HARNESS.md 都不可能穷尽工程中的所有细节。 读者与 Agent 在解析和运用设计文档时，应当对缺省内容保持审慎与克制：

  1. 章节缺省不等于机制禁用：如前所述，未出现某个推荐章节， 仅代表作者没有以该标准标题单独成节，不能据此推定设计排斥该类机制。

  2. 未提及的行动不等于默认授权：在安全与权限边界上， 如果文档没有明确说明某项高风险或跨边界操作 （如推送远端主干分支、修改生产配置、访问外部受限服务）允许 Agent 自主执行， Agent 不得因为文档“没写禁止”就将其解释为已获授权， 而应结合项目背景采取保守策略或向人类确认。

  3. 设计充分性由工程审查判断： 一份 HARNESS.md 所描述的反馈回路是否闭环、 门禁的严格程度是否与项目风险相匹配、信息是否足以让 Agent 建出可用的 harness， 属于工程设计质量的范畴。 这些问题应当在创建、迁移或审查 harness 的过程中由人或 Agent 通过实质性评估来发现和补足，而不由文档格式校验器作机械裁定。

7. 符合性与校验

一份 HARNESS.md 文件是否符合本格式规范， 完全由格式校验器是否报告错误（Error）决定： 只要校验器对一份文件没有报告任何 Error，该文件即符合本格式规范。 警告（Warning）用于向作者反馈结构上的建议， 不影响文件的格式符合性。

必须明确区分格式符合性（Format Conformance） 与设计充分性（Design Adequacy）。 通过格式校验仅代表文件满足了本规范定义的文件结构语法、元数据契约与标题识别规则； 至于正文所描述的 harness 设计是否完整、是否适合目标项目、 能否单凭这份文件成功构建出可运转的工程机制，属于设计内容层面的评估， 不在机器格式校验的职责之内。

本节完整列出校验器应当报告的全部事项，以及明确不作检查的范围。

7.1 错误（Error：导致格式不符合）

出现以下任一情况时，校验器必须报告 Error，文件被判定为不符合本格式：

  1. 文件不是合法的 UTF-8 文本：文件内容无法按 UTF-8 解码。 此时校验器只报告这一项，不再检查其余内容。

  2. Frontmatter 块缺失或语法非法：文件未从第一行开始提供 YAML frontmatter， 未提供匹配的结束分隔行（---）， 或者分隔行之间的内容无法解析为合法的 YAML 映射（Mapping）。

  3. 必填字段缺失、为空或类型错误：name 或 description 字段缺失， 其值为 null、空字符串、仅含空白字符的字符串，或者其值不是 YAML 字符串类型。

  4. 可选字符串字段类型错误：文件中提供了 version 或 license 字段， 但其值不是字符串类型（例如写成了数字、布尔值、列表、映射或空值）。

  5. 包含未知顶层键： frontmatter 中出现了除 name、description、version、license、 metadata 之外的任何其他顶层键。

  6. 顶层键重复：frontmatter 中同一个顶层键出现了两次或多次。

7.2 警告（Warning：不影响格式符合性）

出现以下任一情况时，校验器应当报告 Warning，但文件依然符合本格式：

  1. 正文缺少一级标题（H1）： Markdown 正文中没有任何一个被识别为一级 ATX 标题（# ...）的行。

  2. 正文出现多个一级标题（H1）： Markdown 正文中出现了两个或更多个一级 ATX 标题； 建议校验器对每个文件的此类问题汇总报告一次。

  3. 推荐二级章节（H2）重复出现：第 5.2 节定义的十三个推荐二级标题中， 同一个标题在正文中作为二级 ATX 标题出现了不止一次； 建议校验器按重复的章节名称汇总报告，避免同一章节多次刷屏。

  4. 推荐二级章节（H2）顺序不符：正文中实际出现的推荐二级标题， 其相对先后顺序与第 5.2 节表格中定义的顺序不一致。

  5. name 违反命名或长度建议：name 字符串长度超过 64 个字符， 或者包含除 ASCII 小写字母（a-z）、数字（0-9）和连字符（-）之外的字符， 或者以连字符开头、以连字符结尾，或者包含连续的两个连字符（--）。

  6. description 超过建议长度：description 字符串长度超过 1024 个字符。

7.3 不检查与无报告范围

为保证正文的表达自由与平台扩展的独立性， 校验器不得对以下情况报告任何错误或警告：

  • 省略任意或全部推荐二级章节： 正文中未出现第 5.2 节中的某一个、某几个甚至全部十三个推荐二级标题 （本格式无必选正文章节）。

  • H1 标题文字与导言形式：正文 H1 标题的文字与 frontmatter 的 name 不一致， 或者 H1 标题下方没有编写总体导言段落。

  • 自定义与额外的标题结构： 正文中包含推荐词汇表之外的任意二级标题 （包括中文二级标题或其他自定义标题）， 以及任意层级的子标题（H3–H6）。

  • 正文内容的长度与质量：任何章节正文的字数多少、甚至章节下方为空白， 以及正文中自然语言描述的设计是否准确、合理、完整或可执行。

  • metadata 的内部内容： metadata 字段内部的数据结构、键名、取值类型、是否为空， 以及是否满足特定平台（如 Hub）的扩展规则。

  • 具体工程与客户端细节： 正文是否提及特定的 harness 层级、 特定的工具命令或某一款编码 Agent 客户端的配置。

7.4 标题识别的语法边界

校验器在 Markdown 正文中识别一级标题（H1）与推荐二级标题（H2）时， 遵循 CommonMark 关于 ATX 标题的常规语法边界：

  • 围栏代码块（由三个及以上反引号 ` 或波浪号 ~ 构成的 fenced code block） 内部的任何文本行均不视为标题。

  • 标题行允许在开头的 # 或 ## 之前包含至多三个空格的缩进； # 或 ## 之后必须紧跟至少一个空格或制表符（空标题除外）， 并允许在行尾包含符合 CommonMark 规则的可选闭合 # 序列及尾随空白。

  • 提取出二级 ATX 标题的纯文本内容（去除首尾空白及合法的尾随闭合 # 序列）后， 仅当其与第 5.2 节表中的十三个英文名称之一逐字符精确匹配（区分大小写）时， 才被认定为该推荐二级章节。 任何其他级别的标题、Setext 风格底线标题或拼写不完全匹配的二级标题， 均作为普通正文内容处理，不触发推荐章节的顺序或重复检查。