refactor-code Skill

概要

AIが書いたコードを、経験のある人間のエンジニアがレビューで通す水準にリファクタリングします。目的は「足すこと」ではなく**「削って明快にすること」**です。

AIのコードは、名前を言い換えただけのコメント、起こりえない状況への防御的チェック、一度しか使わない抽象化、似たテストの大量生成などで冗長になりがちです。これらを削り、読む人の認知負荷を下げます。ただし、読む前にメンタルモデルを作るためのドキュメントコメントは削らず、質を上げます。

大原則

• 外部から見た振る舞い（入出力・エラー/例外・副作用）は変えない。
• 公開APIのシグネチャは変えない。変えたい場合は提案だけにとどめる。
• プロジェクトの既存規約（ESLint / golangci-lint / dotnet format / SwiftLint / SwiftFormat / .editorconfig など）を自分の好みより優先する。
• 本体コードとテストは別パスで扱う。同時に変更すると、何が壊れたのか分からなくなるため。
• 一度に扱うのは関数・モジュール単位。大きなファイルは分割して進める。
• 1コミットにつき1種類の変更（コメント整理、インライン化、エラー処理整理など）に分ける。

実行手順

1. 基準線を記録する

着手前にテストとリンターを実行し、結果を記録します。

• 既に失敗しているものがあれば、ユーザーに報告して止まってください。
• テストが無い場合は、先に現状の振る舞いを固定するテスト（特性テスト）を書いてから進めてください。
• カバレッジとミューテーションテストを実行できるプロジェクトでは、その値も記録します（ステップ5で比較するため）。

2. 問題点を列挙する（まだ直さない）

対象コードの問題点を箇条書きでユーザーに示します。この段階ではコードを変更しないでください。先に列挙させることで、見当違いな書き換えを防ぎます。

3. 本体コードをリファクタリングする

下の「ドキュメントコメント」「読みやすくするために変えるもの」「削るもの」「削らずに残すもの」の基準に従って変更します。全言語に共通する判断基準は 読みやすさの共通原則、言語ごとの典型パターンは 言語別パターン を読んでください。迷ったときは「他の人がこのコードを理解するまでにかかる時間が短くなるか」で判断します。

振る舞いを変えないと直せない問題（バグ、公開APIの不備など）を見つけたら、直さずに報告してください。

4. 基準線と比較する

テストとリンターを再実行し、ステップ1と同じ結果であることを確認します。結果が変わったら、直前の変更を戻して原因を調べてください。

5. テストを整理する（別パス）

本体コードのコミットが済んでから、テストに取りかかります。検証している振る舞いは一切減らさないでください。

• 入力違いで同じ振る舞いを試すだけのテストはパラメータ化する（TS: it.each / Go: テーブル駆動テスト / C#: [Theory] + [InlineData] / Swift: Swift Testing の @Test(arguments:)。XCTest のみのプロジェクトでは入力と期待値の配列をループする）。
• 実装の内部手順やモックの呼び出し回数だけを検証するテストは指摘する。削除は提案のみ。
• テスト名は日本語の自然文で「条件 → 期待する結果」を表す。
• 最後に「旧テスト → 新テスト」の対応表を出す。
• カバレッジとミューテーションスコアを整理前後で比較し、下がっていないことを確認する。

6. 報告する

消したものと、判断に迷って残したものを短く報告します。行数が減らなかった場合は、その理由を書いてください。

ドキュメントコメント

JSDoc / Go の doc コメント / XML ドキュメントコメント / Swift の /// ドキュメントコメント（DocC）は、人間が関数本体を読む前にメンタルモデルを作るための情報です。削らずに質を上げてください。

• 公開関数・型には必ず残す。
• 書く内容: 目的、前提条件、戻り値の意味、エラー/例外の条件、副作用、設計上の理由。
• 消す内容: 関数名や引数名をそのまま言い換えただけの記述。
• 非公開関数は、名前だけで意図が伝わらない場合のみ書く。
• 行内コメントは「なぜ」を書く。「何をしているか」の言い換えは消す。

読みやすくするために変えるもの

• 早期return・ガード節でネストを浅くする。
• 長い関数は、本来の目的と無関係な下位問題を名前を付けて切り出す。一度しか使わなくても本来の目的が読みやすくなるなら切り出し、読みやすくならない細切れ関数は作らない。
• 名前は短く具体的にする。スコープが狭いほど短くてよい。

削るもの

• 内部の呼び出し同士での防御的チェック（内部は信頼する）
• 例外/エラーを握りつぶすだけの処理、意味のないログ出力
• 一度しか使わず、名前が新しい情報を足していない関数・クラス・インターフェース（インライン化する）
• 将来のための汎用化、未使用の引数や設定項目
• 重複処理、不要な中間変数（式の意図を名前で伝える説明変数・要約変数は残す）

削らずに残すもの

• 外部入力・公開APIの境界でのバリデーション
• 運用で必要なログ（エラーの原因追跡、監査）
• テストのモック境界やDIの差し替え点になっているインターフェース

他のスキルとの関係

refactor-code は既存コードの整理を担当するスキルです。品質ゲート（フォーマット・カバレッジ・ミューテーションテストなど）の合格ラインはこのスキルの範囲外です。ステップ4・5の確認には、プロジェクトの品質ゲートの基準を使ってください。

TDDで新しく実装する場合のRefactorフェーズも、このスキルの範囲外です。このスキルは、すでに書かれたコードをまとめて整理するときに使います。

サンプル対話

User: AIに書かせたこのサービス層、冗長なので整理してください。

Agent: まずテストとリンターを実行して基準線を記録します。全テスト通過を確認しました。問題点は「引数名を言い換えただけのXMLドキュメントコメントが12箇所」「実装が1つしかない IUserMapper」「内部呼び出しへの重複したnullチェック」です。まだ直していません。この方針で進めます。

User: ドキュメントコメントは消さないでほしいです。

Agent: 公開メソッドのドキュメントコメントは残し、言い換えだけの記述を「例外の条件」「副作用」など読む前に知りたい内容に書き直します。

User: テストが340個もあって読めません。

Agent: 本体のコミットが済んでから別パスで整理します。入力違いだけのテストは [Theory] にまとめ、最後に旧テストと新テストの対応表と、整理前後のミューテーションスコアを出します。