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 toverify, 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 rootpom.xml, orsettings.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
mvnorgradle, which may be another version. - In a multi-module Maven build,
-Dtestfails every module with no matching test; add-Dsurefire.failIfNoSpecifiedTests=false. -pl my-moduleselects a directory and-pl :my-modulean 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.
| Repo | File | Length |
|---|---|---|
| elastic/elasticsearch | AGENTS.md | 17,603 chars |
| spring-projects/spring-framework | AGENTS.md | 4,261 chars |
| netty/netty | AGENTS.md | 3,646 chars |
| apache/kafka | AGENTS.md | 9,997 chars |
| apache/flink | AGENTS.md | 31,484 chars |
| questdb/questdb | CLAUDE.md | 31,426 chars |
| apache/doris | AGENTS.md | 15,639 chars |
| quarkusio/quarkus | AGENTS.md | 6,872 chars |
| apache/pulsar | AGENTS.md | 7,099 chars |
| apache/druid | AGENTS.md | 5,398 chars |
| trinodb/trino | AGENTS.md | 1,592 chars |
| debezium/debezium | AGENTS.md | 20,173 chars |
| StarRocks/starrocks | AGENTS.md | 4,467 chars |
| AutoMQ/automq | AGENTS.md | 1,489 chars |
| apache/cassandra | AGENTS.md | 4,413 chars |
| apache/seatunnel | AGENTS.md | 8,693 chars |
| apache/iceberg | AGENTS.md | 17,430 chars |
| apache/pinot | AGENTS.md | 8,110 chars |
| apache/paimon | AGENTS.md | 3,558 chars |
More examples
- Every language: all 226 files, with the longest and shortest that pass
- Most agent-friendly Java repos: all 28, ranked on every check
- AGENTS.md vs CLAUDE.md: which file to write
- TypeScript (64)
- Python (29)
- Rust (24)
- Go (23)
- C++ (11)
- JavaScript (9)
- Kotlin (8)
- PHP (7)
- Ruby (6)