HARNESS ENGINEERING ・ MASTER SHEET
ハーネスエンジニアリング マスターシート
2つの学習ノートと実装済み2スキルを統合した、ハーネス型スキルを作るための設計リファレンス。12ファイルの中身を1枚に圧縮しています。
格納 04_AI/07_harness/ハーネスエンジニアリング_マスターシート
ファイル 12
構成パターン 6
完成チェック 20項目
更新 2026/08/01
ITERATION
5〜15回
原典の反復前提。
跳ねるのは後半
GATE
全軸AND
1軸でも未達なら
総合点に関係なく不合格
DEFAULT
falseから
受入基準は全部不合格
スタート。証拠で解錠
導入段階の効果
12ファイルは役割で3層に分かれている。判断の土台（01〜02）／コピペ資産（03〜05）／実装仕様（06〜07）、それに手順書（08）と運用（09〜11）。入口は3つだけ覚えればよい。
「別のAIに見せれば客観的になる」という話ではない。生成側も評価側も本質的には甘い。違うのは立場によってチューニングのしやすさが変わる点。
A失敗モード：終盤の息切れ
文脈の上限が近づくと焦って強引にまとめる。実際の上限に達していなくても起きる。対処は圧縮ではなくコンテキストリセット＋ハンドオフ成果物。モデル世代で解消しつつある部品。
B失敗モード：自己評価の甘さ
自分の成果物を採点させると、破綻していても自信を持って絶賛する。正解が数値化できない仕事で深刻。人が指摘すれば直すが自分では気づけない。これが設計の主題。
| 要因 | 生成側が自己評価する場合 | 独立した評価側の場合 |
|---|
| 文脈 | 「なぜこう作ったか」の正当化が全部入っている | 作った過程を一切見ていない。あるのは成果物だけ |
| コミットメント | 自分の判断を否定すると直前の出力と矛盾する | 否定してもコストがない。むしろ否定が仕事 |
| 役割の整合性 | 「完成させる」と「粗を探す」が同一プロンプト内で衝突 | 「粗を探す」だけ。役割が純粋になる |
| サンクコスト | 長時間かけた成果を作り直せと言いにくい | かけた時間を知らない |
| 構造的制約 | 直せる立場なので、直しながら甘く判断できる | 書き込みツールを外せば直せない。判断しかできない |
分離の価値は「客観性」ではなく、役割プロンプトを純粋にできることと権限を構造的に剥がせること。だから「厳しく自己評価せよ」と書いても効かない（厳しい言葉で書かれた甘い評価が返る／些末な欠点3つを挙げて中核の破綻を見逃す／通るテストを書く）。
ハーネスの構成要素は役割で呼び分ける。この名前が .claude/agents/ のファイル名になるので、最初に語彙を固定する。最小構成は前の3つ（プランナー／ジェネレーター／エバリュエーター）で、インテグレーターは分担型・競作型で足す4体目。
| 役 | エージェント名 | やること | やってはいけないこと | tools |
|---|
| プランナー | planner | 依頼を仕様と作業単位に展開。完了条件を実物で判定できる形で書く | 実装詳細を決める（後段が仕様の奴隷になる）／スコープを最小に縮める | Read, Write, Edit, Glob, Grep, WebSearch |
| ジェネレーター | generator / builder | 1単位ずつ実装＋自己評価。証拠を所定パスに残す | 合格判定を出す／複数単位の同時実装／テストの削除・編集 | Read, Write, Edit, Glob, Grep, Bash |
| インテグレーター | integrator / synthesizer | 分担型は結合と機械検証、競作型は比較と選択（棄却理由を残す） | 合格判定を出す／指摘されていない箇所の書き換え | Read, Write, Edit, Glob, Grep, Bash |
| エバリュエーター | evaluator / eval-<軸> | 実物と証拠を見て判定。1行目に PASS / NEEDS_WORK | 自分で直す／証拠を開かずに合格を出す／合理化して見逃す | Read, Glob, Grep（＋MCP） |
役割は現実の職種に対応させる
プランナー＝企画・編集会議、ジェネレーター＝制作担当、エバリュエーター＝校閲・品質検査。工程ではなく職種の粒度で切るのが原則。
自己評価は捨てない
ジェネレーターの自己評価は安い粗いフィルタ。明らかな未実装を先に落とし、高コストなエバリュエーターのサイクルを節約する。役割は「出す前の見直し（安い・甘い）」対「受入検査（高い・厳しい・拒否権あり）」。
自環境の実在エージェント
viz-planner-* / viz-builder-* / viz-integrator / viz-eval-*（図解13体）、strat-planner-* / strat-generator / strat-synthesizer / strat-eval-*（戦略10体）が既にこの4役の構成。
エージェントを書き始める前に型を決める。判定は上から順に。最初の関門は「証拠が決まっているか」で、ここが NO なら設計に進めない。
P1 ＋1体・10〜30分
評価者だけ足す
既存の生成フローに検査と差し戻しを1周足すだけ。ここだけで効果の大半が出る。逆にhookから入ると効果が実感できない。
P3 10〜20体
契約先出し＋分担
並列実装が壊れない条件は3つ。契約を先に確定／別ファイルに分担／契約外の要素の新設を禁止（必要なら申請させる）。
P4 10〜30体
レンズ別競作＋統合
互いを見ない独立案をN本作り、判断基準で比較して1本に統合。足して2で割らない。棄却理由を残すのが価値。
プロンプトの文言より、この4つの構造のほうが効く。お願いではなく構造で縛るのがこの分野の思想そのもの。
1まっさらな文脈
サブエージェントか別プロセス。同一セッションで「次は評価者として」は文脈汚染で効果が薄れる。
2書込権限なし
tools: から Write / Edit を外す。Bashを渡した時点で厳密な読み取り専用ではない点も意識する。
3証拠主義
もっともらしさは正しさではない。「たぶん大丈夫」と仮定していると気づいたら止まって証拠を探す。
4デフォルトFAIL
全基準を false から開始。証拠ゼロの評価はPASSでも無効化する1行で主要な効果が出る。
// ワークフロー側で default-FAIL を担保する（hookを書かなくてもここで効く）
function axisPassed(v) {
if (!v || !Array.isArray(v.evidence) || v.evidence.length === 0) return false // 証拠ゼロは不合格
if (v.verdict !== 'PASS') return false
return (v.scores || []).every(s => s.score >= s.threshold) // 全軸AND
}
評価者を置いても、基準が曖昧なら結局AIの自己判断になる。作り始める前に完了条件を固定するのが要点。実演側のハーネスに無かったのがこれで、「機能が浅い」の原因になった。
効かない基準
感想で決まるので、実質AIの自己判断になる。
資料デザインがきれいであること
議事録正確であること
機能ちゃんと動くこと
実装fillRectangleがmouseUpで呼ばれる（手段を縛りすぎ）
効く基準（3条件を満たす）
実物で判定できる／手段を指定しない／曖昧語を含まない。
資料図解要素の面積比が6割以上（実測値を報告）
議事録元発言に無い固有名詞が0件（引用で証明）
機能実データが返る（プレースホルダを含まない）
実装クリック＆ドラッグで矩形領域を塗りつぶせる
| ドメイン | 証拠（Playwrightに相当するもの） | 手段 |
|---|
| Webアプリ | 動作するUIのスクショ、コンソールログ、APIレスポンス | mcp__playwright__* |
| 資料・図解 | レンダリング結果のスクショ、面積比の実測 | Browser pane / Playwright |
| 議事録 | 元の文字起こし全文（該当箇所を引用させる） | Read, Grep |
| データ分析 | 元データを引き直した再計算、件数の検算 | シート／DBの読み取り |
| 記事・戦略 | 出典URL、リサーチャーの生出力、過去の振り返り資料 | Read, WebFetch |
共通原則：生成側が用意した要約や自己申告を証拠にしてはいけない。一次情報に自分で当たらせる。この手段が「成果物のテキストを読む」以外に思いつかない業務は、まだハーネス化できない。
コードは「テストが通る／通らない」で判定できるが、デザイン・文章・戦略はできない。そこで4軸に分解し、軸ごとに合格ラインを置いて全軸ANDで判定する。
重み：高
質
部品の寄せ集めでなく、一体感のある全体になっているか。
重み：高
独自性
テンプレ・デフォルト・AIっぽさを超えたカスタムな判断の証拠があるか。
重み：低
丁寧さ
階層・余白・一貫性・表記。放っておいてもできるので配点は低め。
重み：低
機能性
目的が伝わり、読者・利用者がタスクを完了できるか。
重みはモデルが苦手な軸に置く。放っておいてもできることに配点しても品質は上がらない。そしてモデルの初期値そのものを減点対象に明記するのが最も効く一手。LLMは平均に回帰するので、平均を罰しないと平均から離れない。
| ドメイン | 減点する「AIっぽさ」を具体語で列挙する |
|---|
| Web / UI | 白カード＋紫グラデーション、角丸12px＋薄いshadowの羅列、絵文字アイコン |
| HTML図解 | 3カラムの箇条書きだけの「図解」、テキスト過多、記号系の装飾 |
| 文章 | 「〜ではないでしょうか」「重要です」「以下の3点が挙げられます」、体言止めの羅列 |
| 分析 | 「相関が見られました」で終わる、示唆が「注視が必要」 |
| 戦略 | 「バランス型」「全方位で強化」「まずは検討する」、担当が「チーム全体」 |
| 議事録 | 「活発な議論が行われた」「今後の課題として認識された」（誰が何をするか不明） |
加えて、点数内訳つきの採点例を2〜3件埋め込む（few-shot）。とくに「格好いいが機能しない → 不合格」の例を入れると甘さが締まる。ここを省くと必ず甘くなる。
停止条件を書き忘れると無限ループとコスト暴走になる。4条件を必ず入れる。差し戻し先も指摘の性質で振り分ける。
1契約充足
全基準が true ／ 全軸がしきい値以上。
2停滞検知
2種類必要。成果物ハッシュの同一性と指摘の同一性。後者が実務で効く。
3予算到達
最大ラウンド数／金額／時間。初期値は3ラウンド。
4人間の停止
キルスイッチファイル。走行中の軌道修正は STEER 方式。
// 停滞検知(b)：同じ指摘が繰り返されている＝直せていない。(a)ハッシュだけでは検出できない
const key = allFindings.map(f => f.where + '|' + f.observed).sort().join('||')
if (key && key === prevFindingsKey) { stopReason = '同一の指摘が繰り返されており改善していない'; break }
prevFindingsKey = key
プレイブックの手順。Step1で証拠が決まらなければ、そこで止めるのが設計ゲート。ここを飛ばして作ったハーネスは机上採点になって効かない。
0判定
やり直しが多い納品物か。年1回の仕事は選ばない
1証拠を決める
テストを読む以外の手段があるか。無ければ中止
5ルーブリック
4軸＋しきい値＋AIっぽさ減点＋few-shot
7ループ制御
停止条件4つ・route分岐・停滞検知2種
設計シートの必須欄（埋まらない欄＝設計の穴）
成果物ファイル1つで表せる形にする
証拠一次情報とその取得手段
基準5〜8件・全部false・実物で判定可能
パターンP1〜P6と選んだ理由
役割接頭辞-役割／tools／書込可否
ゲート軸・しきい値・減点する具体語
検証機械で見る項目と形骸値パターン
停止最大ラウンド・停滞検知・未達時の扱い
差し替えるのは4か所だけ
エージェント定義ライブラリからコピーして、以下だけ変える。他は原典の文言を削らない（各文が特定の失敗モードを潰しているため）。
1description：いつ起動されるべきか（発動精度に直結）
2tools：評価者からWrite/Editを外す
3やらないこと／禁止事項
4出力形式（1行目に判定／JSONスキーマ）
保存先は .claude/skills/ と 04_AI/05_skills/ の両方。エージェントはVaultルートの .claude/agents/ に置く。
運用判断はすべて「評価者は安い」という事実から出る。削るなら生成側の反復回数で、評価者を削ってもコストはほとんど減らない。
反復回数
原典は5〜15回前提。前半は線形、後半で段差のように跳ねる（9回目まで普通→10回目で別物）。記事は3〜5回で収束。実務の初期値は3ラウンド＋停滞検知。
評価者は必ず甘い
最悪の失敗は問題を検出した上で合理化して握り潰すこと。「意図的かもしれない」「MVPとしては許容」を禁止句として明記し、既知の不良品を投げて締める。
部品は仮説
モデル更新のたびに部品を1つ外して品質が落ちるか確認する。落ちなければもう不要。実績：リセット機構、作業単位分割、単位ごとの評価が順に不要化した。
カタログには約50件。頻度の高いものを4カテゴリで抜粋。環境系（D）は自環境で実際に踏んだもの。
A 設計
症状評価者を置いたのに品質が変わらない
原因基準が曖昧で評価者の裁量になっている
症状成果物が抽象的（項目は埋まっている）
原因形骸値を検出していない → 機械検証に実例を追加（最も効く）
症状特定工程だけ品質が低い
原因その工程の担当を置いていない
B 評価者
症状ほぼ常にPASS
原因初期状態は必ず甘い → 既知の不良品でキャリブレーション
症状問題を挙げた上で見逃す
原因合理化の禁止句を書いていない
症状1枚の証拠で全項目が合格になる
原因証拠を使い切っていない
C ループ
症状少しずつ書き換わるが同じ問題が残る
原因停滞検知が成果物ハッシュだけ → 指摘の同一性も見る
症状差し戻しで全面書き換えされる
原因「指摘されていない箇所は書き換えない」が無い
症状評価者の一部が落ちて素通り
原因期待数と実数を比較するガードが無い
D 環境（Claude Code）
症状エージェントが解決できない
原因worktreeで実行、またはセッション開始時スナップショット
症状作業ディレクトリにアクセスできない
原因iCloud配下はサンドボックス拒否 → /tmp で作業する
症状機械検証が黙ってスキップされる
原因argsが文字列で届きデフォルトに落ちている
hookは教材であってセキュリティ境界ではない。Write/Editしか見ておらず、Bash経由なら素通りする。パス一致はbasenameのみで、どの証拠を読んでもどの行も解錠される。段階8として最後に足すもので、最初から入れる部品ではない。
実装済み：図解ハーネス
viz-* 13体・分担型（P3）。実運転済みで、3ラウンドでINCOMPLETE。未達が明示されたので次の一手が決まった。INCOMPLETEは失敗ではない。
実装済み：戦略ハーネス
strat-* 10体・競作型（P4）。構築・校正済みで本番未実行。ループ制御の実コードはこれが最良の参考。
候補：議事録ハーネス
mtg-* 2体。既存スキルに評価者を足すだけ（P1＋P5）。費用対効果が最も高い。設計シート記入済みの実例がプレイブックにある。
議事録ハーネスの実装順序
1
30 MIN
網羅性の検査役を1体作る
元の文字起こし全文と突き合わせ、決定事項の取りこぼしを引用つきで指摘させる。tools は Read と Grep のみ。
2
VERIFY
手動で呼んで効果を確認する
過去の議事録に対して回し、取りこぼしが実際に出るか見る。ここで効かないなら設計を見直す。
3
EXPAND
体裁軸を足してループ化
担当・期限・表記の軸を別エージェントに分け、SKILL.md に差し戻しループと停止条件を書く。