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 マーケットプレイスプラグインとして引き続き使用します。

レイアウト

レイアウトは 1 つです。スキャフォールドされたアプリ（hedera-harness init または Scaffold HBAR による）の中に .harness/ を置きます。ワークスペースはプロジェクト自体です。 レシピファイル内のパスは、プロジェクトルートからの相対パスです。

ファイル	必須？	デフォルトパス	使用者
レシピファイル	はい	.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/runs/ に出力され、パスは変更できません。

引き継ぎ：yarn harness:run または hedera-harness run .harness/spec.yaml。

レシピファイルに必須の内容

必須なのは 4 項目だけです。

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: と 1 対 1 で対応させる必要があります
maxAttempts	3
constraints.packageManager	package.json / ロックファイルから検出
constraints.forbiddenCommands	使用中のもの以外のすべてのパッケージマネージャー
forbiddenFiles / secretScan	.env に加え、ワークスペースごとに 1 つ
requiredFiles	空 — ゲートとなるのはバリデーターです

不明なキーは警告とともに無視されるため、タイプミスはクラッシュではなく機能の低下につながります。 そのような警告はすべて指摘事項として扱ってください。

ステージ

順番に有効化してください。デフォルトは ASSERT のみなので、初回実行のコストを抑えられます。

ステージ	レシピファイルのフィールド	チェック内容
ASSERT	validators.static、validators.commands、requiredFiles、forbiddenFiles、secretScan	ファイル、JSON／テキスト、シークレット、install／lint／build
SMOKE	validators.playwright	開発サーバーが起動すること、ルートが HTTP で正常応答すること、コンソール／禁止テキスト
EVALUATE	eval + validator.enabled: true	エージェントが番号付きのアサーションを評価チェックリストに照らして評価
CHAIN	chainValidation（+ EVALUATE）	一時的な ECDSA テスト署名者、実際のトランザクション、ミラーネットワークでの検証

有効化の完全な順序、ホストの前提条件、YAML ブロックについては、 references/stage-strategy.md を参照してください。

ファイル間の整合性

v3 のデフォルトでは、パスレベルの結合の大部分がなくなりました。それでも一致させる必要がある項目は次のとおりです。

同期する項目	理由
評価チェックリストの routes ↔ Playwright の routes ↔ PRD の成果物ルート	バリデーターは PRD で約束された項目を検証します
すべての PRD ジャーニー ↔ 対応するチェックリスト内のアサーション ≥ 1 件	検証されていないジャーニーは、問題なく通過してしまいます
すべてのアサーション ↔ PRD ジャーニー	対応するジャーニーのないアサーションはスコープの逸脱です
prd: リスト ↔ eval: リスト（両方がリストの場合）	1 対 1 である必要があります。各インクリメントでベンダーに含めるのは、有効なペアのみです
forbiddenFiles ↔ 静的な fileAssertions.forbidden	2 つのゲートで意図は同じです
constraints.packageManager ↔ package.json に対する静的アサーション	検出された値を上書きする場合に限ります
eval ↔ validator.enabled: true	どちらか一方だけでは、レシピの設定が不適切です
アサーションの executableWithTestSigner ↔ chainValidation.enabled	CHAIN がなければ、フラグ付きアサーションは機能しません

templateMetadata.name はホストテンプレートの ID であり、name の機能 スラッグ とは異なる場合があります。これは指摘事項ではありません。

ブラインド評価チェックリストのルール

実行は ブラインド にしてください。PRD にはジャーニーと結果を記載し、番号付きアサーションは 評価チェックリスト に記載します。GLOSSARY.md と references/prd-and-journeys.md を参照してください。

変更の影響を受けやすいローダーフィールド

ハーネスで次のフィールド名が変更された場合は、同じ変更セット内でこのスキルとその評価も更新してください。

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 が実行しない ファイル間の整合性チェックを追加します。終了コードが 0 であれば設定は正しく、 0 以外の場合は指摘事項が 1 行に 1 件ずつ出力されます。

ハーネス 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