workflow-checkpoint-refactor

/workflow:checkpoint-refactor

コンテキストの上限やセッションの境界を越えて状態を保持する、複数フェーズにわたるリファクタリングです。

このスキルを使用する場面

このスキルを使用する場合...	代わりに直接リファクタリングする場合...
10 個以上のファイルにまたがるリファクタリング	1～5 個のファイルを変更する
作業がコンテキストの上限を超える	小規模で対象を絞った変更
セッションをまたいで作業を再開する必要がある	1 回のセッションで完了するタスク
複数の依存するフェーズがある	ファイルごとに独立した変更
大規模なリファクタリングでチームとの連携が必要	個人で行う簡単な修正

コンテキスト

• リポジトリのルート: !git rev-parse --show-toplevel
• プランファイルの有無: !find . -maxdepth 1 -name REFACTOR_PLAN.md
• Git のステータス: !git status --porcelain
• 最近のコミット: !git log --oneline --max-count=5

パラメーター

• --init: 対話形式で新しいリファクタリングプランを作成します
• --continue: 最後に完了したフェーズから再開します
• --status: 現在のプランの進捗状況を表示します
• --phase=N: 特定のフェーズを実行します

プランファイルの形式

プランファイル（REFACTOR_PLAN.md）は、永続的な状態を保持します。これはループのコンパクトな状態パケット（.claude/rules/loop-integrity.md）です。新しいセッションや、以前のフェーズの記憶がないサブエージェントが、このファイルだけを使って作業を再開できなければなりません。そのため、各フェーズには、実行する内容だけでなく、検証済みの内容と変更内容も記録します。これらが記録されていなければ、コンテキストの上限を越えて作業を再開した際に、作業が気付かないうちにやり直されたり、取り消されたりするおそれがあります。

# Refactor Plan: {description}

Created: {date}
Last updated: {date}
Base commit: {hash}
Exit condition: {the literal criterion that ends the whole refactor — e.g. "all phases done, full suite + tsc green on base"}

## Overview
{What is being refactored and why}

## Phase 1: {phase name}
- **Status**: done | in-progress | pending | needs-review
- **Files**: file1.ts, file2.ts, file3.ts
- **Description**: {what this phase does}
- **Acceptance criteria**: {how to verify success — the phase's exit condition}
- **Verifier result**: {what the independent check returned — PASS/FAIL + the criterion it judged; filled in at the phase boundary}
- **Changed since last run**: {what this phase actually touched, so a successor doesn't redo or undo it}
- **Result**: {summary of changes made, filled in after completion}

## Phase 2: {phase name}
- **Status**: pending
- **Files**: file4.ts, file5.ts
- **Description**: {what this phase does}
- **Acceptance criteria**: {how to verify success}
- **Verifier result**: {empty until verified}
- **Changed since last run**: {empty until completed}
- **Result**: {empty until completed}

...

実行

次の複数フェーズにわたるリファクタリングのワークフローを実行します。

ステップ 1: リファクタリングプランを初期化する（--init モード）

--init フラグが指定された場合：

1. 範囲を分析する：リファクタリング対象のファイルを読み、依存関係を把握します
2. 次の条件を満たすフェーズを定義します：
   • 3～7 個のファイルを対象とする（範囲を限定）
   • 明確な受け入れ基準（テスト、型チェック）がある
   • 個別にコミットできる
   • 前のフェーズを土台とする
3. プランファイルを作成する：リポジトリのルートに REFACTOR_PLAN.md を作成します
4. ベースコミットを記録する：git log --format='%H' -1

フェーズの順序：最初に共有ユーティリティと型を扱い、最後にリーフコンポーネントを扱います。テストは実装と同時に行います。

ステップ 2: 既存のリファクタリングを再開する（--continue モード）

--continue フラグが指定された場合：

1. REFACTOR_PLAN.md を読みます
2. 次に保留中のフェーズ（ステータスが pending または needs-review）を見つけます
3. それ以前のすべてのフェーズが done であることを確認します
4. フェーズを実行します（ステップ 4 に進みます）

ステップ 3: 進捗を確認する（--status モード）

--status フラグが指定された場合：

1. REFACTOR_PLAN.md を読みます
2. プランを解析し、フェーズ、説明、ステータス、ファイル数を含むステータステーブルを表示します
3. 終了します

ステップ 4：対象フェーズを実行する（--phase=N またはステップ 2 で選択）

各フェーズで：

1. 計画ファイルからコンテキストを読み取ります（現在のフェーズの詳細）
2. このフェーズで指定されているファイルだけを読み取ります
3. フェーズの説明に従って変更を実装します
4. 適切なツール（tsc、ty check、cargo check、または npm/pytest test）で検証します
5. 検証に失敗した場合：
   • 簡単に直せるエラーは修正します
   • 複雑な場合は、エラーの詳細とともにフェーズを needs-review にします
   • 部分的な作業を WIP: プレフィックス付きでコミットします
6. 検証に合格した場合、受け入れ基準が判断を要するもの（例：「クラスの責務が単一になっている」）であり、単なる機械的なチェックではないときは、独立した検証者による確認を完了の条件とします（テストスイートが成功している、または tsc がクリーンであることは、すでに独立した確認です。テストは、どれだけ懸命に作業したかを考慮しません）：
   • このフェーズの受け入れ基準と変更差分だけを読み取り、ワーカーの推論は参照せずに基準を満たしているかを判断する、新しい Task サブエージェントを起動します。ワーカーは完了と判断する方向に偏るため、ループの停止条件はループの外部から与える必要があります（.claude/rules/loop-integrity.md、原則 1）。基準が動作（「エンドポイントが X を返す」「バグが再現しなくなった」など）に関するものの場合は、これを agent-patterns-plugin:execution-grounded-review に委任します。このエージェントは、外観ではなく実行時の証拠に基づいて各基準を評価するために、まずテストスイートを実行します。
   • 判定結果を、フェーズの Verifier result フィールドに記録します（PASS/FAIL と、判定した基準）。
   • 検証者が FAIL を返した場合は、ステータスを in-progress／needs-review のままにし、done にする前に不足点を解消します。
7. 検証が済んだら、計画ファイルを更新します。ステータスを done にし、Verifier result、Changed since last run、Result を記入してから、次のようにコミットします： git add -u && git commit -m "refactor phase N: {description}"
8. フェーズが残っている場合は、次のフェーズに進むか、--continue を提案します

ステップ 5：サブエージェントへの委任（規模の大きいフェーズ向け）

ファイルが 7 個以上あるフェーズでは、以下を指定して Task サブエージェントに委任します：

• 変更するファイルの一覧
• フェーズの説明と受け入れ基準
• 指示：検証を実行し、計画ファイルを更新して、変更をステージング／コミットする
• 検証に失敗した場合：エラーの詳細とともにフェーズを needs-review にする

復旧パターン

状況	対応
フェーズの途中でコンテキスト上限に達した	新しいセッションを開始し、--continue を実行します
フェーズが needs-review になった	計画で詳細を確認し、問題を修正して、--phase=N を実行します
フェーズ後にテストが失敗する	フェーズのコミットを取り消し、原因を調査して、再実行します
計画の調整が必要	REFACTOR_PLAN.md を直接編集し、フェーズを更新します
ベースブランチが移動した	新しいベースにリベースし、完了済みのフェーズを再検証します

エージェント最適化

コンテキスト	コマンド
計画ファイルの存在を確認	test -f REFACTOR_PLAN.md && echo "exists"
簡易型チェック	npx tsc --noEmit --pretty 2>&1 | head -20
簡易テスト	npm test -- --bail=1 2>&1 | tail -20
フェーズのコミット	git commit -m "refactor phase N: description"
作業状態を確認	npx tsc --noEmit && npm test -- --bail=1
計画のフェーズを表示	grep "^## Phase" REFACTOR_PLAN.md
フェーズのステータスを表示	grep -A1 "^## Phase" REFACTOR_PLAN.md | grep Status

クイックリファレンス

操作	コマンド
新しいリファクタリングを初期化	/workflow:checkpoint-refactor --init
進捗を確認	/workflow:checkpoint-refactor --status
作業を再開	/workflow:checkpoint-refactor --continue
特定のフェーズを実行	/workflow:checkpoint-refactor --phase=3
計画を手動で編集	REFACTOR_PLAN.md を直接編集する

関連スキル

• code-review-checklist - リファクタリングされたコードをレビューします
• refactoring-patterns - リファクタリングの手法
• adversarial-review - 判断ベースのフェーズゲートが委任する、独立した検証者
• execution-grounded-review - 動作ベースのフェーズ受け入れ基準に対する、実行結果に基づく検証者
• .claude/rules/loop-integrity.md - 計画ファイルが状態パケットである理由と、done が独立して判定される理由