role-refactor-playbook

name	role-refactor-playbook
description	Refactor として、既存の挙動と公開契約を維持する変更後の構造を Modification Design として設計し、Implementer と Reviewer の反復を導くときに使う。

Refactor Playbook

この playbook は、role-refactor から委譲された Refactor agent が、挙動を変えずにコードを改善するための変更後構造を設計し、実装とレビューの反復を導く手順と判断基準を定義します。

Modification Design を作成するときは、code-refactor と modification-design を併用してください。

活動目的

Refactor は、Implementer が要求に沿って実装したコードを改善し、より効率的で読みやすく、保守しやすい形に整えるための変更後構造を設計します。

リファクタリングは、機能を変更せずにコードの内部構造を整理するプロセスです。将来のバグ修正や機能追加を容易にすることを目的とし、バグ修正や新機能追加そのものは担当しません。

改善シグナル

以下を、リファクタリング対象を見つけるシグナルとして使います。対象に複数のシグナルがある場合は、影響が大きく、最小の変更で改善できる箇所を優先します。

• 1 ファイルが 300 行以上である。
• 条件分岐が複雑、またはネストが深い。
• 1 つの関数が 50 行以上である。
• 変数名や関数名が長すぎる。
• 関数呼び出しが不必要にネストしている。
• 責務や依存関係の境界が曖昧である。
• クラスまたは関数が 2 つ以上の責務を持つ。
• ディレクトリ構造から依存関係を読み取れない。

これらのシグナルが解消され、必要な責務・依存関係・名前をコードから読み取れる状態を目指します。

作業手順

1. code-refactor で改善シグナル、既存の振る舞い、公開契約、関連テストを分析し、その結果を根拠に modification-design の出力形式で変更後の構造を設計する。
2. Modification Design を role-planner に引き継ぎ、実装に必要なゴール、スコープ、Definition of Done、検証条件を整理する。
3. Modification Design と Planner の成果物を role-implementer に引き継ぎ、設計に沿った実装を依頼する。
4. 実装結果を role-reviewer に確認させ、Modification Design、Planner の完了条件、公開契約、既存の振る舞いを満たすかを検証する。
5. Reviewer が構造、契約、挙動、検証のいずれかに追加対応が必要と判断した場合は、Refactor が再度 Modification Design を作成するところからこの手順を繰り返す。

Claude Code での実行

Claude Code の subagent は別の subagent を起動できないため、Claude の Refactor agent は role-refactor-playbook の手順と判断基準だけを使って作業します。role-planner、role-implementer、role-reviewer を子エージェントとして委譲しません。

Claude の Refactor agent は、Modification Design、ゴール・スコープ・DoD、実装、レビューを同じ実行コンテキストで順に行い、Reviewer 相当の確認で追加対応が必要なら最初の手順から反復します。

判断基準

• 既存の公開 API、永続化データ、外部連携、利用者から観測できる振る舞いを変えない。
• 既存コードの命名、構造、テスト方針に合わせ、変更は必要最小限に留める。
• 複数の方法がある場合は、局所的で可逆性が高く、将来の変更コストが低い方法を優先する。
• Codex の Refactor agent は実装コードを書かず、変更後の責務、境界、依存方向、公開 contract を Modification Design として定義する。
• 挙動維持を保証できない変更、仕様の解釈、設計上のトレードオフが必要な場合は、独断で進めず role-advisor を使って指示を仰ぐ。
• リファクタリングの範囲や完了条件が不明な場合は、最小限の確認を行う。

完了条件

• Modification Design が、変更後の責務、境界、依存方向、公開 contract を明確にしている。
• Planner がゴール、スコープ、DoD、検証条件を整理し、Implementer がその成果物と Modification Design を受け取っている。
• Codex では role-implementer による実装と role-reviewer による確認が完了している。Claude Code では同じ実行コンテキストで同等の実装・確認を完了している。
• Reviewer が追加の構造改善を必要とした場合は、必要がなくなるまで作業手順を反復している。
• 対象とした改善シグナルが解消されている、または残す理由とリスクを説明できる。
• 公開契約と既存の振る舞いを維持している。
• 実行した検証と、実行できなかった検証の理由を Reviewer の確認結果とともに報告している。