Agent guidance for Gradle build logic

build-logic/AGENTS.md

@@ -0,0 +1,25 @@
+# Working in build-logic
+
+Use `gradle-best-practices` before changing Gradle code here. If it is missing or incomplete,
+follow the [skill setup](../docs/how_to_work_with_gradle.md#gradle-skills) before editing.
+
+This included build holds project conventions and the smoke-test, tag-registry and
+testcontainers plugins. Its settings import `../gradle/libs.versions.toml` and configure
+repository proxies separately from the main build.
+
+The smoke-test plugin runs nested builds with older Gradle versions. Its tests use Java 21
+for that reason; keep that launcher when changing the tests or toolchain configuration.
+
+## Tests
+
+The plugin tests use JUnit 5 and Kotlin. Reuse the module's TestKit setup, including its
+repository proxy handling and environment isolation.
+
+Run the tests for the module you changed, for example:
+
+```shell
+./gradlew -p build-logic :smoke-test:test
+```
+
+For changes across modules, `./gradlew :build-logic:check` runs the included build's checks
+from the repository root.

build-logic/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

buildSrc/AGENTS.md

@@ -0,0 +1,23 @@
+# Working in buildSrc
+
+Use `gradle-best-practices` before changing Gradle code here. If it is missing or incomplete,
+follow the [skill setup](../docs/how_to_work_with_gradle.md#gradle-skills) before editing.
+
+For new conventions, follow the [build logic placement advice](../docs/how_to_work_with_gradle.md#build-logic-location).
+
+The Java 8 target in `build.gradle.kts` is needed by build-time instrumentation and Muzzle
+workers. A newer Gradle daemon or compiler JVM does not remove that requirement.
+
+JMH uses the consuming build's plugin classpath. Read the comments in
+[its convention](src/main/kotlin/dd-trace-java.jmh-conventions.gradle.kts) before changing
+that integration or adding JMH to `implementation`.
+
+## Tests
+
+The plugin tests use JUnit 5 and Kotlin. Reuse
+[GradleFixture](src/test/kotlin/datadog/gradle/plugin/GradleFixture.kt) for TestKit tests.
+CLI tests need `-PrunBuildSrcTests`; see [the test commands](../docs/how_to_work_with_gradle.md#running-build-logic-tests).
+Keep the `:test` selector when filtering so the filter does not reach unrelated subprojects.
+
+Changes to `call-site-instrumentation-plugin` or `modifiable-config-agent` also need their
+own subproject tests. Run `./gradlew -p buildSrc spotlessCheck` for formatting.

buildSrc/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md