Imported from TeXmeijin/agent-skills (
.apm/skills/harness-creator/SKILL.md). Install upstream withnpx skills add TeXmeijin/agent-skills --skill harness-creator. Copyright stays with the author.
harness-creator
このスキルは、依頼者から「ハーネスを作りたい」と要求があったときに、定義の取り違えを避けて構築を完遂するための 定義・手順・参照集 である。
SKILL 本体は 定義と手順 で固定する。具象実装パターンは references/ 配下に蓄積する設計であり、今後も増えていく。
0. 最重要前提：「ハーネス」はエージェントにとって誤解されやすい語である
抽象的に「ハーネスを作って」と依頼されたとき、エージェントはハーネスの本来の意味（§1 参照）を見失い、見栄えのよい単発ドキュメント（HTML / Markdown / チェックリストなど）で応答してそれをハーネスと称してしまいやすい。 ドキュメント類はハーネスの 出力先 や アクセサリ にはなり得るが、機械的な Red/Green 判定（§1 の R）を持たないものはハーネスではない。
このスキルが起動した時点で、次の 3 ステップを必ず最初に踏む：
- §1 の定義（unit harness / system harness の二形態）を内部的に再読み込みする
- 依頼が unit / system のどちらの規模に該当するかを判定する（曖昧なら使用者に確認）
- §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 のみ必須 なので、構築は短い：
- 検証コマンドを確定する：対象に対して走らせると
exit 0/exit !=0で機械判定できるコマンドを 1 つ確定する（例：型チェッカ、linter、test runner、format checker） - トリガーポイントに差し込む：hook（editor / pre-commit / pre-push）、CI step、または watcher で、対象が変更されたら検証コマンドを自動実行するように配線する
- 失敗時の挙動を決める：失敗時にコミット/PR/操作をブロックするか、警告のみに留めるかを使用者と合意する
- 動作確認：意図的に違反コードを置いて 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: 起動時のセルフチェック
このスキルを起動した瞬間に、内部で以下を確認する：
- ユーザ依頼に「ハーネス」「harness」が含まれるか、または機械的検証の自動化を要求しているか
- 規模を判定したか：unit（特定操作・特定パターンに差し込む小さな自動検証）か system（複数の検証点・進捗・成果物を覆う大きな仕組み）か。曖昧なら使用者に確認する
- R（機械的 Red/Green 判定）が「人間目視」「気合」「祈り」になっていないか（→ なっていればハーネスではない。スクリプト化を提案）
- unit harness の場合：R 以外を勝手に盛らないこと（hook / CI step 1 つで完結するなら、PROGRESS.md や README.md を作らない）
- system harness の場合：REPF すべてが揃っているか、F（README）に Owner 欄があるか、完了判定が「ファイルを書き終えた」ではなく GREEN 到達になっているか
セルフチェックで NG が 1 つでもあれば、ユーザに明示的に確認を取ってから作業を続ける。