adam bien's blog

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.

Subscribe to airhacks.fm podcast via: spotify| iTunes

Java specifications, JSRs and JavaDoc have been publicly available, crawlable, versioned and consistently formatted for three decades. Jakarta EE and MicroProfile publish theirs as plain HTML on the open web, where Common Crawl picks them up, and Common Crawl is one of the most widely used sources of LLM training data. Beyond the amount of text, the language itself happens to be built the way an LLM likes it.

1. Explicit types. The contract is written down, not inferred by the reader. A generated signature carries its own meaning, and a wrong guess is rejected by the compiler.
2. Verbosity. Redundant syntax works as error correction. The same intent shows up in the type, the name and the annotation, so a single mistaken token rarely survives.
3. Rigid conventions. PascalCase types, camelCase methods, reverse domain packages, one public type per file. Highly predictable, low entropy.
4. Annotations. @Path, @Inject and @GET declare a concern instead of implementing it. The names are standardized and appear identically across the whole ecosystem, so the model recognizes what is being asked for, and the container supplies the registration, the lookup and the lifecycle. Intent without wiring.
5. Backwards compatibility. Java takes source and binary compatibility seriously, and modern tooling still reads class files from compilers that went out of use decades ago. Books, articles and answers from years back describe code that largely still works, so old material stays useful instead of turning into noise.
6. Normative prose. Jakarta specs state requirements as MUST, SHOULD and MAY, usually citing RFC 2119. MicroProfile defines the required behavior and ships a TCK that checks it. The JLS repeats "it is a compile-time error if" throughout. Precise prose, and something executable that verifies it.
7. Implementation independence. @Inject is JSR 330, not the property of any container. It is read by Jakarta EE, Quarkus, Micronaut, Helidon, Spring, WildFly, JBoss EAP, Payara, GlassFish, Open Liberty, WebLogic, Vidocq, Google Guice, Dagger, Eclipse Sisu, Apache Maven and the Eclipse Platform, and CDI adds scopes, qualifiers, producers and events on top of it. Instead of picking between different versions of unrelated vendor implementations, the model writes a token with stable meaning. There are fewer places to go wrong.
8. A fast compiler as verifier. Invented method names never reach production, they fail in the build. javac needs seconds, and java App.java runs a source file without any build step. Generate, compile, correct is cheap enough to become the model's inner loop.

The result is code with very few degrees of freedom:

public class Garage {

    @Inject
    Cars cars;

    @Inject
    Event registered;

    public void register(Car car) {
        this.cars.add(car);
        this.registered.fire(CarRegistered.of(car.id()));
    }
}

The standardized APIs fix the programming model, javac checks the types and signatures, and the container checks the injection points and the wiring. The model fills in a predefined programming model instead of inventing one.

Subscribe to airhacks.fm podcast via: spotify| iTunes

abstract:

Java's radical openness created the perfect LLM training ground: open specifications, open-source implementations, and the complete JCP including every JSR, JEP. LLMs didn't just learn Java syntax - they absorbed its idioms, patterns, and design philosophy.

This session will demonstrate how to use this LLM's Java knowledge through practical techniques and tools such as Claude Code and Kiro. Through live coding, you will learn how to engineer efficient prompts tailored to Java best practices, generate idiomatic Java 21+ code leveraging records, pattern matching, and proper naming conventions, create meaningful system tests, and maintain architectural consistency in enterprise applications. The resulting code is readable by humans and machines alike.

I used the skills from: airails.dev for LLM-assisted code generation. The BCE architecture is described here: bce.design. Also, check out the Java-flavored spec-driven development with sbce.dev

Docker's building best practices recommend multi-stage builds. The first stage compiles the source, the final stage copies the result into a minimal runtime image. That is useful when Docker is the build environment. In a Maven or Gradle centric organization with an existing CI/CD pipeline, Docker is not the build environment.

The pipeline already compiles, tests, and versions the artifact in a controlled, isolated environment. A multi-stage build compiles it a second time, with a different JDK, a different local repository, and a different cache. The image no longer contains the artifact that passed the tests. It contains a rebuild that happens to share the same commit.

The single-stage alternative packages what the pipeline produced:

FROM eclipse-temurin:25-jre-alpine
COPY target/application.jar /opt/application.jar
CMD ["java", "-jar", "/opt/application.jar"]

Ranked by importance:

1. Build once and promote the exact artifact.
2. Use a controlled, isolated, reproducible CI build environment.
3. Keep the runtime image minimal.
4. Use multi-stage Docker builds when Docker is the chosen build environment.

Multi-stage is a technique, not an architectural best practice. Making multi-stage Dockerfiles the rule obscures the more important one: the build tool and the pipeline own the software build, Docker only packages its output.

Agents generate code in seconds, so investing in code quality looks obsolete. My daily work with agents shows the opposite. Every session starts by reading the existing code, and its quality decides how productive the session is.

• Agents amplify the local style. LLMs match the surrounding code. Clear conventions get reproduced, and so does degradation: in a codebase full of Managers and Impls, the agent generates the next one.
• Simplicity saves context. Every additional layer, interface, or indirection is another file the agent has to read before it can change anything. The smaller and flatter the code, the more of the system fits into the context window, and the faster a human reviews the result.
• Vertical slices localize the change. A prompt describes a feature, not a technical layer. One business component per responsibility keeps the change inside a single package: small context, and parallel agent sessions without collisions. Horizontal layering scatters every feature across the whole tree.
• Verbosity creates semantic context. Spelled-out names, explicit signatures, annotations, and JavaDoc that states the intent are context the prompt no longer has to deliver. The same names are navigation: an agent finds a package named after a business responsibility without scanning the project. This complements simplicity: the structure stays minimal, and the names and declarations carry the meaning.
• Every artifact needs a purpose. Agents treat whatever exists as intentional: they maintain dead code, extend speculative abstractions, and route new features through unused flexibility. Code without a purpose misleads the next session.
• Standard patterns are in the LLM weights. Conventions like BCE are described in decades of books and articles, so agents apply them without explanation. A self-invented structure has to be taught in every session.
• Tests are the feedback loop. An agent iterates autonomously only against executable verification; spec-driven workflows like SBCE use the test suite to decide when the work is done. Without tests, the agent cannot verify its own claims.
• Drift is invisible to the agent. Every generated change looks reasonable in isolation, and the agent has no sense of a slowly degrading whole. Architectural review stays a human responsibility, and simple, short code is what keeps it feasible at agent speed.

Code quality was always an investment in the next developer who has to read the code; in agentic development, the next reader arrives with the next prompt.

The conventions from this post are packaged as installable skills for any coding agent at airails.dev.

"Spring Gateway vs nginx vs cloud API gateways: nginx and HAProxy as proxies, cloud gateways transforming HTTP into CloudEvents, authentication, JWTs and content-based routing, BCE as the show's most used term, BCE namespaces from domain ideas, BCE applied to static pages where folders are menu items and cards are feature components without JavaScript, HTMLDB released today: a database built on HTML as valid XML in ~550 lines of Java 25 with no external libraries, tables and rows via CLI, data viewed in the browser as semantic HTML, HTMLDB motivated by agent memory since agents understand XML well, watching agent memory live in a zero-dependency web server, Agent Smith migrated to HTMLDB, symbolic links as convention over configuration for multiple schemas, HTMLDB in the Z family, not an Oracle or Postgres replacement, floci.io: Quarkus-based emulation of Lambda, DynamoDB, Neptune, CodeBuild and ElastiCache with ~20k GitHub stars in 5 months, always reviewing LLM-generated code to refine skills and AI rails, why web frameworks may disappear: LLMs understand the web platform and do not need React, Angular or Svelte developer experience, agents generating perfect web component code without frameworks, an airhacks.live web components workshop deriving a JTree-like structure from design.md, Jakarta EE Core covering ~80% with CDI, bean validation and JAX-RS, exclusive grounding against MicroProfile so code runs on Quarkus without the agent knowing Quarkus, AI rails updates: AWS CDK skill mapping BCE to CDK constructs, static web and vanilla JavaScript sprinkles, a vanilla Java agent on AWS agent core runtime in ~40 lines with 60ms startup and 5KB, ZDMD turning design.md into design tokens for framework-free web components, ported from TypeScript with shorter Java code, time machine to episode 49 from April 2018: WebStart, JavaFX revival since LLMs understand JavaFX well, no frameworks over JSF-to-Angular, JWT system tests with real test tokens, thin WARs, EclipseLink on Payara over shipping Hibernate, query caching from EHCache to Infinispan, a YouTube course on BCE, and a workshop at Munich airport in December"

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

The most asked BCE question is not what the layers mean, but which dependencies are allowed. Inside a business component the dependencies point downwards.

1. boundary to control, control to entity. The boundary offers coarse grained, easy to use methods, the control finer grained, reusable ones, the entity holds the data, as a smart domain object or an anemic record.
2. boundary to entity, directly. A control is only needed for the more complex use cases. For the simple ones, skipping the control is the default.
3. Never entity to control, never entity to boundary. An entity that needs something from above emits an event instead. Any layer of any component can process it, and the entity stays unaware of the receiver.

Between business components three cases matter:

1. boundary to boundary: avoid it. A boundary is designed for external actors, not for other business components. Acceptable at the very beginning, later a control takes over.
2. control to control: allowed, and direct. No interfaces in between required. In Quarkus and MicroProfile applications the control is injected.
3. entity to entity: allowed. Relations between persistent objects would be impossible without it.

Then count the links. A component that communicates less with itself than with its neighbors was cut in the wrong place.

See bce.design for the pattern rules and sbce.dev for the spec-driven workflow built on it.

Episode 6 of the free Screaming Architecture with BCE series applies the rules to two components of the example project:

The full course is available at airhacks.io.

1. BCE/ECB (Boundary-Control-Entity) for ...with static, semantic pages
2. floci.io AWS cloud emulator
3. "the role of the platform in LLM-assisted development" by Ondro at LinkedIn
4. announcement: htmldb
5. Free course: BCE: The Screaming Architecture For Humans and LLMs 👉 airhacks.io
6. New AWS-CDK and web-platform skills 👉 airails.dev
7. One seat left 👉 airhacks.university
8. unscripted: plain HTML showcase 👉 unscripted
9. Time machine: 100 episodes back (49th episode):

   Swing without WebStart, Preventing Web Sessions, Performance Testing with JWT, JPA query result caching, SAML Java Frameworks, JavaScript databinding with WebSockets, Asynchronous Java EE, Using embedded container testing with container resources, When Numbers Are More Important Than Quality

Any questions left? Ask now: gist.github.com/AdamBien/e58d00a2cb06d6ca5e6039bf48f3b1db 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

Web frameworks solve human problems. Readable abstractions, conventions a team can share, a line on a CV that outlasts the project. All of it is about people, and all of it assumes a human types the code and another human reads it.

An agent has no career to build, and gets nothing from an abstraction whose purpose is to be read. Consistency across a codebase comes from the skill the agent follows, not from the framework.

React, Angular, Vue and Svelte all render through the same DOM. The abstraction leaks, the way all non-trivial abstractions leak, so debugging any of them ends in the platform underneath. The platform knowledge is required either way; only the framework is optional.

An agent writes against the web platform instead. A list component is about twenty lines, imports and registration included. The application ships without a package.json, a bundler or a transpiler: an import map resolves the imports, so what the browser loads is what is on disk.

There is also no install step, and no lockfile, transitive graph or postinstall script to audit, which matters more with agents than without: an agent adds packages on its own, and checking what it pulled in is the review that stops happening first.

What frameworks were invented for keeps arriving as standards:

• Custom Elements and Shadow DOM for the component model;
• form-associated custom elements with ElementInternals for validation and form participation;
• ES modules and import maps for dependency resolution without a build step;
• structuredClone() for immutable state updates, in place of Immer;
• Navigation API and URLPattern for routing;
• <dialog>, popover and View Transitions for overlays and animated view changes;
• CSS nesting, :has(), container queries and cascade layers for what used to need a preprocessor.

The gap keeps closing, and it closes faster than it used to. Ideas that start in frameworks now reach the specifications within a release cycle or two, and the Interop project gets them into all three engines in months instead of years, tracked by Baseline. Custom elements already carry the interfaces of GitHub, YouTube, Photoshop on the web, SAP UI5 and Adobe Spectrum. React 19 added proper custom element support, so the frameworks are moving toward the platform rather than away from it.

What the standards do not cover is small enough to stop calling a framework. Templating is lit-html at a few KB. State management is a hundred lines of unidirectional store code. Neither locks the application in.

Widget libraries are needed either way. React and Angular do not ship a data grid or a rich text editor, so both stacks add one, and the interface decides which one an agent can drive. A custom element exposes attributes, properties, events and slots, and that interface is specified, so an agent knows the calling convention for an element it never saw during training. A React component exposes arbitrary props that change between major versions, and the agent needs correctly versioned documentation to drive it.

Platform code outlives the conventions that produced it. Revise the conventions in a skill, and the code generated last year still runs. Move from one framework major version to the next, and the code itself has to move.

Agents Love The Web Platform's Backward Compatibility covers why the specifications are also the better grounding for an agent.

Without further instructions, an agent writes web code from everything it saw during training: tutorials, framework docs, Stack Overflow answers, blog posts from 2014. The output mixes all of it. Restricting the grounding to normative Web Platform specifications (HTML, DOM, CSS, ECMAScript, ARIA) removes the mix.

The Web Platform is unusual as a corpus, because it hardly contradicts itself. A DOM example from 2012 and a DOM example from today still describe the same platform, so old and new material reinforce each other. Documentation for two major versions of the same framework contradicts itself instead, and an agent that read both has no way to tell which half applies.

Public specifications and multiple independent implementations help as well. Neither would be worth much without the strict backward compatibility: a public specification that gets replaced every few years produces the same contradictions as a framework.

Grounded against the specifications, the usual mistakes get rare:

• presenting Chrome behavior as a standard;
• confusing React or Angular conventions with browser requirements;
• inventing APIs that only exist in a framework;
• declaring an older API invalid because a newer one exists;
• treating browser error recovery as authoring advice.

The generated code uses the platform directly: semantic HTML, DOM APIs, Custom Elements, form-associated elements, standard events and CSS. Fewer dependencies and less ceremony. The code also survives longer, because a build tool changing its internals does not force a rewrite.

One catch: backward compatibility also preserves what the platform got wrong. Browsers keep supporting obsolete markup and historical quirks, because existing sites depend on them. Browser support is not an authoring recommendation. An agent grounded in the specifications has to know the difference, and it has to check the browser versions the project supports, not only the specification text.

The web platform section at airails.dev ships the skills that encode this: web-conventions, web-static, web-components, and web-latest.

An agent running on the AWS Bedrock AgentCore Runtime has to implement a minimal HTTP contract: POST /invocations answers requests, GET /ping reports health, both on port 8080. The JDK's built-in jdk.httpserver is sufficient.

The AWS Java Agent Core Runtime CDK quickstarter project implements the contract in vanilla Java 25 with zero external dependencies. The complete contract is implemented in a single interface:

public interface AgentRuntime {

    int AGENT_CORE_PORT = 8080;

    static String invokeAgent(String payload) {
        IO.println("invocation: " + payload);
        return """
            {"time":"%s"}""".formatted(Instant.now());
    }

    static String checkHealth() {
        return """
            {"status":"Healthy"}""";
    }

    static void serve() {
        HttpEndpoint.start(AGENT_CORE_PORT, AgentRuntime::invokeAgent, AgentRuntime::checkHealth);
    }
}

A second interface, HttpEndpoint, wires both routes on the JDK's HttpServer. Every import comes from the JDK. The sample agent answers each invocation with the current UTC time as JSON. Packaged with zb, the complete agent.jar is 5,440 bytes, and the endpoints are serving about 60 ms after JVM start (OpenJDK 25, Apple Silicon).

Deployment is also Java. The project ships with an AWS CDK app (the cdk module) that builds the agent's four-line Dockerfile (Amazon Corretto 25, the jar, an ENTRYPOINT) into an ARM64 container image asset and provisions the AgentCore runtime from it. The image is built and pushed during cdk deploy. The system tests invoke the deployed agent with the AWS SDK's BedrockAgentCoreClient.

The project was developed with /sbce, the spec-driven BCE workflow: the AgentCore contract is declared as EARS requirements (Easy Approach to Requirements Syntax) in the business component's package-info.java, and @Requirement annotations (trimmed from the listing above) trace the boundary methods back to the spec.

The project is part of constructions.cloud, a collection of Java CDK templates and quickstarters.

Subscribe to airhacks.fm podcast via: spotify| iTunes

The /aws-cdk skill generates and reviews Java AWS CDK v2 projects organized as BCE (Boundary-Control-Entity) business components. Infrastructure code follows the same structure as a business application instead of accumulating as a flat list of resources. It ships as an AIrails skill: /aws-cdk.

The main tenet is the separation of stacks from constructs. A stack decides which resources deploy together and lives in boundary. A construct defines how a capability is configured, is reusable across stacks, and lives in control as a stateless factory, preferably an interface with static methods. Immutable data that describes infrastructure without creating it, like build specs and typed value objects, lives in entity.

The remaining ideas follow from that split:

1. Packages are business components named after the AWS capability they provision: s3, cloudfront, cognito, route53, stepfunctions. A component spanning multiple services is named after its domain responsibility.
2. A single CDKApp entry point loads configuration as typed Java records, applies tags, wires stacks in dependency order, and calls app.synth(). Stacks never read CDK context or environment variables; they receive typed records.
3. Regions are pinned in a central Stacks interface exposing StackProps constants. Account and region are never inlined in stack classes.
4. Stacks stay independent. A producing stack passes resource interfaces like IBucket or ITable to consumers, never stack instances.
5. For IAM, grant* methods on the target construct generate least-privilege policies. Explicit PolicyStatements are the fallback.
6. Synthesis stays deterministic and side-effect free: no SDK calls, no timestamps, no randomness during construction. Tests assert on the synthesized CloudFormation template instead of snapshots.

The skill composes with /bce and /java-conventions and ships with a domain-neutral project blueprint. It is also compatible with /sbce, the spec-driven BCE workflow: a capability spec describes one business component, and the code is iterated until it matches the spec. A compilable starter is available at AdamBien/aws-cdk-plain, and constructions.cloud collects example constructs and CDK applications.

A business component is a package named after a single responsibility, and the structure of a system is the sum of these components. The hard part is finding the names. Here is the simplest approach I know, three steps.

1. Say it. Describe what the system does in one sentence, in one breath.
2. Name it. Underline the essential verbs and nouns. Those are your component candidates, and verbs become nouns.
3. Test it. Drop every name that would fit another project. A name that transplants into any system says nothing about this one.

The method reverse-engineers reality. Take zb, a zero dependency builder:

"It discovers the Java sources, compiles them, packs an
 executable JAR, and runs the test hook after the build."

Verbs become nouns: discovers becomes discovery, compiles becomes compiler, packs becomes packer, and hook is already a noun. Open zb and you find exactly those packages: discovery, compiler, packer, hook. That sentence took about ten iterations. packer started as "jar creator", discovery started as "source", and hook did not exist yet.

An online shop: "customers browse the catalog, put products into a cart, place orders, and pay." That gives catalog, cart, orders, payments. Browse collapses into catalog, products are entities inside it. Customers is borderline: a component only when the system manages them, otherwise an entity inside orders.

Say it. Name it. Test it.

Part of the free Screaming Architecture with BCE course.