adam bien's blog

• Java CLI scripts ("JavaScripts") vs. "POJO scripts": the "zlastmod" script listing the last N modified files recursively; the history and naming of POJOs (2003 EJB/CORBA era)
• airails.dev Java CLI script skill: one-shot single-file scripts structured as Boundary Control Entity (BCE)
• New airails.dev JDBC persistence skill using data-oriented programming
• Is deep technology expertise still relevant with LLMs: principles like 2PC, ACID vs. BASE / eventual consistency matter more than ever; green tests are not enough
• Defining great code in the LLM era (preview of the W-JAX Munich talk): easy to find, aligned with requirements, verbose naming, easy to read, consistently structured, without dependencies
• Reading code vs. reading generated Markdown specs or UML diagrams; agents drift toward suboptimal code (POJOs instead of records, JDK 11-style code) unless questioned
• Less extensible, simpler Java code with LLMs: no factories, abstract factories or interfaces without multiple implementations; hexagonal example vs. BCE
• "Go slower to be faster": the bottleneck is business and test departments, not code generation; agent swarms do not help
• Migrating Spring Boot to BCE with Quarkus: repositories/DAOs become plain Java classes with business names (e.g. AccountOpener in eBank), no interfaces, no Manager/Impl/Service/Control suffixes, no GoF builders/factories — enforced by airails.dev Java conventions skill
• airails.dev distribution: plain zip with skills, no CLI, install into .claude/skills, 187-line Java installer script
• BCE communication rules: boundaries call controls directly, a boundary must not invoke a boundary of the same component, cross-component boundary calls allowed, entity-to-entity references across components allowed but cohesion within the package should dominate
• Transaction boundaries always on boundaries; annotate the class, not methods (MicroProfile skill update); a use case is a transaction
• Local inference with Java and Panama FFM: project Argus and Adam's light metal running Gemma locally via llama
• BCE as agentic architecture: business-named top-level packages minimize merge conflicts in parallel agent work and save tokens; demo with the smallest model finding all BCs and excluding health/HTTP/logging infrastructure
• Beyond spec-driven development: spec-driven BCE (SBCE) with specs in package-info.java, bidirectional code/spec sync; new capability brief (user stories for business people mapped to BC specs) and system brief (vision and invariants, once per system) skills
• Free YouTube course "Screaming Architecture for Humans and LLMs" (30 episodes) and the follow-up "Agentic Development with BCE"
• Time machine to episode 52 (2018): CDI across multiple jars and Jandex in Quarkus, avoiding multiple jars and repositories for LLMs, CompletableFuture, microservices ("microservices cancelled" sticker), ECB/BCE
• Validation: JSON-P with hand-written (LLM-generated) validation vs. Bean Validation, OpenAPI conformance; JSON Pointer slash notation for extracting subsets
• Claude Code vs. Codex vs. Mistral Vibe vs. GitHub Copilot CLI: all understand BCE and read package-info; for Java the tool matters little
• Upcoming: W-JAX Munich, J-Fall (Netherlands), Java and LLMs event in Cluj, Romania (BMW TechWorks), airhacks workshop at Munich Airport on December 10th, virtual workshops on agents and migrations

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

Subscribe to airhacks.fm podcast via: spotify| iTunes

The BCE: The Screaming Architecture For Humans and LLMs course is complete: 30 episodes, each under 5 minutes.

Boundary-Control-Entity (BCE) organizes code into packages named after business responsibilities, each with up to three layers: boundary, control, and entity. The package tree shows what the application does, so a developer understands the structure without reading the code. The same property matters for LLMs: a coding agent gets the context it needs from the package names without reading every file.

The course covers:

• Business components as the unit of organization and the responsibilities of the three layers
• Naming without *Impl, *Service, and *Manager
• Interaction rules between components, cyclic dependencies, shared concerns, and when an interface is justified
• BCE applied to CLI applications, AWS CDK, web components, static sites, and tests
• LLMs reviewing, refactoring, and extending BCE codebases

Most episodes walk through real code: ebank (Quarkus, MicroProfile, Jakarta EE), zsmith, a coding agent, and zb, a build tool for dependency-free Java projects. All three are organized with BCE.

The pattern is described at bce.design, the spec-driven variant at sbce.dev, and skills and guardrails for agentic development at airails.dev.

Questions are welcome at the next airhacks.tv episode.

1. Java CLI scripts and the obvious name clash with JavaScript--is "POJO Scripts" a good name?
2. Is it still relevant to deep dive into a specific technology, when everyone seems to be happy with the "good enough" quality produced by LLMs? How does the industry feel right now?
3. BCE: where should repositories, outbound HTTP clients, and their interfaces live?
4. BCE: how should business components communicate--through Boundaries, directly between Controls, or through explicit interfaces?
5. BCE: when are references between Entities belonging to different business components appropriate?
6. BCE: where should transaction boundaries sit, and how should we separate use-case coordination from domain behavior?
7. The local Java inference project: github.com/ProjectArgus-cc/libargus.cc
8. The final episode of the free course "BCE: The Screaming Architecture for Humans and LLMs" is available at airhacks.io
9. Beyond Spec-Driven Development: "From Requirements to Green Tests" with airails.dev
10. Time machine: 100 episodes back (52nd episode):

    CDI components as plugins, CDI bean discovery mode recommendations, dealing with failures in CompletableFuture.allOff, structuring business applications--experiences with ECB, consultancy recommendations, read-only JPA, how to design validations with REST, is JSON-B appropriate for selective serialization, how to implement Flyway migrations with Java EE, most important books about programming

Any questions left? Ask now: gist.github.com/AdamBien/6c8a2e8671acbc43d72dc11fb6a0cc16 and get the answers at the next airhacks.tv. Some questions are also answered with a short video: 60 seconds or less with Java

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

Subscribe to airhacks.fm podcast via: spotify| iTunes

Boundary Control Entity (BCE) was designed for humans: vertical slices named after the domain, one responsibility per layer, and the same structure in every project. The same properties save tokens and prevent wrong turns for coding agents.

BCE was built to reduce human cognitive load. For agents the effect is larger: humans tolerate a messy tree, an agent pays for every file it opens. See bce.design for the pattern and airails.dev for the agent skills.

MVC, DDD, Hexagonal, Onion and Clean Architecture all keep the domain independent of the way it is accessed. The BCE timeline lists the milestones and maps each architecture to BCE: bce.design/timeline.html.

Selected milestones:

• 1979, MVC (Trygve Reenskaug): view and controller are boundaries, the model maps to control and entity.
• 1992, OOSE (Ivar Jacobson): interface, control and entity objects derived from use cases. Interface objects were later renamed to boundary.
• 1997, UML 1.1: «boundary», «control» and «entity» become standard stereotypes.
• 2003, DDD (Eric Evans): business components are modules named in the ubiquitous language. DDD entities and value objects belong in the entity layer.
• 2005, Hexagonal (Alistair Cockburn): driving adapters map to boundaries, the application core to control and entity.
• 2008, Onion (Jeffrey Palermo): the rings map to entity, control and boundary.
• 2012, Clean Architecture (Robert C. Martin): explicitly lists BCE as one of its sources. Clean Architecture uses "boundary" for the interfaces between its circles, not for the layer facing the actors.
• 2014, Microservices (James Lewis, Martin Fowler): a microservice hosts one or more business components.
• 2018, Vertical Slices (Jimmy Bogard): a slice centers on a single request, a business component groups several use cases.

All of them keep the domain independent of the way it is accessed. The differences are in the details:

• BCE structures the code by business components first and applies boundary, control and entity inside each component. Hexagonal, Onion and Clean Architecture are often applied as technical rings at the top level of the application.
• BCE uses concrete classes and introduces interfaces only when there are multiple implementations. Hexagonal ports are interaction contracts and do not require a Java interface per port.
• Boundaries call controls, controls call entities. Calls in the opposite direction are allowed only through events.
• Hexagonal Architecture treats driving and driven actors symmetrically. In BCE, boundaries expose functionality to actors, while controls integrate external resources.

Reference: bce.design. The story behind BCE: airhacks.fm #259: How Boundary Control Entity, UML and Components Happened.

The /sbce skill applies BCE to spec-driven development: one capability spec per business component, with the spec as the boundary contract. Details: sbce.dev.

Free course on airhacks.io: "BCE: The Screaming Architecture For Humans and LLMs".

Subscribe to airhacks.fm podcast via: spotify| iTunes

Subscribe to airhacks.fm podcast via: spotify| iTunes

Subscribe to airhacks.fm podcast via: spotify| iTunes

• floci.io live demo: an AWS cloud emulator written in Java with Quarkus and GraalVM
• floci vs. LocalStack: smaller, faster, many AWS services implemented in Java
• what hexagonal architecture adds to a BCE eBank application
• migrating legacy J2EE projects to Quarkus with LLMs works better than expected
• are outbound integrations boundaries in a BCE Quarkus application?
• zsmith on GitHub and its "concerns" skill from airails.dev
• BCE as agentic architecture
• better code quality keeps agents fast in complex applications - with bad code you hit the wall earlier than humans do
• zagentcapsule (zack): a zero-dependency single executable Java 25 file, about 700 lines, wrapping Apple's container technology on macOS
• zjev: a zero-dependency Java SDK for the jev model, soon to be published
• jev is a fast, cheap classifier rather than a text generator
• time machine to a 2018 gist: the questions have not changed much
• web apps without external dependencies: web components are strong with LLMs, because LLMs are trained on standards
• JFR for business logging: a Kafka-like experience with business events, in-memory logging and streaming at almost no cost
• WebAssembly after eight years: coming and going, it did not overtake JavaScript
• agentic testing: a skill generating at most three tests per method with strong assertions instead of assertTrue
• assertion coverage that catches mutations, fewer meaningful tests with the same structure are easier to review
• skills get shorter as LLMs get more powerful
• the JavaOne talk How to write great Java apps with LLMs and agents is online
• free BCE online course at BCE: The Screaming Architecture For Humans and LLMs with about 15 lessons and more coming

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

1. The homework / challenge: "How could hexagonal architecture improve the BCE eBank application?"
2. Experience with Floci (the Quarkus-based AWS emulator) for local CDK deployments and testing minimal Quarkus serverless projects--integrated into CDK pipelines, or still testing against real AWS accounts?
3. In a BCE-based Quarkus application: are outbound integrations Boundaries as well? REST endpoint, external clients and repository all in boundary, orchestration in control, domain model in entity?
4. Boundary interfaces used by the control hiding the Quarkus REST Clients behind their implementations--or unnecessary abstraction in BCE?
5. Thoughts/update on the JavaOne 2026 presentation: "How to Write Great Java Apps with LLMs and Agents"
6. "What Hexagonal Architecture Adds to a Boundary-Control-Entity (BCE) Project"
7. The state of "Architect-Grade Java with LLMs"
8. Why I'm using VSC?
9. Time machine: 100 episodes back (51st episode):

   Release versioning and git tagging strategies, branching for production vs. testing, build/release workflow automation and auto-deploy, portable multipart file upload with plain JAX-RS, MVC 1.0 future and alternatives for server-side templates with vanilla JS and Web Components, PrimeFaces as a WildFly module instead of WAR packaging, @Stateless vs. @Singleton for JAX-RS resources and thread safety, real-world CI with Jenkins, Maven and Git, structured JSON logging with java.util.logging vs. Log4j 2, separate vs. unified stacks for logs and metrics (Elasticsearch/Kibana vs. Prometheus/Grafana), push-based metrics emission vs. REST metrics endpoints, WebAssembly as the future of the web

Any questions left? Ask now: gist.github.com/AdamBien/c76cf8b4eefeb8239b578c4a1d0009b7 and get the answers at the next airhacks.tv. Some questions are also answered with a short video: 60 seconds or less with Java

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

1. VibeKode Netherlands 2026: How To Write Great Code with LLMs #vibeless
   conference talk VibeKode Netherlands 2026 Utrecht, Netherlands 7 October 2026
   https://vibekode.it/agentic-engineering/java-llm-clean-code/
2. Fewer Tokens, Better Java: Spec-Driven Development at LLM Speed[online event]
   online conference talk 13 October 2026
   https://java.bettercode.eu/veranstaltung-89660-se-0-fewer-tokens-better-java-spec-driven-development-at-llm-speed.html
3. JUGtoberfest 2026, JUG Poznań: Java-First Spec-Driven Development with LLMs
   java user group talk JUGtoberfest 2026, JUG Poznań Teatr Ósmego Dnia, Ratajczaka 44, Poznań, Poland 14 October 2026
   https://crossweb.pl/wydarzenia/jugtoberfest-2026/
4. Silesia JUG #111: Java-First Spec-Driven Agentic Development on Steroids
   java user group talk Silesia JUG #111 Katowice, Poland 21 October 2026
   https://www.meetup.com/silesia-jug/events/316764402/
5. W-JAX 2026: LLM-Assisted Migrations and Modernizations: from Museum to Mainstream
   conference talk W-JAX 2026 Munich, Germany 3 November 2026
   https://jax.de/big-data-machine-learning/llm-assisted-migration-modernization/
6. W-JAX 2026: Disciplined LLM-Assisted Java: Patterns, Architectures and the Process
   conference talk W-JAX 2026 Munich, Germany 3 November 2026
   https://jax.de/ai-development/llm-assisted-java-patterns-architectures/
7. W-JAX 2026: AI Coding war gestern. Jetzt kommen die Agenten!
   conference keynote W-JAX 2026 Munich, Germany 4 November 2026
   https://jax.de/big-data-machine-learning/ai-coding-agentic-engineering-patterns/
8. J-Fall 2026: Java over Markdown: Specs That Compile
   conference talk J-Fall 2026 Pathé Ede, Netherlands 12 November 2026
   https://jfall.nl/timetable-2026/
9. airhacks.university: Architect-Grade Java with LLMs
   in-person workshop airhacks.university Munich Airport, Germany 10 December 2026
   https://airhacks.university
10. Building Local and Serverless LLM Agents[online event]
    online workshop 15 December 2026
    https://workshops.adam-bien.com/building-local-and-serverless-llm-agents.htm
11. LLM-Assisted Legacy System Migration to Modern Java[online event]
    online workshop 17 December 2026
    https://workshops.adam-bien.com/llm-assisted-legacy-system-migration-to-modern-java.htm
12. airhacks.tv Questions and Answers #livestream[online event]
    live streaming show first monday of the month, 8pm CET
    https://www.meetup.com/airhacks/

All of the above announcements are based on my JavaOne 2026 talk, in which I explained why LLMs love Java:

In a recent project (eBank: accounting, customers, transactions, reporting) I checked what Hexagonal Architecture would add to an application organized with Boundary-Control-Entity (BCE). The answer: more classes and little else.

In BCE the unit of organization is the business component (BC), a package named after a responsibility. Each BC has up to three layers: the boundary adapts external protocols (JAX-RS, MCP), the control holds stateless business logic, the entity carries state and behavior. The same capability in both styles:

# BCE
airhacks.ebank.accounting.boundary.AccountsResource
airhacks.ebank.accounting.boundary.AccountsTool
airhacks.ebank.accounting.control.AccountCreator
airhacks.ebank.accounting.entity.Account

# Hexagonal
airhacks.ebank.adapters.in.web.AccountsController
airhacks.ebank.adapters.in.mcp.AccountsTool
airhacks.ebank.application.port.in.CreateAccountUseCase
airhacks.ebank.application.port.out.SaveAccountPort
airhacks.ebank.application.service.CreateAccountService
airhacks.ebank.domain.Account
airhacks.ebank.adapters.out.persistence.AccountJpaEntity
airhacks.ebank.adapters.out.persistence.AccountMapper

1. The boundary is already an adapter. AccountsResource (HTTP) and AccountsTool (MCP) call the same control. Two delivery mechanisms share one control, without an interface between them. An inbound port would formalize a contract with one caller and one implementation.
2. The platform is not an external system. JPA, JAX-RS and CDI are the runtime. A port in front of EntityManager protects against a database swap nobody plans. If Hibernate or PostgreSQL changed, the SQL, the annotations and the test setup would change anyway.
3. One entity instead of three. Account carries JPA, JSON-B and OpenAPI annotations and has behavior like isBalancePositive(). Hexagonal splits it into a domain object, a persistence model and a transport DTO, plus mappers in both directions. For five BCs that is roughly three times the classes.
4. Constraints by construction. The reporting BC must not write. Hexagonal would express this as a query-only port. In eBank AccountQuery uses plain JDBC and never touches the persistence context. A package-info.java documents the reason.
5. Tests over the real protocol. The system test module calls the HTTP and MCP endpoints of the running application. These tests cover more than adapter tests against a mocked port. Business rules on the entity are unit tested without a container.
6. Readability. Open AccountsResource, follow one injection, reach the persistence call. With ports the path is interface, implementation, mapper.

The same properties matter for coding agents. An agent reads the package tree first. The BCE tree names the business (accounting, customers); the Hexagonal tree names the pattern (ports, adapters). Adding a field in eBank touches the entity and the boundary. In Hexagonal it touches the domain object, the JPA entity, the DTO and two mappers. Every additional file is a file the agent can forget, and every mapper is code the agent has to keep in sync. The requirements are placed next to the code: EARS statements (Easy Approach to Requirements Syntax) in package-info.java and a project annotation @Requirement on the boundary methods. The agent implements against the boundary contract and verifies with the system tests. The BCE rules are available as agent skills at airails.dev.

With CDI, a second implementation does not require Hexagonal either. Turning a control into an interface is an IDE refactoring: the injection points stay unchanged, and a qualifier, @Alternative, or a plain if statement selects the implementation. A second persistence technology affects only the controls that use it. Business rules on the entity are already tested without a database, and teams can own business components instead of layers.

See also: Alistair Cockburn's original description and the buckpal Hexagonal reference implementation. Both buckpal and eBank manage bank accounts, which makes the two package trees easy to compare.

Subscribe to airhacks.fm podcast via: spotify| iTunes

Java's open ecosystem—specifications, source code, JSRs, JEPs, mailing lists, MicroProfile, and Jakarta EE—made it an ideal training ground for LLMs. These models learned more than syntax: they absorbed Java's patterns, idioms, and design philosophy. In this live-coding session, we'll explore how to put that knowledge to work with short prompts and rapid iterations. (...)

Presented at JavaOne 2026 (CA, March 2026):

• Spec-Driven BCE (SBCE) in two phases: clarification questions until the requirements are clear, then package-info JavaDoc, then code
• New airails.dev skills: AWS CDK, web sprinkles, Java 25 CLI scripts with BCE
• EARS requirements in JavaDoc, @Requirement annotation generating parameterized tests, zunit and Playwright tests, architecture diagrams from BCE
• Outer loop on top of SBCE: the software factory
• entwickler Summit Berlin demo: Currywurst stand application generated in 10 minutes, 30 to 80 percent token savings
• Do we still need architecture? Serializing agents by dispatching GitHub issues to components
• Agent Smith (zsmith): @Concern for cross-cutting concerns, JFR as business observability with agent turn, subagent and LLM API call events, @Relational event groups, roughly 300 KB with no dependencies
• ZHTMLDB (renamed from HTMLDB) with partial keys, BCE in a single Java 25 script, interfaces instead of classes with private constructors
• BCE versus hexagonal: BCE is stable since 1992, hexagonal is a special case with more plumbing and no naming conventions. Homework: clone eBank and show where hexagonal would improve it
• eBank walkthrough: components, JAX-RS resource and MCP tool from the same component, MCP error handling with success plus descriptive text
• J2EE to Quarkus migration with airails.dev skills: migration advisor, concept extractor, lift and shift versus full migration, JDK 6/8 to Java 25 performance gains
• Domain logic in entities and records, procedural logic in controls
• Automation engines: zsmith, LittleHorse, and the Jev model for if/else decisions via plain Java HttpClient
• Free BCE course on YouTube
• Time machine to episode 50: Swing migration workshop at Munich airport, WebAssembly, exception handling, ThreadLocal versus scoped values, thin WARs, equals and hashCode in JPA entities, JAutodoc and AI

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

1. Another take on opinionated Spec-Driven development with Java
2. Do we still need architectures?
3. Kafkaesque JFR
4. zhtmldb for agent memory
5. You recommend BCE. How do you keep business logic independent from technology? Do you combine BCE with Hexagonal Architecture, or do you think BCE alone is sufficient?
6. How does BCE compare to hexagonal architecture? What are the Pros and Contras? When to prefer one over the other? Does it make sense to migrate from one to the other or is either one good enough so a migration is not justified?
7. Time machine: 100 episodes back (50th episode):

   Swing Migrations Workshop, Exception handling strategies, Transparent and remote UUI propagation, Thin WARs and 3rd party JPA, Equals and hashCode in JPA entities, Remote CDI events, WebSockets testing, Jakarta EE's future, Combining Primefaces with JAX-RS, When Numbers Are More Important Than Quality

Any questions left? Ask now: gist.github.com/AdamBien/fde8e4518d3aa789f962b87ed93675e1 and get the answers at the next airhacks.tv. Some questions are also answered with a short video: 60 seconds or less with Java

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

Subscribe to airhacks.fm podcast via: spotify| iTunes

Before LLMs a senior engineer carried the architecture in their head, and a deviation from it cost typing effort. An agent generates a deviating structure as cheaply as a conforming one, and it does not remember what it generated for the previous feature. Without architecture and design written down, the agent decides everything per feature: where the code goes, how it talks to the rest of the system, which operations to expose, and what the data looks like.

Architecture removes coordination ambiguity: where does this belong, and how does it interact with the rest? It is decided once per system and held constant. It defines what a business component is, that it consists of Boundary, Control and Entity, what each layer may depend on, and how components communicate. The human owns it. Rules a human team treats as guidelines have to be absolute for the agent. It can argue for an exception, but it argues again in every task, without the history behind the rule, and the exception it grants in one component is not remembered in the next. Stricter does not mean more rules. A named architecture such as BCE is three layers, one dependency direction, and a package layout. It compresses pages of rules into a few tokens in the prompt, and the agent never rediscovers it per task. Two agents implementing two features in parallel, with no component structure, edit the same shared classes and overwrite each other's changes. With component boundaries defined up front, each agent works inside its own component. A reviewer checks placement without reading every line.

Design removes implementation ambiguity: how exactly should this piece behave? It is decided per feature, inside the bounds the architecture already fixed. Which operations does this boundary expose, which entities does the component own, is this one control class or three, what is the shape of the record. The agent owns it, steered by a specification. In my projects the specification lives in package-info.java, next to the code it describes (SBCE). The agent implements it, the tests decide whether the result is adequate, and the agent regenerates it when the specification changes.

The test: if a decision would be the same in every business component, it is architecture and belongs in a convention the agent loads once. If it would differ between the orders component and the invoices component, it is design and belongs in the specification of that component. Package layout, layer dependencies and naming rules pass the first test. The shape of an order line item passes the second. A design decision that turns out to be universal gets promoted into the architecture.

In classical projects architecture takes a few days and design takes the rest of the project. With agents the ratio inverts. Design becomes cheap because it is generated. Architecture becomes more valuable because it is the only thing that keeps a thousand generated designs consistent with each other.

Fewer decisions left to the agent means fewer mistakes, fewer corrective turns, fewer tokens, and less human review.

A clarifying question from the agent costs a full round trip. A type declaration costs a handful of tokens. Verbose Java is the cheaper option.

1. Ambiguity costs a turn, verbosity costs tokens. A wrong guess costs a full extra round trip. A declared type costs a few tokens in every turn that follows, and prevents the guess.
2. Constraints are machine-verifiable. javac is the cheapest judge in the loop. A type error costs milliseconds and no tokens. In a dynamic language the same mistake surfaces at runtime or in a review turn.
3. Code is the only context the compiler checks. A sealed interface survives across sessions and developers. A prompt or an instruction file like CLAUDE.md, AGENTS.md or SKILL.md is re-sent on every session and never enforced.
4. Annotations declare rules in a single word. @NotNull, @Size, @Transactional, @Path, @Inject: each states a constraint the agent would otherwise infer from the method body or ask about. Standard annotations compress further, because @Path maps to spec behavior the model has seen thousands of times. An in-house framework has to be explained in every session.
5. Names lead from the requirement to the code. A requirement that mentions the customer email leads the agent to findCustomerByEmail with a single search. A method named get forces it to read the implementation. In a BCE package structure (boundary, control, entity), the package name tells the agent the layer from the import alone. The compiler never checks names, so a misleading name misleads as reliably as a descriptive one guides.
6. Intent is not ceremony. Records, sealed interfaces, generics, final, checked exceptions, annotations and descriptive names carry semantics. Getters, setters and Impl suffixes carry nothing.

Verbose code consumes output tokens and context window. A clarifying question consumes a full round trip on top of both.

A rule from 2013, How To Comment With JavaDoc, predates coding agents and still applies: the WHAT goes in the name, the HOW in the code, and the WHY in the comment. The WHY is the only context the agent cannot derive from the source, so a JavaDoc on a non-obvious decision keeps the rationale in the repository instead of in the prompt. The conventions that made code readable for the next developer make it unambiguous for the agent.

Subscribe to airhacks.fm podcast via: spotify| iTunes

Subscribe to airhacks.fm podcast via: spotify| iTunes

"AI engineers" established a new genre of bragging: how little of the code was written by hand, what percentage the agent generated, how many days since the last manually typed line. The proportion of generated code became the achievement.

Over a century ago, transportation made walking optional. Since then, nobody has opened a story with "I didn't walk here." People talk about where they went.

"Brag about arriving, not about not walking. Brag about shipping, not about not coding."

The users cannot tell a generated line from a typed one, and the maintainers only care whether it is simple and tested. The important details remain the same: the software went into production, it is secure and easy to change, and it works.

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.