detekt 仓库 AI 编码代理实战指南：环境搭建、自检流程与 Kotlin 静态分析规则开发规范

• 开发工具
• 代码质量
• 静态分析
• Lint

本篇指南以 detekt 仓库根目录的 AGENTS.md（AI Coding Agent Guidelines）为核心骨架，面向使用 Claude、Codex、Copilot 等 AI 编码代理的开发者，系统讲解在 Kotlin 静态分析工具 detekt 代码库中如何搭建开发环境、执行构建与自检命令、遵守代码与测试规范，以及按官方流程实现一条全新检测规则并合规地提交 AI 辅助 PR。读完本文，你将掌握从克隆仓库到让新规则通过 CI 全链路检查的完整实操路径。

一、AGENTS.md 是什么：面向 AI 编码代理的协作基线

detekt 仓库中的 AGENTS.md 遵循 agents.md。

这份文档的核心定位是：让 AI 代理与人类开发者遵循同一套工程标准。它覆盖了五个关键领域：

• 项目概览：明确 detekt 是什么、提供哪些能力；
• 开发环境：JDK 版本、Android SDK 前置条件、初始构建命令；
• 验证命令：提交 PR 前必须跑通的 Gradle 任务；
• 代码与测试规范：命名、KDoc、测试框架约定；
• AI 贡献策略：AI 辅助 PR 的硬性要求与禁止事项。

对于希望在 detekt 上做贡献（尤其是实现新规则）的 AI 代理而言，这份文件就是它的"行为准则 + 操作手册"。

二、项目概览：Kotlin 静态代码分析工具的四大能力支柱

AGENTS.md 将 detekt 的能力概括为五点，这些能力都能在当前仓库结构中找到对应实现：

1. 200+ 内置规则的代码异味分析：规则按类别分散在detekt-rules-*系列模块中。以 style 规则集为例，StyleGuideProvider.kt 中注册了超过 80 条规则，涵盖MaxLineLength、TrailingWhitespace、MagicNumber、UnusedImport等常见风格检查。
2. 高度可配置的规则集：所有内置规则汇总于 config/detekt/detekt.yml，可通过active、severity、exclude等键按项目自定义。
3. 多种报告格式：对应detekt-report-html、detekt-report-markdown、detekt-report-sarif、detekt-report-checkstyle等模块。
4. 通过自定义规则、处理器和报告进行扩展：核心扩展点定义在 detekt-api 模块。
5. Gradle 插件与 CLI 两种使用界面：分别对应detekt-gradle-plugin/与detekt-cli/模块。

这些能力是 AGENTS.md 后续所有开发流程的背景：你要实现的每条新规则，最终都会以可配置、可报告、可被 CLI/Gradle 调用的形式交付。

三、开发环境：前置条件与初始构建

3.1 JDK 版本要求

AGENTS.md 明确规定构建需要JDK 17+，并给出两个需要注意的细节：

• 部分detekt-gradle-plugin的测试仅在 JDK 19 或更低版本上运行（即 JDK 20+ 会跳过这类测试）；
• JDK 17 必须可用，因为 build-logic 的 JVM toolchain 依赖它。

因此实际开发中，机器上通常需要同时具备 JDK 17 和更高版本 JDK，由 Gradle toolchain 按任务需求自动选择。

3.2 Android SDK（可选前置条件）

Android SDK 仅在执行特定测试时需要，且未安装时会自动跳过相关测试。只有在修改detekt-gradle-plugin时，缺失 Android SDK 才会成为实际问题。这意味着常规规则开发可以完全不依赖 Android 环境。

3.3 克隆与首次构建

# 克隆并进入仓库 git clone https://gitcode.com/gh_mirrors/de/detekt.git cd detekt # 注意：仅在运行 Gradle 插件功能测试前需要 # ./gradlew publishToMavenLocal # 构建（排除耗时的文档生成任务） ./gradlew build -x dokkaGenerate

其中-x dokkaGenerate用于跳过 Dokka API 文档生成这一耗时任务；而publishToMavenLocal之所以被注释，是因为detekt-gradle-plugin采用独立复合构建（composite build，见detekt-gradle-plugin/下的 settings.gradle.kts），其功能测试需要先向本地 Maven 仓库发布插件才能被测试工程消费。

四、验证命令：提交 PR 前的"自举"检查

detekt 最有趣的一点是它用自己分析自己。AGENTS.md 给出了三组必须掌握的命令：

# 1) 用 detekt 分析 detekt 自身（提交 PR 前必须通过） ./gradlew detektMain detektTest detektFunctionalTest detektTestFixtures # 2) 运行全部测试（含功能测试） ./gradlew test detektFunctionalTest detektFunctionalTestMinSupportedGradle # 3) 修改规则后重新生成配置与弃用清单文档 ./gradlew generateDefaultDetektConfig generateDeprecationList

第一组命令分别对main、test、functionalTest、testFixtures四类源码集执行 detekt 自检，任何一条新代码异味都会在这里暴露。仓库自身的自检配置位于 config/detekt/detekt.yml（规则配置）与 config/detekt/baseline.xml（历史问题基线），这与 CI 工作流（如 .github/workflows/execute-detekt.yaml）保持一致。

第三组命令对应detekt-core的 build.gradle.kts 中注册的两个任务：generateDefaultDetektConfig将各规则模块的 KDoc 元数据拼接生成default-detekt-config.yml，generateDeprecationList生成deprecation.properties。这两个产物是规则文档与 IDE 支持的数据源，修改或新增规则后必须重新生成并提交。仓库还注册了verifyGeneratorOutput任务（见 build.gradle.kts），用git diff --quiet校验生成文件是否过期，过期即抛出 GradleException 提示先执行生成任务。

五、模块结构：一次看懂 detekt 的工程布局

AGENTS.md 用一张精简清单概括了关键模块，结合仓库可以扩展为如下映射：

新增规则时，绝大多数改动集中在detekt-rules-*下的某个模块；只有涉及公共 API 时才会触碰detekt-api（该模块的 API 变更需同步更新 detekt-api/api/detekt-api.api 的 ABI 快照）。

六、代码规范：被 detekt 强制执行的约定

AGENTS.md 的代码规范部分，本质上是"用 detekt 自己的规则约束贡献者"：

• 遵循 Kotlin 官方编码规范，代码风格由detektGradle 任务强制检查（即上一节的detektMain等自检任务）；
• 使用 .editorconfig 中的设置统一缩进、换行等格式；
• 测试类必须以Spec.kt后缀命名——这一约定在仓库中广泛存在，例如 CorrectableRulesFirstSpec.kt、BaselineFormatSpec.kt 等；
• detekt-api与规则模块中的所有代码必须带有 KDoc 文档。

这些不是软性建议：自检任务不通过，PR 就无法合并。

七、测试要求：JUnit 5、类型解析与隔离运行

AGENTS.md 对测试提出三点要求，每一点都能在源码中找到对应实现：

1. 使用 JUnit 5编写测试。
2. 需要类型解析的规则，其测试类需标注@KotlinCoreEnvironmentTest。该注解定义于 detekt-test-junit，通过 JUnit 扩展机制为测试注入KotlinEnvironmentContainer。典型用法见 CanBeNonNullableSpec.kt：

@KotlinCoreEnvironmentTest class CanBeNonNullableSpec(val env: KotlinEnvironmentContainer) { val subject = CanBeNonNullable(Config.empty) @Test fun `reports when class-level vars are never assigned nullable values`() { val code = """ class A(bVal: Int) { private var a: Int? = 5 ... } """ // 配合 lintWithContext 使用类型解析能力 } }

3. 用--run-rule RuleSet:RuleId对新规则做隔离测试。该参数定义于 CliArgs.kt（标记为隐藏参数），解析逻辑在 Spec.kt：按:拆分为RuleSetId:RuleName后构造RestrictToSingleRule运行策略，使分析仅执行指定规则。例如仅运行 style 规则集中的MagicNumber：

./gradlew detekt --run-rule style:MagicNumber

这样可以在真实 Kotlin 项目上快速验证新规则的行为，而不受其他规则干扰。

八、实现新规则的官方五步流程

AGENTS.md 专门为 AI 代理给出实现新规则的流程，结合源码可展开如下：

步骤 1：将规则注册到合适的 RuleSetProvider

每条规则都必须归属某个规则集。RuleSetProvider接口（见 RuleSetProvider.kt）要求实现ruleSetId与instance()，内置规则集则继承 DefaultRuleSetProvider 并通过 ServiceLoader 注册。以 style 规则集为例，StyleGuideProvider.kt 以RuleSetId("style")标识，并将新规则类引用加入instance()返回的规则列表。

步骤 2：编写带<noncompliant>/<compliant>示例的完整 KDoc

规则类继承 Rule（基于 visitor 模式实现，ruleName默认取类名，支持preVisit/postVisit钩子）。KDoc 必须包含对代码异味的解释与修复建议，并给出正反示例。真实案例见 CanBeNonNullable.kt：

/** * This rule inspects variables marked as nullable and reports which could be * declared as non-nullable instead. * * <noncompliant> * class A { * var a: Int? = 5 * fun foo() { a = 6 } * } * </noncompliant> * * <compliant> * class A { * var a: Int = 5 * fun foo() { a = 6 } * } * </compliant> */ class CanBeNonNullable(config: Config) : Rule(config) { // Implementation }

这些 KDoc 片段正是generateDefaultDetektConfig任务生成默认配置与网站文档的数据来源。

步骤 3：用lint()或compileAndLintWithContext()编写测试

规则测试工具集中在 detekt-test：

• lint()：直接对代码字符串执行规则，适用于不依赖类型解析的规则；
• lintWithContext()：需要KotlinEnvironmentContainer环境（对应@KotlinCoreEnvironmentTest），先编译再分析，适用于需要类型信息的规则（当前版本中即 AGENTS.md 所述compileAndLintWithContext的等价实现）。

步骤 4：重新生成配置与弃用清单

./gradlew generateDefaultDetektConfig generateDeprecationList

如第四节所述，此命令将新规则的 KDoc 元数据写入default-detekt-config.yml与deprecation.properties，并需随 PR 一并提交，否则verifyGeneratorOutput会在 CI 中失败。

步骤 5：用--run-rule RuleSet:RuleId在真实项目上验证

将新规则指向真实 Kotlin 工程运行，确认无误报、漏报后再提交 PR（详见第七节）。

九、AI 贡献策略：合规提交 AI 辅助 PR 的七条硬性要求

AGENTS.md 用大篇幅规定了 AI 参与贡献的边界，核心原则是AI 与人类贡献者一视同仁：

1. CI 检查必须全绿：合并前所有自动化检查必须通过，本地先跑./gradlew build与./gradlew detektMain detektTest；
2. 测试覆盖：新规则/新功能必须有全面测试，Bug 修复必须带回归测试；
3. 提交署名：AI 必须在 commit message 中以Co-authored-by:trailer 记为共同作者，例如：

feat: add new rule for detecting X Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Your Name <you@example.com>

4. 禁止批量 AI 回复：不得用 AI 批量回复 review 评论，每条回复须有上下文、有针对性，由人类判断引导对话；
5. Trust But Verify（信任但验证）：AI 生成的代码必须经人类审查，确认其准确、地道，并符合 detekt 的架构与约定；
6. 禁止刷 PR：不得为虚增贡献数量提交无意义 PR，琐碎改动应合理合并，每个 PR 必须提供真实价值；
7. 评审策略：PR 不应由生成它的同一 AI 模型评审；鼓励人类评审，也接受非作者的其他 AI 模型评审。

AI 生成贡献的期望与红线

期望：代码准确、遵循 Kotlin 最佳实践与 detekt 约定（Idiomatic）、公共 API 与规则带完整KDoc（Documented）、PR 聚焦单一主题（Focused）、在 PR 描述中透明声明 AI 参与（Transparent）。

明确禁止的 AI 用法：无人类审查监督的 PR、用 AI 生成无意义或低质量贡献、把 AI 回复直接复制进 review 评论、任何刷贡献指标的行为。

此外，维护者随时可以要求人类对代码或评论提供解释——AI 辅助润色（措辞、语法、清晰度）可以，但判断必须由人类主导。

十、安全、许可与资源导航

• 安全：发现安全漏洞应通过security@detekt.dev上报，完整政策见 SECURITY.md。AI 代理严禁提交引入 OWASP Top 10 等安全漏洞、削弱既有安全措施、或在日志与错误信息中泄露敏感信息的 PR。
• 许可：项目采用 Apache License 2.0，贡献即视为同意按相同条款授权。
• 资源：官方文档站为 detekt.dev；README.md 提供项目概览与快速上手；人类贡献指南见 .github/CONTRIBUTING.md；社区规范见 .github/CODE_OF_CONDUCT.md；涉及类型解析的规则开发请参考 类型解析指南。

结语

AGENTS.md 的价值在于把 detekt 这样一个成熟静态分析项目的要求，翻译成 AI 编码代理可执行的操作清单：先搭好 JDK 17+ 环境，跑通自检命令，再按"注册 RuleSetProvider → 编写 KDoc → 测试 → 生成配置 → 隔离验证"五步实现新规则，最后以 Co-authored-by 署名、经人类审查后提交 PR。对照仓库源码可以看到，这些要求并非停留在文档层面，而是由detektMain自检任务、verifyGeneratorOutput生成校验、@KotlinCoreEnvironmentTest测试注解等机制逐一落地的工程约束。对任何想在 Kotlin 静态分析领域做贡献的 AI 代理或开发者来说，这套流程既是 detekt 的贡献手册，也是理解其内部架构的最佳入口。

• 开发工具
• 代码质量
• 静态分析
• Lint