xp-harness: Skill for Claude Code

harness 検証 — skill / subagent / instruction の発火・振る舞いの事実確認

なぜこの skill があるか

skill / subagent / instruction を改修しても、それが実際に発火するか・意図どおり振る舞うかは transcript を観測しないと分からない。検証の手段は、対象が配布物か改修者向けかで決まる — 配布物 (.apm/ 配下) は sandbox に deploy されるので sandbox で走らせて見る。改修者向け (project root の CLAUDE.md や .claude/ 直置きの skill) は sandbox に deploy されないので、本番の実運用セッションの解析でしか観測できない。この検証のやり方 (sandbox の作り方、起動の仕方、transcript の場所と解析方法) はノウハウの塊で、skill 化しないと検証のたびにゼロから再発明することになる。

ここで言うのは「検証」= 仕組みが意図どおり動いたか（sandbox: 的は改修が定める＝既知）・あるべき振る舞いができているか（本番: 的＝理想を自分で立てて照らす）の確認。核は「できた / できていない」の事実確認。加えて本番セッションでは自走の 良し悪し（止まり方が妥当だったか・判断の質など）まで踏み込んでよい ── ただし二つを守る: 評価は必ず 証拠に接地する（印象・自己分析でなく生 transcript で裏を取る）、点数化・ランク・ベンチには逃げない（偽の精度を生むので扱わない）。当初は良し悪しを扱わない線だったが、観点を型にできる知見が溜まったので拡張した（下記「本番の実運用セッションを見る場合」）。

検証の構造 (全部これの同型)

状態を仕込む → 改修者が Claude Code を起動して走らせる → transcript を解析して発火・振る舞いを観測 → 後片付け

仕込む状態の大きさが検証の目的で変わるだけ。skill の連鎖発火だけならプローブ一式、実フェーズの振る舞いなら要件定義・基本設計 md を置いた途中状態を仕込む。

（上は sandbox で自分が走らせる場合。既に走った 本番の実運用セッション を分析する場合は「状態を仕込む・走らせる」が無く、下記に従う。）

本番の実運用セッションを見る場合 (sandbox でなく、既に走った実運用)

sandbox 検証は「改修した skill が発火・動作するか」で 的が既知（何を確認するかは改修が決める）。一方、本番の実運用セッション（実際のユーザーの自走など）を解析するときは、的が開いている（何を見るべきか自体が定まっていない）。だから最初に 的＝理想を立てる のが最重要ステップになる。仕込み・起動は無く、既に走った transcript を解析するだけ。

理想を先に確定する (最重要・ここを飛ばさない)

• まず分析対象のフェーズ / 範囲を絞る: 実運用セッションは要件定義 → 基本設計 → 実装と複数フェーズ（＝複数 skill）をまたぐのが普通。全部を一度に見ようとせず、見たいフェーズを 1 つ選び、それを統べる skill に絞る。
• 理想は skill の本文から立てる: 対象の実走を統べる skill（実装フェーズなら slice-tdd、E2E なら e2e 等）の 実際の記述を読み、そこから「あるべき振る舞い」を導く。記憶・想像で立てない（skill の文言と食い違い、照合が的外れになる）。
• 照らす版を決める: skill は改修で動くので、対象セッションが実際に発火させた版（transcript に残る本文）に照らす。ファイル側の現在版で照らすと、実走時に無かった規律で判定してしまう。
• 依頼者と合意して固める: 理想の項目をまず短く並べ（発散）、1 項目ずつ深掘りして合意する（収束）。一人で完成形を出さない。認識がズレたまま進めない。
• 理想が固まる前に照合・判定に進まない: 的が定まる前に実走を時系列で並べても、見づらいだけで分析にならない。理想がズレると照合が全部ズレて手戻りになる。理想の各項目が「何を見るか」を決める。

理想を lens に照合する

• 確定した理想の各項目を「見る対象」にして、実走が できている / できていない を、証拠（記録上の実際の記述）付き で照らす。
• 事実（記録から取れるもの）と仮説（内部状態の推測）を分ける。自己分析・因果は捏造されやすいので、判断に効く所は生 transcript で裏を取る（下記手順 4 の「集計を真と扱わない」と同じ）。