refactorkit

refactorkit

すでにあるコードベースを調査するためのツールです。refactorkit はリポジトリを読み込み、変更頻度、モジュールの構造、テストを確認し、構造がコストになっている箇所を見つけます。候補を2つの基準で評価し、最大1つを選び、誰かが議論できる提案としてまとめます。

これは単一の手順で、必要に応じてサブツリーに対象を絞れます（/refactorkit src/payments）。モードはありません。実行するたびに、常に同じ方法で処理します。

提案するだけで、編集はしません

**refactorkit が書き込むのは Markdown ファイル1つだけで、ソースコードには一切触れません。**移動も、名前変更も、抽出も、「ついでのちょっとした整理」もありません。名前に refactor とありますが、このスキルが示すのは常に「どこを、なぜ」だけであり、実作業は提案を引き受けた人に委ねられます。この境界があるからこそ、レポートを信頼できます。調査と編集を同時に行う調査は、すでに結論を決めているため、読んでいるのは提案ではなく、その正当化にすぎません。

このスキルのツールには、意図的に Edit がありません。作成するファイルは新規なので、Write で対応できます。

実行される場面

「どこをリファクタリングすべき？」「このコードベースの構造のどこが問題？」「リファクタリングの機会を見つけて」「このコードは変更しづらい」「アーキテクチャを改善して」「モジュールの境界を監査して」「ここの継ぎ目はひどい」「/refactorkit」。

4つの境界を、それぞれ1行で示します。

• **コードレビューではありません。**レビューでは、誰かが直前に行った作業の欠陥を見つけるために 差分 を読みます。refactorkit は、差分より前から存在する構造を調べるために ツリー を読みます。「変更をレビューして」という依頼は、このスキルの対象ではありません。
• **ドキュメント作成ではありません。**現状のアーキテクチャを説明するのは別の仕事です。refactorkit が説明するのは、まだ存在しないアーキテクチャだけです。
• ビジュアルデザインではありません。「デザイン」という言葉が「リファクタリング」の隣にあると連想されるかもしれませんが、ここでは UI、スタイリング、デザインシステムは扱いません。
• **意思決定記録ではありません。**refactorkit が作成するのは提案であり、承認済みの決定ではありません。提案が既存のアーキテクチャ決定に取って代わる場合は、その旨を記し、このリポジトリで意思決定を記録する仕組みへ引き継ぎます。

用語

調査結果が単なる汎用的な問題点の列挙に陥らないよう、次の用語を正確に使います。

• **モジュール。**内側と外側を持つものなら何でも該当します。ファイル、クラス、パッケージ、サービスなどです。言語上の構文ではなく、境界を指します。
• **インターフェース。**モジュールを正しく使うために、呼び出し側が知っておく必要のあるすべてです。シグネチャだけではありません。順序の制約、必須の設定、副作用、エラーの契約、誰も書き留めていない不変条件も含まれます。インターフェースは、ほとんどの場合、見た目より大きなものです。
• **深さ。**モジュールが隠す振る舞いの量を、学ぶ必要のあるインターフェースの量と比べたものです。深いモジュールは、小さなインターフェースで多くの作業を隠してくれます。浅いモジュールでは、どちらにしてもほぼ同じ負担がかかります。
• **継ぎ目。**システムを引き裂かずに分割できる箇所です。一方を、もう一方を使わずに置き換えたり、偽物に差し替えたり、テストしたりできます。
• **アダプター。**2つのモジュール間でデータの形を変えることだけを役割とするモジュールです。アダプター自体は問題ではありませんが、集まりになっている場合は、両側がデータの形について合意できていない兆候です。
• **局所性。**1つの概念的な変更が、どれだけ一箇所に収まるかを指します。局所性が高ければ機能変更で触るファイルは少なく、低ければ変更が広範囲に波及します。
• **レバレッジ。**修正によって将来の変更がどれだけ簡単になるかを指します。他の点では同等に妥当な候補の優先順位を決める要素です。

**プロジェクト独自のドメイン用語を、全体を通して使ってください。**コードベースで ledger、tenant、shipment という言葉を使っているなら、提案でも同じ言葉を使います。汎用的な「コンポーネント」「サービス」「API」「レイヤー」に置き換えるのは、調査結果が実際に読み込まれず、パターンに当てはめられただけだと示す最も明確な兆候です。そして、アーキテクチャに関する助言をもっともらしく見せながら、何も語らない原因にもなります。

4 つの摩擦パターン

閉じた集合です。refactorkit が探すのはこの 4 つだけで、それ以外は一切探しません。この閉鎖性は重要です。「問題」を際限なく探すと、どのコードベースでも同じような一般論のリストが生成されます。それこそ、このスキルが置き換えるために存在する出力です。4 つすべてが、深さという概念に帰着します。いずれも、インターフェースがその背後にある振る舞い以上のコストを要求する、別々の形だからです。

パターン	内容	探すべき形	見つける担当
浅いインターフェース	インターフェースを習得するコストが、実装を読むコストとほぼ同じ	各メンバーが、別の単位のメンバー 1 つだけに転送する単位	サブエージェント
アダプターの多さ	2 つの別のモジュール間でデータの形を変えることだけを目的とするモジュール。指摘するのは両側で形が一致しないことであり、「アダプターを削除する」ことではありません	1 つの境界に集まって双方向の変換を行う、変換だけを担う単位のクラスター	サブエージェント
テストされていない結合	協力するコンポーネントを立ち上げなければテストできない振る舞い	アサーションより多くの協力コンポーネントを構築するテスト、または隣接する単位がすべてテスト済みなのに未テストの単位	サブエージェント
局所性の低さ	1 つの概念的な変更が多くのファイルに波及する	異なるディレクトリにあるにもかかわらず、同じコミットで繰り返し変更されるファイル	メインセッション

シグナルは形です。 命名規則は言語コミュニティによって異なりますが、形は変わらないため、コード上でどう呼ばれているかにかかわらず、表の構造に一致するものを探してください。まずリポジトリ固有の規約を把握します（以下で読むガードレールから通常は得られます）。そのうえで、このコードベースで使われている名前にかかわらず、上記の構造を探してください。

2 つのゲート

候補はすべて、掲載前に両方のゲートを通過する必要があります。どちらか一方でも通過できない候補は、黙って破棄されます。弱い指摘として表示されることも、但し書き付きで表示されることもありません。

削除テスト。 このモジュールがなくなり、その呼び出し元が機能を引き継いだとき、複雑さは適切な場所に集約されますか。それとも単に移動するだけですか。集約は成果です。移動はリファクタリングのふりをした変更にすぎません。これを出力すると報告が長くなり、読まれなくなります。証拠を 1 文で示し、どの呼び出し元が何を引き継ぐのか、そしてそれがより適切な配置になるかどうかを説明してください。

テスト対象としてのインターフェース。 提案された変更の後、新しいインターフェースだけを通じて、内部に立ち入ることなく振る舞いをテストできますか。できない場合、境界の位置が適切ではありません。この候補は未完成であり、準備が整っていません。このゲートがあることで、境界を移動しただけの提案が、境界を改善する提案として通過するのを防げます。

掲載するすべての候補について、両方の判定をターミナル出力とファイルに必ず記載してください。ゲートの判定が明記されていない候補は、弱い候補ではなく、根拠が示されていない候補です。

強さの尺度

感覚ではなく、この表に照らして、残った候補を評価してください。定義のないバッジはラベルを付けた雰囲気にすぎず、強さは読者が確認せずに信頼する唯一の列だからです。

強さ	条件	順位付け
strong	両方のゲートを通過し、ファイルが変更頻度の上位層にあり、影響範囲を実際のファイル名で示している	最優先候補にできる
moderate	両方のゲートを通過しているが、コードの変更頻度が低いか、影響範囲が広い	strong がない場合に限り、最優先候補にできる
weak	ゲートは通過しているが、成果はスタイル上のもので、呼び出し元が把握すべきことに変化がない	掲載するが、最優先候補にはしない

手順

1. まずガードレールを読む

コードを見る前に、リポジトリですでに決定されていることを確認します。

• リポジトリのルートにあるコンテキストファイルや用語集ファイル（一般的には CONTEXT.md）で、共通言語を確認します。プロジェクト固有のドメイン用語はここに記載されており、命名規則も通常ここに表れています。
• docs/adr/（または、このリポジトリでアーキテクチャ決定記録を保管している場所）で、すでに下された決定を確認します。

承認済みの決定記録を覆す提案では、その番号を明記し、すでに却下された設計を何事もなかったかのように再提案するのではなく、後続の記録を作成する手順に進めてください。決定を覆すこと自体は正当です。気づかずに覆すことが問題です。

どちらのファイルも存在しないのはよくあることです。警告もコメントもせず、そのまま進めてください。

2. 変更頻度で順位付けし、その後グループ化する

git log --format= --name-only --since=<a year or so> を使うと、refactorkit が必要とする2つの情報を、git 以外のツールを使わず一度に得られます。各ファイルの変更頻度（変更頻度による順位付け）と、常に一緒に変更されるファイル（ローカリティの低さを示す、同時変更ペア）です。

ファイルを変更回数順に並べた後、変更頻度の高いファイルを、ディレクトリや機能など、リポジトリに実際に存在する境界に沿って、一貫性のある3～5個の領域にグループ化します。ユーザーがスコープを指定した場合は、その範囲を尊重してください。スコープによって対象ツリーは絞られますが、手法は変わりません。

git の履歴がない場合、つまり浅いクローンか、そもそもリポジトリではない場合は、順位付けを行いません。構造に基づいてスキャンし、優先順位付けを省略したことを明確に伝えてください。そうすれば、対象範囲の説明を実際以上に受け取られずに済みます。

3. 1つの領域につき1つのエージェントを並行して動かす

領域ごとにサブエージェントを1つ起動します。各エージェントは、自分の担当範囲に対して4つの摩擦パターンにあるコード読解パターンのうち3つを適用し、両方のゲートを自分で実行して、候補となる記録の一覧、または明示的な空の結果を返します。空の結果も、まったく問題のない回答です。

メインセッションでは収集できなかった指摘を順位付けする必要があるため、すべてのエージェントに同じ固定形式で結果を返させます。自由形式の文章では、エージェントが読んだものをすべて読み直さないと順位付けできず、並行して作業する意味がなくなります。

フィールド	内容
pattern	3つのコード読解パターンのうち1つ
files	関連するパス
shape	提案する構造を1行で記述
deletion_test	判定と、その根拠を1文で記述
test_surface	判定と、その根拠を1文で記述
blast_radius	変更対象ファイル、変更される呼び出し元
strength	強度の尺度に基づく評価

ローカリティの低さはメインセッションに残します。 すでに把握している同時変更ペアから導き出せるため、ファイルを読む必要はありません。また、領域ごとのエージェントは、異なる領域にありながら一緒に変更されるファイルを構造上確認できません。領域のエージェントに任せると、確実に見落とされます。

サブエージェントツールが利用できない場合は、変更頻度の高い上位部分をインラインでスキャンします。 同じパターンと同じゲートを適用し、どちらの方法を使ったかを明記してください。公開スキルでは、このフォールバックが例外的なケースではなく実行の大部分を占めます。そのため、これは謝罪を添えるべき劣化モードではなく、明確な対象範囲の説明を伴う正式な実行モードです。

4. 統合し、ゲートを通過させ、順位付けし、最有力候補を決める

• ゲート判定が欠けている記録は除外します。 修復せずに除外してください。証拠のないゲート判定こそ、削除テストで検出する対象であり、メインセッションで修復すると、読んでいないコードに判定を下すことになるためです。
• 領域をまたいで重複を排除します。 同じ接続部分が、その両側から見つかることがよくあります。
• 強さ、次にレバレッジ、最後に影響範囲の小ささを基準に順位付けします。
• weak 以外の候補が残った場合は、必ず1つだけ最有力候補に選びます。 他の候補がどのようなものであっても、weak の候補は選ばないでください。残りは次点候補として順位順に並べます。
• 残った候補がすべて weak の場合、最有力候補は選びません。 その結果は「実施する価値のある候補なし」です。次点候補を末尾の表に記載し、ゲートを通過する候補がない場合に従います。

完了条件： すべての記録を除外、重複排除、または順位付けし、最有力候補を1つ選ぶか、「実施する価値のある候補なし」と明示していること。

最有力候補を1つ選ぶことが作業の要です。同じように見える選択肢が5つ並んでいるだけなら、これは実行前の状態と変わりません。

5. 報告してから、成果物を書く

まず簡潔な表（候補、パターン、強さ、影響範囲）を出し、次に最有力候補とその理由、最後に次点候補を示します。

すべての報告にカバレッジ行を含めてください。 ターミナルとファイルの両方に記載します。例：「変更頻度で1,240ファイルを順位付けし、4つの領域から上位40ファイルを読みました。」上限を見えないようにするのは、網羅性についての虚偽です。「構造上の問題はありません」と「そのうち3％を確認しました」の違いでもあります。

成果物は docs/refactor/NNNN-refactor-<slug>-YYYY-MM-DD.md に保存します。4桁の通し番号、小文字の種別プレフィックス、短い小文字のケバブケースの件名スラッグ、末尾の ISO 作成日で構成します。通し番号 NNNN を決めるには、現在の作業ツリー、git worktree list に記載されている他のすべての作業ツリー、および origin/HEAD（git fetch origin の後に git ls-tree --name-only origin/HEAD docs/refactor/）を対象に、docs/refactor/ 内で先頭に付く4桁の通し番号の最大値を調べて1を加えます。該当する番号がなければ 0001 から始めます。並行する作業ツリーで同じ番号が使われないよう、3つすべてを調べてください。リモートがないなど、確認できない対象はスキップします。git がない場合はディレクトリだけを一覧表示します。通し番号はディレクトリごとに管理し、再利用しません。ファイルを編集しても名前は変えません。同じ件名で再実行する場合、別ファイルを作らず、同じファイルをその場で更新します。リポジトリに提案書の既定の保存先や命名規則がすでにある場合は、その規則を優先します。

このファイルには、カバレッジ行、順位付けした表、各候補の問題点、提案する形、より根本的である理由、両方のゲート判定、影響範囲を扱うセクションを1つずつ含めます。さらに、少なくとも最有力候補には変更前と変更後の Mermaid 図を含めます。GitHub や多くのエディターは Mermaid を標準で描画するため、生成した HTML レポートは不要です。

このファイルは提案を PR でレビューするためのものであり、作業メモではないため、永続的なもので、コミット可能です。ただし、refactorkit がこれをコミットすることはありません。

書き込み可能なファイルシステムがない場合（ブラウザベースのエージェント）は、正規のパスを添えたコードブロックとして成果物を出力し、書き込みは省略します。

6. 引き継ぐ

このセクションは手順を示す文体で書いてください。各文は指示を1つだけ含め、能動態、現在形、比喩なしにします。

変更内容。 書き込んだファイルを報告し、ソースファイルには一切触れていないことを明記します。保存先。 パスを示します。次の手順。 最有力候補をフェーズ分けした計画にします。plankit がインストールされている場合は、提案ファイルを入力として指定します。インストールされていない場合は、安全な中間状態ごとにフェーズを1つ設け、各フェーズの達成を証明するチェックを含めて、自分で計画を書きます。次に、その計画をこの順で grillkit による検討、implementkit による実装へ回します。

次点候補：提案が既存の記録に取って代わる場合は、意思決定記録のスキルに回します（インストールされている場合は domainkit を使います）。

候補がない場合、または候補がすべて weak の場合は、次の手順がないことを明記します。 以下を参照してください。

ゲートを通過するものがない場合

問題のない結果も正当な結果であり、refactorkit はそのように報告します。対象範囲を明示し、ゲートを通過したものはないと伝え、ファイルは書き込みません。すべてがweakの結果も同じです。弱い候補をターミナルの表に列挙し、実行する価値のある候補はないと伝え、ファイルは書き込みません。

これは見た目以上に重要です。調査結果を必ず出さなければならない調査では、結果を捏造してしまいます。そして、捏造されたアーキテクチャ上の助言は、本物とまったく同じように見えます。同じ用語、同じ確信に満ちた調子、同じ形式です。「該当なし」が許される回答でなければ、削除テストは真のゲートとは言えません。

ターミナルの行には、"38 個のファイルを src/ 内でスキャンしました。削除テストを通過したものはありません" のように対象範囲を含める必要があります。そうしなければ、結果が空だった場合に、スキャンが実行されなかった場合と区別できません。

注意事項

• ソースは常に一切変更しません。 書き込み可能なのは、新しい Markdown ファイル 1 つだけです。名前の変更、切り出し、「簡単な修正」など、ほかの作業は、明らかに正しい場合であっても範囲外です。
• シェルは読み取り専用で使用します。 git の履歴、ファイルの読み取り、grep のみです。証拠を生成するために分析ツールをインストールしたり実行したりしてはいけません。そのようなツールを探し、その出力を解析する方法では、このスキルがマイナーリリースで変わる形式に依存してしまいます。リポジトリ内のディスクに依存関係グラフやカバレッジレポートなどの成果物がすでにある場合は、それを読み取ります。新たに生成してはいけません。
• 起動せずに案内します。 次に使うキットの名前と 1 行の実行方法を示し、実行はしません。提案を実行するかどうかは読者が決めることであり、調査からビルドまで自動で連鎖するようにすると、その判断を奪ってしまいます。
• 必須にせず、案内します。 名前を挙げたキットがインストールされていない場合でも、すべての推奨事項は通常のアクションに置き換えられます。git しかない素のリポジトリでも refactorkit は役立ちます。
• これらの既定値よりリポジトリの方針を優先します。 確立された成果物の保存場所、文書化された規約、リポジトリのエージェントガイドファイル（CLAUDE.md または同等のファイル）に明記されたポリシーがあれば、そちらに従い、その旨を伝えます。