Agent guidance for Gradle build logic by bric3 · Pull Request #12872 · DataDog/dd-trace-java

bric3 · 2026-10-14T15:13:42Z

What Does This Do

Add folder-specific agent instructions for buildSrc and build-logic, with small Claude Code imports. Keep the shared Gradle advice, skill installation steps and guidance on updating the guide in docs/how_to_work_with_gradle.md.

Motivation

Explain general practices once, and let the folder instructions focus on local constraints. The Gradle guide now covers plugin independence, task dependencies and cache checks alongside the existing advice.

Additional Notes

Contributors install the required skill using the steps in the guide. The provider example was run in an isolated build, including configuration-cache reuse. Repository tests and live Codex/Claude instruction-loading sessions were not run.

Tip

Claude Code v2.1.277+ supports AGENTS.md natively, but its default prefers CLAUDE.md when one exists on the project path, see Claude Code instruction loading.

Contributor Checklist

Format the title according to the contribution guidelines
Assign the type: and (comp: or inst:) labels in addition to any other useful labels
Avoid using close, fix, or any linking keywords when referencing an issue
Use solves instead, and assign the PR milestone to the issue
Update the CODEOWNERS file on source file addition, migration, or deletion
Update public documentation with any new configuration flags or behaviors
Once approved, use merge queue to merge the PR

dd-octo-sts · 2026-10-14T15:48:29Z

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	13.94 s	13.90 s	[-0.5%; +0.9%] (no difference)
startup:insecure-bank:tracing:Agent	12.86 s	12.90 s	[-1.0%; +0.4%] (no difference)
startup:petclinic:appsec:Agent	17.19 s	17.07 s	[-0.2%; +1.6%] (no difference)
startup:petclinic:iast:Agent	17.06 s	17.01 s	[-0.5%; +1.1%] (no difference)
startup:petclinic:profiling:Agent	16.80 s	16.89 s	[-1.6%; +0.7%] (no difference)
startup:petclinic:sca:Agent	17.09 s	16.83 s	[+0.6%; +2.5%] (maybe worse)
startup:petclinic:tracing:Agent	16.13 s	16.13 s	[-0.9%; +0.9%] (no difference)

Commit: a26719e0 · CI Pipeline · Benchmarking Platform UI

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

datadog-datadog-prod-us1-2 · 2026-10-15T13:32:00Z

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 59.54% (+0.00%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: a26719e | Docs | Give us feedback!}

sarahchen6

A few small suggestions, but otherwise looks good! I didn't approve, as this PR is still in draft mode. I support the gradle-best-practices recommendations though 👍

sarahchen6 · 2026-10-15T16:08:48Z

+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.


nit: with the addition in the root AGENTS.md, this and the similar lines in buildSrc/AGENTS.md shouldn't be necessary

I'd rather have it in the two places, precisely because they're in two distinct folders. That way an agent working only in buildSrc can see the link to the gradle doc.

Also, I'd rather avoid adding it to the root AGENTS.md, as it's somewhat specific to gradle folder. And this reinforce the intent for the AGENT there: read this doc, AI!.

sarahchen6 · 2026-10-15T16:09:24Z

+New project-facing conventions usually belong in `build-logic`. This folder still holds
+plugins and shared types that need the `buildSrc` classloader. Keep changes to existing
+plugins where they are unless the task includes moving them.


This could be put in the how_to_work_with_gradle.md doc? I think it's mostly covered in the table under the What are Gradle Files? section

I wanted to reinforce this for humans as well. But you're right maybe I can just point to the right doc section.

sarahchen6 · 2026-10-15T16:10:50Z

+This guide covers Gradle practices and how they apply in this repository, including where
+our current build cannot yet follow a best practice. The project-specific sections explain
+conventions used across the build.
+
+Update this guide when a change affects that shared advice. Keep implementation notes,
+workarounds and procedures for a single plugin or task with its source or local documentation.


nit: simplify to

Suggested change

This guide covers Gradle practices and how they apply in this repository, including where

our current build cannot yet follow a best practice. The project-specific sections explain

conventions used across the build.

Update this guide when a change affects that shared advice. Keep implementation notes,

workarounds and procedures for a single plugin or task with its source or local documentation.

This guide covers shared Gradle practices, repository conventions, and current exceptions. Update it when shared guidance changes; keep guidance specific to one plugin or task beside its source or local documentation.

sarahchen6 · 2026-10-15T16:12:01Z

+### Codex
+
+Ask the built-in [skill installer](https://learn.chatgpt.com/docs/build-skills#install-curated-skills-for-local-use)
+to install the skill from Gradle's repository:
+
+```text
+$skill-installer install https://github.com/gradle/gradle-skills/tree/main/skills/gradle-best-practices
+```
+
+Then invoke it with `$gradle-best-practices`. If it does not appear after installation,
+restart the session.
+
+### Claude Code
+
+Install Gradle's plugin:
+
+```text
+/plugin marketplace add gradle/gradle-skills
+/plugin install gradle-skills@gradle-skills
+```
+
+Invoke the skill with `/gradle-skills:gradle-best-practices`. Each contributor installs the
+plugin for their own setup; naming it in repository instructions does not fetch it.
+See the [upstream installation guide](https://github.com/gradle/gradle-skills#installation)
+for other agents and installation options.
+


we probably don't need to list these instructions ourselves since it's already included in the skill's README? and the agent should already go through that

docs: add Gradle agent guardrails

d9ed185

bric3 added type: documentation tag: no release notes Changes to exclude from release notes comp: tooling Build & Tooling tag: ai generated Largely based on code generated by an AI or LLM labels Oct 14, 2026

bric3 changed the title ~~Add guardrails for Gradle build agents~~ Add agents guardrails for Gradle build logic Oct 15, 2026

bric3 changed the title ~~Add agents guardrails for Gradle build logic~~ Add agent guidance for Gradle build logic Oct 15, 2026

docs: move shared Gradle guidance into the guide

b770d54

sarahchen6 reviewed Oct 15, 2026

View reviewed changes

bric3 changed the title ~~Add agent guidance for Gradle build logic~~ Agent guidance for Gradle build logic Oct 18, 2026

bric3 added 3 commits October 20, 2026 14:11

docs: clarify project dependencies in build logic

a63d334

docs: centralise build logic placement advice

e7dfd30

docs: clarify Gradle guidance and skill setup

a26719e

Navigation Menu

Repository navigation

Agent guidance for Gradle build logic - #12872

Agent guidance for Gradle build logic#12872
bric3 wants to merge 5 commits into
masterfrom
bdu/gradle-agent-guidance

bric3 commented Oct 14, 2026 •

edited

Loading

Uh oh!

dd-octo-sts Bot commented Oct 14, 2026 •

edited

Loading

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Oct 15, 2026 •

edited by datadog-prod-us1-4 Bot

Loading

Uh oh!

sarahchen6 left a comment

Uh oh!

sarahchen6 Oct 15, 2026

Uh oh!

bric3 Oct 20, 2026

Uh oh!

sarahchen6 Oct 15, 2026

Uh oh!

bric3 Oct 20, 2026

Uh oh!

sarahchen6 Oct 15, 2026

Uh oh!

sarahchen6 Oct 15, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		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.

Conversation

bric3 commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Does This Do

Motivation

Additional Notes

Contributor Checklist

Uh oh!

dd-octo-sts Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Oct 15, 2026 • edited by datadog-prod-us1-4 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sarahchen6 left a comment

Choose a reason for hiding this comment

Uh oh!

sarahchen6 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

bric3 Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

sarahchen6 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

bric3 Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

sarahchen6 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

sarahchen6 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bric3 commented Oct 14, 2026 •

edited

Loading

dd-octo-sts Bot commented Oct 14, 2026 •

edited

Loading

datadog-datadog-prod-us1-2 Bot commented Oct 15, 2026 •

edited by datadog-prod-us1-4 Bot

Loading