refactor-code

コードのリファクタリング

動作を変えずに、可読性、凝集度、保守性を向上させます。

リファクタリングのカテゴリ（/refactor code）におけるcodeエンジンです。型アーキテクチャの作業には typescript-expert（そのreferences/rules/ライブラリ）を、コンポーネント アーキテクチャにはreact-refactorを活用します。機械的なAIスロップの除去にはdeslopを、読み取り専用の構造 レビューにはstructural-reviewを使用します。

トリガー

• 関数が50行を超える
• ファイルが300行を超える
• 重複コード（3箇所以上）
• 複雑な条件分岐（ネストが3階層を超える）
• any型
• テストや理解が難しい
• 曖昧な命名や責務の混在
• 不要な抽象化、不要なコード、誤解を招くコメント

手順

1. まず動作を固定する

• 編集する前に既存のテストを読む
• 動作が不明な場合は、現在の呼び出し元と実行時の経路から動作を把握する
• API の変更を明示的に求められていない限り、公開コントラクトを維持する

2. コードベース内のパターンを調べる

コードベースから類似した実装を3つ以上見つけます。命名、エラー処理、ファイル構成、テストのスタイルを合わせます。新しい抽象化を導入する前に、既存のヘルパーを再利用します。

3. 明確さを重視してリファクタリングする

小さく段階的に、変更は一度に1つずつ行います。次の順に優先します。

1. より適切な名前を付ける
2. 関数を小さく、焦点を絞ったものにする（長いメソッドをヘルパーに切り出す）
3. 制御フローを明確にする
4. 重複を取り除く
5. 不要なコードと誤解を招くコメントを取り除く
6. 型とインターフェースを絞り込む（anyを適切な型に置き換える）
7. 定数を切り出す（マジックナンバーや文字列を置き換える）
8. サービス／コンポーネントを切り出す（ビジネスロジックをコントローラーから移動し、大きなコンポーネントを分割する）

4. 過剰な設計を避ける

• 流行しているという理由だけでパターンを導入しない
• 巧妙な間接化より、わかりやすいコードを優先する
• 実際の重複や混乱を減らせる場合に限り、抽象化を切り出す

5. 変更のたびにテストを実行する

bun run test <specific-test-file>

ヒューリスティック

• 1つの関数は1つの役割を担う
• 名前は実装の細部ではなく、意図を説明する
• コメントは、コードですでに示されている内容の繰り返しではなく、理由を説明する
• 条件分岐は、頭の中で前後を行き来せずに上から下へ読めるようにする
• 共通ロジックは1箇所にまとめる。ただし、読みにくい抽象化を招く場合は避ける

危険信号（作業を止めて再検討する）

• data、item、temp、helper、utilのような汎用的な名前
• 関数の意味を変えるブール値パラメーター
• 取得、変換、レンダリングをすべて行う関数
• 検証ロジックやマッピングロジックの重複
• 不確実さを覆い隠すコメントアウトされたコードやTODO
• リファクタリング中の動作変更
• テストの失敗
• 公開APIの変更が必要
• コードの動作が不明

チェックリスト

開始前：

• すべてのテストが成功している
• コードの動作を理解している
• 参考にできる実装パターンがある
• 現在の作業コードをコミットしている

作業中：

• 変更は一度に1つ
• 変更のたびにテストを実行する
• 公開APIを維持する
• 何をしたかだけでなく、理由を記録する

完了後：

• すべてのテストが引き続き成功する
• 動作に変更がない
• コードの可読性が向上している
• パフォーマンスが同等以上である