---
name: harness-engineering
description: skills・rules・agents・テンプレートを改善・保守するメタスキル。手戻り・ルール不足・責務の曖昧さ・テンプレート重複が繰り返し発生したときに使う。通常の機能実装や TDD には使わない。
---

# harness-engineering

## 使うタイミング

- 同じ補足説明・修正が繰り返し必要になった
- 複数の skill / rule / agent の責務が曖昧で手戻り・重複が発生
- skill / rule / agent の不足が品質・速度を継続的に落としている
- ユーザーがハーネス自体の改善を要求
- 別プロジェクトからの移植直後・大規模リネーム後の固有化と重複排除
- `.spec-runner/scripts/*.js`（lint/drift 検証・図生成）が design-docs.instructions.md のルールを
  正しく検証できず、誤検知（正しい記述に警告）・検知漏れ（誤った記述を通す）が発生した
- 同種の drift/lint 誤検知を個別の `drift-ok` 注記で場当たり的に回避し続けている
  （3件目が出たら検証ロジック自体を直す判断をする。design-docs.instructions.md の「3つ目のUCで共通化」原則と同じ）
- design-docs.instructions.md のブロック構成・列構成を変更したのに、対応する scan.js/render.js/lib.js の
  パーサー・検証・図生成が追従していない

使わない: 1回限りの例外対応 / 通常の実装・バグ修正 / アプリコードの TDD / 言い回しの微調整。

## Phase 1: 問題の抽出

何が詰まり、どこに無駄が出たか整理 -> 一時的か構造的（再発する）か判定 -> 改善対象を特定（skill / rule / agent / template）。
出力: 問題の要約・再発条件・変更対象候補。

## Phase 2: 対応方針の決定

1. 最小変更で解決できる対象を選ぶ。まず既存資産を直す。新 skill は「繰り返し使う独立ワークフロー」がある場合だけ
2. Claude / Copilot 両テンプレートへの影響を確認

## Phase 3: 修正

修正前に `.github/skills/harness-engineering/references/harness-format.md` を読む。

1. 意図が変わらない最小差分で修正（責務重複を増やさない。主要フローを壊さない。承認前提のフローを短絡しない）
2. このファイルは `.claude/` 側編集後の hook（`.spec-runner/scripts/sync-mirrors.js`）が自動生成している。直接編集しない（`.claude/` を導入していないプロジェクトではこの節は対象外）
3. スクリプト（`.spec-runner/scripts/*.js`）変更時は `node .spec-runner/scripts/scan.js` でエラーがないことを確認する
4. references / templates は必要な範囲だけ更新

### spec-runner スクリプト（lib.js / scan.js / render.js）を直すときの追加注意

- **場当たり対応を疑う**: 個別ケースに `drift-ok` を書いて回避するのではなく、そのケースを生む条件（列の有無・値の形）を関数レベルで判定できるよう検証ロジック自体を直す
- **正規表現変更は既存 docs 全体で検証する**: 1つの誤検知を直す正規表現の変更は、他の全設計書のマッチ結果を変えうる（例: 括弧を含む型名・日本語ラベルへの対応拡張が、既存の半角記号ケースの挙動を変えた実例あり）。`node render.js` 後に `git diff docs/` で全差分を目視し、意図しない変化がないか確認する
- **同じ判定を複数箇所に書きそうになったら共通化する**: `lib.js` にドメイン判定（例: 列構成の正規化）を1つの関数として作り、`scan.js`（lint・drift）と `render.js`（図生成）の両方から呼ぶ。3箇所目の分岐が生まれた時点で共通化する（design-docs.instructions.md の「3つ目のUCで共通化」原則と同じ）
- **列構成の変更は3段への影響を洗い出す**: design-docs.instructions.md のブロック構成・列を変えたら、パース（`lib.js` の `parseIo`/`parseSpecData` 等）→ 検証（`scan.js` の lint/drift）→ 図生成（`render.js`）の3段すべてに影響がないか確認する
- 修正後は `node render.js` → `node scan.js` を実行し、`lint: 0, drift: 0`（既知の unmapped を除く）を確認してからバックエンド/フロントエンドのテストを流す

## Phase 4: 反映確認

`harness-format.md` の「プロジェクト固有化チェック」「重複排除チェック」を当てる。加えて:

- 変更が問題の原因に直接効いているか
- 関連 skill / rule / agent / template に矛盾・反映漏れがないか
- 今回限りのノイズをルール化していないか
- spec-runner スクリプトを直した場合: 同じ判定ロジック（列挙値・列構成の分岐等）が `scan.js` と
  `render.js` に別々に書かれていないか（`lib.js` の共有関数を経由しているか）grep で確認する
- design-docs.instructions.md のルール文言と、それを検証する scan.js の実装が一致しているか
  （ルール文言だけ直して検証ロジックを直し忘れる、または逆のパターンがないか）
- skill 名・起動条件を変えたら CLAUDE.md と一致しているか
- CLAUDE.md の肥大化（20行超 -> rules / skills へ移動を検討）
- docs 構造・命名・node_id に影響するなら design-docs.instructions.md と整合しているか