> For the complete documentation index, see [llms.txt](https://livlog-llc.gitbook.io/engineering-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://livlog-llc.gitbook.io/engineering-handbook/aineitibu/24-refactoring.md).

# 24. リファクタリング

## 目的

動作確認とテストで固定した仕様を変えずに、コードの読みやすさ、変更しやすさ、責務の明確さを改善します。

## 実施する時点

探索中の実装を早い段階で抽象化すると、まだ確定していない仕様に構造が引きずられます。原則として次の順にします。

```
動作確認 → テストで仕様固定 → リファクタリング
```

明らかな安全性問題や、コンパイルできない重複は実装中に直して構いません。しかし、広い共通化やレイヤー再編は、振る舞いを確認した後に独立したタスクとして行います。

## 対象

* 意図が分かる命名への変更
* 重複処理の削減
* 長すぎるメソッドやコンポーネントの分割
* Controller、Service、Repositoryなどの責務整理
* 条件分岐やデータ変換の読みやすさ改善
* 不要になった試行コード、コメント、importの削除
* テストfixtureやヘルパーの整理

将来使うかもしれない機能の追加や、要件にない挙動変更はリファクタリングではありません。

## 仕様変更と混ぜない

リファクタリング依頼には、次を明記します。

```
既存仕様、公開API、DBの意味、画面上の振る舞いを変更しない。
仕様変更が必要だと判断した場合は実装せず、理由を報告する。
```

変更前後で同じテストが成功することを確認します。仕様変更が必要なら、別の要件、設計、タスクとして扱います。

## 差分を小さく保つ

AIは、関連箇所を見つけると広範囲を一括で整えようとする場合があります。対象ファイルまたはクラスを限定し、変更後に差分量を確認します。

差分が大きくなった場合は、次のように分けます。

1. 命名変更
2. メソッド抽出
3. 重複削除
4. 責務移動
5. テスト整理

機械的変更と意味のある変更を分けると、レビューしやすくなります。

## AIへの依頼例

```markdown
対象は `OrderService` と対応する単体テストだけです。
既存仕様と公開メソッドの入出力を変更せず、重複している検証処理を整理してください。
新しい依存関係や共通基盤は追加しないでください。
変更前後で既存テストを実行し、差分、テスト結果、仕様を変えていない根拠を報告してください。
```

## 手順

1. 動作確認とテストが完了していることを確認する
2. 改善する問題を1つ選ぶ
3. 変更対象と不変条件を明記する
4. AIに限定したリファクタリングを依頼する
5. 差分を読み、不要な変更を戻す
6. 対象テストと既存テストを再実行する
7. 必要なら性能、ログ、画面も比較する

## AIに依頼すること

* 現在の問題と改善目的に限定して変更する
* 既存仕様を変えない
* 新しい抽象化の必要性を説明する
* 変更前後のテスト結果と変更範囲を報告する

## 人間が確認すること

* 本当に読みやすく、保守しやすくなったか
* 抽象化が現在の要件に対して過剰でないか
* 仕様変更や性能劣化が紛れ込んでいないか
* 差分が大きすぎる場合に分割できるか