gradle-best-practices

Gradle のベストプラクティス

プロジェクトを Gradle の公式ベストプラクティスに照らして監査し、構造化された検出事項レポートを作成し、問題を修正するための具体的なコード変更を提案します。チェックと修正の対象は、ビルドスクリプト（*.gradle.kts、*.gradle）、設定ファイル、gradle.properties、ラッパーの設定、バージョンカタログ、および buildSrc/ と build-logic/ 内の Java／Kotlin／Groovy ソースです。

ベストプラクティスのカタログは、このスキルに事前処理済みの状態で同梱されており、references/ にあります。 ディスクから読み込んでください。実行時にネットワークから取得しないでください。

信頼できる情報源

カタログは階層化されており、各実行では必要な階層だけを読み込みます。以下の手順で指示されている以上の内容を読まないでください。読み込み結果はコンテキストに残り、その後の各ターンで再送信されるため、一度読み込んだファイルも、その後のターンごとにトークンを消費します。

• references/detection.md — エントリーの読み方と症状のインデックスです。ステップ 3 で一度だけ読み込みます。
• references/<category>.md — カテゴリごとに 1 ファイルあり、各エントリーのタイトル、アンカー、重大度区分、前提条件、検出手順、および修正の概要が記載されています。簡潔に設計されており、判断に使う階層です。Fix: の行を含め、検出事項の記述に必要な情報がすべて含まれています。ステップ 2 で選ばれたファイルだけを読み込んでください。ファイルは 7 つです：general.md、structuring-builds.md、dependencies.md、tasks.md、performance.md、security.md、testing.md。
• references/fixes/<anchor>.md — ベストプラクティスごとに 1 ファイルあり、ルール、修正の詳細、および多くのエントリーでドキュメント独自の Kotlin DSL による Don't／Do の例が記載されています。これは任意の詳細情報であり、必須の階層ではありません。カテゴリのエントリーにある Fix: の行だけでは変更を実施できない場合に限り、修正に取りかかる際に 1 つずつ読み込んでください。先回りして読み込まないでください。ファイルは 48 個あります。推測で読み込むと、何の利点もないままコンテキストを消費します。
• references/index.md — 出典情報のみを記載しています。収集日、参照元の URL、カタログの再生成に使用した全 48 エントリーの一覧が含まれます。実行時には絶対に読み込まないでください。 実行に必要な情報はすべてここに含まれており、約 7,400 文字と 1 ターンを無駄に消費します。

ベストプラクティスへの直接リンクは、https://docs.gradle.org/current/userguide/best_practices_<category>.html#<anchor> です。URL のカテゴリ部分にはカテゴリファイル名のハイフンをアンダースコアに置き換えたものを使います。そのため、structuring-builds.md → best_practices_structuring_builds.html となります。読者が詳細を確認できるよう、これらの URL を記載してください。ただし、同梱ファイルを読み込み、ネットワークから取得しないでください。最新のアンカーの一部はまだ current で参照できません。その場合は、代わりに https://docs.gradle.org/nightly/userguide/… を記載してください。

モード

• 監査モード（デフォルト。「ビルドをチェックして」「Gradle を監査して」「問題はありますか？」など）：ステップ 1～5 を実行し、レポートを提示したところで終了します。その後、ステップ 6 で修正を適用するか確認してください。
• 適用モード（「ベストプラクティスを適用して」「ビルドを修正して」「ビルドを最新化して」など）：ステップ 1～5 を実行して検出事項を集め、簡潔に要約した後、ステップ 6 に進み、優先度の高い項目から修正を提案します。

質問で処理を止めない

ユーザーに返答する機会がない場合（回答前に終了する自動実行や単一ターンの実行など）は、このスキル内の「ユーザーに尋ねる」または「確認を得る」という手順をすべて、推奨される選択肢を選び、その判断と理由をレポートに記録して続行する指示として扱ってください。入力を待ったままセッションを終了してはいけません。構造に関わる修正については、質問する代わりに計画をレポートに記載してから実行してください。

ステップ 1: プロジェクトの Gradle ファイルを検出する

glob パターンを使って、プロジェクト内の Gradle 関連ファイルを探します:

パターン	目的
**/settings.gradle.kts、**/settings.gradle	設定ファイル
**/build.gradle.kts、**/build.gradle	ビルドスクリプト（ルート + サブプロジェクト）
**/gradle.properties	プロパティファイル（ルート + サブプロジェクト）
**/gradle/wrapper/gradle-wrapper.properties	Wrapper 設定
**/gradle/libs.versions.toml	バージョンカタログ
**/buildSrc/**/*.{kt,kts,groovy,java}	buildSrc のソース（src/main/ を含む）
**/build-logic/**/*.{kt,kts,groovy,java}	build-logic のソース（src/main/ を含む）
**/*.gradle.kts、**/*.gradle	規約プラグインおよびその他の Gradle スクリプト

検出した各ファイルを読み取ります — チェックは存在だけでなく内容に依存します。

Gradle ファイルがまったく見つからない場合は、これは Gradle プロジェクトではないと思われる旨をユーザーに伝えて停止します。

ステップ 2: このプロジェクトが違反しうるカテゴリファイルだけを読む

まずステップ 1 で見つかった内容からトリアージします。カテゴリファイルは、その前提条件が満たされた場合にのみ読み取ります:

カテゴリファイル	読み取る条件
general.md	常に — すべての Gradle ビルド。
performance.md	常に — すべての Gradle ビルド。
dependencies.md	dependencies {} ブロック、repositories {} ブロックが存在する、またはバージョンカタログが存在する。
structuring-builds.md	プロジェクトが複数ある、ソースファイルがどこかに存在する、buildSrc/ が存在する、または settings に include( が現れる。
tasks.md	ビルドがタスクを登録または設定する、または buildSrc/ / build-logic/ にタスクやプラグインのソースがある。いずれも存在しない場合は完全にスキップします。
security.md	Wrapper が存在する（gradle/wrapper/gradle-wrapper.properties）、またはビルドがアーカイブ（jar、war、任意の AbstractArchiveTask）を生成する。
testing.md	プロジェクトが独自のタスク型またはプラグインを定義している。プラグインを利用するだけのビルドではスキップします。

スキップしたカテゴリは正当な 該当なし です — そのエントリを数え、どのカテゴリをなぜスキップしたかを述べてください。黙って省略しないでください。

カテゴリファイルが見つからない、または読み取れない場合は、その旨を伝えて停止します — 記憶しているベストプラクティスやドキュメントの取得にフォールバックしないでください。

ステップ 3: 各エントリの検出手法をカタログから取得する

今すぐ references/detection.md を読み取ってください。 そこにはカタログエントリの構造 （When: / Detect / 重大度 / Fix:）、レシピに記載されたトークンは閉じた集合ではなく例であるという規則、ファイル同士を比較することでのみ判断できる 4 つのエントリ、およびビルドスクリプトのトークンをエントリにマッピングする症状インデックスが含まれています。これにより、あらゆるチェックを自分で再導出する必要がなくなります。

ステップ 4: プロジェクトをチェックする

各検出結果を次の項目とともに記録します: ベストプラクティスのタイトル、アンカー URL、違反が現れるファイルと行、1 文の説明、重大度バンド。カテゴリエントリの Fix: 行がレポートの Fix: 行です — references/fixes/ 配下のファイルを 1 つも開かずに検出結果を報告する実行は、意図どおりに動作しています。

違反は相互排他的ではありません: 1 行が同時に複数のプラクティスに違反することがあり、ある行を 1 つのプラクティスに一致させてもそれが尽きるわけではありません。例: アクションを持つ 2 つのタスク間の dependsOn 'listMaintainedCars' は タスク名をハードコードしない（文字列）と dependsOn を避ける（結合）の両方に違反します — 文字列形式を dependsOn someTaskProvider に修正すると前者は解消されますが後者は残ります。検出結果が同じ行を共有していても、違反したプラクティスごとに 1 件の検出結果を記録します。

ステップ 5: レポートを提示する

問題が見つからなかった場合は、1 行だけ出力します: 問題は見つかりませんでした。 その後停止します。

それ以外の場合:

# Gradle Best Practices Audit

Catalog: bundled with this skill — captured [catalog_captured], Gradle [catalog_gradle_version]
Best practices evaluated: N
Best practices not applicable: N

## Summary
| Priority | Count |
|---|---|
| High | N |
| Medium | N |
| Recommendation | N |

## Issues

### [Category]

**[Best Practice Title]** — [High / Medium / Recommendation]
- **Where:** file.gradle.kts:12, other-file.gradle.kts:5
- **Issue:** What's wrong, concretely.
- **Fix:** What to change.
- **Reference:** https://docs.gradle.org/current/userguide/best_practices_<category>.html#<anchor>

任意: HTML レポート

ユーザーが HTML レポート（優先度/場所でソート可能、クリック可能なリンク付き）を希望する場合は、markdown レポートの代わりに（またはそれに加えて）build/reports/best-practices-audit.html に書き出すことを提案してください。

ステップ 6: 修正を適用する

監査モードでは、次のように尋ねます: 「これらの修正のいずれかを適用しましょうか？ ビルドスクリプト、設定、プロパティ、バージョンカタログ、および buildSrc/ / build-logic/ 配下のソースに対するコード変更を提案できます。」 返答が得られない場合（「質問でブロックしない」を参照）は、確認せずに修正を適用します。

適用モードでは、質問をスキップして直接進めます。

修正を適用する際:

• references/fixes/ ファイル内では、Don't ブロックが一致させるべき形であり、Do ブロックが書き込むべき形です。長いブロックは、実際に異なる行の周辺を抜粋し、// ... で省略を示します。周囲の足場ではなく、形をコピーしてください。カテゴリ項目の Fix: 行が変更を曖昧にしている場合、または自分自身の言い回しではなくドキュメントの正確な Do の形が欲しい場合に開いてください。修正が曖昧でなければ、それを適用して先に進んでください。

  5 つの項目（modularize_builds、no_source_in_root、favor_composite_builds、use_convention_plugins、test_custom_types_with_testkit）には Don't/Do のペアがありません。ドキュメントの例がプロジェクト全体のレイアウトだからです。これらの Fix の文章が仕様であるため、プロジェクト構造に触れる際はそれらを参照してください。

• 最も優先度の高い問題から始めてください。関連する修正をグループ化します（例: すべての repositories {} ブロックを一度に移動する）。

• 単純な修正（org.gradle.caching=true の追加、-all.zip から -bin.zip への名前変更、rootProject.name の追加、apply plugin: から plugins {} ブロックへの置き換え、タスクへの group/description の追加、.get() を .map { } に置き換える）については、ファイルをその場で編集し、差分を表示してください。

• buildSrc/ または build-logic/ におけるソースレベルの修正（PathSensitivity.ABSOLUTE の置き換え、@TaskAction 内の project. アクセスの削除、消費可能な設定への attributes { } の追加）については、編集を適用し、ファイルを読み直してまだコンパイルできることを確認してください。

• 構造的な修正（buildSrc/ から build-logic/ への移行、プロジェクトのモジュール化、Groovy DSL から Kotlin DSL への変換、重複からの規約プラグインの抽出）については、まず計画を説明し、ユーザーの確認を得てください — または、無人で実行する場合は計画を記録して確認なしで進めてください — その後、各ステップの後にチェックポイントを設けて段階的に適用してください。

• 各修正の後、変更されたツリーに対してその項目の Detect 行を再実行して、変更が問題を解決したことを確認してください — 自分の編集を読み直すことによってではなく。この 2 つは、あるべき以上にしばしば食い違います: ファイルが削除されずに空にされた、プロバイダーが get() されていないのに文字列化する API に渡された、などです。ビルドの成功は確認にはなりません。 そのどちらもコンパイルに成功し ./gradlew build を通過しながら、その慣行が侵害されたままになっています。したがって、修正が宣言ではなく値を変更する場合は、実際にコンシューマーに到達する値を確認してください。修正が関連する問題を明らかにした場合（例: リポジトリを settings に移動すると FAIL_ON_PROJECT_REPOS を設定すべきことが判明する）、それをフォローアップとして提示してください。

• いかなる所見も修正不能として記録する前に、その項目の Fix: 行を最後まで読み直してください。 いくつかの項目は複数のルートを持ち、条件によって選択されます — avoid_depends_on はタスク間でアーティファクトが流れるかどうかで分岐し、avoid_provider_get_outside_task_action は受け取るパラメータの型で分岐します。「これは振る舞いを変えずには修正できない」は、ほとんどの場合、最初のルートを試し、適用不可と判断し、行の残りを読まなかったことを意味します。項目が真に修正不能であるのは、それが示すすべてのルートを試し、それぞれが失敗した理由が記録されている場合だけです。

• ある行を修正した後、残りの所見とカタログ全体に対してそれを再確認してください: ある側面の修正が、同じ場所にある違反をそのまま残したり、新しい違反を導入したりすることがよくあります。

• ユーザーが修正を断った場合は、そのままにして先に進んでください。