harness-creator

name

harness-creator

description

検証可能な「ハーネス」を構築する。ハーネス＝ある対象を機械的に駆動して検証する自家製の仕組み。規模で 2 形態に分かれる：**unit harness**（特定の操作・ファイル変更・コードパスに差し込む小さな自動検証。hook / CI step / lint runner 等。最小要件は Red/Green 機械判定のみ）と **system harness**（施策・プロジェクト全体を覆い、複数の検証点・進捗・成果物を一括管理する大きな仕組み。最小要件は REPF: Red/Green 観測 + Progress 追跡 + Executable artifacts + Flow 文書）。複数の unit harness が集まって system harness を構成しうる。トリガー：「ハーネスを作って」「harness を構築」「RED/GREEN で観測したい」「再発防止のフックを差し込みたい」「失敗が許されない作業の前準備」「複数の検証点を一括管理したい」。**コピペ用 HTML / Markdown 手順書 / チェックリスト単独はハーネスではない**（機械的検証 R が無いため）。依頼が抽象的なら最初に規模（unit / system）を確認すること。

harness-creator

このスキルは、依頼者から「ハーネスを作りたい」と要求があったときに、定義の取り違えを避けて構築を完遂するための 定義・手順・参照集 である。 SKILL 本体は 定義と手順 で固定する。具象実装パターンは references/ 配下に蓄積する設計であり、今後も増えていく。

---

0. 最重要前提：「ハーネス」はエージェントにとって誤解されやすい語である

抽象的に「ハーネスを作って」と依頼されたとき、エージェントはハーネスの本来の意味（§1 参照）を見失い、見栄えのよい単発ドキュメント（HTML / Markdown / チェックリストなど）で応答してそれをハーネスと称してしまいやすい。 ドキュメント類はハーネスの 出力先 や アクセサリ にはなり得るが、機械的な Red/Green 判定（§1 の R）を持たないものはハーネスではない。

このスキルが起動した時点で、次の 3 ステップを必ず最初に踏む：

1. §1 の定義（unit harness / system harness の二形態）を内部的に再読み込みする
2. 依頼が unit / system のどちらの規模に該当するかを判定する（曖昧なら使用者に確認）
3. §2 のアンチパターンに自分の構想が落ちていないか自己点検する

これらを省略してハーネスと称する成果物を作ることを禁ずる。

---

1. ハーネスの定義（固定）

ハーネスとは、ある対象を機械的に駆動して検証する自家製の仕組みである。

ハーネスは規模により 2 形態に大別される。両者は二者択一ではなく、複数の unit harness が集まって system harness を構成する という composition の関係にある。古典的テスト分野（unit / integration / system test harness）の階層分類に準拠した命名である。

1.1 unit harness（部分ハーネス）

特定の作業・ファイル変更・コードパス・操作の前後に 差し込んで 検証を自動化する、小さな仕組み。

例：

• editor / git hook で型チェッカ・linter を自動実行（例：PHP 変更時に PHPStan）
• pre-commit / pre-push hook の単独チェック
• CI ワークフローの単一 step（test, lint, type check）
• 1 つのファイル変更を検知して 1 つの検証を走らせる小スクリプト

最小要件：

• R（Red/Green の機械判定）のみが必須。exit 0 / exit !=0 等で機械的に pass/fail が判定できる
• P / E / F は省略してよい（hook 設定 1 ファイル、CI step 1 ブロックで完結することが多い）

1.2 system harness（全体ハーネス）

施策・プロジェクト・移行作業など、複数の検証点・進捗・成果物を一括管理する 大きな仕組み。複数の unit harness を統合する役割を持つことがある。

例：

• 複数リポ・複数リソースをまたぐ移行作業の一括検証フレーム
• 1 つの施策に対する「着手前 RED → 完了後 GREEN」をすべての観測軸でカバーする検証一式
• 中断・再開・引き継ぎが起きうる長期作業の進捗管理つきハーネス

最小要件（REPF 全て必須）：

記号	コンポーネント	役割
R	Red/Green 観測機構	各サブタスクが未達(RED) / 達成(GREEN) / 中間(WARN) を、コマンド一発で機械的に判定できる
P	Progress 追跡構造	全サブタスクの状態を一覧でき、各タスクの進行・依存関係・Owner を追える
E	Executable artifacts	説明ではなく、そのまま実行・コピペ・参照されるアーティファクト（スクリプト / JSON / yaml / SQL / コマンド列など）
F	Flow documentation (README)	使用者が「何を、どの順で、誰の権限で」実行するかが書かれた読み物

略して REPF 要件。system harness を名乗る成果物は、1 つでも欠けたら「system harness 未満」となる。

1.3 どちらを作るか

あなたの状況	作るべきもの
「ある操作の度に、ある検証を機械的に走らせたい」	unit harness
「再発防止のため、特定パターンを自動検知したい」	unit harness
「複数の検証点・複数の成果物・進捗管理を伴う施策全体を駆動したい」	system harness
「複数の unit harness を統合して、一括で状態を可視化したい」	system harness

依頼が抽象的に「ハーネスを作って」と来た場合、規模を最初に確認すること。ここを取り違えると、unit で済む話に REPF 一式を作って過剰になるか、system が必要なのに hook 一発で済ませて不足する。

---

2. アンチパターン（これはハーネスではない）

「ハーネス」を名乗るには、最低でも R（機械的 Red/Green 判定） が必須。R を持たない成果物は unit harness ですらない。

成果物	これは何か	何が足りないか
Markdown 手順書のみ	runbook / procedure	R が無い（人間が目視で判定する設計はハーネスではない）
コピペ用 HTML ビューワ	cheat sheet / コマンド配布媒体	R が無い
チェックボックスだけの MD	checklist	R が無い
gh issue / gh project のテンプレ	issue tracker	R が無い
Dashboard / 監視画面（人間が読むだけ）	observation surface	R が無い（人間判定）

加えて、system harness を名乗るには REPF すべてが必要。R はあっても P / E / F のいずれかが欠ければ unit harness 止まりであり、system harness と称してはならない。

成果物	これは何か	何が足りないか（system harness としては）
シェルスクリプト 1 本だけ	unit harness / tool	P と F が無い
hook 設定 + 検証コマンドだけ	unit harness / hook	P と F が無い
check.sh + リソースファイル群のみ	system harness 未満	P と F が無い

判定法（system harness 用）：成果物だけ渡された未来の自分が、依頼内容を忘れていても、README.md を読んで check.sh を走らせて RED 一覧を見れば、付属のリソース・スクリプト群を使って作業を再開できる構造になっているか？ なっていなければ system harness ではない（unit harness としては機能しうる）。

---

3. 構築手順

3.0 unit harness の構築（簡略版）

unit harness は R のみ必須 なので、構築は短い：

1. 検証コマンドを確定する：対象に対して走らせると exit 0 / exit !=0 で機械判定できるコマンドを 1 つ確定する（例：型チェッカ、linter、test runner、format checker）
2. トリガーポイントに差し込む：hook（editor / pre-commit / pre-push）、CI step、または watcher で、対象が変更されたら検証コマンドを自動実行するように配線する
3. 失敗時の挙動を決める：失敗時にコミット/PR/操作をブロックするか、警告のみに留めるかを使用者と合意する
4. 動作確認：意図的に違反コードを置いて RED になることを 1 度確認、修正して GREEN になることを確認

これ以上の構造（PROGRESS.md、README.md、リソースファイル群）は 不要。複数の unit harness を統合・進捗管理したくなった時点で、§3.1 以降の system harness 構築手順に移行する。

3.1 system harness の構築手順

ここからは system harness を作る場合の手順。

Step 1: REPF 設計の宣言（コード書く前）

ハーネス着手を宣言する前に、以下を箇条書きで明示して使用者に確認を取る。

このハーネスの REPF 構成:
  R: <観測対象とコマンド体系。観測軸ごとにサブモードに分割する場合はその分け方も明示>
  P: <進捗構造。表の列構成、Owner の置き方、TaskCreate との併用有無など>
  E: <生成する成果物。リソース定義ファイル / 差分パッチ / 補助スクリプトなど、ハーネス利用者が直接食わせる/参照する形のもの>
  F: <README で示すフロー。前後ステップの順序、Owner の切り替わり、GREEN 到達の確認方法>

REPF のいずれかが「未定」「TBD」「後で考える」になっている場合、ハーネス構築には進めない。先に詰める。

Step 2: ディレクトリ構造の固定

ハーネスは以下の構造で配置する（リポジトリ内の作業用ディレクトリ、または依頼に応じた指定パス）。

<harness-root>/
├── README.md                # F: フロー文書
├── PROGRESS.md              # P: 進捗追跡
├── check.sh                 # R: 状態観測スクリプト（必要に応じてサブモード切替可能）
├── baseline-YYYY-MM-DD.txt  # R: check.sh の初回出力（着手時点の RED スナップショット）
├── <resource-dir-a>/        # E: 必要に応じて。リソース定義ファイル群
├── <resource-dir-b>/        # E: 〃
└── (cheat-sheet.html)       # オプション：コピペ専用 UI。ハーネス本体ではないため括弧扱い

<resource-dir-*> は作業内容次第で命名・分割する。観測のみで完結する作業（リソース作成を伴わない検証）なら省略可。

Step 3: check.sh の必須要件

• 引数なしで全観測を実行できること（bash check.sh で全件が見える）
• 観測領域が複数ある場合はサブモードで部分実行できること（例：bash check.sh <subset>）。短いフィードバックループを保つため
• 出力は表形式で STATUS 列に ✅ GREEN / ⚠️ WARN / ❌ RED を出す
• 末尾に Summary 行を出す（Summary: GREEN=X WARN=Y RED=Z / TOTAL=N）
• 冪等：何度走らせても副作用ゼロ（読み取り専用 API のみ）
• 認証失敗時は即終了（無音で RED を返すと「設定未完」と「観測不能」が混ざり進捗が破綻する）

Step 4: 着手前 baseline の固定

check.sh > baseline-YYYY-MM-DD.txt を最初に必ず走らせて保存する。これが RED から GREEN への進捗の基準になる。

Step 5: PROGRESS.md の構造

最低限、以下のテーブル構造で書く。

| Phase | Item | Owner | RED 観測 | GREEN 条件 | 状態 |
|---|---|---|---|---|---|
| ... | ... | 指示者 / エージェント | check.sh の該当行 | check.sh が GREEN | ⏳ in-progress |

Owner 欄を必ず置く（権限を要する操作は指示者、ファイル生成や下準備はエージェント、のように分担を明示）。

Step 6: 完了判定

「ハーネスが完成した」と宣言できるのは、未来の自分または別の作業者に、README.md のみを渡して、check.sh 実行で RED 一覧から作業再開し、リソースファイル群（あれば）を使い切って GREEN まで到達できる構造になっているとき、その時のみ。ファイルを書き終えただけではハーネスは完成していない。最低 1 回 check.sh を走らせて baseline を取り、Summary 行が出ることを確認するまでが構築の責務。

---

4. 新パターン追加プロトコル

このスキルは定義は固定だが、具象実装パターンは今後の開発を通して増えていく。 ハーネスを作って、それが実際にワークしたら、指示者の確認を経た上で、新パターンとしてリファレンスに追記すること。

4.1 追加トリガー

ハーネスを使った作業群が全 GREEN に到達し、かつ 指示者がそのハーネスが意図通りに機能したことを確認した発言を行った時点で、エージェントは以下を提案する：

このハーネス（<slug>）は REPF を満たし、全 GREEN に到達しました。
references/NNN-<slug>.md として新パターンに追記してもよいですか？
追記する場合、含める情報は: 適用領域（形質） / 前提 / アウトプットの形 / 観測軸 / 学び・落とし穴 / 再利用可能テンプレ。
固有名詞（プロジェクト名・人名・社名・実リソース名）は記載せず、抽象化した形質ベース記述で書きます。

指示者が承認したらのみ書き込む。未承認のまま勝手に追記してはいけない。 また、書き込み時には固有名詞・実 ID・実リソース名・人名を一切含めない（外部公開時の情報漏洩防止）。

4.2 リファレンスファイルのフォーマット

references/NNN-<slug>.md は以下の節を必ず含む。冒頭で [unit] / [system] の規模タグを明示する：

# <パターン名> [unit | system]

## 適用領域
<どんなときにこのパターンが効くか>

## 構成（system の場合は REPF、unit の場合は R のみ）
- R: <検証コマンドと観測対象>
- P: <system のみ：進捗構造>
- E: <system のみ：成果物配置>
- F: <system のみ：README で示したフロー要点>

## ディレクトリ構造（実物）
<実際の配置を tree で>

## check.sh の構造
<観測ロジックの設計判断>

## 学び・落とし穴
<やってみて気付いた notation / 再利用時に必ず踏むべき初期検証 / 失敗パターン>

## 再利用可能なテンプレ・スニペット
<次回ほぼコピペで使える断片。固有名詞・実 ID は含めない>

4.3 リファレンスの index

references/ 配下に新規追加されたら、本 SKILL.md 末尾の §5 リファレンス一覧 に必ず 1 行追記する（ファイル名・適用領域 1 行サマリ）。

---

5. リファレンス一覧

新しいパターンを追加するたびに、以下に 1 行ずつ追記する。各エントリには [unit] / [system] の規模タグを付ける。

• 001-cli-pre-post-checker.md [system] — マシン内の既存認証済み CLI（クラウド / SaaS / コードホスティング / DB など任意）を使って、作業の前後で状態を機械的に RED/GREEN 判定する shell ハーネス。対象数は 1 個でも複数でも適用可能

---

付録 A: 起動時のセルフチェック

このスキルを起動した瞬間に、内部で以下を確認する：

1. ユーザ依頼に「ハーネス」「harness」が含まれるか、または機械的検証の自動化を要求しているか
2. 規模を判定したか：unit（特定操作・特定パターンに差し込む小さな自動検証）か system（複数の検証点・進捗・成果物を覆う大きな仕組み）か。曖昧なら使用者に確認する
3. R（機械的 Red/Green 判定）が「人間目視」「気合」「祈り」になっていないか（→ なっていればハーネスではない。スクリプト化を提案）
4. unit harness の場合：R 以外を勝手に盛らないこと（hook / CI step 1 つで完結するなら、PROGRESS.md や README.md を作らない）
5. system harness の場合：REPF すべてが揃っているか、F（README）に Owner 欄があるか、完了判定が「ファイルを書き終えた」ではなく GREEN 到達になっているか

セルフチェックで NG が 1 つでもあれば、ユーザに明示的に確認を取ってから作業を続ける。