# Refactor Mindset

> リファクタリング（構造・境界・契約の再設計を含む）の要否と進め方を、変更容易性を高める方向で判断するスキル。ローカル開発完了後に「リファクタリングして」「整理して」「きれいにして」と言われたとき、コードが理解・保守しにくいとき、Code Smell への対処が必要なときに使用する。境界の引き方・責務配置の詳細判断は module-boundary-design を使う。

- Skill: `efoo-team/refactor-mindset` (Agent Skill)
- Install (CLI): `npx skillmds@latest add efoo-team/refactor-mindset`
- Raw SKILL.md: https://api.skillmd.com/api/skills/efoo-team/refactor-mindset/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: efoo-team (https://skillmd.com/u/efoo-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/efoo-team/refactor-mindset

---


# Refactoring

構造と意図の整合をとり、変更容易性（changeability）を高める。
リファクタリングの目的は、将来の変更コストを下げること。それ以外にない。

詳細なコーディングルールではなく、「まともなエンジニアなら理解している良いコードとは何か」にフォーカスする。

## 前提: ローカル開発状態

このスキルの対象は、開発完了後でまだステージング・プロダクションに反映されていないコードである。
外部への影響を気にせず、**構造をあるべき姿に大胆に合わせられる**。

## 使用時期

- コードが理解しにくい、または保守しにくい場合
- 関数・クラスが大きすぎる場合
- Code Smellに対処が必要な場合
- コード構造のせいで機能追加が困難な場合
- ユーザーが「コードをきれいにして」「リファクタリングして」「改善して」と求めた場合

---

## リファクタリングの2つの次元

リファクタリングは以下の2つの次元で行われる。両方を意識して行う。

### 1. 内部の衛生

コードの読みやすさ・書きやすさを改善する行為。外部から観測できる振る舞いは変えない。

- 意図を伝える命名
- 重複の排除
- 関心の分離
- 不要なものの削除

### 2. 構造の再設計

責務・境界・契約・依存関係を見直し、変更容易性を高める行為。
旧来はリファクタリングと区別されていたが、AIの認知範囲と実行能力を前提に本スキルに含める。

目的は、**目の前のタスクに局所最適化された構造を壊し、将来の変更を見据えた構造へ再設計すること**にある。

AIは現在のタスクに引っ張られて局所最適なコードを作りやすい。
構造・契約・境界・データ設計を見直し、将来の変更コストを下げる方向に補正することを重視する。

---

## AI向けの原則

以下の原則は「人間」が主体で設計・コーディングしていた旧来の考え方である。
人間を上回る認知範囲と実行手数を持つAIが自律的にコードを改善する上では、これらは適用しない。

### 適用しない従来の原則

1. ~~リファクタリングは日常の開発フローの中で少しずつ行うもの~~
2. ~~「間違えようがないほど小さい変更」を1ステップとし、それを繰り返す~~

### AIが従うべき原則

**構造を観察し、不適切なら大きく変える**

些細なロジック修正や見た目の変更の際は適用不要。
変更の関連範囲を十分に調査した上で、構造・状態・境界に問題があれば根本から正す。

**中途半端を避ける**

ファイル分割や、責務移譲、分離、そのほかリファクタリングに伴いルール・規約が変更されうる場合は、
必ずこのプロジェクト全体を一度精査すること。
新しいルールや規約変更が統一を持って全体最適されることを目指す。

中途半端な変更によって例外が増える変更は避ける。
逆にやる時は一気にやる。AI前提では大規模な変更であっても一貫性が保たれるのであれば広範囲に実施すべき。

**関連変更を漏らさない**

変更に関連する部分を十分に調査し、網羅的に扱う。
一部だけ改善して他を放置すると、かえって一貫性が損なわれる。

---

## 実施フロー

### Phase 1: 内部の衛生

```
1. 理解
   コードの内容を読み、何をしているかを把握する

2. 観測
   「観測シグナル」セクションの各観点でコードを評価する

3. 仮説立案
   観測した兆候に対して「何が問題か」の仮説を立てる
   兆候の検知 → 即修正は禁止

4. 検証
   呼び出し元・依存関係で仮説を検証する

5. 処方
   仮説が正しければ適切な変更を選択する
```

### Phase 2: 構造の再設計

```
1. 目的の理解
   変更の目的・意図・範囲を理解する

2. 構造の観察
   責務、境界、依存方向、契約の形状、データ構造、命名を洗い出す

3. 境界デザイン
   機能境界・責務分離・モジュール分割を判断する
   → module-boundary-design スキルを必ず参照すること

4. 再構築
   観察結果に基づき構造を再整理・構築する
   中途半端にせず、関連範囲を一貫して変更する
```

---

## 判断原理

観測シグナルの「対応原理」列が参照する、良い構造の普遍ルール。一般論の展開ではなく判断の軸として使う。

- **結合の配置**: 結合は無くせない。変わるもの同士を一緒に、変わらないものと分離し、依存は安定側（変化が少ない側）へ向ける。循環依存は設計の誤りなので必ず解消する。境界の引き直し自体は module-boundary-design の担当。
- **意図の明確さ**: 命名は実装ではなく責務を表す。コメントが要る箇所は抽出＋意図を伝える命名で消せないか考える。命名に迷うのは設計に迷いがある兆候。
- **抽象化はコストである**: 間違った抽象を共有するより重複を許容する方がコストが低い。抽象化は可変性を「広げる」だけでなく「制限する」ことでもある。
- **複雑性の管理**: 複雑性はゼロにできない。本質的複雑性（ドメイン固有）は受け入れ、偶有的複雑性（設計のまずさ由来）は排除する。
- **転用可能性の判断**: ドメイン知識に依存しない汎用処理は転用可能性が高い。高いと判断したときだけ抽象化を検討する。

---

## 観測シグナル

判断原理の具体的な現れ方。兆候を検知したら、まず対応する原理に照らして仮説を立てる。
検知 → 即修正は禁止。

**境界・責務配置に関わるシグナルは module-boundary-design の担当。** 責務の混在（1つの関数・クラスが複数の理由で変更される）、変更の広範囲への波及、他モジュール内部構造への直接依存、循環参照、Manager / Handler / Processor などの汎用名、同じ名詞が文脈で意味を変える（Bounded Context の混線）、条件分岐が増殖する間違った抽象の共有——これらを検知したら、境界の引き直し・責務配置は module-boundary-design を参照する。本スキルは以降の、リファクタリング実行上のシグナル（重複と過剰抽象、複雑性、意図を表す命名）を扱う。

### 抽象化の兆候

| シグナル | 何を兆しているか | 対応原理 | 確認すべき質問 |
|---------|----------------|---------|--------------|
| 似た処理が複数箇所にある | 抽象化の未発見、または意図的な分岐 | 抽象化はコストである | 転用可能性は高いか。2箇所以上で実際に使われているか |
| 将来必要になるかもしれない抽象化 | 予測による過剰設計 | 抽象化はコストである | 現在の具体例だけで十分か |

### 複雑性の兆候

| シグナル | 何を兆しているか | 対応原理 | 確認すべき質問 |
|---------|----------------|---------|--------------|
| 起こり得ない状態への防御コード | 偶有的複雑性の増殖 | 複雑性の管理 | このエラーは実際に起こりうるか |
| 正常系の流れを妨げるtry-catch | 防御的コーディングの過剰 | 複雑性の管理 | 正常系の可読性を損なっていないか |
| 同じ失敗を複数層で処理している | 責務の不明瞭さ | 複雑性の管理 | どの層でこの失敗を扱うべきか |
| エラー型や意味が潰れている | 情報の喪失。呼び出し元が判断できない | 複雑性の管理 | エラーの原因と回復手段が伝わるか |

### 命名の兆候

| シグナル | 何を兆しているか | 対応原理 | 確認すべき質問 |
|---------|----------------|---------|--------------|
| 名前から責務が読み取れない | 意図の欠落 | 意図の明確さ | この名前を見て何をするか分かるか |
| コメントで補足が必要な名前 | 命名の失敗。抽出で表現できないか | 意図の明確さ | 抽出＋適切な命名でコメントを不要にできるか |

---

## アンチパターン

AIがリファクタリングで犯しやすい誤り。

- **Smellの全消し** — 兆候を欠陥と誤解し、文脈なしで修正する
- **予測抽象化** — 将来のユースケースを予想して抽象化する
- **過剰防御** — 起こり得ないシナリオにエラーハンドリングを追加する
- **部分改善** — 関連範囲の一部だけ直し、一貫性を崩す
- **命名だけの修正** — 構造問題を放置し、名前だけ変えて完了とする
- **規約の機械的適用** — 判断原理を飛ばしてパターンを当てる

---

## 完了条件

以下の条件を満たせば完了：

- 関連範囲の一貫性が保たれている
- 中途半端なルール・例外の増加がない
- 構造が意図を反映している
- 将来の変更に耐える形になっている