gradle-kotlin-dsl-doctor

Gradle Kotlin DSL Doctor

ソースマッピング：Kotlin_Spring_Developer_Pipeline.md（SK-04）に由来する Tier 1 の重要スキルです。

ミッション

妥当と判断できる範囲で、最小限の変更によりビルドを安定させます。 Gradle の問題は、単なる構文の問題ではなく、互換性やモデルの問題として扱います。

まず読むもの

• settings.gradle.kts
• ルートおよびモジュールの build.gradle.kts
• gradle.properties
• gradle/libs.versions.toml またはその他のバージョンカタログ
• gradle-wrapper.properties
• 失敗したタスクの Gradle 出力全文

失敗の分類

編集を始める前に、問題を分類します。

• プラグインの解決またはプラグインのバージョン不一致
• Kotlin DSL の構文または型安全なアクセサーの問題
• 依存関係の解決または BOM の競合
• JDK ツールチェーンまたはターゲットの不一致
• ソースセットまたはテスト実行環境の設定ミス
• plugin.spring、plugin.jpa、KAPT、KSP などのコンパイラープラグインの問題
• タスクの接続またはマルチモジュールの規約に関する問題

作業手順

1. 失敗したタスクと、最初に現れる重要なエラー行を特定します。
2. 問題がプラグインの解決、依存関係の解決、コンパイル、テスト実行、パッケージ化のどこで発生しているかを判断します。
3. 現在のバージョンの管理元を洗い出します。
   • Spring Boot プラグイン
   • Kotlin プラグイン
   • Gradle ラッパー
   • JDK ツールチェーン
   • バージョンカタログまたは規約プラグイン
4. 手動でバージョンを宣言するのではなく、プロジェクトが Spring Boot BOM からバージョンを継承すべきか確認します。
5. 可能な限り、変更対象を最小のファイルに絞ります。全体的な書き換えより、モジュール内での修正を優先します。
6. ビルド全体を実行する前に、修正を検証できる最小限のコマンドを提案します。

Kotlin と Spring の確認事項

• Spring 管理下のクラスがプロキシに依存する場合、kotlin("plugin.spring") が設定されていることを確認します。
• JPA エンティティがある場合、kotlin("plugin.jpa") が設定されていることを確認します。
• JVM ターゲットと Java ツールチェーンが一致していることを確認します。
• kotlin-reflect、シリアライゼーション、コルーチンの各ライブラリが、使用中の Kotlin バージョンと整合していることを確認します。
• このプロジェクトでアノテーション処理に KAPT と KSP のどちらを使うべきか確認します。

推奨する修正方針

• 新しいバージョンを追加する前に、不要な明示的バージョン指定を削除します。
• 可能な限り、Spring Boot BOM に互換性のある依存関係のバージョン管理を任せます。
• ファイル全体の置き換えより、小さな差分を優先します。
• バージョンカタログ、規約プラグイン、ビルドロジックモジュールなど、既存の規約を維持します。
• 修正が複数のモジュールにまたがる場合は、それが必要となる依存関係グラフを説明します。

高度なビルド診断

• 依存関係の宣言に関する問題と、バリアント選択に関する問題を区別します。依存関係が存在していても、誤った JVM ターゲット、分類子、または機能が解決されることがあります。
• リポジトリで Spring Boot BOM に加えて platform(...) または enforcedPlatform(...) を使用しているか確認します。競合解決の動作が変わります。
• プラグインの実際の信頼できる情報源が、モジュールのビルドファイルではなく、pluginManagement、バージョンカタログ、または規約プラグインかどうかを確認します。
• 実行可能 JAR ではなく通常の JAR を公開すべきライブラリモジュールに Boot プラグインが適用されていないか確認します。
• プロジェクトで構成キャッシュを使おうとしている場合は、その互換性を確認します。カスタムビルドロジックでのタスクへの先行アクセスや変更可能なグローバル状態が、不可解な Gradle の挙動の原因であることがよくあります。
• KAPT、KSP、コード生成、ソースセットの接続において、生成ソース用ディレクトリや現在欠けているタスクの実行順序が必要か確認します。
• 新しいリポジトリやバージョン変更を提案する前に、依存関係ロック、検証メタデータ、リポジトリポリシーファイルを確認します。
• モジュール間の依存関係が IDE と CI で異なる挙動をする場合は、テストフィクスチャ、インクルードビルド、コンポジットビルドを確認します。

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

• バージョンを管理するレイヤーがどれなのか（ラッパー、プラグイン、プラットフォーム、バージョンカタログ、モジュールのオーバーライド）を優先して説明してください。これにより、直近の修正後に同じずれが繰り返し発生するのを防げます。
• ビルドが CI でのみ失敗する場合は、依存関係の宣言を変更する前に、ラッパーのバージョン、JDK ベンダー、org.gradle.jvmargs、構成キャッシュのフラグ、リポジトリの認証情報を比較してください。
• 新しい Gradle バージョンでカスタムタスクやプラグインが動作しなくなる場合は、その変更を通常の依存関係や Kotlin コンパイラーの修正と切り分けてください。
• ビルドで依存関係の置換やインクルードビルドを使用している場合は、API の不整合を診断する前に、解決されたアーティファクトがローカルソースなのか、公開済みのバイナリなのかを確認してください。

出力の契約

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

• Root cause：何が壊れているのか、またビルドのどの段階で問題が発生しているのか。
• Minimal patch：適用する Gradle の変更を正確に示します。
• Why this works：修正の根拠となる互換性ルールまたは Gradle モデルの事実。
• Verification：確信度が低い順から高い順に、1 つ以上のコマンド。
• Follow-up risk：修正によってビルドは通るものの、技術的負債が残る場合に限ります。

ガードレール

• 根拠のない依存関係やプラグインのバージョンをでっち上げないでください。
• Kotlin DSL を Groovy や Maven の構文に書き換えないでください。
• 似ているというだけで、関係のないモジュールを変更しないでください。
• 強い明示的な理由がない限り、force や過度な除外を使ってバージョンの競合を隠さないでください。
• ビルドモデル自体が誤っている場合、キャッシュのクリアを主な修正方法として推奨しないでください。

有用性の高いコマンド

リポジトリでコマンドを実行できる場合は、次を使用してください。

• ./gradlew help
• ./gradlew build
• ./gradlew :module:compileKotlin
• ./gradlew dependencies
• ./gradlew dependencyInsight --dependency <artifact>

品質基準

このスキルを適切に実行すると、ビルドモデルが以前より明確になり、CI でも有効な修正が得られます。 不適切な実行では、根拠のないバージョンを問題に当てずっぽうに当てはめ、過剰に書き換えたり、Spring Boot の互換性モデルを無視したりします。