adam bien's blog

How to Start an LLM-Assisted Java Project 📎

Most context engineering goes into supplying the model with knowledge. For a Java project nearly all of that is redundant, because the model already read the specs. What it does not have is an opinion about how your project should look. That is the only thing worth supplying.

  • Skip the knowledge plumbing. Java SE, Jakarta EE and MicroProfile APIs stay stable across versions, so what the model learned at training time still applies today. MCP servers, documentation indexes and vector stores mostly re-supply what it already has.
  • Start brownfield. I do not generate a project from nothing. quarkus-microprofile for services, java-cli-app for tools, aws-quarkus-lambda-http-api-cdk-plain for AWS Lambda behind an HTTP API.
  • Keep the starter tiny. The CLI template is three kilobytes, a README and one App.java. That fixes the package layout, the build and the naming conventions without describing any of them in prose.
  • Pick a well represented and stable architecture. BCE has been described since the nineties and has not moved since, so naming it is enough. A homegrown layering has to be taught in every session.
  • Keep AGENTS.md minimal. Build instructions only. How to start dev mode, how to package, how to run the system tests. The structure is already visible in the project.
  • Put the design principles in skills. A handful of rules is enough, and "use Java SE libraries first" is the one that pays for itself immediately.

The useful content of an AGENTS.md is roughly this much:

cd service
mvn quarkus:dev

cd service-st
mvn verify

Everything else is either already in the code or belongs in a skill. The dependency rule is a good example. Without it the model reaches for whatever library it has seen in a million GitHub projects. With it, the JDK is the default and a new dependency has to be argued for.

The skills implementing BCE for each of these stacks: java-conventions, microprofile-server, java-cli-app and aws-cdk. Installation for any coding agent at airails.dev.

Working code and a few principles. The rest it already knows.