gradle-best-practices

Gradle 最佳实践

根据官方 Gradle 最佳实践审查项目，生成结构化的发现报告，并提出具体的代码更改来修复问题。检查和修复范围涵盖构建脚本（*.gradle.kts、*.gradle）、设置文件、gradle.properties、Wrapper 配置、版本目录，以及 buildSrc/ 和 build-logic/ 下的 Java/Kotlin/Groovy 源代码。

最佳实践目录已随此技能一并提供，并预先整理在 references/ 中。 请从磁盘读取。运行时不要从网络获取任何内容。

信息来源

目录采用分层结构，每次运行只读取所需的层。除非以下步骤明确要求，否则不要多读——每次 Read 的结果都会保留在上下文中，并在后续每一轮重新发送，因此文件每多读一次，后续每轮都会增加 token 消耗。

• references/detection.md — 如何读取条目，以及症状索引。在步骤 3 中读取一次。
• references/<category>.md — 每个类别对应一个文件，包含各条目的标题、锚点、严重性等级、前置条件、检测方案和一行修复摘要。内容刻意保持简洁：这是用于判断的层，其中包含撰写发现报告所需的所有信息，包括 Fix: 行。只读取步骤 2 选中的文件。共 7 个文件：general.md、structuring-builds.md、dependencies.md、tasks.md、performance.md、security.md、testing.md。
• references/fixes/<anchor>.md — 每项实践对应一个文件，包含规则、完整修复说明，以及大多数条目中官方文档提供的 Kotlin DSL Don't/Do 对照。这是可选的深入资料，并非必读层。只有当类别条目的 Fix: 行不足以完成更改时，才读取相应文件；并且应在处理每项修复时逐个读取，切勿提前读取。共 48 个文件；推测性读取只会浪费上下文，没有任何收益。
• references/index.md — 仅记录来源信息：抓取日期、来源 URL，以及用于重新生成目录的完整 48 项列表。运行时绝不要读取。 每次运行所需的信息都已包含在此处以外的文件中；读取它只会无谓消耗约 7,400 个字符和一轮对话。

任意最佳实践的直接链接格式为 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/，或设置文件中出现 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：检查项目

记录每项发现，包括：最佳实践标题、锚点 URL、出现违规的文件和行号、一句话描述，以及严重程度级别。类别条目的 Fix: 行就是报告中的 Fix: 行——运行时无需打开 references/fixes/ 下的任何文件便能报告发现，正是预期行为。

违规并非互斥：同一行可能同时违反多项实践，将某行与一项实践对应起来并不代表检查完毕。例如：两个带有操作的任务之间存在 dependsOn 'listMaintainedCars'，这既违反 不要硬编码任务名称（字符串），也违反 避免使用 dependsOn（耦合）——将字符串形式修复为 dependsOn someTaskProvider 可以解决第一项，但仍会留下第二项。即使多项发现位于同一行，也应针对每项违规实践分别记录一项发现。

步骤 5：提交报告

如果没有发现问题，只输出一行：No issues found. 然后停止。

否则：

# 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 报告（可按优先级／位置排序，并包含可点击链接），可提出将报告写入 build/reports/best-practices-audit.html，以替代 Markdown 报告或与之并列。

第 6 步：应用修复

在 Audit 模式下，询问：“你希望我应用其中哪些修复？我可以为你的构建脚本、设置、属性、版本目录以及 buildSrc/ / build-logic/ 下的源代码提出代码更改建议。”如果无法收到回复（参见“切勿因提问而停滞”），则不要提问，直接应用修复。

在 Apply 模式下，跳过提问，直接继续。

应用修复时：

• 在 references/fixes/ 文件中，Don't 代码块是需要匹配的形态，Do 代码块是需要写入的形态。较长的代码块会围绕实际存在差异的行摘录，并用 // ... 标记省略部分；请照着形态修改，而不是照搬周围的脚手架代码。如果类别条目的 Fix: 行对更改说得不够明确，或你想使用文档中精确的 Do 形态而非自行措辞，请打开相应文件。若修复方式明确，则直接应用并继续。
• 五个条目（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 行，确认更改解决了问题——不要仅仅重新阅读自己的编辑。两者的结果往往并不一致：文件被清空却没有删除；或者移除了 provider 的 get()，却把它传给会将其字符串化的 API。**构建成功不代表问题已解决。**这两种情况都能通过编译并通过 ./gradlew build，但违规做法仍然存在。因此，当修复改变的是值而非声明时，要检查实际传递给使用方的值。如果修复揭示了相关问题（例如，将仓库移动到设置中后发现还应设置 FAIL_ON_PROJECT_REPOS），请将其作为后续事项指出。
• **在记录任何发现为无法修复之前，请重新阅读该条目的 Fix: 行直到末尾。**其中有些条目会根据条件提供多种方案——avoid_depends_on 取决于制品是否在任务之间传递；avoid_provider_get_outside_task_action 取决于接收参数的类型。“不更改行为就无法修复”通常意味着你尝试了第一个方案，发现它不适用，却没有读完剩余内容。只有尝试了条目列出的所有方案，并记录每种方案失败的原因后，该条目才算确实无法修复。
• 修复某一行后，要根据剩余发现和完整目录再次检查：针对某个方面的修复往往会遗留同一位置的其他违规，也可能引入新的违规。
• 如果用户拒绝某项修复，就保持原样并继续。