| 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 つ以上の責務を持つ。
- ディレクトリ構造から依存関係を読み取れない。
これらのシグナルが解消され、必要な責務・依存関係・名前をコードから読み取れる状態を目指します。
作業手順
code-refactor で改善シグナル、既存の振る舞い、公開契約、関連テストを分析し、その結果を根拠に modification-design の出力形式で変更後の構造を設計する。- Modification Design を
role-planner に引き継ぎ、実装に必要なゴール、スコープ、Definition of Done、検証条件を整理する。
- Modification Design と Planner の成果物を
role-implementer に引き継ぎ、設計に沿った実装を依頼する。
- 実装結果を
role-reviewer に確認させ、Modification Design、Planner の完了条件、公開契約、既存の振る舞いを満たすかを検証する。
- 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 の確認結果とともに報告している。
