Guides · Java
How to write an AGENTS.md for a Java project
Measured across 40 of the most-starred Java repositories on GitHub. The median scores 44 out of 100.
What Java repos get wrong
Java scores second lowest, and the reasons are unusually consistent. Every single Java repository measured commits no lint or format configuration. 92% pin no dependency lockfile, and the same share offer no test command an agent can discover, because Maven and Gradle conventions live in build files an agent has to interpret rather than in a place it looks first. Naming the commands in an AGENTS.md is worth more here than in any other ecosystem, precisely because nothing else exposes them.
Most common failures
share of 40 Java repositories scoring zero on each
Lower is better here. These are failures, not scores.
A working example
Commands first, conventions second, none of the persuasion a README carries. The test is whether a capable stranger could make a small change and verify it using only this file.
Save it at the root of the repository
as AGENTS.md. Tool-specific files like CLAUDE.md or .cursorrules still work, but
AGENTS.md is the one every tool reads.
# AGENTS.md ## Setup ./mvnw verify -DskipTests ## Commands ./mvnw test # full suite, must pass before any commit ./mvnw spotless:check ./mvnw package ## Conventions - Tests mirror the package under src/test/java. - Use the wrapper, never a system-installed maven. ## Gotchas - Requires JDK 21. See .java-version.
The two lines that matter most
If you write nothing else, write these. An agent that cannot install the project cannot start, and one that cannot run the tests cannot tell whether it broke something.
# install./mvnw verify -DskipTests# verify./mvnw test
Have it drafted instead
Point the tool at a repository and it writes the file from what is already there, rather than from a template.
For private code, the same rubric runs on your machine and sends nothing anywhere:
$ npx agentreadme --write-agents
Other ecosystems