| name | refactoring |
| description | Executes safe, incremental refactoring with rollback capability. Triggers: refactor, restructure, extract, consolidate, decompose, move, rename, split, merge, reorganize. Covers: feature responsibility migration, store split/merge, component decomposition, utility extraction, type consolidation, dependency rule fixes. Takes optional argument: /refactoring <target-directory or instruction>
|
Safe Refactoring
段階的・巻き戻し可能なリファクタリングを実施する。
CLAUDE.md の方針を厳守すること。プロジェクト固有のコードパターンは docs/development-patterns.md を参照。
前提条件
| 参照ファイル | 用途 | スタブ時のフォールバック |
|---|
docs/project.md | コマンド | project-config.md §3 を直接参照 |
docs/architecture.md | 依存方向ルール | project-config.md §4.4 を直接参照 |
docs/development-patterns.md | コード規約 | project-config.md §11 を直接参照 |
基本姿勢
- 振る舞いを変えない — リファクタリングは外部の振る舞いを保持したまま内部構造を改善する
- 段階的に進める（各ステップでテストがグリーンであること）
- 巻き戻し可能な単位でコミットする
- 仕様が曖昧な場合は実装前に質問する（推測で進めない）
- 過剰な抽象化をしない
使い方
/refactoring <対象ディレクトリ or リファクタリング指示>
引数は省略可能。省略した場合はユーザーに対話的に確認する。
ファイルパスやディレクトリを指定した場合はその範囲をリファクタリング対象とする。
例
/refactoring src/features/assignment/ のコンポーネントを分割する
/refactoring 依存方向違反を修正する
/refactoring output/tasks/TASK_refactor_stores.md
出力先
- リファクタリングコード:
src/ 配下
- レポート: 会話内で提示
他スキルとの連携
| 前工程 | 本スキル | 後工程 |
|---|
/plan /code-review | /refactoring | /code-review /e2e-testing |
リファクタリングパターン
1. Feature 責務移動
機能モジュール間の直接依存を shared 層経由に修正する。
- 移動対象を特定（型、ユーティリティ、定数）
- 共有レイヤーの適切な場所に移動
- 元の場所からリエクスポートで後方互換を維持
- 依存方向チェックコマンド（
project-config.md に記載）で違反解消を確認
2. ストア分割・統合
- 永続化キーを維持する
- スキーマの構造変更時は optional で追加（後方互換）
- ストア間参照の整合性を確認
3. コンポーネント分解
- Container（ストア/hooks使用）と Presentational（props のみ）を分離
- Container は pages ディレクトリまたは feature トップに配置
- Presentational は components ディレクトリに配置
- 分解後も同じ props インターフェースを維持
4. 共有ユーティリティ抽出
- 複数 feature で使用されるロジックを共有レイヤーに移動
- 元の場所からリエクスポートで後方互換を維持
- テストも合わせて移動または参照を更新
5. 型定義の整理
- バリデーションスキーマからの型導出に統一
- 手動定義の型とスキーマの乖離を解消
- 共有型定義ディレクトリに集約
6. 依存方向違反の修正
- 依存方向チェックツールで違反を検出
- アーキテクチャの依存方向ルール（
project-config.md に記載）に沿って修正
リファクタリングワークフロー
Phase 0: 前提条件確認
既存テストが全件パスしていることを確認する（リファクタリング開始のベースライン）。
プロジェクトの検証コマンド（docs/project.md 参照）を実行する。
全件パスしない場合はリファクタリングを開始しない。先に既存の問題を修正する。
Phase 1: スコープ分析
- 影響範囲の特定 — 変更対象ファイルと依存ファイルを一覧化
- 依存関係の把握 — 依存方向チェックで現状の依存グラフを確認
- テストカバレッジの把握 — カバレッジベースラインを記録
- リスク評価 — 影響範囲の大きさに応じてステップ分解の粒度を決定
Phase 2: リファクタリング計画
- リファクタリングをステップに分解（各ステップがテスト可能な単位）
- ステップ間の依存関係を明示
- 巻き戻しポイントを設定
🚏 設計ゲート: リファクタリング計画を提示し、確認を待つ
Phase 3: 段階的実行
各ステップで以下を繰り返す:
- コード変更を実施
- テスト実行
- 静的解析
- 依存方向チェック
- テストがグリーンであることを確認
テストが失敗した場合: 原因を特定し修正する。修正できない場合はステップを巻き戻す。
Phase 4: 完了確認
- 全体検証: プロジェクトの検証コマンドをすべて実行
- カバレッジ比較: Phase 1 のベースラインと比較（低下していないこと）
- ドキュメント更新: 下記「ドキュメント同期」に従い
docs/ を更新
🚏 完了ゲート: 完了レポートを提示
出力契約
セクション定義
| セクション | 必須 | 制約 |
|---|
| 概要 | ✅ | パターン名（列挙値）, 変更ファイル数, ステップ数 |
| ステップ別実行結果 | ✅ | 全ステップをテーブルで一覧化 |
| Before/After品質比較 | ✅ | 4指標（テスト件数, カバレッジ, 依存方向違反, 循環依存）必須 |
| 変更サマリー | ✅ | 4分類（移動, 新規, 削除, リエクスポート）で整理 |
| ドキュメント更新 | ✅ | 更新した docs/ ファイルと変更内容 |
パターン列挙値
| パターン | 適用場面 |
|---|
| Feature責務移動 | 機能間の直接依存を共有層経由に修正 |
| ストア分割 | 1ストアを複数ストアに分離 |
| ストア統合 | 複数ストアを1ストアに統合 |
| コンポーネント分解 | 巨大コンポーネントをContainer/Presentationalに分離 |
| 共有ユーティリティ抽出 | feature固有ロジックを共有レイヤーに移動 |
| 型定義整理 | 手動型定義のスキーマ導出への統一 |
| 依存方向違反修正 | 依存チェックツール違反の解消 |
語彙制約
| 用語 | 定義 |
|---|
| ステップ | テスト可能な最小の変更単位 |
| 巻き戻し | ステップの変更を git checkout で取り消すこと |
| リエクスポート | 移動元から移動先への export { X } from '...' による後方互換維持 |
| ベースライン | Phase 0で記録した品質指標の初期値 |
構造制約
- ステップは番号順（1, 2, 3...）で記述
- Before/Afterの変動列は符号付き（
+3, -2, ±0）
- 変更サマリーのファイルパスは
src/ からの相対パス
- カバレッジが低下した場合はその理由を付記する
レポートフォーマット
# リファクタリングレポート: [対象の概要]
## 概要
- パターン: [列挙値から選択]
- 変更ファイル数: X
- ステップ数: Y
## ステップ別実行結果
| # | ステップ | テスト | 静的解析 | 依存方向 | 状態 |
| - | -------- | ------ | -------- | -------- | ---- |
| 1 | [内容] | pass | OK | OK | 完了 |
## Before / After 品質比較
| 指標 | Before | After | 変動 |
| ---- | ------ | ----- | ---- |
| テスト件数 | X | Y | +Z |
| カバレッジ（行） | X% | Y% | +Z% |
| 依存方向違反 | X | Y | -Z |
| 循環依存 | X | Y | -Z |
## 変更サマリー
- 移動: [ファイル一覧]
- 新規: [ファイル一覧]
- 削除: [ファイル一覧]
- リエクスポート: [ファイル一覧]
## ドキュメント更新
- [更新した docs/ ファイルと変更内容]
ドキュメント同期
リファクタリング後、影響を受ける docs/ ファイルを必ず更新する。
| 変更内容 | 更新対象 |
|---|
| feature追加・削除・リネーム | docs/architecture.md |
| コンポーネント追加・削除・移動 | docs/architecture.md |
| テストファイル追加・削除・移動 | docs/architecture.md |
| 共有レイヤー変更 | docs/architecture.md |
| ストア追加・分割・統合 | docs/project.md |
| ルート追加・変更・削除 | docs/project.md |
| スキーマのフィールド追加・変更 | docs/data-model.md |
| コードパターン・落とし穴の発見/変更 | docs/development-patterns.md |
Git操作
--no-verify は使用禁止（pre-commit / pre-pushフックを迂回しない）- フック失敗時はエラーの原因を修正する
--force は原則禁止- 各ステップ完了時に巻き戻し可能なコミットを作成する
禁止事項
- テストがグリーンでない状態でのリファクタリング開始
- 振る舞いの変更を伴う変更（それはリファクタリングではなく機能変更）
- 後方互換を壊す変更（リエクスポートなしでの移動）
docs/development-patterns.md に記載されたアンチパターンの使用--no-verify によるフック迂回
