Back to Details

create-harness-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Harness Spec

创建Harness规格说明

Grill a Hedera feature idea into a complete recipe for hedera-harness.
Load the shared vocabulary first: read 
../harness-spec-anatomy/SKILL.md
 and its GLOSSARY.md. Use those terms exactly.
Targets hedera-harness schemaVersion 3.
These skills are for authoring. Recipes do not list skills — product plugins from 
hedera-skills
are discovered per run and the generator picks. Keep the run blind: the PRD carries journeys and outcomes; numbered assertions live in the evaluate checklist.
Works in Claude Code (marketplace plugin) and Cursor / other agents that load SKILL.md. Prefer 
/grilling
when that skill is installed; otherwise use the inline protocol — Claude Code typically takes the inline path.
将Hedera功能想法梳理打磨成完整的配方，用于hedera-harness。
请先加载通用词汇表：阅读
../harness-spec-anatomy/SKILL.md
及其GLOSSARY.md，严格使用其中的术语。
目标版本为hedera-harness schemaVersion 3。
这些技能用于编写工作。配方中不列出技能——
hedera-skills
中的产品插件会在每次运行时被发现并由生成器选择。请保持运行盲测状态：PRD承载用户旅程和成果；编号断言存放在评估检查清单中。
本技能可在Claude Code（市场插件）以及Cursor/其他加载SKILL.md的Agent中使用。若已安装对应技能，优先使用
/grilling
；否则使用内联协议——Claude Code通常采用内联方式。

Step 1: Locate the target

步骤1：定位目标

A recipe lives at 
.harness/
inside a scaffolded app. There is no other layout.
SituationWhat to do
Cwd is a scaffolded app (Scaffold HBAR or 
hedera-harness init
)		Author into its 
.harness/
Cwd is an app without 
.harness/
hedera-harness init
adopts the harness in place
No app yet
hedera-harness init <dir>
(optionally 
--template <name>
)
Cwd already has 
.harness/spec.yaml
Check 
schemaVersion
. If absent, 
1
, or 
2
, rewrite to v3 (or regenerate with 
init
and reapply edits). 
hedera-harness migrate
is gone.
Never treat a v1/v2 recipe as loadable. 
contract:
→ 
eval:
, drop 
skills:
, set 
schemaVersion: 3
.
Paths in the recipe file are relative to the project root.
配方存放在已搭建应用的
.harness/
目录下，没有其他目录结构。
场景操作方式
Cwd是已搭建的应用（通过Scaffold HBAR或
hedera-harness init
创建）		在其
.harness/
目录中编写
Cwd是没有
.harness/
的应用		执行
hedera-harness init
在当前目录接入harness
还没有应用执行
hedera-harness init <dir>
（可选添加
--template <name>
参数）
Cwd已有
.harness/spec.yaml
检查
schemaVersion
。如果不存在、为1或2，重写为v3版本（或用
init
重新生成后重新应用修改）。
hedera-harness migrate
命令已移除。
切勿将v1/v2版本的配方视为可加载版本。需将
contract:
改为
eval:
，移除
skills:
字段，设置
schemaVersion: 3
。
配方文件中的路径均相对于项目根目录。

Step 2: Grill

步骤2：梳理打磨

Follow references/grilling.md. Prefer 
/grilling
if available; otherwise use the inline protocol there.
Do not write files until the user confirms shared understanding.
遵循references/grilling.md中的说明。若可用，优先使用
/grilling
；否则使用其中的内联协议。
在用户确认双方理解一致前，不要写入任何文件。

Step 3: Emit the recipe

步骤3：生成配方

Prefer copying the shipped skeleton — it is always current:
bash
cp -r "$(npm root -g)/hedera-harness/skeletons/project-harness/." .harness/
Then:
  1. Write 
    .harness/prd.md
    (or one file per increment under 
    .harness/prds/
    ) from the grill. Product-facing only — keep the run blind.
  2. Fill 
    .harness/spec.yaml
    . Required: 
    schemaVersion: 3
    , 
    name
    , 
    description
    , and 
    baseline
    with a command literally named 
    install
    . Leave every default commented out. A four-key recipe is complete. Omit 
    agent:
    unless the user wants Cursor (default is Claude).
  3. Write 
    .harness/validators/static.json
    and 
    .harness/validators/yarn.json
    against the feature deliverables. Do not assert on 
    template.json
    — create-scaffold-hbar removes it when scaffolding.
  4. Do not add a 
    skills:
    list. Mention relevant Hedera services in the PRD so the generator can pick product skills.
  5. Add SMOKE / EVALUATE / CHAIN only if the user opted in during the grill — see 
    harness-spec-anatomy
    → references/stage-strategy.md. If 
    prd:
    is a list and EVALUATE is on, write a matching 
    eval:
    list.
  6. Install the SMOKE host package if you just enabled it — at the project root, not only inside a workspace. Doctor imports 
    playwright
    from next to 
    hedera-harness
    , and Yarn 
    nmHoistingLimits: workspaces
    hides 
    packages/nextjs
    installs.
    • SMOKE → 
      yarn add -D playwright
      (or npm/pnpm equivalent) Skip the add if the root 
      package.json
      already lists it. Do this as part of emit, not as a follow-up after 
      doctor
      fails. CHAIN does not need a project install: 
      @hiero-ledger/sdk
      ships with 
      hedera-harness
      . Only the operator env vars are host-provided.
Reconstruct bodies by hand only when the skeleton is unavailable: 
harness-spec-anatomy
→ references/spec-files.md.
优先复制随附的骨架模板——它始终是最新版本：
bash
cp -r "$(npm root -g)/hedera-harness/skeletons/project-harness/." .harness/
随后执行以下操作：
  1. 根据梳理结果编写
    .harness/prd.md
    （或在
    .harness/prds/
    目录下为每个增量编写单独的文件）。仅面向产品视角——保持运行盲测状态。
  2. 填写
    .harness/spec.yaml
    。必填项：
    schemaVersion: 3
    、
    name
    、
    description
    ，以及包含字面名为
    install
    命令的
    baseline
    字段。所有默认配置请保持注释状态。 包含四个键的配方即为完整配方。除非用户指定使用Cursor，否则省略
    agent:
    字段（默认使用Claude）。
  3. 针对功能交付物编写
    .harness/validators/static.json
    和
    .harness/validators/yarn.json
    。不要对
    template.json
    做断言——create-scaffold-hbar在搭建项目时会移除该文件。
  4. 不要添加
    skills:
    列表。请在PRD中提及相关的Hedera服务，以便生成器选择对应的产品技能。
  5. 仅当用户在梳理过程中明确选择时，才添加SMOKE / EVALUATE / CHAIN阶段——参见
    harness-spec-anatomy
    → references/stage-strategy.md。如果
    prd:
    是列表且启用了EVALUATE，则编写对应的
    eval:
    列表。
  6. 如果刚启用了SMOKE阶段，请安装其宿主包——需在项目根目录安装，而不仅仅是在工作区内安装。doctor命令会从
    hedera-harness
    的同级目录导入
    playwright
    ，而Yarn的
    nmHoistingLimits: workspaces
    配置会隐藏
    packages/nextjs
    中的安装包。
    • SMOKE → 
      yarn add -D playwright
      （或npm/pnpm的等效命令） 如果根目录的
      package.json
      中已列出该包，则跳过安装。此步骤需作为生成配方的一部分执行，不要等到
      doctor
      运行失败后再补充。 CHAIN阶段不需要在项目中安装依赖：
      @hiero-ledger/sdk
      已随
      hedera-harness
      一同发布。仅需宿主提供操作员环境变量。
仅当无法获取骨架模板时，才手动构建文件内容：参考
harness-spec-anatomy
→ references/spec-files.md。

Step 4: Completion criterion

步骤4：完成标准

Two checks, in order:
bash
undefined
按顺序执行两项检查：
bash
undefined

1. Does the recipe load? (authoritative — schema, defaults, baseline, network)

1. Does the recipe load? (authoritative — schema, defaults, baseline, network)

hedera-harness doctor .harness/spec.yaml --recipe-only
hedera-harness doctor .harness/spec.yaml --recipe-only

2. Is it coherent across files? (traceability, stage pairing, blind rule)

2. Is it coherent across files? (traceability, stage pairing, blind rule)

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

`check-spec.sh` runs `doctor` itself, so running it alone is enough when the
harness CLI is installed. If it reports that the schema was **not** validated,
that is a partial result — install or upgrade the harness and rerun.

**Done when `check-spec.sh` exits clean.**

Then hand off:

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

`check-spec.sh`会自动运行`doctor`，因此在已安装harness CLI的情况下，仅运行该脚本即可。如果脚本报告schema**未**通过验证，说明结果不完整——请安装或升级harness后重新运行。

**当`check-spec.sh`无错误退出时，即为完成。**

随后交付使用：

```bash

Prefer /review-harness-spec next, then:

Prefer /review-harness-spec next, then:

hedera-harness run .harness/spec.yaml --max-attempts 3
hedera-harness run .harness/spec.yaml --max-attempts 3

or: yarn harness:run

or: yarn harness:run


Point at the harness README for install, agent auth, and stage host
prerequisites. `hedera-harness doctor` (without `--recipe-only`) checks those.
Do not expand CLI teaching beyond these next commands.

安装、Agent认证和阶段宿主的前置条件请参考harness的README。`hedera-harness doctor`（不带`--recipe-only`参数）会检查这些条件。除了以下命令外，不要展开讲解CLI的其他用法。

Additional resources

额外资源

  • references/grilling.md
  • 配套技能：
    /review-harness-spec
  • 词汇表：
    /harness-spec-anatomy
  • 上游文档：docs/authoring-a-recipe.md