Claude Code の大規模リファクタを 1 コミット単位で巻き戻せる状態に保つ — チェックポイント設計とロールバック検知の実装メモ

あなたはこのリポジトリで refactor.checkpoints.yml に沿ったリファクタを行います。
今回のタスクは CP1 の範囲のみです。
 
制約:
1. CP1 の intent と invariant だけを満たす差分を作る。
   既存 OrderService のコードは 1 行も変更しない。
2. CP1 の範囲を超える変更が必要だと判断したら、実装せず
   「CP2 として提案します」と明記し、理由を 2〜3 行で書く。
3. 出力は次の JSON で返す:
   {
     "diff_summary": "変更点の要約",
     "invariant_check": "CP1 の invariant を破っていないことの根拠",
     "almost_broke": "範囲外に手を出しかけて踏みとどまった箇所（必ず1つ以上）"
   }

#!/usr/bin/env bash
# .git/hooks/pre-push — 大規模リファクタの粒度を機械的に守らせる
set -euo pipefail
 
MAX_LINES=300
range="origin/main..HEAD"
 
# 1) 各コミットがチェックポイント ID を含むか
bad_msg=$(git log --format='%H %s' $range | grep -viE 'CP[0-9]+' || true)
if [ -n "$bad_msg" ]; then
  echo "✗ チェックポイント ID (CP1 等) のないコミットがあります:"
  echo "$bad_msg"
  exit 1
fi
 
# 2) 1 コミットあたりの変更行数が上限を超えていないか
while read -r sha; do
  lines=$(git show --stat --format='' "$sha" | tail -1 | grep -oE '[0-9]+ (insertion|deletion)' \
          | grep -oE '[0-9]+' | paste -sd+ - | bc)
  lines=${lines:-0}
  if [ "$lines" -gt "$MAX_LINES" ]; then
    echo "✗ コミット ${sha:0:8} は ${lines} 行（上限 ${MAX_LINES}）。分割してください。"
    exit 1
  fi
done < <(git rev-list $range)
 
# 3) 各コミット時点でビルドが通るか（任意・重い場合は CI 側へ）
echo "✓ 粒度チェック通過"

この diff は約 XXX 行でレビューが困難です。次のルールで分割案を作ってください。
 
- 1 コミット目: 型定義と空実装のみ（振る舞いは変えない）
- 2 コミット目: 旧処理を新型に寄せるが、呼び出し元は変えない
- 3 コミット目: 呼び出し元を新抽象へ切り替える
- 4 コミット目: 旧実装を削除する
 
必須条件: 各コミットを単体で適用した時点でアプリがビルド・起動できること。
保証できない分割案は出力しないでください。

この変更について次の 3 点をセルフレビューしてください。
1. 既存コードが暗黙に依存していた契約で、今回壊している可能性のあるもの
   （例: 例外の伝播経路・ログフォーマット・初期化順序・null の扱い）
2. テストが無いが、本番で壊れると痛い経路
3. 1・2 のうち、あなた自身が自信を持てない箇所（ゼロ回答は禁止・最低 1 つ）

# rollback_check.py — マニフェストの閾値で戻すべきか判定する
import sys, yaml, statistics
 
cp = yaml.safe_load(open("refactor.checkpoints.yml"))
sig = cp["rollback_signals"]
 
def p95(series):
    s = sorted(series)
    return s[min(len(s) - 1, int(len(s) * 0.95))]
 
# before/after は監視基盤から取得した同区間のサンプル
before_lat = [...]   # デプロイ前の応答時間(ms)
after_lat  = [...]   # デプロイ後の応答時間(ms)
after_err  = ...     # デプロイ後のエラー率(%)
 
reasons = []
if p95(after_lat) > sig["p95_latency_ms"]:
    reasons.append(f"p95={p95(after_lat)}ms > {sig['p95_latency_ms']}ms")
if after_err > sig["error_rate_pct"]:
    reasons.append(f"error_rate={after_err}% > {sig['error_rate_pct']}%")
 
# 形の変化も見る: 中央値が 20% 以上右へ寄ったら警告
if statistics.median(after_lat) > statistics.median(before_lat) * 1.2:
    reasons.append("中央値が 20% 以上悪化（テスト緑でも要確認）")
 
if reasons:
    print("⟲ 直前チェックポイントへ戻す候補:")
    print("\n".join(reasons))
    sys.exit(1)
print("✓ ロールバック不要")