refactor

リファクタリングワークフローのスキル

概要

既存コードを改善するための2つのトラックからなるワークフローです。小規模で範囲が限定されたリファクタリングにはポリッシュトラック、アーキテクチャの変更や移行にはオーバーホールトラックを使用します。どちらのトラックでも、着手を決める前の調査と、ドキュメントの更新を必須としています。

トリガー

次の場合にこのスキルを有効にします：

• ユーザーが {{COMMAND_PREFIX}}refactor コマンドを実行した
• ユーザーが既存コードの構造を改善したい
• ユーザーが「refactor」、「restructure」、「clean up」、「migrate」と言及した
• ユーザーがコードの「移動」、「抽出」、「名前変更」、「再編成」を依頼した

使い分け： ユーザーが「fix」または「clean up」と言った場合、コードは動作するものの構造を改善する必要があるなら {{COMMAND_PREFIX}}refactor を使用します。何かが壊れている（エラー、クラッシュ、誤った動作）場合は {{COMMAND_PREFIX}}debug を使用します。

ワークフローの概要

                              {{COMMAND_PREFIX}}refactor
                                  |
                            +-----+-----+
                            |  Explore  |
                            +-----+-----+
                                  |
                   +--------------+--------------+
                   |                             |
              --polish                       (default)
                   |                             |
                   v                             v
          +--------------+              +--------------+
          |    Polish    |              |   Overhaul   |
          |    Track     |              |    Track     |
          +--------------+              +--------------+

コマンドインターフェース

リファクタリングワークフローを開始する

# Default: overhaul track
{{COMMAND_PREFIX}}refactor "Description of what needs refactoring"

# Fast path: polish track
{{COMMAND_PREFIX}}refactor --polish "Small contained refactor description"

# Explore first, then decide track
{{COMMAND_PREFIX}}refactor --explore "Unsure of scope, explore first"

ワークフロー中のコマンド

# Switch from polish to overhaul (during explore/brief)
{{COMMAND_PREFIX}}refactor --switch-overhaul

# Resume after context compaction
{{COMMAND_PREFIX}}rehydrate

トラックの比較

項目	ポリッシュ	オーバーホール
範囲	<=5 ファイル、単一の関心事	制限なし
ワークツリー	なし（直接作業）	あり（分離）
委任	なし	あり（ワークフロー全体）
ドキュメント	必須の更新フェーズ	必須の更新フェーズ
人によるチェックポイント	0	1（マージ）

refactor と debug の使い分け

判断材料	{{COMMAND_PREFIX}}refactor を使用	{{COMMAND_PREFIX}}debug を使用
コードは動作するが、乱雑または複雑	はい	いいえ
何かが壊れている、または誤っている	いいえ	はい
「再編成すべき」	はい	いいえ
ユーザーからバグやリグレッションの報告がある	いいえ	はい
パフォーマンスの低下	構造上の問題なら {{COMMAND_PREFIX}}refactor に切り替える	{{COMMAND_PREFIX}}debug から開始する（調査）
動作するコードにおける SOLID 原則違反	はい	いいえ
本番環境のログにエラーがある	いいえ	はい

判断の目安： 動作するコードへの 不満（読みづらい、SOLID 原則に違反している、ロジックが重複している）がある場合は、{{COMMAND_PREFIX}}refactor を使用します。症状（動作するはずのものが動作しない）がある場合は、{{COMMAND_PREFIX}}debug を使用します。

特性テスト（両トラック共通）

既存コードの動作を変更する前に、特性テストで現在の動作を記録します。これは両トラックで必須の事前ステップです：

1. 変更前： コードが現在どのように動作しているか（どう動作すべきかではなく）を記録するテストを書きます。代表的な入力を使い、最も適切な観測可能な接点（API、CLI、統合境界、関数）を通じてコードを実行し、実際の出力や作用を検証します。
2. 変更中： 特性テストが失敗した場合は、動作が変わったことを意味します。意図的な変更か、偶発的な変更かを評価します。
3. 変更後： どの特性テストの失敗が想定どおりだったかを記録します。残りの特性テストはリグレッションテストになります。

これは、Michael Feathers が Working Effectively with Legacy Code で示したアプローチに沿ったものです。変更する前に、動作を理解します。

オラクルの完全性チェック（両トラック共通）

特性テストは、動作が変わったかどうかを知らせる安全網であるオラクルです。リファクタリング中にオラクルを編集しない場合にのみ、この安全網は機能します。リファクタリングを完了する前に、テストの差分を確認します：

git diff -- tests/

リファクタリング中にテストオラクルへ追加すること（新しい特性テストや新しいケース）はできますが、既存の特性テストのアサーションを、気づかれないように変更してはなりません。オラクルを気づかれないように編集すると、安全網が無効になります。テストは変更後の動作に対して成功するようになり、特性テストが検出するはずだったリグレッションが隠されてしまいます。特性テストのアサーションを本当に変更する必要がある場合、それは動作の変更です。そのことを明示して理由を説明し、リファクタリングの差分に何の説明もなく含めないでください。

設計時の制約（両トラック共通）

brief フェーズでは、アプローチを決定する前に、リファクタリングに関係するアーキテクチャ上の不変条件に基づいた制約セクションを提示してください。これは、リファクタリングにおける設計時の /ideate のフェーズ 0 に相当し、選択ルールには同じ単一の信頼できる情報源を使用します。詳しくは @skills/ideate/references/constraint-anchoring.md を参照してください。.exarchos/invariants.md のエントリ（cost-of-load: always-load）を読み込み、制約セクションを出力してください。カタログ登録が条件です。 .exarchos.yml: invariants.catalogs にカタログが登録されていない場合は、制約セクションを出力せず、そのまま進めてください。brief フェーズでの配置については、@skills/refactor/references/brief-template.md を参照してください。

Polish トラック

小規模で範囲の限定されたリファクタリング（5 ファイル以下、単一の懸案事項）向けの高速パスです。オーケストレーターが直接コードを記述できます（オーケストレーターの制約に対する例外）。ワークツリーは使用せず、委任もしません。

HSM フェーズ：explore → brief → polish-implement → polish-validate → polish-update-docs → completed

各フェーズの詳細な手順、状態管理、自動チェーンの動作については、@skills/refactor/references/polish-track.md を参照してください。

Overhaul トラック

アーキテクチャの変更、移行、複数ファイルの再構成向けの厳密なパスです。ワークツリーによる分離を使った、完全な委任モデルを採用します。

HSM フェーズ：explore → brief → overhaul-plan → overhaul-plan-review → overhaul-delegate → overhaul-review → overhaul-update-docs → synthesize → completed

各フェーズの詳細な手順、スキルの呼び出し、自動チェーンの動作については、@skills/refactor/references/overhaul-track.md を参照してください。

状態管理

リファクタリングのワークフローを初期化します。

action: "init", featureId: "refactor-<slug>", workflowType: "refactor"

実行時に状態スキーマ全体を確認するには、describe を使用します。exarchos_workflow({ action: "describe", actions: ["init"] }) を実行してください。

フェーズの遷移とガード

順番に進む必要があります。 すべてのフェーズを順番どおりに通過する必要があります。後続フェーズに必要なデータがすでに揃っていても、フェーズをスキップすることはできません。たとえば、explore から overhaul-plan に進む前に、必ず brief に遷移する必要があります。explore → overhaul-plan のように直接進もうとすると、HSM によって拒否されます。brief からは polish-implement または overhaul-plan に進む必要があり、completed に直接進むことはできません。各遷移では、単一の set 呼び出しで phase パラメーターとともに送信する updates によって、ガードを満たす必要があります。各手順での正確なツール呼び出しについては、@skills/refactor/references/polish-track.md または @skills/refactor/references/overhaul-track.md を参照してください。

すべてのフェーズ遷移には、満たす必要があるガードがあります。遷移する前に、各ガードの正確な前提条件を @skills/checkpoint/references/phase-transitions.md で確認してください。

すべての遷移で、前提条件を updates に、遷移先を phase に指定して、単一の set 呼び出しを行います。

スキーマの確認

パラメーターのスキーマを確認するには exarchos_workflow({ action: "describe", actions: ["update", "init"] }) を使用し、フェーズ遷移、ガード、プレイブックのガイダンスを確認するには exarchos_workflow({ action: "describe", playbook: "refactor" }) を使用します。

判断ランブック

explore フェーズでトラックを選択する基準については、判断ランブックを照会します。 exarchos_orchestrate({ action: "runbook", id: "scope-decision" })

このランブックでは、ファイル数、構造への影響、PR の範囲に基づいて、polish トラックと overhaul トラックのどちらを選ぶかを判断するための基準を体系的に示します。

トラックの切り替え

explore フェーズまたは brief フェーズで作業範囲が polish の上限を超えた場合は、{{MCP_PREFIX}}exarchos_workflow の action: "update" を使用して、track を "overhaul" に設定し、explore.scopeAssessment.recommendedTrack を更新します。

範囲のしきい値： 影響を受けるファイルが 5 個を超える、または変更がモジュール境界をまたぐ場合は、overhaul トラックを推奨します。

切り替えの指標：

• 影響を受けるファイルが 5 個を超える
• 複数の懸案事項が特定された
• モジュールをまたぐ変更が必要
• テストカバレッジの不足により、新しいテストが必要

出力：「作業範囲が polish の上限を超えました。overhaul トラックに切り替えます。」

統合ポイント

重要： すべてのスキル呼び出しでは、明示的な Skill() ツール呼び出しを必ず使用してください。

スキル	呼び出し	使用方法
{{COMMAND_PREFIX}}plan	{{CHAIN next="plan" args="--refactor <state-file>"}}	概要からタスクを抽出
{{COMMAND_PREFIX}}delegate	{{CHAIN next="delegate" args="<state-file>"}}	TDD のためにサブエージェントをディスパッチ
{{COMMAND_PREFIX}}review	{{CHAIN next="review" args="<state-file>"}}	品質レビュー
{{COMMAND_PREFIX}}synthesize	{{CHAIN next="synthesize" args="<feature>"}}	PR の作成

アンチパターン

しないこと	代わりにすること
調査を省略する	まず必ずスコープを評価する（references/explore-checklist.md を参照）
大規模な変更に polish を使う	スコープが拡大したら overhaul に切り替える
ドキュメントの更新を省略する	ドキュメントの更新は必須（references/doc-update-checklist.md を参照）
リファクタリング中に機能を追加する	スコープクリープにつながるため、概要の目標に従う
「コードを移動するだけ」だからとテストを省略する	リファクタリングではテストによる検証が必要
polish 用に設計ドキュメントを作成する	代わりに state file の概要を使う
overhaul で main ブランチ上で作業する	worktree による分離を使う

Exarchos との統合

Exarchos MCP ツールが利用可能な場合、リファクタリングのワークフロー全体でイベントを出力します。

1. ワークフロー開始時（explore）： {{MCP_PREFIX}}exarchos_event に action: "append" を指定し、workflowType が "refactor" の workflow.started を出力します
2. トラック選択時： phase が指定された場合、exarchos_workflow の set によって自動的に出力されます。選択したトラック（polish/overhaul）を含む workflow.transition を出力します
3. 各フェーズの遷移時： phase が指定された場合、exarchos_workflow の set によって自動的に出力されます。from/to/trigger/featureId を含む workflow.transition を出力します
4. overhaul トラックのスタッキング： {{COMMAND_PREFIX}}delegate が処理します（サブエージェントは実装担当者向けプロンプトに従い、git commit と git push を使用します）
5. polish トラックのコミット： 単一の git commit -m "refactor: <description>" と git push を実行します。複数ブランチのスタッキングは不要です
6. 完了時： 終端状態への遷移時、exarchos_workflow の set によって自動的に出力されます。"completed" への workflow.transition を出力します