Agent Friendly Code

What to put in an AGENTS.md for a Java repo

Say whether the build is Maven or Gradle, and run it through the wrapper the repo commits (./mvnw, ./gradlew), which fetches the build tool version the project pins. In a multi-module build, say how to build and test one module.

Which commands should it list?

  • ./gradlew buildassembles and runs every check, tests included
  • ./gradlew test --tests FooTest.barone test class or method
  • ./mvnw verifythe Maven lifecycle up to verify, integration tests included
  • ./mvnw -pl :core -am testone module, plus the modules it depends on
  • ./mvnw test -Dtest=FooTest#barone test method, with Surefire

Write them as your repo runs them, with its package manager and flags, plus how to run one test.

What layout should it explain?

  • The modules and what each holds: <modules> in the root pom.xml, or settings.gradle(.kts).
  • The JDK version the build needs.
  • Any generated sources (annotation processors, protobuf, OpenAPI) and the task that makes them.

What do agents get wrong?

  • Use the wrapper, not an installed mvn or gradle, which may be another version.
  • In a multi-module Maven build, -Dtest fails every module with no matching test; add -Dsurefire.failIfNoSpecifiedTests=false.
  • -pl my-module selects a directory and -pl :my-module an artifactId.

From the official docs: docs.gradle.org/gradle_wrapper.html (new tab) · docs.gradle.org/java_plugin.html (new tab) · docs.gradle.org/java_testing.html (new tab) · maven.apache.org/wrapper (new tab) · maven.apache.org/introduction-to-the-lifecycle.html (new tab) · maven.apache.org/guide-multiple-modules.html (new tab) · maven.apache.org/test-mojo.html (new tab). The rest of the file is the same for any project: what goes in an AGENTS.md.

Java repos with an AGENTS.md or CLAUDE.md (19)

19 of the 28 Java repos on the leaderboard have an AGENTS.md or CLAUDE.md at the root, and 19 are long enough to pass the AGENTS.md check in full. Most-starred first; each file name links to the file.

Java repos on the leaderboard with an AGENTS.md or CLAUDE.md
RepoFileLength
elastic/elasticsearchAGENTS.md 17,603
spring-projects/spring-frameworkAGENTS.md 4,261
netty/nettyAGENTS.md 3,646
apache/kafkaAGENTS.md 9,997
apache/flinkAGENTS.md 31,484
questdb/questdbCLAUDE.md 31,426
apache/dorisAGENTS.md 15,639
quarkusio/quarkusAGENTS.md 6,872
apache/pulsarAGENTS.md 7,099
apache/druidAGENTS.md 5,398
trinodb/trinoAGENTS.md 1,592
debezium/debeziumAGENTS.md 20,173
StarRocks/starrocksAGENTS.md 4,467
AutoMQ/automqAGENTS.md 1,489
apache/cassandraAGENTS.md 4,413
apache/seatunnelAGENTS.md 8,693
apache/icebergAGENTS.md 17,430
apache/pinotAGENTS.md 8,110
apache/paimonAGENTS.md 3,558

More examples