計測・ツール実行の規律

性能計測もツール実行も、失敗回避の核(exit 検証・ハーネス内 timeout・投げっぱなし禁止)は同じなので 1スキルにまとめる。ここに書くのは特定のツールやモジュールに依存しない、常に効く規律。 固有名(モジュール名・パス・既定値)は書かない — それらが変わるたびスキルが腐るため。 対象ツールの起動方法・実行環境・既定値は、スキルではなくそのリポジトリの正本ドキュメントを都度参照する。 新しい失敗を踏んだら、対応する規律があるか確かめ、無ければ規律を1行足す。

鉄則(最優先)

1. こけているタスクを待ち続けない。 前景で実行し、exit code と出力の実体を見てから成否を判断する。 外枠の exit 0 や背景タスクの完了通知を成功と誤認しない(中のコマンドが失敗しても外枠は 0 を返す)。
2. 既知の失敗を繰り返さない。 実行前に既知の失敗チェックリストを1回なぞる。同じ轍を二度踏まない。
3. 長時間処理の上限と kill はコマンド自身の中に持つ。 外側ランナー(ハーネスの実行ツール)の timeout パラメータや 自動背景化に頼らない(背景化した子プロセスはオーファン化して kill しきれないことがある)。重い処理と判断した コマンドは、同梱の run_capped.py(python3 .claude/skills/run-and-bench/run_capped.py <上限秒数> -- <コマンド...>) で包む。上限到達時は子プロセスの停止を試み、kill の成否によらず終了コード 124 で呼び出し側へ復帰する。

ツール実行

• 起動コマンドや実行環境を推測で決めない。 エントリポイント・使う仮想環境・引数を正本で裏取りしてから走らせる。
• 前景で実行し実体で検証する。 そのシェル/ランナーで正しい exit code を明示表示し(exit code の 取り方はシェルにより異なる。成否真偽と取り違えない)、生成物の実体(サイズ・更新時刻)を確認してから 報告する。投げっぱなしにせず、結論を先に書かない。
• 生成物はユーザーが見える場所に置く。 scratchpad / temp はユーザーから不可視。視聴・確認用は プロジェクトの所定ディレクトリにコピーする。
• 使い捨ての計測・検証スクリプト自体はリポジトリ直下の .scratch/ に置く。 .gitignore で 除外済みなので git add が物理的に失敗し、誤コミットを構造的に防げる。作業ツリー内(libs/・ tools/ と同階層)なので、それらへの相対 import や worktree ごとの before/after 比較はそのまま 成立する。上の「生成物は可視の場所へ」とは別物——.scratch/ はスクリプトそのものの置き場であり、 コミット対象にも視聴対象にもしない。リポジトリ直下・追跡下のパスへ一時スクリプトを置かない。
• コード変更中にベースライン/対策版を走らせない。 並行ワーカが変更後コードを再 import して 計測を汚染する。走行を止め、安定状態で取り直す。
• spawn / 再 import 型の子プロセスを使う処理のスクラッチ実行は、その言語・ランナーで必要な エントリポイントガードを必ず置く(Python なら if __name__ == "__main__":)。ガード無しはワーカが モジュールを再 import して暴走する(逐次経路では露見しないので油断しない)。

性能計測

• 指標と目的を一致させる。 速度を評価するなら wall time(補助に呼び出し回数等)、削減を評価するなら サイズ/件数。速度対策の効果を件数で測る等、指標と目的を取り違えない。
• 前後を同一条件で比較する。 評価したい1変数だけ動かし他は固定する。決定済みの前提どうしを比較しない。
• ノイズは反復で潰す。 同一プロセス内で対策を env / 変数でトグルし、ON/OFF を交互に複数回(目安3回)、 平均・最小・符号一致を見る。単発の差(±数%)で判断しない。env トグルなら spawn ワーカも import 時に 同じ値を読むので一貫する。ベースラインは対策 OFF の安定状態で取る。
• タイムボックスする。 単発計測は5分が目安(長くても10分)。重い条件はスライス縮小・対象を絞る。 上限到達時の打ち切りは、外側ランナーの timeout に頼らずコマンド自身の中で行う(鉄則(最優先))。
• 1対策ごとに前後計測し、速くならなければ却下する。 borderline・副作用大なら Codex に諮る。

判断

• 未検証の効果を断言しない。 期待だけで「〜になっているはず」と言わず、実測・実視聴で確認するまで保留する。
• 証明できる性質は証明する。 代表サンプルの結果(N 件で 0% 等)は反例の不在を保証しない。 一般則として示せるものは、サンプルで済ませず証明する。

既知の失敗チェックリスト(着手前に1回なぞる)

規律	ありがちな失敗の形
起動コマンド・実行環境を推測しない	推測の起動形/誤った仮想環境で実行して失敗
spawn はガード必須・編集中に走らせない	ワーカがモジュール再 import で暴走/編集中の走行でベースライン汚染
exit/実体で検証	外枠 exit 0・背景完了通知を成功と誤認
生成物は可視の場所へ	出力を scratchpad/temp に置きユーザーが発見できず
一時スクリプトは .scratch/ へ	リポジトリ直下や追跡パスに置き誤コミット
指標と目的を一致	速度対策の効果を件数(サイズ)で評価
確定前提どうしを比較しない	決定済みの値を別案と比べ無意味な差を出す
反復でノイズ除去	単発比較で符号が安定せず判断
上限/ kill はスクリプト内・打ち切り可能な構成	計測が時間上限を超えて止まらない/プールがオーファン化して kill 不能
未検証を断言しない	効果を実測前に「はず」と断言
証明できる性質は証明する	一般則を代表サンプルだけで済ませ反例を見落とす