request-refactor-plan

request-refactor-planスキルの概要

request-refactor-planが実際にしてくれること

request-refactor-plan は、あいまいなリファクタリングの発想を、レビュー可能でスコープが明確な、段階的実行プランへ落とし込み、GitHub issueとして起票できる形に整えるためのスキルです。いきなりコード変更に入るのではなく、ユーザーへのヒアリング、リポジトリ調査、選択肢の比較、スコープ定義、テスト観点の確認、そしてコミット単位のロールアウト計画まで、エージェントを順序立てて導きます。

このスキルが最も向いているケース

request-refactor-plan は、コードベースの一部を整理し直す必要があること自体は分かっているものの、まだ安全に進めるための実行計画が固まっていない開発者やチームに向いています。特に次のような場面で有効です。

• 実装を始める前にリファクタリングの準備をしたい
• リファクタリング用のRFCやissueを書きたい
• リスクの高い整理作業を、小さく巻き戻し可能なコミットに分解したい
• 作業前にスコープ、制約、テスト方針を明確にしたい

本当に解決している仕事

このスキルの価値は、単に「リファクタリング計画を生成する」ことではありません。重要なのは、先に適切な質問をさせ、コードベースを確認させ、安全に実行できる大きさまで計画を絞り込むことで、リファクタリングのリスクを下げる点にあります。スコープが不明確、依存関係が見えない、変更が膨らみがち、といった状況では、一般的なプロンプトよりも request-refactor-plan のほうがはるかに適しています。

request-refactor-planが他と違う理由

最大の違いは、ワークフローの規律にあります。request-refactor-plan は進め方に明確な考え方を持っており、順序を重視します。

1. 問題の詳細を集める
2. リポジトリ内で前提を確認する
3. 代替案を検討する
4. 実装上の詳細をヒアリングする
5. スコープ内外を定義する
6. テストカバレッジとテスト計画を確認する
7. 作業を小さなコミットに分割する
8. 結果をGitHub issueとしてまとめる

この構造があるため、request-refactor-plan for Refactoring は、単発で「計画を書いて」と頼むより実務に使いやすくなっています。

インストール前に知っておくべきこと

このスキルは軽量です。リポジトリ上で確認できる実体は SKILL.md のみで、追加のスクリプト、テンプレート、補助ファイルは見当たりません。そのため導入自体は簡単ですが、出力の質は、渡すリポジトリ文脈とヒアリング時の回答品質に強く左右されます。補助アセット込みで高度に自動化されたプランナーを期待しているなら別物です。一方で、明快で再利用しやすい計画ワークフローが欲しいなら、かなり相性のよいスキルです。

request-refactor-planスキルの使い方

request-refactor-planのインストール

request-refactor-plan skill は、skills対応環境で次のコマンドでインストールできます。

npx skills add mattpocock/skills --skill request-refactor-plan

すでにソースを参照できる環境なら、まず request-refactor-plan/SKILL.md を確認してください。このスキルでは、そのファイル自体が実装の全体像なので、追加の補助フォルダを探し回る必要はありません。

最初に読むべきファイル

最初に見るべきなのは次です。

• SKILL.md

このスキルでは、README.md、metadata.json、rules/、resources/ のような補助ファイルは確認されていません。導入時の疑問の大半は、この単一のワークフロードキュメントから把握できます。

request-refactor-planが必要とする入力

request-refactor-plan をうまく使うには、「Xをリファクタリングして」だけでは不十分です。最初のメッセージには、少なくとも次の情報を含めるのが理想です。

• 影響を受ける領域やファイル
• 現在の問題点を開発者の言葉で説明したもの
• なぜ今それをやる必要があるのか
• 既知の制約
• 仮の解決アイデア
• 締切や互換性要件の有無
• 今すぐ実装したいのか、後続作業として計画だけ欲しいのか

弱い入力例:

• 「auth moduleのリファクタリングを手伝って。」

強い入力例:

• 「auth moduleのリファクタリング計画を作りたいです。src/auth では token parsing、session validation、HTTP concerns が混在しています。今のつらさは middleware と handler の間でロジックが重複していることで、機能追加が遅くなり、error handling も一貫しません。parsing と policy checks を分離すべきだと思っていますが、抽出で済ませるべきか、service layer を導入すべきかはまだ判断できていません。既存のAPI responseは壊せず、小さなコミットで安全に出せる計画が必要です。」

request-refactor-planの実運用フロー

実務での request-refactor-plan usage は、だいたい次の流れになります。

1. エージェントに、リファクタリング要求または計画作成をしたいと伝える
2. 問題の詳細と大まかな解決案を共有する
3. エージェントにリポジトリを調べてもらい、前提を検証させる
4. 代替案、制約、スコープに関する追加質問に答える
5. 対象コードのテスト期待値を確認する
6. 最終成果物として、小さなコミット単位まで分解したGitHub issue草案を求める

これは「投げたら終わり」のスキルではありません。設計上、ヒアリング駆動です。

あいまいな目標を良いプロンプトに変える方法

次のような構成でプロンプトを書くと、request-refactor-plan は機能しやすくなります。

• Problem: 今どこが痛いのか
• Current area: どの module、service、file が関係しているのか
• Suspected causes: coupling、duplication、ownership の曖昧さ、テスト不安定、命名の揺れ
• Constraints: backward compatibility、締切、チームの慣習
• Non-goals: 変えてはいけないもの
• Testing state: 現在のテスト状況、不足、未確認点
• Desired output: GitHub issue、RFC、またはコミット単位の計画

例:

「request-refactor-plan を使って refactor issue の準備を手伝ってください。Problem: src/payments で provider adapters と domain rules が混在しており、安全に provider を追加しづらいです。Current area: src/payments/* と checkout integration tests。Constraints: API contract の変更不可、この sprint では schema 変更不可。Non-goals: billing の再設計はしない。Testing state: adapters の unit coverage は十分だが、integration coverage は弱い。Desired output: 小さなコミットと明確なスコープ境界を持つ GitHub issue。」

リポジトリ調査が重要な理由

このスキルは、エージェントにリポジトリを探索し、あなたの前提を検証するよう明示的に求めます。これは重要です。というのも、多くのリファクタリング計画は、起票者の頭の中の理解だけを前提にした時点で失敗しやすいからです。request-refactor-plan を正しく使うとは、少なくとも次の点をエージェントに確認させることです。

• 痛みのある箇所が局所的なのか、横断的なのか
• 実際にどの module 同士が結合しているのか
• テストカバレッジが存在するか
• 「分かりやすい」解決策が、より広い変更波及を生まないか

リポジトリ調査をさせない場合、計画の質はかなり落ちると考えてください。

代替案とスコープの扱い方

このスキルのよい点は、最初に思いついた解決策を正解だと決め打ちしないことです。別案があるか、代替案のほうがよいかをエージェントが尋ねてきたり提案してきたりするのは、邪魔ではなく機能です。良いリファクタリング計画は、作業を狭めることで生まれることがよくあります。

• subsystem を再設計するのではなく、責務を1つ切り出す
• コードを動かす前にテストを改善する
• 振る舞いを変える前に境界面を切り出す
• 今の痛みを解消するのに不要な architecture 変更は後回しにする

最終成果物の見え方

request-refactor-plan guide は、少なくとも次のセクションを持つGitHub issueを想定しています。

• ## Problem Statement
• ## Solution
• commit-by-commit implementation steps
• testing expectations
• clear scope boundaries

最も価値が高いのは、文章の要約そのものではなく、小さなコミットへの分解です。ここがあることで、怖いリファクタリングが実行可能な作業に変わります。

一般的なプロンプトではなく、これを使うべき場面

計画の厳密さが必要なら request-refactor-plan を使うべきです。一般的なプロンプトでも、もっともらしい計画は返ってくるかもしれませんが、次の要件があるときはこのスキルのほうが強いです。

• 実際のリポジトリに照らした検証が必要
• スコープを明示的に詰めたい
• 実装前に代替案を洗い出したい
• テスト戦略まで議論したい
• 大きな書き換えではなく、ごく小さなコミット列に落としたい

導入時によくあるつまずき

最大のつまずきは、問題の定義が粗いことです。チームが開発者視点の痛み、制約、non-goals をきちんと説明できないと、このスキルは良い質問自体はしてくれますが、計画が抽象的なままで実行に落ちない可能性があります。実務では、「architecture をきれいにしたい」のような広すぎる依頼ではなく、実在する1つの痛みと、具体的な1つのコード領域を持ち込むのが最短ルートです。

request-refactor-planスキルのFAQ

request-refactor-planは大規模リファクタリング専用ですか？

いいえ。むしろ、中規模で一見すると簡単そうに見えるリファクタリングでこそ価値が出やすいです。大規模な変更にも有効ですが、このスキルが特に光るのは、ほどほどの整理作業が際限ない再設計に膨らむのを避けたいときです。

初心者でも使いやすいですか？

はい。問題を説明できて、コードベースに関する質問へ答えられるなら、初心者にも使いやすいです。request-refactor-plan は、特にジュニアが必要としがちな構造化を与えてくれます。ただし、リポジトリ理解そのものを置き換えるものではありません。回答が弱ければ、計画の質もそこで頭打ちになります。

request-refactor-planは、直接リファクタリングを依頼するのと何が違いますか？

直接「リファクタリングして」と頼むと、エージェントは実装に向かいやすくなります。request-refactor-plan は、そこを意図的に減速させます。コード変更に入る前に、問題設定、代替案、スコープ、テスト、段階的な進め方へ焦点を当てるのが違いです。

request-refactor-planスキルはコードも書いてくれますか？

主目的は実装ではなく計画です。生成されたissueやコミット計画を、後続のコーディング作業のガイドとして使うことはできますが、スキル自体の中心は、安全で具体的なリファクタリング要求を作ることにあります。

request-refactor-plan for Refactoringを使わないほうがよいのはどんなときですか？

次のような場合は見送って構いません。

• 変更が小さく、やることも明白
• すでにレビュー済みの完全な実装計画がある
• 計画よりも今すぐのコード修正が必要
• 実態としてはリファクタリングではなく、機能設計やアーキテクチャ提案である

こうしたケースでは、より直接的なプロンプトのほうが速い場合があります。

GitHubは必須ですか？

ワークフローの終点はGitHub issueの作成なので、GitHubとの相性が最もよいのは確かです。ただし、別のトラッカーを使っていても、issueテンプレート的な構造は計画成果物として十分有用で、そのまま他へ転記できます。

学ぶべき隠しファイルや自動化ヘルパーはありますか？

確認できるリポジトリ情報の範囲では見当たりません。このスキルは、単一ドキュメント型のワークフローに見えます。理解しやすい反面、追加の自動化、schema、強制ルールのようなものまでは期待しないほうがよいです。

request-refactor-planスキルを改善する方法

問題の書き方をもっと鋭くする

request-refactor-plan の結果を最も早く改善する方法は、「コードが汚い」といった曖昧な品質不満ではなく、開発フロー上の痛みとして問題を書くことです。たとえば、次の観点があると強くなります。

• 今、どの変更がやりづらいのか
• 何の duplication や coupling が原因なのか
• どこで自信を失っているのか
• 現在の構造がどんなコストを生んでいるのか

こうすると、エージェントが具体的に検証しやすくなります。

Non-goalsを明示する

多くのリファクタリング計画は、non-goals が欠けているために肥大化します。何を変えてはいけないのかを明確に伝えてください。

• public APIs
• database schema
• user-facing behavior
• performance profile
• release timing

これにより、request-refactor-plan はより小さく、現実的な進行順を作りやすくなります。

ファイルやmoduleの手がかりを渡す

エージェントがリポジトリを調べる前提でも、怪しいホットスポットは先に示したほうがよいです。特に有効なのは次のような情報です。

• directories
• service names
• entry points
• failing tests
• duplicated implementations

これがあると推測が減り、リポジトリ検証の精度が上がります。

テストカバレッジは正直に伝える

このスキルは、そのコード領域にテストがあるかどうかを明示的に確認します。カバレッジが弱いなら、早い段階でそう伝えるべきです。強い出力はしばしば、次のどれを先にやるかの判断に依存します。

• まず characterization tests を足す
• integration coverage を拡充する
• safety net ができるまで危険な移動を後回しにする

テスト不足を隠すと、自信過剰な計画になりやすくなります。

フェーズ分けではなく、小さなコミットを求める

このスキル自体も小さな手順を促しますが、出力品質をさらに上げたいなら、phase 単位ではなく commit 単位の粒度を要求してください。「extract service layer」のような phase はまだ大きすぎます。よりよい commit の切り方は、たとえば次のようなものです。

• 現行挙動の characterization tests を追加する
• 振る舞いを変えずに helper を抽出する
• call site を1か所だけ差し替える
• テスト通過後に dead path を削除する

リファクタリングのリスクが本当に下がるのは、この粒度です。

代替案の比較を必須にする

よくある失敗は、最初の解決策に早く固執しすぎることです。request-refactor-plan skill を改善したいなら、少なくとも2つのアプローチを比較し、なぜ一方がこのリポジトリではより安全・小規模・可逆的なのか説明するよう、明示的に依頼してください。

レビュー後に初稿を絞り直す

最初の計画が出たあと、狙いを絞ったフィードバックを添えてもう1回回すと、かなり実用度が上がります。たとえば次の観点です。

• まだ大きすぎるステップはどれか
• スコープが曖昧な箇所はどこか
• 検証が必要な前提は何か
• テスト手順の記述が足りない部分はどこか

最初のプロンプトを長くするより、この短い2回目の見直しのほうが効くことが多いです。

ありがちな失敗パターンを監視する

主にチェックしたい品質問題は次のとおりです。

• スコープが静かに再設計へ膨らんでいる
• コミット手順がまだ大きすぎる
• テスト戦略が抜けている
• 前提がリポジトリ調査に裏打ちされていない
• もっともらしいが、実際の file や module に結び付いていない solution 文になっている

こうした兆候が見えたら、検証済みのコード領域と、より小さな変更単位に基づいて計画を書き直すよう求めてください。

出力を実務に載せる最善のやり方

request-refactor-plan が強い issue 草案を出してきたら、それをそのまま静的な成果物として終わらせず、実行用ドキュメントとして扱うのがベストです。

• チームでレビューする
• 大きすぎるコミットは削るか分割する
• リスクの高い手順には担当者を付ける
• 関連するテストや module をリンクする
• 実態に合わせて issue を更新する

このスキルの価値が最も高く出るのは、単に計画を作ることではなく、リファクタリングを着手しやすくし、実行を安全にし、レビューしやすくするところにあります。