harness-spec-anatomy

Harness Spec 解剖

关于 hedera-harness 配方的唯一事实来源。操作技能 (/create-harness-spec、/review-harness-spec) 会在此查阅术语； 它们负责工作流。请严格使用 GLOSSARY.md 中的粗体术语。

面向 hedera-harness schemaVersion 3。旧版配方加载时会直接失败。 没有 migrate 命令——请改写为 v3，或使用 hedera-harness init 重新生成并重新应用编辑。

这些技能用于编写，不用于生成器运行。 配方不会列出技能。每次运行都会从 hedera-skills（native-services-js、system-contracts、cross-chain、 dev-intelligence）发现产品插件，生成器会选择 PRD 所需的插件。不要将编写技能加入该 集合；它们仍是 Cursor / Claude Code 市场插件。

目录结构

仅有一种目录结构：脚手架应用中的 .harness/（由 hedera-harness init 或 Scaffold HBAR 创建）。工作区就是项目本身。配方文件中的路径相对于项目根目录。

文件	必需？	默认路径	使用方
配方文件	是	.harness/spec.yaml	Harness CLI
PRD	是	.harness/prd.md（或 prd: 列表）	生成器
静态验证器	ASSERT	.harness/validators/static.json	静态验证器
命令验证器	ASSERT	.harness/validators/yarn.json	命令验证器
Playwright 冒烟测试	SMOKE	.harness/validators/playwright-smoke.yaml	Playwright 阶段
评估检查清单	EVALUATE	.harness/eval.json（或 eval: 列表）	EVALUATE 验证器

以上所有路径都是默认值。省略键时，harness 会使用默认值；只有要指定其他位置时才填写键。 产物始终写入 .harness/runs/，此路径不可配置。

交接方式：yarn harness:run 或 hedera-harness run .harness/spec.yaml。

配方文件必须包含的内容

只要求四项：

schemaVersion: 3
name: my-feature
description: What you want the agent to build in this project.

baseline:
  commands:
    - name: install          # required, and used for install fingerprinting
      command: yarn install
    - name: build
      command: yarn next:build

其他所有内容——prd、validators.*、maxAttempts、agent、constraints、 forbiddenFiles、secretScan、requiredFiles——都会采用默认值或自动检测。 未设置这些内容的 v3 配方依然完整且正确。精简内容和完整注释模板见 references/spec-files.md。

baseline 不等于 validators.commands。 baseline 用于证明项目在生成 之前运行正常；validators.commands 则在生成之后进行评估。baseline 中必须有名为 install 的命令。

值得了解的默认值

键	默认值
agent	claude——除非用户需要 cursor，否则省略
prd	.harness/prd.md；列表会按顺序提供增量
eval	不存在（关闭 EVALUATE）。单个值会评估每个切片；列表必须与 prd: 一一对应
maxAttempts	3
constraints.packageManager	根据 package.json / lockfiles 检测
constraints.forbiddenCommands	除当前使用的包管理器以外的所有包管理器
forbiddenFiles / secretScan	.env，以及每个工作区各一个
requiredFiles	空——验证器才是门槛

未知键会被忽略并显示警告，因此拼写错误会导致效果降级而非崩溃。请将此类警告视为一项发现。

阶段

按顺序启用。默认仅启用 ASSERT，因此首次运行成本较低。

阶段	配方文件字段	检查内容
ASSERT	validators.static、validators.commands、requiredFiles、forbiddenFiles、secretScan	文件、JSON/文本、密钥、安装/代码检查/构建
SMOKE	validators.playwright	开发服务器启动；路由 HTTP 正常；控制台 / 禁止文本
EVALUATE	eval + validator.enabled: true	Agent 对编号断言进行评分，断言位于评估检查清单中
CHAIN	chainValidation（+ EVALUATE）	临时 ECDSA 测试签名器；真实交易；mirror 验证

完整启用顺序、主机前置条件和 YAML 代码块： references/stage-strategy.md。

跨文件一致性

v3 默认设置移除了大部分路径级耦合。仍须保持一致的内容：

保持同步	原因
Evaluate 检查清单 routes ↔ Playwright routes ↔ PRD 交付内容中的路由	验证器会检查 PRD 承诺的内容
每个 PRD 用户旅程 ↔ 对应检查清单中的 ≥ 1 条断言	未经验证的用户旅程会悄然通过
每条断言 ↔ 一个 PRD 用户旅程	孤立断言会导致范围蔓延
prd: 列表 ↔ eval: 列表（两者均为列表时）	必须一一对应；每次增量仅 vendoring 活动的一对
forbiddenFiles ↔ 静态 fileAssertions.forbidden	两道关卡，一个目的
constraints.packageManager ↔ 对 package.json 的静态断言	仅在覆盖检测到的值时需要
eval ↔ validator.enabled: true	单独配置其中任何一项都会导致配方配置错误
断言 executableWithTestSigner ↔ chainValidation.enabled	若未启用 CHAIN，标记的断言不会生效

templateMetadata.name 是宿主模板标识，可以与 name 中的功能 slug 不同。这不算问题。

Blind / evaluate 检查清单规则

保持运行盲测。PRD 包含用户旅程和结果；带编号的断言放在 evaluate 检查清单中。参见 GLOSSARY.md 和 references/prd-and-journeys.md。

对变更敏感的加载器字段

当 harness 重命名这些字段时，请在同一个变更集中更新此技能及其 eval：

schemaVersion、agent、baseline、prd、eval、validators.static、 validators.commands、validators.playwright、validator、 chainValidation、constraints、templateMetadata、requiredFiles、 forbiddenFiles、secretScan、executableWithTestSigner、maxAttempts。

已移除 — 加载时若存在会直接失败：contract、extend、logging、 skills、seed、generator。

机械检查

bash <path-to>/harness-spec-anatomy/scripts/check-spec.sh <project-root>

请根据已安装技能的位置解析脚本路径。该脚本会运行 hedera-harness doctor --recipe-only，检查架构和加载器有效性，然后补充 doctor 不会执行的跨文件一致性检查。退出码为零表示配置无误；非零时每行输出一项问题。

如果无法使用 harness CLI，脚本仍会运行一致性检查并说明情况——请将其视为部分结果，而非通过。

附加资源

• GLOSSARY.md
• references/spec-files.md
• references/prd-and-journeys.md
• references/eval-checklist-guide.md
• references/stage-strategy.md
• scripts/check-spec.sh
• 上游：docs/authoring-a-recipe.md