Incremental Refactoring

探索結果を次のセッションへ残し、一度に扱う変更を独立して検証・レビューできる単位に限定する。

1. 既存記録と依頼範囲を確認する

調査のみ、実施、再開のどれを依頼されたか読み取る。目的と許可範囲を確認し、既に許可された作業の承認を繰り返し求めない。

プロジェクト固有の候補の登録方法・保存先・更新手順は AGENTS.md に記載し、このスキルではその規約に従う。運用を新しく決める・変更する場合は、次のセッションも同じ方法で再開できるよう AGENTS.md に反映する。一時的なユーザー指定は今回の作業に優先し、恒久的な運用変更とは区別する。規約も指定もなければ、既存の refactoring-discoveries/ を使い、なければプロジェクトルートに作成する。従来の候補記録もそのまま読み、全件の形式変換や番号変更はしない。

保存先の選択と実施対象の選択を区別する。ユーザーが指定した台帳・候補集合だけを今回の対象とする。指定候補がすべて対象外でも、別の台帳や近くのシンボルで補充しない。対象外の理由を指定台帳に保存し、今回の実施対象がないことを報告する。

候補の対象・根拠・テスト状況を現在のコードと照合する。行番号だけで対象を決めない。照合した対象の古い行範囲・カバー済み表記は更新する。過去の指標や呼び出し元を現在確認できない場合は過去記録・未確認と区別し、現在の根拠として転記しない。削除済み・改善済みなら理由付きで対象外にする。既存候補で依頼を満たせる場合、全面的な再探索は不要。

2. 探索結果を保存する

対象が未指定または探索を依頼された場合に、保守上の具体的な問題を調べる。発見した候補は会話だけで終わらせず、候補記録に沿って保存する。調査のみの依頼ではソースを変更しない。

ファイルとシンボル・責務を照合して重複を統合し、既存の根拠と識別子を保持する。同名関数でも対象が違えば別候補とする。ファイル名や採番の形式は既存運用を尊重する。

並列探索を使う場合、各担当は結果を返し、集約担当だけが共有台帳を書き込む。並列機能がなくても逐次で完了する。

3. 今回の変更単位を選ぶ

原則、独立して検証・レビューできる1候補を選ぶ。このスキルを適用する場合、対象指定で探索を省略しても記録は省略しない。ソースを変更する前に、選んだ対象、目的、今回変更する範囲、完了条件を候補台帳へ保存する。既存候補がなければその対象の記録を作る。複数候補の実施依頼でも一括編集せず、一つずつ区切る。

複数ファイルでも同じ目的に不可欠なら一つの単位としてよい。別の目的の整理・バグ修正・最適化は混ぜない。途中で見つけた改善は新しい候補として保存する。

候補が大きすぎる場合は、依存順と各段の完了条件を持つ子候補へ分割する。親候補に分割先を残し、今回実施する子候補だけを選ぶ。不可分の変更を機械的にファイル数や行数で分けない。

複数候補を進める場合、未レビューの差分が積み上がらないよう、各単位を独立したPR・作業ブランチなどでレビュー可能にしてから次へ進む。公開が許可されていない場合は最初の単位までを完了し、残りと次の着手点を保存する。コミットで区切るだけで一つのPRへ全候補を積み上げない。

4. 検証しながら実施する

動作保持と範囲管理を守る。関連テストを変更前後に実行し、正常系・境界・異常系・副作用のうち、変更に関係する経路の検証根拠を確認する。

変更前に、重要な経路について「確認する振る舞い・検証方法・確認済み／未確認」を候補記録へ残す。外部処理が複数ある場合は、各処理の失敗時に後続処理が呼ばれるか、例外がどう伝わるかも具体化する。

テストが不足する場合は許可範囲で検証を補うか、変更範囲を縮める。それでも重要な振る舞いを確認できなければ、その候補を中断し、不足経路と再開条件を具体的に保存する。テスト変更禁止などユーザーの制約を優先する。テスト成功だけで全経路を検証済みとしない。

無関係な既存テストの失敗を隠さず記録し、今回の変更による失敗と区別する。関連する検証ができない場合は未検証を明示する。

変更中に依存や修正箇所が想定より広がったら、作業を追加する前に今回の境界を見直す。分離できる残りは候補へ戻す。変更を戻す必要がある場合は今回の差分だけを対象とし、ユーザーや他担当の変更を巻き戻さない。

5. 完了と引き継ぎを保存する

動作保持、改善効果、予定範囲内の差分を確認する。候補を完了に更新し、変更箇所・検証コマンドと結果・未検証範囲を保存する。中断時は理由と再開条件を保存する。完了・対象外の候補を自動削除しない。

保存後に候補記録を読み返し、現在の状態・行範囲・検証状況が一意に読めることを確認する。実施記録を末尾へ追記するだけで、古い「未着手」「カバー済み」や行範囲を現在の情報として残さない。現在の欄を更新し、保存したい旧情報は明示した履歴区画へ移す。選ばなかった候補も今回照合したなら、その照合結果と未確認事項を反映する。

最後に実施内容、今回扱わなかった候補、次の着手点を短く報告する。次のセッションは台帳を読み、現状照合から再開できる状態にする。