Introduction

You are in a senior backend interview. The interviewer says: design checkout with Postgres and Kafka.

You draw an Order Service. You save the order. You send OrderCreated. Looks done.

Then the interviewer leans in: “What if the database commits but Kafka is down?”

You freeze. That freeze is what costs you the offer.

This article covers the famous dual write problem, the two ways it breaks, and the pattern that answers it: the Transactional Outbox. At the end there is a cheat-sheet you can say out loud in 30 seconds. The same answer also keeps a real checkout honest in production.

Prefer video? Everything below runs live in this one:

Full code: dual-write-outbox-pattern on GitHub

Two writes that must agree

The scenario: an Order Service, Postgres, and Kafka. The user clicks buy, and you owe two things that must agree:

1. Save the order in the database.
2. Publish OrderCreated, so stock, payment and shipping can react.

If both happen, you are consistent. If only one happens, the system lies. That gap is the whole interview.

Here is what most candidates draw: Order Service on the left, Postgres in the middle, Kafka on the right. One solid arrow to Postgres (save order), one solid arrow to Kafka (send event). It looks safe.

It is not, because there is no transaction that spans both. That is the definition of a dual write: two systems, no shared transaction. Put a cross on either arrow and watch what breaks.

Failure A: the ghost order

You save to Postgres. The commit succeeds. Then Kafka is down, or the network times out, or the broker rejects the batch.

Now the database says order 1234 exists. But stock was never reserved. Shipping never starts. Payment reconciliation sees nothing. Support gets a ticket: “where is my order?”

You can’t find the order in Kafka. The database says yes. The rest of the distributed system says nothing happened.

Failure B: the ghost event

So you try to be clever and send to Kafka first. It succeeds. Then Postgres fails: a duplicate key, a constraint violation, a serialization error.

Now you have reserved stock, triggered payment and started shipping prep, for an order that does not exist. You can’t query it. You can’t cancel it cleanly. You can’t refund it by id. Downstream teams act on a phantom.

Same diagram, opposite cross. If you stop here, it is the same failed interview.

Retries don’t fix atomicity

The follow-up kills most people. Can you just retry? Can you swap the order? Can you add try/catch?

No. Retries don’t fix atomicity. They change the failure.

• Retry the Kafka send after Postgres committed, and you may send twice. If the first send reached the broker but your code timed out and sent again, the retry creates a duplicate, and downstream charges twice.
• Retry Postgres after Kafka succeeded, and the event is already out, whatever the database decides.

(One precision: the Kafka producer’s own internal retries don’t duplicate, because idempotence is on by default since Kafka 3.0. The duplicate comes from your application sending again.)

You moved the problem without solving it. Now you need the senior vocabulary. There are three delivery guarantees, and only two are real across two systems:

• At most once: you may lose events, but you never duplicate.
• At least once: you never lose events, but duplicates are possible.
• Exactly once, across Postgres and Kafka, as two writes in your code with no shared transaction: does not exist. Anyone who promises it just failed the question.

Note the scope. Kafka does have exactly-once semantics inside Kafka, and you can get exactly-once when the read position and the output live in the same system. What doesn’t exist is exactly-once for a dual write your application performs against two independent systems.

For checkout, money and inventory, the choice is at least once plus idempotence. A duplicate you can ignore beats a lost order you never knew about.

Two fixes that look right (and aren’t)

Before the answer, it helps to know exactly why the tempting ones fail. Each is a follow-up a good interviewer will try.

@Transactional

@Transactional gives you atomicity for one transaction manager. Your database and your broker are two resources, so there are two commits, one after the other. Whichever commits second can still fail after the first one succeeded. You are back to Failure A or Failure B, only with less obvious timing.

Spring does have support for putting both under one annotation. With KafkaTransactionManager (or a KafkaTemplate synchronized to another transaction manager), a Kafka transaction is started and committed alongside your database transaction. That reduces the window. It does not close it: the two commits are still separate, and the second one can fail after the first one went through. The old ChainedKafkaTransactionManager, which tried to chain them, has been deprecated since Spring Kafka 2.7. Read the Spring for Apache Kafka transactions chapter and note what it promises: synchronization, not atomicity across both systems.

Two Phase Commit

2PC (two-phase commit) is the textbook answer to “atomic across two systems”. A coordinator asks every participant to prepare, and only if all say yes does it tell them to commit. It is real, and PostgreSQL supports prepared transactions. It still loses in this scenario, for three reasons:

• Kafka is not an XA resource. Kafka does not join an external 2PC today. KIP-939 proposes it, but its public 2PC APIs were pulled from the Kafka 4.1 release until the feature is ready, and the work is still open (KAFKA-15370). Check the release notes before you quote this in an interview, because it is the one sentence here that can go stale.
• It blocks on failure. A participant that has voted yes holds its locks and waits for the coordinator. If the coordinator dies between the two phases, that participant is stuck until someone resolves it. For checkout, that means locked rows on your hottest table.
• It couples availability. Every checkout now needs the database and the broker and the coordinator healthy at the same moment. Microservices.io makes the same point: 2PC is not viable because the database or broker may not support it, and coupling the service to both is undesirable anyway.

Both share one root: they try to make two independent systems agree at one instant. The outbox gives up on the instant and asks for agreement eventually, with a durable record in between.

The sentence that passes

If you propose Two Phase Commit here, you fail on the follow-up. 2PC blocks on failure (a prepared participant waits for the coordinator), and Kafka is not an XA resource. That is why the Outbox comes first.

Here is the sentence interviewers accept in most cases. Memorize it:

I avoid dual write by writing business state and an outbox record in one local transaction, then relaying that record to Kafka with at-least-once delivery and an idempotent consumer.

It names the strategy, the transaction boundary, and the trade-off with its fix. It takes fifteen seconds to say. The rest of the article is what happens when the interviewer asks you to unpack it.

Step 1: one local transaction

The code in this article comes from a small runnable demo: Spring Boot 4.1, Java 21, Postgres and Kafka in Docker Compose, Flyway migrations. Create a second table in the same Postgres database:

CREATE TABLE outbox_events (
    id             BIGSERIAL PRIMARY KEY,
    aggregate_type TEXT NOT NULL,
    aggregate_id   TEXT NOT NULL,
    topic          TEXT NOT NULL,
    payload        JSONB NOT NULL,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    published      BOOLEAN NOT NULL DEFAULT false
);

It lives next to the orders table. That placement is the trick.

Your Java code changes in one critical way. Inside one @Transactional method you do two database writes and zero calls to Kafka:

@Transactional
public Order placeOrder(NewOrder command) {
    Order order = orderRepository.save(Order.from(command));
    outboxRepository.save(OutboxEvent.orderCreated(order));
    return order;
}

Same database, same local transaction. Either both rows commit, or both roll back. No partial success, no ghost order, no ghost event. Postgres atomicity protects both rows together.

You turned a distributed write into a local write.

One JPA detail: payload is JSONB in the table but a String in the entity. Without a hint, Hibernate binds it as varchar and Postgres rejects the insert. The demo maps it like this:

@JdbcTypeCode(SqlTypes.JSON)
private String payload;

One note on BIGSERIAL: the relay below reads in id order, so ids should grow with insertion. Don’t use a random UUID v4 here; if you need UUIDs, use UUIDv7. Know the limit, though: a sequence value is taken at insert time, not at commit time, so id order is close to commit order but not identical. Events of the same order still leave in order as long as the transactions that write them for one order run one after the other (for example, because each one updates that order’s row and takes its lock). Don’t promise global order.

What goes in the outbox row

A few design choices matter more than they look:

• The payload is a contract. It is what other teams read from Kafka, so treat it like an API: version it, and don’t dump your internal entity into it.
• aggregate_id becomes the Kafka key. Events of the same order then land on the same partition, which is what preserves their order (more on that below).
• The outbox id is the event id. The consumer uses it to detect duplicates. Debezium’s own outbox example does the same: its docs describe the event id as usable by consumers to detect duplicate events.
• Treat the table as insert-only. The relay flips the published flag in the polling design, but nothing should rewrite the business content of an event after the fact.

The idea is not new. Chris Richardson documents it as the Transactional Outbox pattern on microservices.io, together with its two ways of publishing: the polling publisher and transaction log tailing. Those are exactly the polling and CDC options below.

Step 2: the relay

A separate relay publishes to Kafka, asynchronously. Start simple: a scheduler runs every few hundred milliseconds, selects a batch where published = false ordered by id, sends each row to Kafka with its outbox id as the event id, then marks it published.

@Scheduled(fixedDelay = 300)
@Transactional
public void relay() {
    List<OutboxEvent> batch =
            outboxRepository.findTop100ByPublishedFalseOrderByIdAsc();
    if (batch.isEmpty()) {
        return;
    }

    int acked = 0;
    for (OutboxEvent event : batch) {
        ProducerRecord<String, String> record = new ProducerRecord<>(
                event.getTopic(), event.getAggregateId(), event.getPayload());
        record.headers().add("event_id",
                String.valueOf(event.getId()).getBytes(StandardCharsets.UTF_8));
        try {
            SendResult<String, String> result = kafkaTemplate.send(record).join(); // wait for the broker ack
            log.info("Kafka ack: eventId={} topic={} partition={} offset={}",
                    event.getId(),
                    result.getRecordMetadata().topic(),
                    result.getRecordMetadata().partition(),
                    result.getRecordMetadata().offset());
            event.markPublished();
            acked++;
        } catch (CompletionException ex) {
            log.error("Kafka send failed, will retry: eventId={} topic={}",
                    event.getId(), event.getTopic(), ex.getCause());
            break; // keep order: stop at first failure, retry next tick
        }
    }
    log.info("Outbox batch done: acked={} pending={}", acked, batch.size() - acked);
}

The join() is not decoration. KafkaTemplate.send is asynchronous and returns a CompletableFuture. Without waiting for the ack, the method would mark the row published and commit even when the send failed, and you would lose the event. join() blocks until the broker answers, and a failed send surfaces as a CompletionException. (Prefer join() over get() here: get() throws checked exceptions, and @Transactional does not roll back on checked exceptions by default.)

On a failure the loop stops at that row on purpose. Rows that were already acked stay marked and commit. The failed row and everything after it stay unpublished and come back on the next tick, in the same order. Skipping the failed row and sending the next one would break per-order ordering. (Scheduling needs @EnableScheduling on the application class.)

The relay runs in its own thread, outside the request path. Checkout stays fast: the request waits for Postgres, not for Kafka.

This pattern is common enough that someone packaged it. Namastack Outbox is an open-source library for Spring Boot: inside the same transaction you call outbox.schedule(payload, key), and the library runs the relay, the retries and the ordering per key. The interviewer will still ask how it works, so know the hand-rolled version.

What if the relay crashes?

That is the next question. Say the relay sends to Kafka, then crashes before marking the row published. On restart, it sends again.

That is expected, and correct. You get at-least-once by design. So you never promise exactly-once from the relay. You promise that the consumer can handle the same event twice.

A lost event becomes impossible on a relay crash, because the row stays in the database until Kafka acks it. (After the ack, durability is Kafka’s job. Replication settings such as min.insync.replicas still matter.) A duplicate becomes harmless because of the next step.

The relay in depth

The relay is the part of the pattern that looks trivial and has the most edge cases. Think of it as a sequence of steps, and ask what a crash does at each one:

• Crash before the send: nothing was published and the row is still unpublished. The next run sends it. Nothing lost, nothing duplicated.
• Crash after the send, before the commit that marks it: Kafka has the event, the database still says unpublished. The next run sends it again. A duplicate, handled by the consumer.
• Send fails (broker down, timeout): join() throws, the loop stops at that row, and it stays unpublished (rows acked before it commit as published). The relay keeps retrying while the outage lasts. Orders keep being accepted, and the outbox simply grows.
• Commit fails after a successful send: same as the second case: a duplicate later.

So the relay has exactly one invariant: a row is marked published only after the broker acknowledged it. Everything else is allowed to repeat.

Three things to know when you run it for real:

1. Holding a transaction while you wait for Kafka. In the demo, the database transaction stays open during each send. That is simple and correct, but a slow broker means a long-lived transaction. Production relays often claim a batch, publish, and then mark in a short second transaction, accepting more duplicates in exchange. Which is right depends on your batch size and your broker’s latency.
2. More than one relay instance. Two relays reading the same rows will publish everything twice. The standard fix is a row-level lock that skips rows another transaction already holds:

SELECT * FROM outbox_events
WHERE published = false
ORDER BY id
LIMIT 100
FOR UPDATE SKIP LOCKED;

SKIP LOCKED has existed since PostgreSQL 9.5, and the SELECT documentation warns that it provides an inconsistent view of the data. That is the price: with several instances, two events of the same order can be picked by different relays and leave out of order. Libraries such as Namastack advertise strict ordering per key with automatic partitioning across instances; if you hand-roll it, you have to build that yourself.

3. Poison rows. A payload that can never be serialized or a topic that does not exist will fail on every run and block the head of the queue. Decide up front: retry with backoff, count attempts, and move the row to a failed state that raises an alert instead of retrying forever. This is another reason to reach for a library at the start.

Producer settings that make “at least once” real

At-least-once only holds if the producer is configured not to drop acknowledged-looking writes:

• acks=all makes the leader wait for the in-sync replicas before acknowledging.
• enable.idempotence=true stops the producer’s own internal retries from creating duplicates. It has been the default since Kafka 3.0 (KIP-679), except for a bug that left it off in 3.0.0 and 3.1.0 (KAFKA-13598).
• min.insync.replicas defaults to 1, so “acknowledged” can mean one copy. For data you can’t lose, raise it together with the topic’s replication factor. See the broker configs.

Note what idempotence does not do: it dedupes retries inside one producer session. It cannot know that your relay crashed and re-sent the same row after a restart. That duplicate is yours to handle at the consumer.

Step 3: the idempotent consumer

Most tutorials stop at the relay. Don’t.

The consumer keeps a table called processed_events, with the event id as the primary key:

CREATE TABLE processed_events (
    event_id     TEXT PRIMARY KEY,
    processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

When OrderCreated arrives, the stock service reads the event_id header, opens a local transaction and inserts that id with ON CONFLICT DO NOTHING:

@KafkaListener(topics = "orders")
@Transactional
public void onOrderCreated(ConsumerRecord<String, String> record) {
    String eventId = new String(
            record.headers().lastHeader("event_id").value(), StandardCharsets.UTF_8);

    int inserted = jdbc.update(
            "INSERT INTO processed_events (event_id) VALUES (?) ON CONFLICT (event_id) DO NOTHING",
            eventId);
    if (inserted == 0) {
        log.info("event {} already processed, skipping", eventId);
        return;
    }

    JsonNode json = mapper.readTree(record.value());
    jdbc.update("UPDATE stock SET quantity = quantity - ? WHERE product = ?",
            json.get("quantity").asInt(), json.get("product").asText());
    log.info("event {} applied: stock decremented", eventId);
}

If the row went in, apply the business update in that same transaction: here, decrement stock. A real system would also create the shipment, in the same transaction if it lives in the same database. If the same event arrives again, the insert hits the primary key and writes nothing. Zero rows means duplicate, so you skip the side effect. The duplicate dies there.

Two details worth saying out loud:

• Use the outbox id as the event id, not the aggregate_id. Two different events for the same order would collide on the aggregate id.
• A charge on an external payment gateway sits outside your database transaction. Pass the event id as that gateway’s idempotency key.

Even the Namastack docs say it: handlers and downstream consumers should be idempotent, because a record may be delivered more than once.

The idempotent consumer in depth

The pattern comes from the same catalog: Idempotent Consumer. It works because the dedupe record and the business change commit in the same local transaction. Three consequences:

• Order of operations matters. Insert into processed_events first, then do the work, all in one transaction. If the work throws, the insert rolls back too, so the retry is processed instead of being skipped as a duplicate. Debezium’s example makes the same point: if the transaction rolls back, the event is not marked as processed, and the exception sends it back to the Kafka consumer loop to be retried.
• Commit the Kafka offset after the database commit. If you commit the offset first and crash, the event is lost. If you commit it after, a crash causes redelivery, which the table absorbs. Again: at-least-once, made safe.
• ON CONFLICT DO NOTHING reports zero rows for a skipped insert. That is why the code can use the row count as the duplicate signal. See the INSERT documentation.

Other ways to get idempotency, when a dedupe table is not the best fit:

• Natural idempotency. Some operations are safe to repeat by nature: “set status to SHIPPED” or an upsert keyed by the order id. If the handler can be written that way, you may not need a table.
• Version or sequence checks. Store the last applied version per aggregate and ignore anything older or equal.
• Idempotency keys at the edge. For calls to an external system, such as a payment gateway, send the event id as the gateway’s idempotency key. Your database cannot roll back their side effect.

Operationally, processed_events grows forever unless you trim it. A reasonable rule is to delete rows older than the longest time an old event could still be redelivered (retention of the topic, plus any replay window you allow). That number is your call, not a standard: size it from your own retention settings.

Polling first, CDC later

If you made it this far, here is a bonus for the interview. There is still room for an upgrade.

The line that shows judgment: “I start with polling for simplicity, and I move to CDC when I need speed.”

Polling (what we built):

• Simple, easy to understand, easy to debug with SQL: you can see the unpublished rows, and you can replay by resetting a flag.
• Good enough for most checkouts.
• The cost is load and delay: you poll the database, and you add tens to hundreds of milliseconds before an event leaves.
• With several relay instances you need SELECT … FOR UPDATE SKIP LOCKED, and then two events of the same order can leave out of order. That is why libraries such as Namastack partition the work by key across instances.

CDC (Change Data Capture) with Debezium:

• It doesn’t replace the Outbox. It replaces polling. Debezium tails the Postgres write-ahead log, and every insert into the outbox table streams to Kafka almost instantly.
• No selects, no published flag, lower latency, less load on the database.
• The cost is operations: you run Kafka Connect, manage connectors, schemas, snapshots and restarts, and monitor lag in a new system. Postgres needs wal_level=logical (see logical decoding).
• Debezium treats the outbox as an insert-only queue (it ships an EventRouter transform for this), so your table schema may need a mapping.

For ordering, use the order id as the Kafka key, so events for the same order land on the same partition. Kafka keeps order inside a partition, as long as your relay sends them in order. And with polling, archive published rows nightly so the table stays fast.

So say it like this: polling first, log-based CDC when latency actually hurts and you can afford the operations.

Your 30-second cheat-sheet

Screenshot this, then say it in order.

1. Name it. Dual write: two systems, no shared transaction.
2. Show the ghosts. Database wins and Kafka loses is a ghost order. Kafka wins and the database loses is a ghost event.
3. Kill the naive fixes. @Transactional can’t make Kafka and the database atomic. Retries create duplicates. Swapping the order doesn’t help.
4. Give the fix. One local transaction for order plus outbox. An async relay. At-least-once delivery plus an idempotent consumer with a processed_events table.
5. Show judgment. Polling first. CDC with Debezium when you need speed. Never Two Phase Commit for checkout.

Then go to the whiteboard. Draw the Order Service, Postgres with orders and outbox_events, one local transaction around both, the async relay to Kafka, and the processed_events table under the consumer. Point to the box and say “atomic write.” Point to the arrow and say “reliable publish.” Point to the table and say “safe retry.”

Three gestures, and you pass.

Now go back to the interview. Same question: what if the database commits but Kafka is down? This time, you have the sentence.

Ship it this week

The same design works in production. This week:

• Start with outbox plus polling. A library like Namastack gives you the relay and the retries out of the box.
• Add idempotency keys on every consumer.
• Archive published rows nightly.
• Add metrics for relay lag and duplicate rate.
• Add an alert on the age of the oldest unpublished row.
• Only add Debezium when polling latency actually hurts.

Outbox versus the alternatives, honestly

The outbox is not free, and an interviewer who has run one will ask what it costs you:

• Eventual consistency. Between the commit and the relay, other services don’t know about the order yet. Your UI and APIs must tolerate that.
• Extra moving part. A table, a relay (or Kafka Connect), metrics and cleanup. You trade a distributed-correctness problem for an operational one. That is usually a good trade, not a free one.
• Duplicates are part of the contract. Every consumer must be idempotent. If you can’t enforce that across teams, the pattern’s guarantee is weaker than it looks.
• Ordering is per key, not global. Kafka orders within a partition. Design keys accordingly.

When is it overkill? If the event is a best-effort notification where losing one is fine (a cache invalidation, a metric), a plain fire-and-forget publish may be the honest answer. The outbox is for events whose loss would make the system lie: orders, payments, stock.

How to prove it works

An outbox you have never seen fail is a belief, not a guarantee. Four tests worth writing:

1. Kafka down. Stop the broker, place an order, assert the order and the outbox row exist and the request succeeded. Start the broker, assert the event arrives.
2. Crash between send and mark. Kill the relay process right after the send. Restart it and assert the event appears twice in the topic, and that the consumer’s effects happened once.
3. Same event twice. Feed the consumer the same event id two times, assert one stock decrement and one processed_events row.
4. Rollback. Force the consumer’s business step to throw, assert no processed_events row remains, and that the retry succeeds.

Further reading

Patterns and concepts:

• Transactional Outbox, Chris Richardson, microservices.io
• Idempotent Consumer, microservices.io
• Saga: the pattern to read next, for business flows that span several services

Tools and docs:

• Debezium Outbox Event Router and the walkthrough Reliable Microservices Data Exchange With the Outbox Pattern
• Namastack Outbox and its docs: an Apache-2.0 Spring Boot library
• Spring for Apache Kafka: transactions
• Kafka message delivery semantics
• PostgreSQL: logical decoding, the mechanism CDC tools read
• PostgreSQL: INSERT … ON CONFLICT
• KIP-939: participating in 2PC and KAFKA-15370

Key takeaways

• Saving to a database and publishing to a broker is a dual write. No ordering of the two, and no retry, makes it atomic.
• Both orderings fail: DB first gives a ghost order, Kafka first gives a ghost event.
• Exactly-once across two systems you write to yourself doesn’t exist. Choose at-least-once plus idempotence.
• The Outbox turns the distributed write into a local one: business row and event row in the same transaction.
• A relay crash produces duplicates, never losses. The idempotent consumer makes duplicates harmless.
• Polling first, CDC when latency hurts. Never 2PC for checkout.

Watch the video: Why Your System Design Interview Fails (The Dual Write Problem) More on YouTube: subscribe to Java Plus AI for the full series.

If this saved you from a freeze, a few 👏 help others find it.

The Dual Write Problem: the Outbox Answer That Passes the Interview was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

Telling an agent in prose which files it may touch is a wish. Here is how a class declared in a JSON file, one Java hook and an end-of-turn sweep turn it into a rule, with real block messages and the gaps left in.

Introduction

A design run once edited docker-compose.yml.

The run was a feature pipeline whose only job is to write specs under docs/. Every skill involved said so, in prose, in its own instructions. The run finished, and a schema-registry service block was sitting in the compose file anyway.

Nothing had been hacked and no tool was misused. The agent was being helpful in a direction nobody had asked for, and the only thing standing between it and the file was a sentence it was free to ignore.

This is the part of Nerviz I think is the most useful beyond Nerviz, so this article is about it: every skill and every subagent has a write territory, declared as data, and everything outside it is refused. If you haven’t read the pillar article of the series, the short version is that Nerviz is a harness for Spring Boot on Claude Code: guides steer the model before it acts, sensors check what it did. This is a sensor.

Why a denylist loses

The obvious first fix is a list of files the design run must not touch. Put docker-compose.yml on it and move on.

That list is written after the fact. It contains exactly the files someone already got burned by. The next incident is a file nobody had thought of, and by definition it is not on the list. The model has a much bigger imagination for helpful edits than you have for forbidden ones.

An allowlist flips the question. Instead of “what must this skill never touch?”, you ask “what may this skill write?”, and the answer is short, because a skill has one job. A design skill writes one use case folder. That’s it. docker-compose.yml was not in that answer, so it never needed to be named anywhere.

The change in the decision record that introduced this is one line: the territory model is “Allowlist, deny by default”, and the denylist it replaced was dropped.

Classes, as data

Listing the allowed paths per skill would duplicate a lot of lines across 34 skills. Nerviz groups them.

Every skill belongs to exactly one class, and every agent to exactly one agent class. Both are declared in one file, .claude/schemas/extensions.json, which is the single owner of what each class may write. Eight skill classes:

• design: writes docs/use-cases/UC-*/** and docs/use-cases/BACKLOG.md. The skills that each write one partial of a use case.
• orchestrator: writes docs/use-cases/** and docs/lessons-learned/**. The pipeline skills that chain others. Two of them, new-feature-implement and init-project, override that to nothing, because everything they do is delegated to subagents.
• build: the class default is empty on purpose. Each skill carries its own override, because project-bootstrap writes the whole tree while gof-design-patterns writes one Java class.
• observer: nothing. A skill that reports on the project and writes to it is a bug.
• meta: .claude/, CLAUDE.md, .github/ and other harness files. One skill, the one that edits the harness itself.
• ops: nothing. Its effect is git, over the shell.
• report: docs/lessons-learned/**.
• media: docs/diagrams/**. It arrived in v0.46.0 with the diagram skill, because that path belonged to no class before.

And four agent classes, driver, executor, installer and verifier. The executor, the one that implements an approved spec, may write src/**, the single status line of the spec it closes, and the POMs. A verifier, which reads a public issue written by a stranger, may write nothing in the repository at all.

A comment inside the file explains the thing I like most about the design: an empty list is a decision, not an omission. Coverage is total, too. A skill on disk that no class lists is a failure, and the schema hook names it.

The hook reads this data. There is no list of paths in the Java source, so changing a territory is a JSON edit and adding a skill touches no code.

Checkpoints

First checkpoint: the file tools

The guard is a Java hook, ArchHook.jar, registered on PreToolUse. A territory opens when a skill from a class is invoked and closes at the next prompt. While it is open, every Write, Edit, MultiEdit and NotebookEdit is matched against the class’s write_allow.

I ran it by hand against a copy of the harness. A /new-feature run starts, the first design skill is called, and it tries to write the compose file:

❌ `use-case-design` is class `design` — docker-compose.yml is outside its territory.
   write_allow: docs/use-cases/UC-*/**, docs/use-cases/BACKLOG.md
Put the content in the spec as a code block, or finish the run and invoke the
skill that owns this path. If the path is legitimately this skill's, widen
skill_classes.design in .claude/schemas/extensions.json — retrying will not help.

Exit code 2, and the write never happens. Notice what the message does. It names the class, lists what the class may write, and tells the model where the content belongs instead (the spec, as a code block). The last line says retrying will not help, which matters: a model that is told only “refused” tends to try again with a different spelling.

A write to docs/use-cases/UC-001-x/UC-001-domain.md in the same run goes through silently.

Second checkpoint: the shell

Blocking Write and Edit is not enough, and I learned that from a run, not from a design session. A later run wrote two files with a heredoc and passed through every hook, because every hook matched on a tool name and Bash was in no matcher. The host’s own instructions even preferred Bash for edits.

So there is a Bash matcher too. The hook reads the command for the write shapes it understands, listed in the same JSON file: > and >>, tee, truncate, sed -i, perl -i, cp, mv, install, rsync, dd of=, and a shell wrapper like sh -c “…”, which it re-parses one level. The same compose edit, as a command:

sed -i '' 's/a/b/' docker-compose.yml

gets the same block message, same exit code. And in the same run, a design skill trying to invoke a build skill gets this:

❌ `project-bootstrap` is class `build` and `use-case-design` (class `design`) is open — a design run does not materialize files.
Record what is missing in the partial and in the consolidated spec, finish the run,
then invoke `/project-bootstrap` from a prompt of its own.

A build skill cannot even be called during a design run. That is what makes the pipeline docs-only in the mechanism, not only in prose.

Now the honest part. This parser is deliberately incomplete. A shell has more ways to write a file than any list can hold, and a parser that blocks whatever it cannot read would stop ./mvnw on its first false positive and be switched off the same week. A target containing $, a backtick, a glob or ~ is skipped without a word. The decision record says the bar is not completeness: it is that the obvious spellings stop being free.

Third checkpoint: what actually changed on disk

For the spellings the parser skips, there is a net that does not care which tool wrote. At the end of every turn, a Stop hook, guard sweep, compares the working tree against a baseline taken when the prompt arrived, and judges what changed against the same territory.

I simulated a write the tool-time guards could not see, a plain Python open(…, ‘w’), then ended the turn:

❌ This turn wrote outside what the open phase and the frozen folders admit.
   The tool-time guards did not see these writes — a shell spelling they do not
   parse, or a tool with no matcher. Revert them, or report them and stop.

❌ `new-feature` is class `orchestrator` — docker-compose.yml is outside its territory.
   write_allow: docs/use-cases/**, docs/lessons-learned/**

Two limits, both in the repository’s own documentation. It is detection, not prevention: the file is already written when it fires, and the model is told to revert it. And it is git-shaped: a path that git ignores never shows up in git status, so it is never swept. The baseline is the reason it does not flag a tree that was dirty before you started.

One more detail that cost a real bug. The sweep first judged every change against whatever phase was open at the end of the turn. A /new-feature run that ended by chaining git-publish (class ops, which writes nothing) had its own approved spec flagged. The fix was to have the sweep judge only the writes no tool-time guard had already admitted.

Subagents are judged by their own class

A subagent starts with a clean context, which is why it exists, and that raises a question: whose territory applies when it writes?

The answer is its own. Every write a subagent makes carries its agent_type, and the hook checks the path against that agent’s class, whatever phase the caller left open. Here is the agent that installs ArchUnit trying to touch the compose file:

❌ agent `archunit-installer` is class `installer` — docker-compose.yml is outside its territory.
   write_allow: pom.xml, **/pom.xml, src/test/java/**/ArchitectureTest.java, ...
Report the path in the summary you return and stop, or hand it to the piece
that owns it. If the path is legitimately this agent's, widen
agent_classes.installer in .claude/schemas/extensions.json — retrying will not help.

This used to be the weak spot. Before agent classes existed, each agent’s instructions carried a prose contract such as “does not write docker-compose.yml”, and the guard gave all four agents an unconditional bypass. None of those promises was enforced by anything. Today the promise is data.

Because the territory is keyed on the agent type, there is no state file to read and no ordering to race. The payload names the agent on every single write.

What it does not cover

I’d rather you hear these from me:

• With no skill running, nothing is restricted. A territory opens when a skill is invoked. Editing a file by hand, or asking the model for an edit outside any skill, is never blocked. That is on purpose, and it means this is a guarantee about skills, not about the model in general.
• The shell parser is a best effort, as above. The sweep catches the rest after the fact, and only if git can see the path.
• A chain adds up. When a build skill calls another build skill, the phase holds both territories, so each writes its own paths. That rule was added after a chain of two real skills was refused its own pom.xml. The cost is that an early skill in a chain can write what a later one is entitled to.
• It lives inside Claude Code. The hooks are Claude Code hooks. Another assistant would need its own port.

The nearest neighbour

The closest idea I found is a per-task scope script in another Spring-aware harness: enforce-files-in-scope.sh in loiane’s project, which limits writes to the files of the active task. That is a similar instinct, and it is the right one.

The differences are modest but real. Here the territory is per class and stored as data, so one edit changes every skill in the class. Shell writes and the end-of-turn sweep are covered. And the enforcement is one Java file tested on three operating systems, not bash and jq. I would re-check the other project before quoting me, because both repos move.

Steal this, even without Nerviz

1. List what each skill may write, not what it may not. Start from the job. A design skill emits a spec, so its list is the spec folder.
2. Put the lists in one data file and have the hook read it. Prose in the skill’s body is the thing that failed.
3. Make the message do the work. Name the class, show the allowed paths, say where the content belongs, and say that retrying will not help.
4. Cover the shell, then sweep. Parse the spellings people really type, then compare the working tree at the end of the turn for everything else.
5. Judge subagents by their own identity. If your hook ignores which agent is writing, every subagent has the caller’s powers.
6. Test it with the incident. Make the file that burned you a test case that must fail. A territory you have never watched refuse a write is a guess.

Key takeaways

• Prose telling a model which files it may write is a wish. An allowlist enforced by a hook is a rule.
• A denylist only contains the incidents you already had. An allowlist covers the one you didn’t.
• Classes keep the data small: eight for skills, four for agents, with per-skill overrides where a class cannot share a territory.
• Check at three points: the file tools, the shell forms you can read, and a sweep of what actually changed. Each one has a hole the next one covers.
• It restricts skills and subagents, not you. By design.

So here is my question: what is the one file your AI assistant has edited that you never asked it to touch, and could you have predicted it? Tell me in the comments.

• Try it: claude plugin marketplace add nerviz-ai/marketplace, then /nerviz:new-project.
• Repository: nerviz-ai/nerviz. A star helps others find it.
• Site: nerviz.dev.
• Output of a real run: nerviz-ai/bank-app.

If this saved you from a surprise edit, a few 👏 help others find it.

Giving Every AI Skill a Write Territory was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

Building a practical API security lab with Java 21, Spring Boot, Spring Security, Spring Data JPA, and automated tests.

Introduction

Authentication and authorization are two fundamental concepts in backend security, but they solve different problems.

Authentication answers:

Who are you?

Authorization answers:

What are you allowed to access?

An API can authenticate a user successfully and still expose private information if it fails to verify whether that user is authorized to access the requested resource.

This type of vulnerability is known as Broken Object Level Authorization (BOLA). It is a major API security risk addressed by the OWASP API Security Top 10.

To understand the issue in practice, I built a Spring Boot security lab that demonstrates an intentionally vulnerable document endpoint and a second endpoint that enforces document ownership.

GitHub repository: https://github.com/EagleSoft461/bola-lab

1. Understanding BOLA

Imagine an application that allows authenticated users to retrieve documents through an API:

GET /api/documents/{documentId}

The backend receives a document ID, queries the database, and returns the matching document.

The vulnerability occurs when the application checks whether the document exists but does not verify whether the authenticated user is allowed to access it.

Consider this scenario:

1. User A owns a private document.
2. User B is authenticated.
3. User B requests the document owned by User A.
4. The backend retrieves the document without checking ownership.

If the API returns the document, authentication has succeeded, but object-level authorization has failed.

The important lesson is simple:

Knowing an object’s identifier must not grant permission to access it.

A secure API must enforce authorization whenever a user attempts to access a protected resource.

2. Building the Security Lab

I implemented the demonstration using the following technologies:

• Java 21
• Spring Boot
• Spring Security with HTTP Basic authentication
• Spring Data JPA
• H2 in-memory database
• Maven
• JUnit and MockMvc

The document entity contains three fields:

UUID id;
UUID ownerId;
String title;

The id identifies a document, while ownerId identifies its owner.

The lab uses two test users to simulate a common authorization scenario: one user attempts to access a document belonging to another user.

The objective is to compare two implementations and verify their behavior through automated tests.

3. The Vulnerable Implementation

The insecure service retrieves a document using its ID alone:

documentRepository.findById(documentId);

This query checks whether a document exists. It does not verify whether the authenticated user owns that document.

For demonstration purposes, the vulnerable behavior is exposed through a dedicated endpoint:

GET /api/lab/insecure/documents/{documentId}

In the automated test, one authenticated user requests a document owned by the other user.

The endpoint responds with 200 OK and returns the document.

This confirms that the endpoint does not enforce the ownership rule.

The issue is not that the application failed to authenticate the requester. The issue is that it failed to authorize access to the specific object.

4. Implementing Ownership-Based Authorization

To address this problem, I added a repository method that queries by both document ID and owner ID:

documentRepository.findByIdAndOwnerId(
    documentId,
    authenticatedUserId
);

This changes the data-access operation in an important way.

Instead of retrieving any document with the requested ID, the query returns a document only when both conditions match:

• The document ID matches the requested ID.
• The owner ID matches the authenticated user’s ID.

The secure service uses this repository method, while the controller obtains the authenticated identity from Spring Security.

The protected endpoint is:

GET /api/documents/{documentId}

If the requested document does not belong to the authenticated user, the repository lookup returns no result. The controller responds with 404 Not Found.

Returning 404 is a deliberate choice for this lab. Depending on an application's requirements and information-disclosure policy, 403 Forbidden may also be appropriate.

The key requirement is that the backend must not return a protected document to an unauthorized requester.

This approach also avoids relying on the frontend to hide documents or prevent users from changing resource IDs. Authorization must be enforced on the server.

5. Verifying the Behavior with Automated Tests

I used JUnit and MockMvc to test both implementations.

The tests compare the responses when one authenticated user attempts to access another user’s document.

Test scenarioObserved resultInsecure endpoint: another user requests the document200 OKSecure endpoint: another user requests the same type of protected resource404 Not Found

I ran the two targeted tests with Maven:

.\mvnw.cmd "-Dtest=DocumentControllerTest#insecureEndpointAllowsAnotherUserToReadDocument+secureEndpointBlocksAnotherUserFromReadingDocument" test

The output confirmed the expected HTTP statuses:

Secure endpoint HTTP status: 404
Insecure endpoint HTTP status: 200

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

BUILD SUCCESS

Both tests passed.

The results demonstrate the intended contrast: the vulnerable endpoint returns the document, while the ownership-protected endpoint does not return it to another user.

Figure 1. Automated tests demonstrating the different authorization behavior of the two endpoints.

These tests provide repeatable evidence of the behavior in this lab. They do not prove that every authorization path in a larger application is secure; broader coverage and additional security testing would still be necessary.

6. What I Learned

Building this lab helped me connect backend implementation details with practical API security principles.

Authentication is not authorization

A valid authenticated identity does not grant unrestricted access to every resource in an application.

Authorization must be enforced at the object level

Endpoints that read, update, delete, or export user-owned resources need appropriate access-control checks.

Database queries can support authorization

Querying by both resource ID and owner ID makes the ownership condition explicit. It also reduces the risk of retrieving a resource without applying the intended ownership constraint.

This pattern is useful, but it does not replace a complete authorization design. Applications with shared resources, teams, delegated access, or role-based policies may need additional rules.

Automated security tests are essential

Testing only whether an endpoint returns a successful response is not enough.

Tests should also verify that users cannot access resources outside their permissions.

UUIDs do not replace authorization

Using UUIDs instead of sequential identifiers does not solve BOLA. Resource identifiers may be difficult to guess, but the server must still verify permissions for every relevant request.

7. Limitations and Future Improvements

This repository is an educational demonstration, not a production-ready application.

It uses HTTP Basic authentication, in-memory test users, and an H2 in-memory database to keep the example focused.

A production application would require a broader security review, including secure identity management, credential handling, HTTPS, authorization coverage across all relevant endpoints, and appropriate integration and security tests.

Possible next steps for this lab include:

• Adding ownership checks for document updates and deletion.
• Testing role-based and shared-resource permissions.
• Adding integration tests against a production-like database.
• Expanding coverage for missing resources and unauthorized operations.
• Integrating the test suite into a continuous integration pipeline.

The intentionally vulnerable endpoint should remain confined to a controlled educational environment and must not be exposed as a public production endpoint.

Conclusion

BOLA demonstrates how a small omission in backend authorization logic can undermine an otherwise authenticated API.

Compare these two repository methods:

documentRepository.findById(documentId);

documentRepository.findByIdAndOwnerId(
    documentId,
    authenticatedUserId
);

The first retrieves a document based on its identifier alone. The second includes the ownership condition in the lookup.

That difference is central to the behavior demonstrated by this project.

Building the lab gave me practical experience with Spring Security, Spring Data JPA, and automated testing for object-level authorization.

Explore the source code and tests: https://github.com/EagleSoft461/bola-lab

References

• OWASP API Security Top 10 — API1:2023 Broken Object Level Authorization
• OWASP Insecure Direct Object Reference Prevention Cheat Sheet

Understanding BOLA in Spring Boot: From Vulnerable Endpoints to Ownership-Based Authorization was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Problem

You start a Spring Boot Java project with a 30-line CLAUDE.md.

Six months later it has 400 lines. The model ignores half of them. The same rule lives in three skills that no longer agree. Picture the failure: the file says “the domain doesn’t import Spring” on one line and “services are annotated with @Service" two hundred lines later, and a @Service ends up on a domain class. Nobody can say which instruction lost.

The usual reaction is to rewrite the prompt: shorter, sharper, in capitals. It helps for a week.

The problem was never the wording. The AI “forgets” the architecture because nothing tells it, cheaply and reliably, what is true in this project, and nothing stops it when it gets it wrong.

A better sentence cannot fix a missing mechanism.

So I stopped writing prompts and built a harness. This article is the pillar of a series about it: what a harness is, how it maps onto Claude Code, and one complete run you can open on GitHub and check line by line.

Agent = model + harness

The working definition in 2026 is short: an agent is a model plus a harness.

The model is the LLM. The harness is everything around it that shapes what it does: instructions, context, tools, permissions, tests, review, feedback. When an agent behaves badly, you usually blame the model. Most of the time the harness is where the bug is.

Birgitta Böckeler, writing on martinfowler.com, splits the harness into two kinds of controls (see her harness engineering memo):

• Guides act before the model does. They steer it: instructions, procedures, examples, the spec of what you want built.
• Sensors act after. They observe what the model did and push back: tests, linters, the build, a hook that refuses a write.

Claude Code already supplies the model and the tool loop. It does not supply the rest, and for Spring Boot the rest is a lot:

• which architecture you chose
• which package may import which
• what a use case must specify before code exists
• what happens when the model reaches for a file it should not touch

That “rest” is what I built. I call it Nerviz, after Pier Luigi Nervi, the engineer-architect whose once said: the structures are their own form.

It lives at https://github.com/nerviz-ai/nerviz and the site is nerviz.dev (and btw is open source).

Guides and sensors, mapped to files you can open

Here is the same split, with the actual pieces.

Guides, before the model acts:

• Norms in .claude/rules/. One file per rule, loaded on demand through paths: a norm about persistence enters the context only when a file in its territory is touched.
• Skills in .claude/skills/. Procedures plus exemplars: how to create a REST adapter, step by step, with a reference controller that compiles.
• Blueprints. The architecture, as a YAML file. Nine of them (hexagonal, clean-architecture-single-module, onion, vertical-slice, modular-monolith…) plus a template for your own.
• The spec of the feature being built: one approved document per use case.

Sensors, after the model acts:

• Hooks that refuse a forbidden import, a write outside a skill’s territory, an edit to an approved spec, or a force push.
• The incremental build. Every write to a .java file triggers a test-compile of the touched module.
• ArchUnit and a compose health gate.
• CI that validates the harness itself, not only the code it generates.

One line from the project’s own rules explains the split better than I can: hooks verify, they do not teach. If something must always hold, it is not prose in a guide. It is a hook or a permissions.deny line.

That is why the 400-line CLAUDE.md fails. It asks a guide to do a sensor’s job. A guide is a request. The model may weigh it, forget it, or lose it to a longer instruction two hundred lines below. A sensor is a fact: the write is blocked, or it is not.

What a sensor looks like

Every hook in Nerviz launches one precompiled jar, built from a single Java file (ArchHook.java), in exec form:

{ 
  "type": "command", "command": "java",
  "args": ["-jar", "${CLAUDE_PROJECT_DIR}/.claude/hooks/ArchHook.jar", "check"] 
}

No shell is invoked, so bash, PowerShell or WSL make no difference, and there is one implementation instead of a .sh and a .ps1 that drift apart. The audience has a JDK by definition, so the dependency already exists.

The architecture reaches the hook as data. The generated project carries a .claude/forbidden-imports.txt like this one, from the example project below:

src/main/java/dev/nerviz/bankapp/domain/model|org.springframework.
src/main/java/dev/nerviz/bankapp/domain/model|jakarta.
src/main/java/dev/nerviz/bankapp/application/usecase|dev.nerviz.bankapp.infrastructure.

Read it as: nothing under domain/model may import org.springframework. or jakarta., and a use case may not import infrastructure. When Claude writes a .java file that breaks a line, the check hook exits with code 2 and the write is refused, with a message that names the rule. The model is not asked to remember. It is told no..

Every mode of ArchHook

check is one of twelve modes in the same file. Each is registered in settings.json against a Claude Code event, and every list a mode reads (recognized frontmatter fields, write territories, which services to probe) is data in .claude/schemas/extensions.json, never a constant in the Java. Adding a skill to a class is one entry, not a code change.

On every write to a .java file (PostToolUse):

• check: blocks. Reads .claude/forbidden-imports.txt and refuses a file that imports a prefix forbidden in its module (exit 2). If the boundary holds, it runs an incremental test-compile of the touched module, so code that does not compile is refused too. Typed by hand as check , it exits 1 for a path that is not an existing .java file instead of passing in silence.
• format: never blocks. Runs spotless:apply on the touched module. A failure is ignored: formatting is a courtesy, not a gate.

On every write to the harness’s own files (PreToolUse, PostToolUse and Stop):

• schema: blocks. Validates the instruction files themselves. The frontmatter of skills, agents and rules against the fields the runtime actually recognizes (the runtime ignores an unknown field without a word, and claude plugin validate lets it through), the body sections each class requires, the paths a shell injection in a skill reads, a skill named after a native command, a rule with no paths. It also checks every hook registration in settings.json, .mcp.json with a secret scan, the plugins that must stay disabled, and the export manifest against what is on disk.

Around each action of a skill or agent (UserPromptSubmit, PreToolUse, Stop):

• guard: blocks. Write territory, deny by default. Every skill belongs to one of seven classes and every agent to one of four, and the class lists the paths it may write. It has six sub-modes: prompt snapshots the working tree at the start of a turn, call refuses a build-class skill during a design run, write judges Write and Edit, bash reads shell write shapes (>, tee, sed -i, sh -c “…”) and refuses a force push, sweep runs at Stop and re-checks what git says changed this turn, and status prints the open phase as one JSON line for a UI mod. An approved spec folder is frozen. A subagent is judged by its own class. With no phase open there is no restriction: a person editing by hand is not a skill overstepping.

At the end of a turn (Stop):

• tests: blocks. Runs verify, without integration tests and coverage, on the modules changed since HEAD. It is deferred while a writer subagent is still running, tracked by markers at SubagentStart and SubagentStop. With no HEAD (a repository with no commit yet), it runs nothing.
• compose gate: blocks. Checks that every compose service is up and that no foreign container holds its ports. Published ports have to be reachable and advertised at an address a host client can resolve, image: tags have to match the ones src/test pins for Testcontainers, and every ${VAR:default} pointing at a service has to hold on the host and inside the app container. Typed without gate, compose prints the same report and never blocks. Docker is not a dependency: with no compose file, no docker on the PATH or a stopped daemon, it reports and returns.

Context and trail (generated project only, never block):

• context. At SubagentStart, injects the design-pattern catalog into agents whose class asks for it, so the catalog is in context every time and does not depend on the model remembering to read it.
• audit. Hooked to eleven lifecycle events, it writes one Markdown report per skill or agent run. audit genesis fills a new project’s GENESIS.md (start, finish, tokens) from the session transcripts, because a number the model wrote would be memory.

By hand or from CI:

• doctor. Diagnoses the setup on this machine, including a personal skill that shadows a project one. doctor gate is the same report as a CI step: exit 1 when a line the project lists as gating is red (no boundary rules, a source file importing what its module forbids, invalid schema, stale hook jar, broken hook registrations, bad .mcp.json). It exists because a bare doctor only printed, and a CI step once went green on ENFORCEMENT OFF.
• export. Writes a target project’s .claude/ from the manifest, transformed for one blueprint and stamped with provenance. It is deterministic on purpose, and CI requires two exports per blueprint to produce identical trees. It exits 2 and writes nothing when the destination’s Spring Boot line is below the supported floor.
• boundary-map. Writes .claude/forbidden-imports.txt from a blueprint: one line per prefix for a multi-module layout, derived package by package for a single-module one. It exits 2 and writes nothing when the blueprint yields no rule, because a map with no rule blocks nothing.
• build. Compiles ArchHook.java into ArchHook.jar. build — verify, run by CI, fails when the committed jar is not byte for byte what the source compiles to under the pinned JDK. The jar starts in about 0.3 s, against about 3.3 s to recompile from source on every call.

Five of the twelve can block: check, schema, guard, tests and compose gate. The rest format, measure, diagnose, write or build. One caveat: a hook that cannot verify something exits 0 on purpose, which is safe but can give a false green, so doctor exists to say when enforcement is silently off.

The proof: one run, in public

Claims about harnesses are cheap. So the series is built on one project anyone can open: https://github.com/nerviz-ai/bank-app, a Spring Boot 4 application on Java 21, generated by Nerviz from a single command.

Step 1: /init-project

This is the flow the command follows, step by step. Only the first step is a conversation. The rest runs in a background agent:

/init-project
     │
     ├─ 1. INTERVIEW, in the main session — blueprint · coordinates · build · features · TLS · Sonar
     │
     ▼  agent: project-initializer (isolated context, model: sonnet, asks nothing)
     │
     ├─ 2. VALIDATES blueprint — 6-rule checklist            [fails fast]
     ├─ 3. BASE via Spring Initializr (curl)                 [GA versions, nothing hardcoded]
     ├─ 4. RESTRUCTURES into modules per the blueprint       [exemplars give the shape]
     ├─ 5. GENERATES forbidden-imports.txt + root and module CLAUDE.md/AGENTS.md, CI, Checkstyle,
     │      lombok.config, logback, Dockerfile + docker-compose
     ├─ 6. EXPORTS norms, development skills, executor agents — the project is self-contained
     ├─ 7. INSTALLS hooks (ArchHook.jar + extensions.json + settings.json), opens the audit trail
     ├─ 8. VERIFIES build + smoke + tested boundary block; writes README + GENESIS.md
     ├─ 9. REPORT in the fixed output contract
     ├─ 10. GENESIS.md figures from the session transcripts — Started, Finished, tokens
     └─ if the build is green: OFFERS git-publish — two independent confirmations

And here is one real run of it:

The command opens with an interview in the main session: blueprint, coordinates, build tool, features, TLS, Sonar. Then a background agent (project-initializer, running on sonnet, with an isolated context and instructions to ask nothing) takes over and does the rest: validates the blueprint, pulls the base project from the Initializr, restructures it into the blueprint’s layout, generates the config, installs the hooks, and builds.

What it generated:

• Blueprint clean-architecture-single-module, with the versions the Initializr resolved that day (Java 21, Spring Boot 4.1.1, Maven). None of them came from the model’s memory.
• 15 boundary rules in .claude/forbidden-imports.txt, with the block verified before the run reports success (the report says “blocking verified”). A harness that only claims enforcement is a guide in disguise.
• Zero business code. No ExampleController to delete. The first feature comes from a real spec.
• A .claude/ that travels with the project: norms, development skills, executor agents, the hook, its schema, and the active blueprint. The project does not need the generator afterwards.
• A root CLAUDE.md of 120 lines. It is an index and a list of invariants. The detail lives in norms that load only when needed.

The result starts and verifies as a normal Spring Boot project:

One honest note about that report. The GENESIS.md says so itself: it is a one-time reconstruction, with no per-tool-call timeline, because no audit hook existed yet when the project was born. Start, finish, tokens and cost are the exception, and they are read from the transcripts. Every report written after it is produced by a hook.

Step 2: /new-feature

Inside the generated project, in a new session, I typed one line (typos included, because that is how people type):

/new-feature create one rest endpoint do save entity customer (name, securitynumber (11 digitis), bornDate (only above 18 yeas old)

The command has two flows, and the argument decides which one runs. This one creates the spec:

/new-feature <feature description>     (or UC-NNN-slug to resume a draft, or empty to list)
     │
     use-case-design → domain-modeling → rest-api-architect (unless GraphQL only)
        → graphql-api-architect (conditional)
        → security-architect (conditional) → http-client-architect (conditional)
        → ai-architect (conditional) → search-architect (conditional)
        → messaging-architect (conditional) → jobs-architect (conditional)
        → persistence-architect → cache-architect (conditional) → test-architect
     │  one use case per run; a split goes to docs/use-cases/BACKLOG.md
     │  design skills write only docs/ — never src/, never docker-compose.yml, never git
     │  a missing DB or broker is asked about and recorded: add it, runs elsewhere, or by hand
     │  each one decides the design patterns of its own layer, in its partial
     │
     ▼  consolidates into UC-NNN-spec.md (status: draft)
     ▼  asks approval → status: approved (the guard hook freezes the folder from here)
     ▼  git-publish (the approved spec only)
     ▼  prints the next two commands:  /clear  ·  /new-feature-implement UC-NNN-slug

The conditional layers only run when the use case needs them. And here is the run:

This is where the harness earns its name. The request does not go to “the model, please build it”. It goes through a chain with one owner skill per layer: use-case-design, then domain-modeling, then rest-api-architect, then persistence-architect, then test-architect. Each one writes only its own part of the spec, and each one asks only the questions that change its design: who may call it, what happens on a duplicate, how the age rule is computed, how long data is kept.

Layers the use case does not need are not silently skipped. The final spec records them as not applicable, with the reason: no security design because the endpoint is public and the project has no filter chain, no messaging because the use case emits no event, no jobs because nothing is scheduled.

Then the part I care about most. The spec is consolidated into one UC-001-spec.md, you approve it, and from that moment a hook freezes the spec folder. Only the status line, the checklist toggles and the changelog may still change. Code is written afterwards, in a second command (/new-feature-implement UC-001-create-customer) run after /clear, so the implementation session does not pay, on every turn, for the 250 to 370 thousand tokens of context the design left behind.

The numbers come from the run’s audit report, written by a hook:

• 10 minutes 15 seconds in total, of which 1 minute 59 seconds waiting for my answers. About 8 minutes of active work.
• About USD 3.46, on claude-opus-5–5. This is a projection: the audit prices the run’s tokens at API rates, as if an API key were used. The harness never uses one, because it runs inside Claude Code, so this is not a charge. Read it as the size of the run, not as a bill.
• The slowest step was test-architect at 2 minutes 17 seconds (28% of active time).

The result is public: the approved spec and its partials. You can read it before you decide whether any of this is for you.

What you can steal without installing anything

Even if you never touch Nerviz, three ideas carry over to any .claude/ folder:

1. One owner per rule. If the same norm lives in two files, they will diverge. Keep it in one and cite it by path.
2. If it must always hold, make it a sensor. A sentence in CLAUDE.md is a request. A hook that exits with code 2, or a permissions.deny line, is a fact. Spend your sensors on the three or four rules whose violation actually hurts.
3. Measure the runs. You cannot lower a bill you cannot read. A hook that writes what each skill and agent run did costs zero tokens and survives a dead session.

Everything is open source (MIT). The harness is at nerviz-ai/nerviz, the site is nerviz.dev, and the project it generated is at nerviz-ai/bank-app.

Key takeaways

• Agent = model + harness. When an agent misbehaves, look at the harness before the model.
• Guides steer, sensors check. A 400-line instruction file asks a guide to do a sensor’s job.
• Architecture belongs in data and hooks, not in prose. A forbidden import should be refused with exit code 2, not remembered.
• Say what it costs. Claude Code only, Spring Boot only, and expensive by design.

So here is my question for you: what is the rule in your CLAUDE.md that the model ignores most often, and what would it take to turn it into a sensor? Tell me in the comments.

If this saved you from one more 400-line CLAUDE.md, leave a few 👏 (you can clap up to 50 times), and send it to the teammate whose instruction file has a section called “IMPORTANT”.

I Stopped Writing Prompts and Built an Agent Harness for Spring Boot was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

Remember the moment in Part I when adding one more thread turned perfectly working code into a crime scene? 🕵️

Here’s the plot twist nobody tells you: in modern Java, you rarely need to manage threads by hand at all. 🎬

Picture a service that needs data from three places before it can answer. Do you writenew Thread(...), sprinkle join() everywhere, and hope for the best? There's a far better way: stop managing threads and start describing workflows.

In this Part II, let’s understand:

• ⚡ CompletableFuture: run work in the background, chain it, combine it, and rescue it when it fails
• 🌱 @Async: Spring Boot’s one-annotation shortcut, and the hidden executor trap behind it
• 🪤 Production pitfalls: every one comes with a fix you can copy

All the CompletableFuture examples come from runnable code in my Multithreading repo on GitHub (Java 17, Spring Boot 4.1.1). Clone it, run it, break it. 👇

1. 🚧 Why Plain Future Hits a Wall

First, what is asynchronous programming? It means starting N tasks in separate threads without blocking the main thread, then getting notified when each one finishes (or fails). Non-blocking code, real concurrency. 🎯

Java has offered ways to do this for years: Future, ExecutorService, ThreadPool. But Future has four painful limits, and CompletableFuture was built to remove every one of them:

Think of Future as a restaurant receipt you must stand at the counter holding, because get() blocks. CompletableFuture is the buzzer that vibrates when your order is ready, and it can even tell the kitchen what to cook next. 🍔

2. 🚀 Your First Async Tasks: runAsync vs supplyAsync

Two entry points, one simple rule:

• runAsync(Runnable) returns CompletableFuture<Void>. It means "run this in the background; I don't need anything back." 🏃
• supplyAsync(Supplier<T>) returns CompletableFuture<T>. It means "run this and supply me a value." 🎁

Both have an overload that accepts your own Executor. Without one, the task runs on the JVM-wide ForkJoinPool.commonPool().

The demo code reads 1,000 employee records from a JSON file that acts as a mock database, so you don't need to set up a database.

runAsync: when there’s nothing to return

public CompletableFuture<Void> saveEmployees() {
    return CompletableFuture.runAsync(() -> simulateEmployeeSave());
}

supplyAsync: when you want a result back

public CompletableFuture<List<Employee>> getEmployeesFromDatabase() {
    return CompletableFuture.supplyAsync(() -> {
        try {
            return EmployeeDatabase.fetchAllEmployees();
        } catch (IOException e) {
            throw new CompletionException("Unable to read employees.json", e);
        }
    });
}

The method returns immediately with a future. Only a call to get() or join() blocks. ⏱️

💡 Tip: checked exceptions. A Supplier or Runnable cannot throw checked exceptions, so wrap them in a CompletionException. The future carries the failure to the caller: get() surfaces it as an ExecutionException whose cause is your original IOException.

ExecutorService executor = Executors.newFixedThreadPool(5);
try {
    demo.saveEmployeesWithCustomExecutor(executor).get();
} finally {
    executor.shutdown(); // you created it, you close it
}

🪤 Pitfall #1: the vanishing task. The common pool uses daemon threads. If main returns before your task finishes, the JVM exits and the task silently disappears. Fix: in a console app, wait with get() or join() at the outer boundary, and only there.

🪤 Pitfall #2: the JVM that never exits. Threads in your own pool are non-daemon. Forget shutdown() and the program hangs forever after the work is done (a quick test confirms it). Fix: always shut down in a finally block.

💡 Tip: seeing Thread-0 instead of ForkJoinPool.commonPool-worker-1? CompletableFuture only uses the common pool when it has more than one thread of parallelism (cores minus one by default). On a machine or container with 2 or fewer CPUs, every task gets a brand-new thread instead. Also remember the common pool is shared by the whole JVM, so give blocking I/O tasks their own executor.

▶️ Run it yourself: CF_runAsync.java and CF_supplyAsync.java. Each has a main(), and the console prints which thread ran each task.

3. 🛑 Taking Control: complete(), Timeouts, and a Dangerous Myth

A CompletableFuture doesn't have to be born from a task. You can create an empty one and finish it yourself:

CompletableFuture<String> future = new CompletableFuture<>();

future.get();                            // blocks until someone completes it
future.complete("cached-or-default");    // completes it manually (first writer wins)

The classic use case: a task is taking too long, so you hand back a cached or default value instead of keeping the user waiting. ⏳

🪤 Pitfall: complete() does NOT stop the task. It's tempting to think that completing a slow future kills the thread working on it. It doesn't. In a quick test, complete("cached") returned true and get() returned instantly, yet the original task still ran to the very end in the background. cancel(true) is no better, because CompletableFuture ignores the interrupt flag: the future reports isCancelled(), but the thread keeps working and is never interrupted.

The fix: use the built-in timeout helpers (Java 9+) and be clear about what they do.

// Stop waiting after 2 seconds and use a fallback value
String price = CompletableFuture.supplyAsync(() -> fetchPriceSlowly())
        .completeOnTimeout("cached-price", 2, TimeUnit.SECONDS)
        .join();

// Or fail loudly: the future completes with a TimeoutException
CompletableFuture<String> strict = CompletableFuture.supplyAsync(() -> fetchPriceSlowly())
        .orTimeout(2, TimeUnit.SECONDS);

Both helpers stop the waiting, not the work. If the task itself must stop early, build that into the task: check a flag or Thread.interrupted() inside its loop. 🛡️

4. 🔗 Chaining: Build a Pipeline, Not a Pyramid

Chaining means linking dependent stages: each stage waits for the previous one to finish, and the result of the whole chain is just another CompletableFuture. No nested callbacks, no pyramid of doom. 🏔️

Three methods cover almost everything:

📧 Real use case: the training reminder pipeline
Goal: remind every new joiner whose training is still pending.

Fetch all employees from the “database”

1. Fetch all employees from the “database”
2. Keep only the new joiners
3. Keep only those with training pending
4. Collect their email addresses
5. Send the reminders

return CompletableFuture.supplyAsync(() -> fetchEmployees()) // 1. get everyone
      .thenApply(employees -> employees.stream()
            .filter(e -> "TRUE".equals(e.getNewJoiner()))
            .toList())                               // 2. new joiners
      .thenApply(employees -> employees.stream()
            .filter(e -> "TRUE".equals(e.getLearningPending()))
            .toList())                             // 3. training pending
      .thenApply(employees -> employees.stream()
            .map(Employee::getEmail)
            .toList())                              // 4. email addresses
      .thenAccept(emails -> 
            emails.forEach(this::simulateEmailNotification)) // 5. notify
      .thenRun(() -> System.out.println("Reminder workflow finished"));

Read it from top to bottom: each stage receives the previous stage’s result and prepares it for the next. The first three continuations transform data, so they use `thenApply()`. Sending reminders consumes email addresses, so it uses `thenAccept()`. The final message needs no previous result, so it uses `thenRun()`.

🪤 Pitfall #1: the flipped filter. A wrong boolean compiles fine and runs fine. On the sample data, filtering on "FALSE" instead of "TRUE" in step 3 would email the 263 people who already finished their training, and skip the 241 who haven't. Fix: give predicates names (isTrainingPending(employee)) and unit-test them.

🪤 Pitfall #2: “which thread runs my stage?” A plain thenApply doesn't schedule a new task. Measuring both cases shows: if the previous stage is still running, your stage runs on the thread that completes it; if the previous stage is already done, your stage runs on the calling thread (main, in a quick test). So a heavy transformation can quietly block your caller. Fix: for heavy or blocking stages, use thenApplyAsync(fn, executor) and choose where the work runs.

▶️ Run it yourself: ChainingTasksOnCompletableFuture.java prints the thread name at every stage, so you can watch the hand-offs happen.

5. 🤝 Combining Futures: Four Patterns, One Cheat Sheet

Real apps rarely do just one thing. To pick the right tool, ask one question: are the tasks dependent or independent?

1️⃣ thenCompose: task B needs the result of task A

Example: fetch an employee, then fetch that employee’s rating. The second lookup is itself asynchronous.

CompletableFuture<Integer> ratingFuture = demo.getEmployee()
        .thenCompose(demo::getEmployeeRating);

Here getEmployee() returns a CompletableFuture<Employee>, and getEmployeeRating(Employee) returns a CompletableFuture<Integer>.
Use thenApply and you get a future inside a future: CompletableFuture<CompletableFuture<Integer>>, which you would have to unwrap with get().get().thenCompose flattens it into a single CompletableFuture<Integer>.

If you know Streams: thenApply is map, thenCompose is flatMap. 🧠

The two stages run one after the other, and nothing guarantees they share a thread.

🪤 Pitfall: passing null downstream. If the lookup ends with .orElse(null), the next stage crashes with a NullPointerException far away from the real problem. Fix: fail fast with a clear message, so the future completes exceptionally right where the problem is:

.orElseThrow(() -> new IllegalStateException("Employee not found: " + id))

2️⃣ thenCombine and thenAcceptBoth: two independent tasks

When neither task needs the other, start both and merge the results:

CompletableFuture<Map<String, Long>> genderCountFuture = demo.countEmployeesByGender();
CompletableFuture<Long> newJoinerCountFuture = demo.countNewJoiners();

CompletableFuture<String> summaryFuture = genderCountFuture.thenCombine(
        newJoinerCountFuture,
        (genderCounts, newJoinerCount) ->
                "Employees by gender: " + genderCounts + "; new joiners: " + newJoinerCount);

Both tasks run concurrently, and the function fires once both have succeeded. On the sample data, that means 501 female, 499 male, and 504 new joiners.

• thenCombine combines two results and produces a new one
• thenAcceptBoth consumes two results and produces nothing (CompletableFuture<Void>)

🪤 Pitfall: accidental serial execution. Calling get() or join() on the first future before starting the second turns your parallel code sequential.
Fix: start every future first, then combine or wait.

3️⃣ allOf: wait for ALL of them (more than two)

CompletableFuture<String> weatherFuture = CompletableFuture.supplyAsync(() -> fetchWeather());
CompletableFuture<String> newsFuture    = CompletableFuture.supplyAsync(() -> fetchNews());

CompletableFuture.allOf(weatherFuture, newsFuture)
        .thenRun(() -> System.out.println(weatherFuture.join() + " - " + newsFuture.join()))
        .join();

allOf is non-blocking and returns a CompletableFuture<Void>, so you read each result yourself with join(). That is safe inside the callback, because every future is already done. ✅

🪤 Pitfall: allOf is not fail-fast. If one future fails, allOf still waits for all the others, then completes exceptionally, and the good results are hidden behind the failure. Fix: give each future its own fallback before combining, so one failure can't sink the batch:

CompletableFuture<String> newsFuture = supplyAsync(() -> fetchNews()).exceptionally(ex -> "news: unavailable");

4️⃣ anyOf: the first one wins 🏁

CompletableFuture<Object> fastest = CompletableFuture.anyOf(cf1, cf2);
fastest.thenAccept(price -> System.out.println("Received the first stock price: " + price));

It returns a CompletableFuture<Object>, so you cast the result yourself.

🪤 Pitfall: anyOf races completions, not successes. If the fastest future fails, that failure is your answer, even though a slower future would have succeeded. Fix: turn failures into "never completes" and add a timeout as the safety net:

static <T> CompletableFuture<T> ignoreFailure(CompletableFuture<T> f) {
    return f.handle((value, ex) -> ex == null
                    ? CompletableFuture.completedFuture(value)
                    : new CompletableFuture<T>())      // a failure never completes
            .thenCompose(Function.identity());
}

Object winner = CompletableFuture.anyOf(ignoreFailure(cf1), ignoreFailure(cf2))
        .orTimeout(2, TimeUnit.SECONDS)   // if everything fails, don't wait forever
        .join();

📋 The cheat sheet

▶️ Run it yourself: CombiningCompletableFutures.java demonstrates thenCompose, thenCombine and thenAcceptBoth end to end, with thread names printed.

🩹 When Things Go Wrong: Don’t Let Failures Vanish

Here’s the good news: when one stage of a chain fails, the stages after it are skipped and the failure travels down the chain until something handles it. So a single handler at the end can cover the whole pipeline. 🛟

String message = CompletableFuture.supplyAsync(() -> riskyCall())
      .thenApply(result -> result.toUpperCase())     // skipped if riskyCall() fails
      .handle((value, ex) -> ex == null
              ? "OK: " + value
              : "Failed: " + ex.getCause().getMessage())
      .join();

🪤 Pitfall #1: the silent failure. A failed future that nobody observes prints nothing and throws nothing. The error simply vanishes. A runAsync whose lambda throws is gone without a trace unless something looks at the outcome. Fix: end every chain with a handler.

CompletableFuture.runAsync(() -> sendEmail())
        .whenComplete((v, ex) -> {
            if (ex != null) log.error("Email failed", ex);
        });

🧯 The CompletableFuture Pitfall Checklist
Eight traps, eight fixes. Pin this above your monitor before your next code review. 📌

6. @Async: let Spring run the method in the background 🌱

CompletableFuture is plain Java. If you live in Spring Boot, there's a shortcut: put @Async on a method, and Spring runs it on another thread so the caller never waits. ⚡

Two steps:

1. Add @EnableAsync to your main class (or any @Configuration class). It switches on Spring's asynchronous method execution.
2. Annotate a method of a Spring bean with @Async.

First, enable async support and define a small pool:

@Configuration
@EnableAsync
public class AsyncConfig {
    @Bean("employeeExecutor")
    public ThreadPoolTaskExecutor employeeExecutor() {
        ThreadPoolTaskExecutor pool = new ThreadPoolTaskExecutor();
        pool.setCorePoolSize(2);
        pool.setMaxPoolSize(4);
        pool.setQueueCapacity(20);
        pool.setThreadNamePrefix("employee-");
        return pool;
    }
}

Spring manages this bean’s initialization and shutdown. The pool sizes are illustrative; tune them for your workload.
Now place the fetch in a Spring service:

@Service
public class EmployeeService {
    @Async("employeeExecutor")
    public CompletableFuture<List<Employee>> fetchEmployees() {
        try {
            return CompletableFuture.completedFuture(
                    EmployeeDatabase.fetchAllEmployees());
        } catch (IOException ex) {
            throw new CompletionException("Employee fetch failed", ex);
        }
    }
}

When another bean calls this service through its injected Spring proxy, Spring submits the method to `employeeExecutor` and returns a future. The pool can reuse a worker; not every call needs to create a new thread.

The common pitfall: calling an @Async method from another method in the same class bypasses Spring’s proxy (the default mode), so it runs synchronously on the caller’s thread. Fix: move the method into a separate bean and call it through the injected reference.

🏁 Three Words. Everything You Need.

Chain dependent steps. ⛓️
Combine independent ones. 🤝
Catch every failure. 🛟

That’s CompletableFuture. Everything else is detail, and you’ve just seen it all.

Now, confession time. 🙋 We covered a lot of traps in this article. Which one has burned you the most?

1️⃣ 🐌 The join() in the middle. You went async, then blocked yourself.
2️⃣ 🤫 The silent failure. An exception vanished, and nothing got logged.
3️⃣ 🧟 The JVM that never exits. You forgot to shutdown() your executor.

Vote in the comments with 1, 2, or 3, or tell me the worst one you’ve ever shipped. 💬 Let’s see which one wins.

Then do these before you close the tab:

• 👏 Clap if you learned something
• 🔁 Share it with the teammate who still writes new Thread()
• ➕ Follow for more on Java backend development and design

Threads were Level 1. You just unlocked the rest of the game. 🚀

Threads are the engine. CompletableFuture and @Async are the steering wheel. 🏎️ was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

Two threads increment a counter that starts at 10. You expect 12. You get 11.

Elsewhere, two workers are waiting for each other, and neither finishes. Another program submits seven tasks, but only six get processed.

These outcomes have explanations: a lost update, a deadlock, and a saturated thread pool. Understanding them makes multithreading much less mysterious.

I built a small Java project to explore these mechanisms directly. In this article, we’ll follow the same progression: create threads, let them share data, coordinate their work, and control how many tasks run at once.

Want to experiment as you read? Open this Multithreading repository. It uses Java 17. Concurrency demonstrations have their own main() methods. Run those classes directly.

Some examples intentionally expose unsafe behavior so we can understand the fix.

1. What Actually Changes When We Add a Thread?

A thread is a path of execution inside a process. A Java program can have several of these paths making progress concurrently.

Concurrency means work can overlap in time. Parallelism means work executes at the same instant, usually on different CPU cores. Multiple threads enable concurrency; they don't guarantee parallel execution or faster code.

Threads within a process share its address space, including the Java heap. Each thread has its own execution stack. That shared heap makes communication convenient, but it also lets two threads reach the same mutable object.

Compared with separate processes, threads typically have lower communication and context-switching costs. Those costs still exist, though, and creating more threads than the workload needs can hurt performance.

2. Starting Threads: Thread, Runnable and One Easy Mistake

The project demonstrates two basic approaches.

Extend Thread

Put the work inside an overridden run() method:

class Thread1 extends Thread {
    @Override
    public void run() {
        System.out.println(Thread.currentThread().getName());
    }
}

Create and start it:

Thread worker = new Thread1();
worker.start();

Implement Runnable

Here, the task is separate from the thread that executes it:

class Thread2 implements Runnable {
    @Override
    public void run() {
        System.out.println(Thread.currentThread().getName());
    }
}

new Thread(new Thread2(), "worker-2").start();

For a short task, a lambda is enough:

Thread worker = new Thread(() -> {
    System.out.println("Running inside "
            + Thread.currentThread().getName());
}, "worker-lambda");

worker.start();

Runnable is usually the better default for describing work. It keeps task logic separate from thread management and leaves your class free to extend another class.

start() and run() do different things

• start() starts a new thread, which executes run().
• Calling run() directly is an ordinary method call on the current thread.
• After start(), the caller continues without waiting for the new thread to finish.

That is why ThreadTester can print its main-thread exit message before worker output finishes.

Need to wait? Use join()

worker.start();
worker.join();             // The calling thread waits for worker to finish.
System.out.println("Worker finished");

worker.join(1000) limits the wait to approximately one second, subject to scheduling. It does not stop the worker when the wait expires. join() itself never starts a thread.

3. Thread States and Daemon Threads: Know What You’re Waiting For

Java exposes six thread states:

Some diagrams split “ready” and “running.” Java’s Thread.State combines those ideas underRUNNABLE; there is no separate SLEEPING enum value.

Daemon means a different shutdown role

The project marks one worker as a daemon:

Thread background = new Thread(new Thread2(), "background");
background.setDaemon(true);
background.start();

Set daemon status before calling start().

During normal JVM shutdown, daemon threads do not keep the process alive once all non-daemon threads have finished. Their remaining work is not guaranteed to complete.

Daemon status is independent of priority. A daemon thread is not inherently low priority, and an ordinary user thread is not inherently high priority.

Use this distinction when deciding whether background work must finish before the application exits.

4. Shared Data: Where the Interesting Bugs Begin

The project’s StackOperations gives two threads the same Stack instance: one pushes values while the other pops them.

The stack deliberately has no synchronization. Its push operation contains this sequence, with an artificial delay omitted here:

if (isFull()) {
    return false;
}

elements[++top] = element;

It looks compact, but it involves three steps: check capacity, updatetop, and write an array element. Another thread can interfere between those steps.

A race condition happens when two or more threads update the same shared value at the same time. The final result then depends on unlucky timing.

The stack has a broader problem: its index, capacity checks, and array contents must remain consistent together. An unsynchronized execution can violate that relationship.

The sleeps in the project increase the chances of interleaving. They do not guarantee a particular failure, and a successful run does not prove the code is thread-safe.

5. synchronized: Protect the Whole Operation

Every Java object has an associated monitor (lock). A synchronized block acquires that monitor before entering its body.

For the stack, one correction is to synchronize both operations on the same instance.

public synchronized boolean push(int element) {
    if (top == elements.length - 1) {
        return false;
    }
    elements[++top] = element;
    return true;
}

public synchronized int pop() {
    if (top == -1) {
        return Integer.MIN_VALUE;
    }
    return elements[top--];
}

Each capacity check and its corresponding update now happen while holding the same lock.

Which object is being locked?

• A synchronized instance method locks this.
• A synchronized static method locks the class’s Class object.
• A synchronized block locks the object supplied in its parentheses.

A block allows a smaller critical section:

synchronized (lock) {
    // Check and update shared state here.
}

All accesses that need coordination must use the same locking discipline. Synchronizing push() while leaving pop() unprotected does not solve the problem.

Synchronization also provides visibility: changes made before releasing a monitor become visible to a thread that subsequently acquires that same monitor.

6. volatile and AtomicInteger: Different Guarantees

volatile is a field modifier that guarantees visibility: when one thread writes the field, other threads see the new value instead of a stale cached copy. volatile makes shared updates visible.

private volatile boolean running = true;

The precise guarantee comes from Java’s memory model: a volatile write happens-before subsequent reads of that field. This establishes visibility and ordering. Calling it “always bypassing CPU caches” oversimplifies it.

But volatile does not make this compound operation atomic:

count++;

Reading, calculating, and writing still form a sequence that can interleave with another thread’s sequence.

AtomicInteger gives us an atomic increment

For counters, java.util.concurrent.atomic gives you a lighter tool than synchronized.

import java.util.concurrent.atomic.AtomicInteger;

public class ThreadSafeCounter {
    private final AtomicInteger count = new AtomicInteger(0);

    public void increment() { count.incrementAndGet(); }  // atomic ++count
    public int getValue()   { return count.get(); }
}

It works through Compare-And-Swap (CAS), a hardware-supported instruction, in a non-blocking retry loop:

1. Read the current value (say 10)
2. Compute the new value (11)
3. Write 11 only if memory still holds 10
4. If another thread got there first, the CAS fails and retries with the fresh value

No lock, no blocking, and no lost updates. The same package has AtomicLong, AtomicBoolean, AtomicIntegerArray and AtomicLongArray.

Choose the guarantee your data needs:

• A simple shared status flag: volatile may be enough.
• A counter increment: AtomicInteger fits naturally.
• Several values that must change consistently: protect the whole operation, for example with synchronized.

7. Deadlock: Two Locks, Zero Progress

Locks solve races, but they can cause a new problem. A deadlock is when two or more threads are blocked forever, each waiting for a lock the other holds. This is a circular wait, and the application simply hangs.

Object lockA = new Object(), lockB = new Object();

Thread t1 = new Thread(() -> {
    synchronized (lockA) {
        Thread.sleep(2000);
        synchronized (lockB) { System.out.println("t1 done"); }
    }
});

Thread t2 = new Thread(() -> {
    synchronized (lockB) {          // opposite order!
        Thread.sleep(2000);
        synchronized (lockA) { System.out.println("t2 done"); }
    }
});

t1 Holds lockAand wants lockB.
t2 Holds lockBand wants lockA.
Nobody moves.

In the repo, Deadlock.java reproduces this with opposing lock orders. It's a nice bug to watch happen once, safely.

The classic fix: make every thread acquire locks in the same order. That breaks the circular wait.

8. sleep(), wait(), and notify(): The Lock Makes the Difference

These methods appear together in concurrency discussions, but their effects differ:

You must own the object’s monitor before calling its wait(), notify()or notifyAll() methods. Also, wait() releases only that object's monitor, not every lock the caller might hold.

Notification does not guarantee immediate execution. The awakened thread must acquire the monitor and recheck its condition. Similarly, when a sleep duration expires, the thread becomes eligible to resume; it does not promise immediate CPU time.

These details become much easier to remember in the producer-consumer example below.

9. Thread pools: stop creating threads like it’s free

Creating a thread isn’t free. The JVM has to allocate its stack, program counter, and more. A thread pool is a set of worker threads that get reused for many tasks.

Why use one?

• Saves thread creation time, because threads are reused
• Removes the overhead of managing thread lifecycles by hand
• Limits how many threads exist, which avoids excess context switching

The framework

Executor → ExecutorService → implemented by ThreadPoolExecutor (TPE) and ForkJoinPool. ScheduledExecutorService extends ExecutorService and is implemented by ScheduledThreadPoolExecutor. TPE is the customizable one, so that's the one to learn.

The constructor:

ThreadPoolExecutor executor = new ThreadPoolExecutor(
    2,                                   // corePoolSize
    4,                                   // maximumPoolSize
    10, TimeUnit.MINUTES,                // keepAliveTime + unit
    new ArrayBlockingQueue<>(2),         // workQueue (bounded!)
    Executors.defaultThreadFactory(),    // threadFactory
    new CustomRejectionHandler()         // rejection policy
);

executor.allowCoreThreadTimeOut(true);

class CustomRejectionHandler implements RejectedExecutionHandler {
    @Override
    public void rejectedExecution(Runnable r, ThreadPoolExecutor executor) {
        System.out.println("Rejected task by the thread: "
            + Thread.currentThread().getName() + " - " + r.toString());
    }
}

allowCoreThreadTimeOut(true) is a method, not a constructor argument. It lets even core threads die after keepAliveTime when idle.

How a task actually flows

⚠️ Correction time. A common summary says the pool “first checks if a thread is free.” That’s not what happens. A ThreadPoolExecutor decides in this order:

1. Fewer than corePoolSize threads running? Start a new thread for the task, even if other threads are idle.
2. Otherwise, try to put the task in the queue.
3. Queue full and threads < maximumPoolSize? Start an extra thread.
4. Otherwise, reject the task.

Core threads are also created lazily as tasks arrive, unless you call prestartAllCoreThreads().

Let’s trace it with my example: core = 2, max = 4, queue capacity = 2, and 7 tasks that each sleep for 3 seconds.

executor.allowCoreThreadTimeOut(true);

for (int i = 1; i <= 7; i++) {
    int taskId = i;
    executor.submit(() -> {
        try { Thread.sleep(3000); } catch (Exception e) { /* handle */ }
        System.out.println("Task " + taskId + " processed by: "
                           + Thread.currentThread().getName());
    });
}
executor.shutdown();

The pool’s lifecycle

• Running: accepts new tasks via submit().
• Shutdown: shutdown() stops accepting new tasks and finishes the existing ones.
• Stop: shutdownNow() stops accepting tasks, interrupts running ones, and returns the list of tasks that never started. It can't force-kill a task that ignores interrupts.
• Terminated: the end. Check with isTerminated().

Don’t forget to shutdown(). The default factory creates non-daemon threads, so a pool you never shut down can keep your JVM alive.

10. The Producer-Consumer problem

This is the classic coordination puzzle. Producers insert items into a shared, fixed-size buffer and consumers remove them. It must work with:

• Empty buffer: consumers must not try to take
• Full buffer: producers must not try to add
• Uneven speeds: nothing gets overwritten, and nobody consumes from empty slots

There are two approaches:

Approach 1: manual coordination with wait() / notify()

private final Queue<Integer> buffer = new LinkedList<>();
private static final int CAPACITY = 5;

// producer
synchronized (buffer) {
    while (buffer.size() == CAPACITY) {
        buffer.wait();               // full? give up the lock and wait
    }
    buffer.add(item);
    buffer.notifyAll();              // wake up waiting consumers
}

// consumer
synchronized (buffer) {
    while (buffer.isEmpty()) {
        buffer.wait();               // empty? wait
    }
    int item = buffer.remove();
    buffer.notifyAll();              // wake up waiting producers
}

⚠️ Always check the condition in a while loop, never an if. Threads can wake up spuriously, or another thread may have grabbed the item first. Prefer notifyAll() when producers and consumers share one lock, so you don't wake the wrong kind of thread.

In the repo, this approach is demonstrated in UsingThreads.java: synchronized, wait() and notify(). It works, but it's easy to get subtly wrong.

Approach 2: let a BlockingQueue do the work

BlockingQueue<Integer> queue = new ArrayBlockingQueue<>(5);

// producer: blocks automatically when the queue is full
queue.put(item);

// consumer: blocks automatically when the queue is empty
int item = queue.take();

That’s it. No manual locks, no wait() loops. The queue handles empty and full for you (both methods throw InterruptedException, so handle it). Pair it with the Executor framework to manage the producer and consumer threads, and you have the production-style answer. That's UsingBlockingQueue.java in the repo.

Beyond Manual Synchronization: What’s Next?

You’ve now tackled the foundational core of Java concurrency — from orchestrating thread pools and managing synchronization to solving classic concurrency challenges like the Producer-Consumer problem. You have full control over low-level thread execution.

But raw threads and blocking queues are only the beginning. Modern Java applications often demand non-blocking, declarative asynchronous code without the headache of manual synchronization locks.

Java addresses these challenges through higher-level abstractions like CompletableFuture and Spring’s @Async capabilities — allowing you to chain asynchronous tasks, handle errors gracefully, and offload background operations seamlessly without blocking the main execution path.

Interested in deep diving into these modern, non-blocking asynchronous patterns? I’ll be covering them in my next article! Follow me on Medium so you don’t miss the next drop, and check out the complete companion code for this guide in my GitHub Multithreading repository.

Which of these bugs has bitten you the hardest: the lost update, the deadlock, or the pool that wouldn’t shut down?

Why Does Your Java Code Break When You Add Another Thread? was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

The One Line That Decides Whether the Skill Exists

You spent an afternoon writing a skill for your backend service. Three hundred lines describing exactly how a REST endpoint gets built in this codebase: the controller, the DTOs, the validation, the error mapping.

Then you typed “add an endpoint to list orders.” Claude Code improvised. It didn’t follow a single step.

Here’s what actually happened. Your skill wasn’t ignored. It was never opened. And the reason fits in one line of that file.

This article explains why, and what to do about it:

• how a skill actually loads, and why the body is invisible until it’s chosen
• why a vague description fails, and a three-part template that routes reliably
• the frontmatter fields that change behavior, including one typo that fails silently
• when a skill is the wrong tool altogether

Prefer video? I walk through the same file, with the before-and-after running live, in this episode

Three layers, three loading moments

A skill isn’t one thing that loads all at once. It’s three layers, and each one loads at a different moment.

Layer 1: the name and the description. This is the only part that sits in context all the time. Each skill gets one entry in a listing that the model scans on every request.

Layer 2: the body of SKILL.md. It enters the conversation only when the skill is invoked: by you, typing the slash command, or by the model, deciding the skill is relevant. Once it's in, it stays in. Claude Code doesn't re-read the file on later turns.

Layer 3: everything else in the folder. Reference docs, examples, scripts. These load only when the body tells the model they exist. And scripts get executed, not read.

If you write backend code, you already know this pattern: it’s lazy loading. In Spring terms, the skill is a @Lazy bean. The container knows it exists from startup, but nothing is built until someone asks for it.

That design is why skills are cheap. You can have twenty of them and pay context only for the one-line entries. But it has a consequence that’s easy to miss:

The model decides whether to open a skill without ever seeing its body. Layer 1 is all it has.

What the model sees when it picks a skill

Here’s roughly what reaches the model when you send “add an endpoint to list orders” in a project with a handful of skills:

Available skills:
  db-migration     Writes Flyway migrations for schema changes...
  kafka-consumer   Adds a Kafka consumer with retry and DLQ...
  rest-endpoint    Api Rest Helper
  test-slice       Creates @WebMvcTest and @DataJpaTest slices...
  openapi-sync     Regenerates the OpenAPI spec from controllers...

User: add an endpoint to list orders

Read it the way the model does. Your request talks about endpoint, list, orders. The entry says Api, Rest, Helper. There’s no shared word and no clear intent. The model moves on and writes the code from its own defaults, and your procedure stays on disk.

So stop thinking of the description as documentation. It’s a routing rule, written for a reader that only ever sees this one line.

A description template that routes

A description that routes well answers three questions, in this order.

1. What does it do, concretely? Name the output, not the topic. “Creates a new REST endpoint in this Spring Boot service: controller, request and response DTOs, validation, error mapping, OpenAPI annotations.”

2. When should it be used, in the user’s words? List the verbs and nouns people actually type. “Use when asked to add, create, or expose an endpoint, route, or API for a resource.”

3. When should it not be used? Name the nearest neighbor that could steal the request. “Not for calling external APIs from this service.”

Here’s the before and after for rest-endpoint:

---
name: rest-endpoint
description: Api Rest Helper
---

---
name: rest-endpoint
description: >-
  Creates a new REST endpoint in this Spring Boot service — controller,
  request and response DTOs, validation, error mapping, OpenAPI annotations.
  Use when asked to add, create, or expose an endpoint, route, or API for a
  resource. Not for calling external APIs from this service.
---

If you want a fill-in-the-blanks version for your own skills:

<Verb>s <concrete output> in <scope>. Use when asked to <verb>, <verb>, or
<verb> <noun>, <noun>, or <noun>. Not for <nearest neighbor>.

Two rules make the template hold up:

• Key use case first. If the listing truncates anything, it truncates the tail.
• Use synonyms on purpose. “Endpoint, route, or API” costs three words and covers three ways to say the same thing. That’s not filler; that’s the routing table.

Test it like a method signature

Here’s the mental model I use. When you decide whether to call a method, you don’t read its body. You read its signature:

List<OrderResponse> listOrders(OrderFilter filter);

Name, input, output: enough to decide. The description is your skill’s signature, and the caller is a model that never sees the implementation.

So the test is simple. Cover the body. Put your description next to the other entries in the listing, with a real user request in front of you. Would you pick it? If you hesitate, the model will too, and every line below the frontmatter might as well not exist.

The frontmatter fields worth knowing

The description decides whether a skill opens. A few other fields decide who can open it and how it runs.

Three structural rules, and one trap:

• The frontmatter is YAML between two --- lines, and the opening --- must be the very first line of the file. Not after a comment, not after a blank line.
• name becomes the slash command. Leave it out and the folder name is used.
• Old .claude/commands/ files still work as skills, in the older layout.

Now the trap. Write disable-model-invokation: true, with a k, and Claude Code won't recognize the field. It won't complain either. No error, no warning. The skill loads as if the line weren't there, so the model can invoke the side-effecting skill you meant to lock down.

The typo is just the most visible case of a broader rule. Claude Code only acts on the frontmatter fields it officially supports. Anything else, whether misspelled or invented on purpose (priority: high, owner: payments-team, run-tests: always), has no runtime behavior at all. Nothing enforces it, nothing validates it, nothing reads it as configuration. At best, the line reaches the model as plain text, and then it's up to the model to infer what you meant, or not. That's a hope, not a guarantee.

So the rule is simple: use only the official fields. If a behavior isn’t in the skills documentation, a custom key won’t create it. Put the intent where something will honor it: in the description, in the body as an explicit instruction, or in a hook if it has to happen every time.

Write the body as standing instructions

Remember layer 2: the body is read once, when the skill is invoked, and never re-read. That changes how you phrase it.

“Run the tests” is a one-time step the model may consider done after the first edit. “Run the tests after every edit” is a standing instruction that survives the rest of the turn.

And if something must happen every single time, with no exceptions, a skill is the wrong place for it. A skill can only ask. Guarantees belong to hooks, which run as code outside the model. (That’s the argument of the previous article in this series, Rules, Skills, Agents, Hooks: Which Claude Code Primitive Is Law?)

When a skill is the wrong tool

A perfect description won’t save a skill that shouldn’t exist. Before you write one, check what problem you’re actually solving:

Key takeaways

• A skill that misfires wasn’t ignored. It was never opened. The model chooses from the one-line listing, without seeing the body.
• Write the description as a routing rule: what it does, when to use it in the user’s words, and when not to. Key use case first; 1,536 characters max.
• Use only official frontmatter fields, and validate them. An unknown field is silently ignored: no runtime behavior, at most a hint the model may or may not pick up. A typo in disable-model-invocation can unlock a skill with side effects.
• Pick the right primitive. If it must always happen, it’s a hook, not a skill.

Here’s a five-minute exercise: open your .claude/skills/ folder and read only the descriptions. I'd bet at least one of them is a caption, not a routing rule.

Thank you for making it this far and for your valuable time reading this article.

Before you go:

• Be sure to clap 👏
• Share with other developers who might benefit from this solution!
• Follow the author to support: https://lucas-fernandes.medium.com/subscribe
• Donate: Buy me a Coffee ☕

Claude Code Skills: Why Yours Never Fires was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

You open the Claude.md of your Spring Boot project and write, in capital letters:

AFTER ANY CODE WRITTEN UNDER SOURCE MAIN FOLDER, RUN THE PROJECT'S TESTS.

Claude Code finishes the change, marks the task as done, and never runs a single test.

The first reaction is always the same: the model is dumb, or lazy, or it ignored you on purpose. But none of it is true. The model didn’t disrespect you. You used the wrong tool.

Writing a rule in prose and expecting it to be obeyed every time is the most common mistake in the whole Claude Code ecosystem, and it happens because nobody shows you how the pieces relate to each other.

That’s what this article does. I’ll put the four Claude Code main extensions file on one map, give you a single question that picks the right one every time, and then show what happened when I let Claude Code work inside a small Spring Boot project built around that map.

This is the written version of the first episode of my YouTube playlist on the Claude Code ecosystem, on the Java Plus AI channel. In the video I draw the map piece by piece and run the demo live.

The map nobody gave you

Claude Code has four primitives you write yourself:

• Rules: your CLAUDE.md files
• Skills: .claude/skills/<name>/SKILL.md
• Subagents: files in .claude/agents/
• Hooks: commands configured in .claude/settings.json

The official docs explain each one well, but in isolation. They don’t put them side by side, and that gap is exactly where people pick the wrong one.

So instead of four definitions, I use two axes. Every primitive answers two questions, and only two.

When does this enter the context? Always, on demand, or never, because it runs outside the model. In practice this is a cost axis. Anything that is always loaded, you pay for in tokens, on every message, for the whole session.

Who decides whether this is respected? The model or the computer. This is the axis that matters. At the top, behavior is heuristic: the model reads, interprets and decides. At the bottom, behavior is deterministic: code runs, and the result doesn’t depend on anyone’s interpretation.

Keep the word deterministic in mind. Three of the four primitives live at the top. Only one lives at the bottom, and it’s the one almost nobody uses properly.

Rules: always on the table, never guaranteed

Rules are your CLAUDE.md. It's a Markdown file loaded into context when the session starts, and it stays there. There is a hierarchy:

~/.claude/CLAUDE.md covers every project you touch, CLAUDE.md at the project root goes into git so the whole team gets it, and a CLAUDE.md in a subdirectory loads only when the agent works in that folder.

Rules are great for things that always apply: your stack, your style, what this repository is.

They’re bad at anything long and anything conditional. Every line is paid on every message, and it’s text the model reads, not a command it executes. Reading is not obeying. That makes rules the most expensive primitive you have and the weakest guarantee. It’s also why a 400-line CLAUDE.md stops working. The model didn't get dumber. The file became noise.

Skills: knowledge that shows up only when needed

A skill is a folder under .claude/skills/ a SKILL.md inside. The frontmatter has two fields that really matter: name and description.

Here’s the trick. The only thing that stays loaded all the time is the description, one line per skill. The body, with its steps, scripts and examples, doesn't touch the context until the model decides the skill is relevant. That's how you document twenty procedures without paying for twenty procedures on every message.

And here’s the part almost nobody takes seriously: the description isn't documentation. It's the trigger. Write it vaguely and the skill never loads. You'll swear the agent ignored your procedure, when in fact it never read it.

A skill is still heuristic. The model chooses whether to load it and whether to follow it. But it’s cheap heuristic, and that puts it in a different category from a rule.

Subagents: a worker with its own context

A subagent is a file in .claude/agents/. The difference from a skill is one thing, and it's a big one: a subagent runs in its own context window.

It gets a task and works alone. It can read fifty files, take the wrong path, make a mess. Only the result comes back to the main agent, so the mess never pollutes your context. It can also run with a restricted tool set or on a different model.

That’s why I apply this rule without exceptions:

A subagent only justifies its existence for one of three reasons: to preserve context, to restrict tools, or to switch models. If none applies, it should have been a skill.

This isn’t pedantry. A subagent costs a new context window, duplicated tokens and a narrow return channel: you get a summary back, not everything it saw. Without one of those three reasons, you’re paying for isolation and throwing information away.

Rules, skills and subagents differ in cost and in isolation. On the vertical axis, though, they’re identical. All three sit above the line.

Hooks: the only part that doesn’t negotiate

A hook is a command you configure in .claude/settings.json. Claude Code runs it on lifecycle events: before a tool runs (PreToolUse), after it runs (PostToolUse), when you submit a prompt (PreToolUse), when a session starts (SessionStart), when the agent tries to stop (Stop). The command always runs. The model has no vote. It isn't even consulted.

What makes hooks worth it is the exit code. Exit 0 and everything continues. Exit 2 and the action is blocked, and whatever the hook wrote to stderr goes back to the model as a correction.

That's the difference between "please don't do this" and "this won't happen."

My rule of thumb: a hook verifies; it doesn’t teach. If you can check it with a command (a forbidden import, a class in the wrong layer, a broken build), don’t write it in prose. Write it as a hook.

Prose is a request. A hook is law.

The single question

With the map complete, you can see what I wanted to show from the start. Rules, skills and subagents all depend on the model reading, interpreting and agreeing. Their guarantee is the same: probably. Hooks sit below the line, and below means it happens no matter what the model thought.

So here’s the question that replaces the whole docs page:

Can this fail without anyone noticing?

If yes (an architecture rule, a forbidden import, a secret that must never leak, a commit that can’t happen without review), it goes below the line. It’s a hook. End of discussion.

If not, because it’s judgment, style or procedure, it stays above the line, and the other axes decide for you:

• applies always: rule
• applies sometimes: skill
• needs its own context, restricted tools or another model: subagent

I spent years rejecting pull requests from people who solved with a code comment what the compiler should have guaranteed. This is the same mistake with a new tool. Prose doesn’t compile.

Hands on: the map in a real Spring Boot project

Theory is cheap, so I built a minimal Spring Boot 4 / Java 21 REST app with one real file for each case: demo-project-java-plus-ai-example.

No database, a couple of endpoints, just enough app for something real to sit behind a rule, a skill and a hook.

“The project uses Java 21 and Spring Boot 4”: rule

It always applies and it’s context, so it lives in CLAUDE.md:

## Stack

This project uses Java 21 and Spring Boot 4. Always target that version —
don't downgrade the parent POM or the `java.version` property to make a
dependency fit.

Short, unconditional, true for every task. That’s the whole job of a rule.

“How to create a REST endpoint here, in eight steps”: skill

A long procedure that applies only sometimes. Look at the description: it says what the skill does and when to use it, because that line is all the model sees until it loads the skill.

---
name: rest-endpoint
description: How to create a REST endpoint in this project, in eight steps. Use when asked to add, create, or expose a new REST endpoint or API route in this Spring Boot app.
---

# Creating a REST endpoint here

1. Decide the resource and the HTTP method — one verb per endpoint, no
   verbs in the URL (`/api/greetings/{name}`, not `/api/getGreeting`).
2. Add a `@RestController` class in `src/main/java/com/javaplusai/demo/`,
   named after the resource (`GreetingController`, not `GreetingApi` or
   `GreetingService`).
3. Map the method with `@GetMapping`/`@PostMapping`/etc., not the generic
   `@RequestMapping`.
4. Model the response as a `record`, nested in the controller unless it's
   reused elsewhere.
5. No persistence. This project has no database — if the endpoint needs
   state, it's out of scope here.
6. Constructor injection only for any collaborator, per `CLAUDE.md`. Never
   field injection.
7. Add a `@WebMvcTest` for the controller with `MockMvc`, asserting status
   and body via `jsonPath`.
8. Run the project's tests before considering the endpoint done — see the
   `Stop` hook in `.claude/settings.json`, which does this automatically.

“After any code under /src, run the tests": hook

That capital-letters rule from the opening? Wrong primitive. It’s an invariant, so it belongs in a Stop hook that runs the test suite before the agent may finish. The wiring in .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/run-tests.sh"
          }
        ]
      }
    ]
  }
}

And the core of .claude/hooks/run-tests.sh (full file in the repo):

CURRENT_HASH="$(find "$SRC_DIR" -type f -name '*.java' -exec sha256sum {} \; | sort | sha256sum | awk '{print $1}')"
PREVIOUS_HASH="$(cat "$HASH_FILE" 2>/dev/null || echo "")"

if [ "$CURRENT_HASH" = "$PREVIOUS_HASH" ]; then
    exit 0
fi

if ! ./mvnw -q test 2>test-output.log; then
    echo "Tests failed after a change under /src. Fix the failures below before finishing:" >&2
    cat test-output.log >&2
    rm -f test-output.log
    exit 2
fi

echo "$CURRENT_HASH" > "$HASH_FILE"
rm -f test-output.log
exit 0

The hash check is the detail most people miss. Stop doesn't fire only when a task ends. It fires every time Claude finishes a response, including when it just answers a question. Without the guard, "what does this class do?" costs you a full Maven run. With it, the suite runs only when Java code under src/main/java changed since the last green run.

What Claude Code did inside this project

In the video, I open Claude Code in the project and type, typo included:

create new ednpoint rest example

Here’s what the recording shows:

1. The skill loaded on its own. First line of the transcript: Skill(rest-endpoint) — Successfully loaded skill. I never named the skill. The descritpion matched, and that was enough.
2. It followed the procedure. It read GreetingController for the pattern and created TimeController with GET /api/time a nested TimeResponse record.
3. It respected the rule. The controller needs a java.time.Clock. No Clock bean existed, so it added one to DemoApplication and injected it through the constructor, as CLAUDE.md says.
4. It wrote a @WebMvcTest with a fixed clock (step 7) and ran the tests (step 8).
5. The tests failed. Its diagnosis: “Bean clash: DemoApplication’s clock bean conflicts with test override.”
6. It fixed the test, renaming the test bean to fixedClock() and marking it @Primary, then re-ran ./mvnw -q test. All green.

The fix, as committed:

@TestConfiguration
static class FixedClockConfig {

    @Bean
    @Primary
    Clock fixedClock() {
        return Clock.fixed(FIXED_INSTANT, ZoneOffset.UTC);
    }
}

The hook had nothing to block, and that’s the point

Notice who caught the failing test: Claude, because step 8 of the skill told it to. This time, the heuristic layer did its job.

But this time is the problem. Step 8 is still prose. On another day, with a longer session, a fuller context or a vaguer prompt, the model may skip it, exactly like it skipped the capital-letters rule. The skill makes running the tests likely. The hook makes it certain. Had Claude tried to finish with a red suite, the Stop hook would have exited 2, handed the Maven output back, and the session couldn't end until the tests passed.

That’s the division of labor I want in every project. The layers above the line make good behavior probable. The layer below the line makes bad behavior impossible.

What to take away

Don’t memorize the four names. Remember the line in the middle of the map. Almost every frustration I see with AI agents (the ignored rule, the skill that never loads, the subagent that burned a fortune to return three lines) comes from someone putting something on the wrong side of it.

Before your next instruction, ask: can this fail without anyone noticing? If yes, write a hook. If no, choose between rule, skill and subagent by when it applies and whether it needs isolation.

Then open your CLAUDE.md and find the line that should have been a hook all along. There's usually at least one. Tell me in the comments which one it was in yours.

• Code from the video: demo-project-java-plus-ai-example
• More on YouTube: subscribe to Java Plus AI for the full series.

Thank you for making it this far and for your valuable time reading this article.

Before you go:

• Be sure to clap 👏
• Share with other developers who might benefit from this solution!
• Follow the author to support: https://lucas-fernandes.medium.com/subscribe
• Donate: Buy me a Coffee ☕

Your CLAUDE.md Rule Got Ignored. You Picked the Wrong Primitive. was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.

Your First Chat Endpoint — Zero Cloud Cost, Fully Local

Large Language Models are everywhere, but every provider speaks a slightly different dialect. OpenAI, Anthropic, Google Gemini, Ollama — each has its own SDK, authentication scheme, and response format. What if you could stand up a single gateway that unifies them all behind one API?

In this series, we’ll build exactly that: a production-grade LLM gateway using Spring Boot and Spring AI. By the end, you’ll have rate limiting, API key auth, PII guardrails, caching, streaming, and a pluggable provider system.

But we start simple. In this first article, we’ll build a working gateway that:

• Exposes an OpenAI-compatible POST /v1/chat/completions endpoint
• Routes requests to a local Ollama instance (zero cost)
• Returns responses in the exact format the OpenAI SDK expects
• Handles validation and errors gracefully

Let’s get started.

Prerequisites

• Java JDK 21+ — Runtime
• Maven 3.9+ — Build tool
• Ollama (latest) — Local LLM runtime
• IDE (IntelliJ / VS Code) — Development environment

Pull a model before we begin:

ollama pull llama3

Project Setup

We’ll use Spring Boot 3.5.x with Spring AI 1.1.x. Here’s the core of our pom.xml:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.14</version>
</parent>

<properties>
    <java.version>21</java.version>
    <spring-ai.version>1.1.5</spring-ai.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-ollama</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Key points:

• Spring AI BOM manages all AI-related dependency versions
• spring-ai-starter-model-ollama auto-configures a ChatModel bean that talks to Ollama
• Validation starter gives us @Valid + Jakarta annotations

Application Configuration

spring:
  application:
    name: spring-llm-gateway
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3
          temperature: 0.7
server:
  port: 8080

Spring AI picks this up automatically — no manual bean wiring needed. The ChatModel is ready to inject.

Defining the API Contract

We want our gateway to be a drop-in replacement for the OpenAI API. That means snake_case JSON and the exact same response shape. Here are our DTOs:

Request

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class GatewayRequest {
    
    @NotBlank(message = "Model cannot be blank")
    private String model;

    @NotEmpty(message = "Messages cannot be empty")
    @Valid
    private List<ChatMessage> messages;

    private Double temperature;

    @JsonProperty("max_tokens")
    private Integer maxTokens;

    @JsonProperty("top_p")
    private Double topP;
}

Message

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ChatMessage {
    
    @NotBlank(message = "Role cannot be blank")
    private String role;
    
    @NotBlank(message = "Content cannot be blank")
    private String content;
}

Response

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class GatewayResponse {
    
    private String id;
    private String object;
    private Long created;
    private String model;
    private List<ChatChoice> choices;
    private TokenUsage usage;

    @JsonProperty("system_fingerprint")
    private String systemFingerprint;
}

Choice & Usage

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ChatChoice {
    
    private Integer index;
    private ChatMessage message;

    @JsonProperty("finish_reason")
    private String finishReason;
}

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class TokenUsage {
    @JsonProperty("prompt_tokens")
    private Long promptTokens;
    @JsonProperty("completion_tokens")
    private Long completionTokens;
    @JsonProperty("total_tokens")
    private Long totalTokens;
}

The @JsonProperty annotations ensure our Java camelCase maps to OpenAI's snake_case on the wire. Any OpenAI SDK or Spring AI OpenAI client can consume this without modification.

The Chat Service — Bridging Spring AI

This is where the magic happens. Spring AI’s ChatModel abstraction lets us call any LLM provider through a unified interface. We map our DTOs to Spring AI's internal types, call the model, and map back.

@Service
@RequiredArgsConstructor
public class ChatService {
    
    private final ChatModel chatModel;

    public GatewayResponse complete(GatewayRequest request) {
        List<Message> messages = request.getMessages().stream()
            .map(this::toMessage)
            .toList();
        
        OllamaChatOptions.Builder optionsBuilder = OllamaChatOptions.builder()
            .model(request.getModel());
        if (request.getTemperature() != null) {
            optionsBuilder.temperature(request.getTemperature());
        }
        if (request.getMaxTokens() != null) {
            optionsBuilder.numPredict(request.getMaxTokens());
        }
        if (request.getTopP() != null) {
            optionsBuilder.topP(request.getTopP());
        }
        Prompt prompt = new Prompt(messages, optionsBuilder.build());
        ChatResponse response = chatModel.call(prompt);
        return mapToGatewayResponse(request.getModel(), response);
    }

    private Message toMessage(ChatMessage message) {
        return switch (message.getRole().toLowerCase()) {
            case "system" -> new SystemMessage(message.getContent());
            case "user" -> new UserMessage(message.getContent());
            case "assistant" -> new AssistantMessage(message.getContent());
            default -> throw new IllegalArgumentException("Invalid role: " + message.getRole());
        };
    }

    private GatewayResponse mapToGatewayResponse(String model, ChatResponse response) {
        List<ChatChoice> choices = IntStream.range(0, response.getResults().size())
                .mapToObj(i -> {
                    var generation = response.getResults().get(i);
                    return ChatChoice.builder()
                            .index(i)
                            .message(ChatMessage.builder()
                                    .role("assistant")
                                    .content(generation.getOutput().getText())
                                    .build())
                            .finishReason(generation.getMetadata() != null
                                    ? generation.getMetadata().getFinishReason()
                                    : null)
                            .build();
                })
                .toList();
        var usage = response.getMetadata() != null && response.getMetadata().getUsage() != null
                ? response.getMetadata().getUsage()
                : null;
        return GatewayResponse.builder()
                .id("chatcmpl-" + UUID.randomUUID().toString().replace("-", "").substring(0, 24))
                .object("chat.completion")
                .created(Instant.now().getEpochSecond())
                .model(model)
                .choices(choices)
                .usage(usage != null
                        ? TokenUsage.builder()
                                .promptTokens(usage.getPromptTokens().longValue())
                                .completionTokens(usage.getCompletionTokens().longValue())
                                .totalTokens(usage.getTotalTokens().longValue())
                                .build()
                        : null)
                .build();
    }
}

What’s happening here:

1. Message mapping — We convert our simple role/content DTOs into Spring AI’s typed message objects (UserMessage, SystemMessage, AssistantMessage)
2. Options building — Ollama-specific options like numPredict (their name for max_tokens) are set conditionally
3. Response mapping — We extract generations, token counts, and metadata into our OpenAI-compatible response shape
4. ID generation — We follow OpenAI’s chatcmpl- prefix convention

Error Handling

A production gateway needs structured error responses. We create a base exception and a global handler:

@Getter
public class GatewayException extends RuntimeException {
    private final int status;
    private final String code;
    public GatewayException(String code, int status, String message) {
        super(message);
        this.code = code;
        this.status = status;
    }
    public GatewayException(String code, int status, String message, Throwable cause) {
        super(message, cause);
        this.code = code;
        this.status = status;
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, Object>> handleValidation(MethodArgumentNotValidException ex) {
        String message = ex.getBindingResult().getFieldErrors().stream()
            .map(error -> String.format("%s: %s", error.getField(), error.getDefaultMessage()))
            .reduce((a, b) -> a + "; " + b)
            .orElse("Validation failed");
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
            .body(Map.of("error", Map.of("code", "VALIDATION_ERROR", "message", message)));
    }

    @ExceptionHandler(GatewayException.class)
    public ResponseEntity<Map<String, Object>> handleGatewayException(GatewayException ex) {
        HttpStatus status = switch (ex.getCode()) {
            case "MODEL_NOT_FOUND" -> HttpStatus.NOT_FOUND;
            case "PROVIDER_ERROR" -> HttpStatus.BAD_GATEWAY;
            default -> HttpStatus.INTERNAL_SERVER_ERROR;
        };
        return ResponseEntity.status(status)
                .body(Map.of("error", Map.of("code", ex.getCode(), "message", ex.getMessage())));
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<Map<String, Object>> handleIllegalArgument(IllegalArgumentException ex) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(Map.of("error", Map.of("code", "BAD_REQUEST", "message", ex.getMessage())));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handleGeneric(Exception ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(Map.of("error", Map.of("code", "INTERNAL_ERROR", "message", "An unexpected error occurred")));
    }
}

This gives us:

• 400 for validation failures (missing model, empty messages, invalid role)
• 404 for model-not-found scenarios
• 502 for upstream provider errors
• 500 as a safe catch-all (never leaks internal details)

The Controller — Wiring It Together

The simplest layer. One endpoint, one method:

@RestController
@RequestMapping("/v1")
@RequiredArgsConstructor
public class ChatController {
    private final ChatService chatService;
    @PostMapping("/chat/completions")
    public ResponseEntity<GatewayResponse> chatCompletions(@Valid @RequestBody GatewayRequest request) {
        GatewayResponse response = chatService.complete(request);
        return ResponseEntity.ok(response);
    }
}

Note the path: /v1/chat/completions — identical to OpenAI's. Any client configured to point at http://localhost:8080 as the base URL will work seamlessly.

Testing It

Start Ollama and the gateway:

ollama serve
mvn spring-boot:run

Happy path

curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [
      {"role": "user", "content": "Say hello in one word"}
    ]
  }' | jq .

Response:

{
  "id": "chatcmpl-ee0b0603f6c346799756417f",
  "object": "chat.completion",
  "created": 1777552454,
  "model": "llama3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 3,
    "total_tokens": 18
  },
  "system_fingerprint": null
}

Validation error

curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}]
  }' | jq .

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "model: Model cannot be blank"
  }
}

Using It as an OpenAI-Compatible Backend

Here’s the payoff. Any application that speaks the OpenAI protocol can now point at your gateway. For example, another Spring Boot app using Spring AI’s OpenAI starter:

spring:
  ai:
    openai:
      base-url: http://localhost:8080
      api-key: not-needed
      chat:
        options:
          model: llama3

No code changes in the consumer. Just config. It will call your gateway, which routes to Ollama locally, and everything works.

This also means tools like LangChain, LiteLLM, or any OpenAI-compatible client library can consume your gateway out of the box.

Project Structure

com.llmgateway
├── SpringLlmGatewayApplication.java
├── controller/
│   └── ChatController.java
├── model/
│   └── dto/
│       ├── GatewayRequest.java
│       ├── GatewayResponse.java
│       ├── ChatMessage.java
│       ├── ChatChoice.java
│       └── TokenUsage.java
├── service/
│   └── ChatService.java
└── exception/
    ├── GatewayException.java
    └── GlobalExceptionHandler.java

What’s Next

We have a working, OpenAI-compatible LLM gateway running entirely on your machine. In the next article, we’ll add:

• Multi-provider support — OpenAI, Anthropic, Google Gemini alongside Ollama
• Provider registry — route requests to the right provider based on model name
• Dynamic configuration — add providers via YAML without code changes

The foundation is solid. Time to make it scale.

All code is available on GitHub. Star the repo and follow along as we build this out.

Build an OpenAI-Compatible LLM Gateway with Spring Boot and Spring AI was originally published in Spring Boot World on Medium, where people are continuing the conversation by highlighting and responding to this story.