Skip to content
Agent Friendly Code

What to put in an AGENTS.md for Spring Boot

Most Spring Boot code agents learned is 3.x, and Boot 4 breaks it: starters are split into modules, Jackson 3 moves packages, and test annotations were removed. State the Boot version and build tool.

By Himanshu Singh · Updated · How we score →

Which commands should it list?

  • mvn spring-boot:runor gradle bootRun; runs exploded, as in the IDE
  • mvn spring-boot:test-runor gradle bootTestRun: the test main, with dev services

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

What layout should it explain?

  • Maven or Gradle, and whether the wrapper (./mvnw, ./gradlew) is checked in.
  • Whether src/test has a test main that starts dev services with SpringApplication.from(…).
  • application.properties or application.yaml, and which profiles exist.

What do agents get wrong?

  • Boot 4 needs Java 17+ and Jakarta EE 11; spring-boot-starter-web is deprecated for spring-boot-starter-webmvc.
  • Jackson 3: import tools.jackson.* (annotations stay in com.fasterxml.jackson.annotation), and @JsonComponent is now @JacksonComponent.
  • @MockBean and @SpyBean were removed for @MockitoBean and @MockitoSpyBean; @SpringBootTest no longer sets up MockMvc without @AutoConfigureMockMvc.
  • Put @ServiceConnection on a Testcontainers field instead of writing connection properties by hand.

From the official docs: github.com/Spring-Boot-4.0-Migration-Guide (new tab) · docs.spring.io/system-requirements.html (new tab) · docs.spring.io/running-your-application.html (new tab) · docs.spring.io/dev-services.html (new tab) · docs.spring.io/testcontainers.html (new tab). The rest of the file is the same for any project: what goes in an AGENTS.md.

Spring Boot repos with an AGENTS.md or CLAUDE.md (4)

Built on Spring Boot; 4 pass the AGENTS.md check in full.

Spring Boot repos with an AGENTS.md or CLAUDE.md
RepoFileLengthStarsLanguageScore
halo-dev/haloAGENTS.md 2,056 chars40.4k ★Java82.7
alibaba/nacosAGENTS.md 23,656 chars33.5k ★Java84.5
conductor-oss/conductorAGENTS.md 9,485 chars32.5k ★Java80.0
apolloconfig/apolloAGENTS.md 4,100 chars29.8k ★Java81.8

By language: Java AGENTS.md examples · Kotlin AGENTS.md examples

More examples: Next.js · React · FastAPI · Flutter · Android · .NET · Rails · Vue · Laravel · Django · Angular · React Native · iOS · all examples