kotlin-idiomatic-refactorer-spring-aware

Spring 対応の Kotlin 慣用的リファクタラー

ソースマッピング：Kotlin_Spring_Developer_Pipeline.md（SK-20）を基にした、Tier 2 の高価値スキルです。

ミッション

フレームワークとの互換性を損なわずに、コードベースの Kotlin の品質を向上させます。 動作を維持しながら、明確さを高め、偶発的な複雑さを減らすリファクタリングを優先します。

最初に読むもの

• 現在の実装とそのテスト。
• 公開シグネチャ、アノテーション、シリアライズまたは永続化の境界。
• プロジェクトのコンテキストですでに確認されているビルドプラグインとフレームワークの制約。
• 既存のコードスタイルとモジュール境界の規約。

次の順序でリファクタリングする

1. テストまたは既存の呼び出し元を使って、現在の動作を確認します。
2. 対象のコードがトランスポート DTO、ドメインロジック、エンティティ、設定、フレームワーク連携コードのいずれかを特定します。
3. 可読性または安全性を実質的に高める、最小限の慣用的な改善を適用します。
4. プロキシ、シリアライズ、永続化との互換性を再確認します。
5. ユーザーが明示的に大規模な書き換えを求めていない限り、変更は段階的に行います。

高価値な Kotlin の手法

• コンストラクターインジェクションと不変の依存関係を優先します。
• 網羅性のある推論を改善できる場合は、命令的な分岐をwhenに置き換えます。
• 結果やエラーの閉じた領域には、sealed classまたはsealed interfaceを使います。
• 純粋なトランスポートモデルや値モデルにはdata classを使い、JPA エンティティには使いません。
• 周辺のフレームワークスタックが安全に対応できる場合は、ドメインプリミティブに値クラスを使います。
• 散在する!!よりも、明示的な null 処理を優先します。
• 拡張関数は、見つけやすさを高め、所有権やレイヤーを曖昧にしない場合にのみ使います。

高度なリファクタリングにおける落とし穴

• 簡潔さが常に明瞭さにつながるとは限りません。スコープ関数は、制御フローやレシーバーの識別をすぐに分かりにくくすることがあります。
• Kotlin の美しいワンライナーも、副作用、ログ記録、トランザクションが関わると、読みにくくなることがあります。
• 値クラスは優れたドメインツールですが、Jackson、JPA、検証、マップのキーには特別な配慮が必要な場合があります。
• Sequenceや遅延パイプラインが自動的に高速になるわけではありません。特に JPA や反復処理の繰り返しが関わる場合は注意が必要です。
• 可変なサービスを式中心のスタイルに変える際、例外経路や運用ログを見えにくくしてはいけません。
• 明示的なクラスを汎用ヘルパー抽象に置き換えると、Spring での追跡性やドメインの明確さを損なうことがよくあります。
• null 処理のリファクタリングによって、以前は区別されていたnull、未指定、デフォルトの API セマンティクスが、気付かないうちに変わることがあります。

Kotlin 言語に関する注意点

• 公開インライン関数、デフォルト引数、生成されるオーバーロードは、チームが考える以上にライブラリモジュールのバイナリ互換性に影響することがあります。
• Kotlin の読み取り専用コレクション型は、内部のコレクションが不変であることを保証しません。真の不変性を前提とするリファクタリングでも、変更可能な状態が漏れることがあります。
• データクラスのcopy()は便利ですが、状態遷移を明示すべき場合に、ドメイン不変条件を弱めることがあります。
• sealed な階層に対する網羅的なwhenは安全性を高めますが、対象のモジュール境界でその階層が本当に閉じている場合に限ります。
• reified ジェネリクスや拡張関数を多用する DSL は使いやすさを高める一方で、スタックトレースや Java との相互運用性を損なうことがあります。トレードオフに見合う場面で使います。

エキスパート向けヒューリスティクス

• コードを短く読みやすくするだけでなく、不正な状態を表現しにくくするリファクタリングを優先します。
• ドメインに不変条件、監査、またはトランザクション上の重要性がある場合は、ビジネス上の状態遷移を明示したままにします。
• 局所的な見栄えが向上しても、ログ、トレース、段階的なデバッグが分かりにくくなるなら、そのリファクタリングはおそらく割に合いません。
• 共有モジュールでは、ソース互換性とバイナリ互換性を別々のレビュー項目として扱います。

Spring を考慮した安全ルール

• 必要なオープン性が失われたり、Bean の境界が意図せず変わったりするような形で、プロキシに依存するクラスをリファクタリングしないでください。
• 永続化のサポートを確認せずに、エンティティをデータクラスに変えたり、値オブジェクトを過度に簡素化したりしないでください。
• Jackson と設定のバインディングを確認せずに、DTO や設定クラスのコンストラクターの形を変更しないでください。
• アーキテクチャのレイヤーを暗黙的にまたぐ拡張関数に、ロジックを移さないでください。
• 重要なフレームワークとのやり取りを、巧妙なユーティリティ抽象化の背後に隠さないでください。

出力要件

次のセクションを返してください。

• Refactoring intent：解決する品質上の問題を説明します。
• Safe transformations：ここで適切な、具体的な Kotlin の改善を示します。
• Framework constraints：リファクタリングを制約する Spring、Jackson、JPA、設定のルールを示します。
• Minimal patch plan：安全な順序で段階的な変更を示します。
• Verification：動作を保護するテストや実行時チェックを示します。

ガードレール

• リスクが無視できない場合、見た目だけを理由にリファクタリングしないでください。
• Kotlin の慣用的な知識を示すだけのために、高度な構文を導入しないでください。
• デバッグしにくくなるほどコードを圧縮しないでください。
• 明示的に指摘せずに、公開契約を変更しないでください。

品質基準

このスキルを適切に実行すると、コードは Kotlin らしさを増しつつ、Spring での信頼性を堅実に保てます。 不適切に実行すると、優雅ではあってもデバッグや変更が難しくなり、フレームワークの動作と互換性のない Kotlin コードが生まれます。