<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Ai on Vitalii Sukach</title><link>https://vitaliisukach.dev/tags/ai/</link><description>Recent content in Ai on Vitalii Sukach</description><generator>Hugo</generator><language>en-us</language><lastBuildDate>Sun, 15 Nov 2026 10:00:00 +0000</lastBuildDate><atom:link href="https://vitaliisukach.dev/tags/ai/index.xml" rel="self" type="application/rss+xml"/><item><title>Your AI Assistant Is Just Another Team That Ignores Your Bounded Context</title><link>https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/</link><pubDate>Sun, 15 Nov 2026 10:00:00 +0000</pubDate><guid>https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/</guid><description>AI assistants cross DDD boundaries like a new team that never read the design docs. Make the domain explicit for the AI, then enforce it with tests.</description><content:encoded><![CDATA[<p><img alt="A cheerful robot with a &ldquo;New team – Day 1&rdquo; badge breaks through the wall of a garden labelled &ldquo;Loyalty&rdquo;, carrying a glowing jar of points and dropping coins behind it. It ignores the open gate nearby with the sign &ldquo;LoyaltyService – please use this entrance&rdquo;, and an unread AGENTS.md scroll lies on the ground. Two surprised developers with coffee mugs watch." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/image-01.jpg"></p>
<blockquote>
<p><strong>TL;DR</strong></p>
<ul>
<li>An AI assistant takes the shortest path through your code, and that path usually crosses a boundary.</li>
<li>It sees code, not intent. If the rules live in people&rsquo;s heads, the AI can&rsquo;t follow them.</li>
<li>Write the bounded context down in an <code>AGENTS.md</code> next to the code: language, invariants, public API, forbidden dependencies.</li>
<li>Prompts are suggestions, tests are guarantees. Enforce the boundary with ArchUnit.</li>
</ul></blockquote>
<h2 id="the-ai-wrote-a-feature-that-works-and-breaks-four-rules">The AI wrote a feature that works and breaks four rules</h2>
<p>The ticket was simple: &ldquo;Customers get 2x loyalty points on their birthday.&rdquo; An AI assistant opened the checkout module, found the loyalty repository, and produced this:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">CheckoutService</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">OrderRepository</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyAccountRepository</span><span class="w"> </span><span class="n">loyaltyAccountRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// constructor omitted</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">completeCheckout</span><span class="p">(</span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="p">,</span><span class="w"> </span><span class="n">Customer</span><span class="w"> </span><span class="n">customer</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">order</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">loyaltyAccountRepository</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">.</span><span class="na">findByCustomerId</span><span class="p">(</span><span class="n">customer</span><span class="p">.</span><span class="na">getId</span><span class="p">()).</span><span class="na">orElseThrow</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="kt">long</span><span class="w"> </span><span class="n">points</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">order</span><span class="p">.</span><span class="na">getTotal</span><span class="p">().</span><span class="na">longValue</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">customer</span><span class="p">.</span><span class="na">getBirthday</span><span class="p">()).</span><span class="na">equals</span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">now</span><span class="p">()))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">points</span><span class="w"> </span><span class="o">*=</span><span class="w"> </span><span class="n">2</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">points</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">loyaltyAccountRepository</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>It compiles. The tests pass. The feature works in the demo. Here is what it breaks:</p>
<ul>
<li><strong>Checkout reaches into Loyalty&rsquo;s persistence.</strong> <code>LoyaltyAccountRepository</code> is an internal detail of another context.</li>
<li><strong>Points before payment.</strong> The order is saved, not paid. A failed card still earns points.</li>
<li><strong>Checkout changes the balance itself.</strong> Calling <code>setBalance()</code> from checkout skips every rule <code>LoyaltyService</code> is supposed to enforce.</li>
<li><strong>No event.</strong> <code>PointsEarned</code> is never published, so the email service and analytics never hear about it.</li>
</ul>
<p><img alt="Diagram: CheckoutService in the Checkout context has two paths into the Loyalty context. The intended path goes to LoyaltyService, the public API that returns DTOs. The AI&rsquo;s shortcut, marked with a red cross, goes straight to the hidden LoyaltyAccountRepository and LoyaltyAccount. The rules it breaks: uses another context&rsquo;s repository, points before payment, sets the balance directly, publishes no event." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-shortcut.jpg"></p>
<p>None of this is new. A team that joined last month and never read the design docs would write the same code, for the same reason: nobody told them where the boundary was.</p>
<h2 id="why-the-ai-crosses-the-line">Why the AI crosses the line</h2>
<p><strong>The shortest path wins.</strong> The assistant is asked to make a feature work. A repository that&rsquo;s already on the classpath is the shortest path to a working feature. Nothing in the code says &ldquo;don&rsquo;t.&rdquo;</p>
<p><strong>It sees code, not intent.</strong> Your bounded contexts exist in a whiteboard photo, a Confluence page and the heads of three senior engineers. The AI reads <code>src/main/java</code>. If a public setter exists, the AI reads that as permission to call it.</p>
<p><strong>There is no ubiquitous language in the prompt.</strong> &ldquo;Add birthday points at checkout&rdquo; puts the rule in checkout. A domain expert would say &ldquo;Loyalty awards double points for orders paid on the customer&rsquo;s birthday.&rdquo; Same feature, different owner.</p>
<p>This is exactly how a new team behaves when it joins without onboarding. We already know the fix for that team. It works for the AI too.</p>
<h2 id="step-1-ask-the-ai-to-discover-the-domain-first">Step 1: Ask the AI to discover the domain first</h2>
<p>Before writing rules, find out what the code already says. Use the AI as a reader, not a writer.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Read the packages under com.shop.domain.loyalty.
</span></span><span class="line"><span class="cl">Build a glossary of the domain terms you find: class names, method
</span></span><span class="line"><span class="cl">names, enum values, event names. For each term give a one-line
</span></span><span class="line"><span class="cl">definition based only on the code. Mark terms that mean different
</span></span><span class="line"><span class="cl">things in different places, and terms that look like technical
</span></span><span class="line"><span class="cl">names rather than business language (e.g. &#34;updateRecord&#34;).
</span></span><span class="line"><span class="cl">Do not suggest changes yet.
</span></span></code></pre></div><p>Then look for the leaks:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">List every class outside com.shop.domain.loyalty that imports a
</span></span><span class="line"><span class="cl">Loyalty entity or repository, or reads/writes the loyalty_account
</span></span><span class="line"><span class="cl">table through a repository, JdbcTemplate or native query.
</span></span><span class="line"><span class="cl">Calls to LoyaltyService that only get DTOs back are fine. Skip them.
</span></span><span class="line"><span class="cl">For each one, show the file, the line, and whether it reads or
</span></span><span class="line"><span class="cl">writes. Group the results by calling module.
</span></span></code></pre></div><p>The second list is your boundary violations. Controllers and app-layer services that call <code>LoyaltyService</code> and get DTOs back are not on it, because that&rsquo;s the intended way in. The list is often longer than expected. Each entry is either a missing public API or a missing event.</p>
<h2 id="step-2-write-the-context-down-where-the-ai-will-read-it">Step 2: Write the context down where the AI will read it</h2>
<p>Put an <code>AGENTS.md</code> in the Loyalty domain package, <code>com/shop/domain/loyalty/</code>. It&rsquo;s a shared convention: Codex, Cursor, GitHub Copilot, Gemini CLI and other assistants read it when they work in that directory. Keep it short and specific.</p>
<p>Recent versions of Claude Code read <code>AGENTS.md</code> too, but only when the project has no <code>CLAUDE.md</code>. If your repo already has one, Claude skips <code>AGENTS.md</code> by default. Don&rsquo;t copy the rules into a second file, because two copies drift apart. Add a <code>CLAUDE.md</code> next to <code>AGENTS.md</code> that imports it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="ni">@AGENTS</span>.md
</span></span></code></pre></div><p>Now every assistant on the team reads the same rules, and you maintain them in one place.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gh"># Loyalty context
</span></span></span><span class="line"><span class="cl"><span class="gh"></span>Purpose: award and redeem points. Loyalty owns the balance. Nobody else writes it.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Language
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> Points: whole, non-negative amount. Never &#34;credits&#34; or &#34;bonus&#34;.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Earn: add points for a paid order. Redeem: spend points at checkout.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Earning rule: how many points an order is worth (base rate, birthday 2x).
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Invariants
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">1.</span> balance &gt;= 0, always.
</span></span><span class="line"><span class="cl"><span class="k">2.</span> Points are earned only for paid orders. Only com.shop.listener calls earnForPaidOrder().
</span></span><span class="line"><span class="cl"><span class="k">3.</span> Only LoyaltyService changes a LoyaltyAccount. The entity holds data, no logic.
</span></span><span class="line"><span class="cl"><span class="k">4.</span> Every state change publishes an event in the same transaction.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Public API
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> LoyaltyService: balanceOf(CustomerId), redeem(CustomerId, Points),
</span></span><span class="line"><span class="cl">  earnForPaidOrder(...) (listeners only). Returns DTOs, never entities.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Events out: PointsEarned, PointsRedeemed.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Loyalty doesn&#39;t listen to other domains. App-layer listeners call its service.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Forbidden
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> Code outside domain/loyalty using its entity or repository packages.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Loyalty using other domains&#39; entities or repositories. Use their service or events.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Writing loyalty tables from SQL, scripts or admin tools.
</span></span></code></pre></div><p>Two things matter here. The language section gives the AI the words to use in names and commits. The forbidden section names the shortcuts you&rsquo;ve already seen it take.</p>
<p>A real system has more than one context. Don&rsquo;t put them all in one file. Give each domain package its own <code>AGENTS.md</code>, and keep a short context map at the root:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">src/main/java/com/shop/
</span></span><span class="line"><span class="cl">├── AGENTS.md          ← context map: one line per domain + global rules
</span></span><span class="line"><span class="cl">├── controller/        ← REST controllers
</span></span><span class="line"><span class="cl">├── service/           ← use cases that combine several domains
</span></span><span class="line"><span class="cl">├── dto/               ← request/response DTOs for the frontend
</span></span><span class="line"><span class="cl">├── listener/          ← event listeners that connect domains
</span></span><span class="line"><span class="cl">├── common/            ← shared kernel: Money, CustomerId, OrderId
</span></span><span class="line"><span class="cl">└── domain/
</span></span><span class="line"><span class="cl">    ├── loyalty/
</span></span><span class="line"><span class="cl">    │   ├── AGENTS.md  ← Loyalty only
</span></span><span class="line"><span class="cl">    │   ├── service/   ← LoyaltyService: the only entry point
</span></span><span class="line"><span class="cl">    │   ├── dto/       ← what the service returns, plus events
</span></span><span class="line"><span class="cl">    │   ├── entity/    ← LoyaltyAccount (hidden)
</span></span><span class="line"><span class="cl">    │   └── repository/ ← hidden
</span></span><span class="line"><span class="cl">    ├── ordering/      ← same shape, own AGENTS.md
</span></span><span class="line"><span class="cl">    └── customer/      ← same shape, own AGENTS.md
</span></span></code></pre></div><p>The top-level packages are a thin application layer. When the frontend needs a balance plus order details on one page, a top-level service calls <code>LoyaltyService</code> and <code>OrderService</code> and builds the response DTO. When one domain&rsquo;s event should trigger work in another, a listener in <code>listener/</code> connects them. Neither layer ever injects a domain&rsquo;s repository.</p>
<p><img alt="Diagram: the application layer in com.shop contains controller/, service/, dto/ and listener/. Arrows point down into the domains in com.shop.domain: loyalty/, ordering/ and customer/. Each domain has public service/ and dto/ packages and hidden entity/ and repository/ packages. ArchUnit enforces that nothing outside a domain touches its entity/ or repository/, and that no domain depends on the application layer." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-layers.jpg"></p>
<p>The root file says what each domain owns and how others use it: its service or its events. Global rules go here too: domains never depend on the top-level packages, and a domain&rsquo;s service returns DTOs, never entities. Each domain file covers only its own language, invariants and dependencies.</p>
<p>Domains still need some shared language. <code>earnForPaidOrder()</code> takes <code>Money</code>, <code>CustomerId</code> and <code>OrderId</code>, and Ordering uses the same types. These live in <code>common/</code>, which DDD calls a shared kernel: a small set of types every domain may use.</p>
<p>Keep it to immutable value records like these, with validation and no business logic. No entities, services or frontend DTOs belong there. Every team depends on it, so a change to <code>common/</code> needs every team&rsquo;s agreement.</p>
<p>Say this in the root <code>AGENTS.md</code>; without that rule, an assistant will start moving anything that two domains need into <code>common/</code>.</p>
<p>This split matters for three reasons. Assistants load a nested file only when they work in that folder, so a change to Checkout doesn&rsquo;t pull in fifteen other contexts. Each context keeps its own vocabulary, so &ldquo;Account&rdquo; in Loyalty never gets mixed up with &ldquo;Account&rdquo; in Billing. And each team owns its file.</p>
<p>If you use Claude Code and your repo already has a <code>CLAUDE.md</code>, repeat the trick from above in every domain: put a one-line <code>CLAUDE.md</code> with <code>@AGENTS.md</code> next to each domain&rsquo;s <code>AGENTS.md</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">domain/
</span></span><span class="line"><span class="cl">├── loyalty/
</span></span><span class="line"><span class="cl">│   ├── AGENTS.md
</span></span><span class="line"><span class="cl">│   └── CLAUDE.md      ← contains only: @AGENTS.md
</span></span><span class="line"><span class="cl">└── ordering/
</span></span><span class="line"><span class="cl">    ├── AGENTS.md
</span></span><span class="line"><span class="cl">    └── CLAUDE.md      ← contains only: @AGENTS.md
</span></span></code></pre></div><p>It&rsquo;s tempting to import every domain&rsquo;s <code>AGENTS.md</code> from the root <code>CLAUDE.md</code> instead. Don&rsquo;t. Claude Code loads the root file and everything it imports at the start of every session, so every context&rsquo;s rules would be loaded all the time. A <code>CLAUDE.md</code> inside a domain folder is loaded only when Claude works on files in that folder.</p>
<h2 id="step-3-make-the-ai-work-inside-the-context">Step 3: Make the AI work inside the context</h2>
<p>Now rewrite the feature request. Point it at the context and ask it to reason about invariants before it writes code.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Read com/shop/domain/loyalty/AGENTS.md first.
</span></span><span class="line"><span class="cl">Feature: Loyalty awards double points for orders paid on the
</span></span><span class="line"><span class="cl">customer&#39;s birthday.
</span></span><span class="line"><span class="cl">Before writing code:
</span></span><span class="line"><span class="cl">1. Say which bounded context owns this rule and why.
</span></span><span class="line"><span class="cl">2. List every invariant from AGENTS.md this change touches.
</span></span><span class="line"><span class="cl">3. List the classes you plan to change. Flag any outside
</span></span><span class="line"><span class="cl">   domain/loyalty.
</span></span><span class="line"><span class="cl">Wait for my confirmation. Then implement it inside the
</span></span><span class="line"><span class="cl">LoyaltyService with unit tests for each invariant.
</span></span></code></pre></div><p>The &ldquo;wait for confirmation&rdquo; step is where you catch a wrong plan. It costs one message instead of a code review.</p>
<p>The entity only holds data:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">LoyaltyAccount</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.domain.loyalty.entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">MonthDay</span><span class="w"> </span><span class="n">birthday</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Points</span><span class="w"> </span><span class="n">balance</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// getters and setters, no logic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><code>Points</code> is a record that rejects negative values in its constructor, so <code>balance &gt;= 0</code> holds no matter who sets the balance.</p>
<p>The rules live in <code>LoyaltyService</code>. It&rsquo;s the only class that changes a <code>LoyaltyAccount</code>, and every change publishes an event in the same transaction:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">LoyaltyService</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.domain.loyalty.service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyAccountRepository</span><span class="w"> </span><span class="n">accounts</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ApplicationEventPublisher</span><span class="w"> </span><span class="n">events</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// constructor and balanceOf() omitted</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">earnForPaidOrder</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">OrderId</span><span class="w"> </span><span class="n">orderId</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                                 </span><span class="n">Money</span><span class="w"> </span><span class="n">paidAmount</span><span class="p">,</span><span class="w"> </span><span class="n">LocalDate</span><span class="w"> </span><span class="n">paidOn</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">load</span><span class="p">(</span><span class="n">customerId</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Points</span><span class="w"> </span><span class="n">earned</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Points</span><span class="p">.</span><span class="na">forAmount</span><span class="p">(</span><span class="n">paidAmount</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">paidOn</span><span class="p">).</span><span class="na">equals</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBirthday</span><span class="p">()))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">earned</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">earned</span><span class="p">.</span><span class="na">times</span><span class="p">(</span><span class="n">2</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">plus</span><span class="p">(</span><span class="n">earned</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">accounts</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">events</span><span class="p">.</span><span class="na">publishEvent</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PointsEarned</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">orderId</span><span class="p">,</span><span class="w"> </span><span class="n">earned</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="n">PointsDto</span><span class="w"> </span><span class="nf">redeem</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">Points</span><span class="w"> </span><span class="n">points</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">load</span><span class="p">(</span><span class="n">customerId</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">isLessThan</span><span class="p">(</span><span class="n">points</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">throw</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">InsufficientPointsException</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">points</span><span class="p">,</span><span class="w"> </span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">minus</span><span class="p">(</span><span class="n">points</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">accounts</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">events</span><span class="p">.</span><span class="na">publishEvent</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PointsRedeemed</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">points</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">PointsDto</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="nf">load</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">accounts</span><span class="p">.</span><span class="na">findByCustomerId</span><span class="p">(</span><span class="n">customerId</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">.</span><span class="na">orElseThrow</span><span class="p">(()</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">LoyaltyAccountNotFoundException</span><span class="p">(</span><span class="n">customerId</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The setters are public, so in principle anyone could call them. Two things stop that: the entity package is closed to code outside Loyalty, and inside Loyalty only <code>LoyaltyService</code> may call the setters. Step 5 turns both into tests.</p>
<p>The balance change and the event are in one transaction. Listeners annotated with <code>@TransactionalEventListener</code> run only after that transaction commits, so a rolled-back change never sends an event.</p>
<p>Neither domain knows about the other. Ordering publishes <code>OrderPaid</code> without knowing who listens. Loyalty exposes <code>earnForPaidOrder()</code> without knowing where paid orders come from. The rule that links them, &ldquo;a paid order earns points&rdquo;, lives in the application layer, in a listener that combines the two domains. It translates the event into a call and does nothing else:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Component</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">OrderPaidListener</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.listener</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyService</span><span class="w"> </span><span class="n">loyalty</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OrderPaidListener</span><span class="p">(</span><span class="n">LoyaltyService</span><span class="w"> </span><span class="n">loyalty</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">this</span><span class="p">.</span><span class="na">loyalty</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">loyalty</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@TransactionalEventListener</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="p">(</span><span class="n">propagation</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Propagation</span><span class="p">.</span><span class="na">REQUIRES_NEW</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">void</span><span class="w"> </span><span class="nf">on</span><span class="p">(</span><span class="n">OrderPaid</span><span class="w"> </span><span class="n">event</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">loyalty</span><span class="p">.</span><span class="na">earnForPaidOrder</span><span class="p">(</span><span class="n">event</span><span class="p">.</span><span class="na">customerId</span><span class="p">(),</span><span class="w"> </span><span class="n">event</span><span class="p">.</span><span class="na">orderId</span><span class="p">(),</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="n">event</span><span class="p">.</span><span class="na">amount</span><span class="p">(),</span><span class="w"> </span><span class="n">event</span><span class="p">.</span><span class="na">paidOn</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Checkout doesn&rsquo;t know Loyalty exists. A failed payment never produces <code>OrderPaid</code>, so it never produces points.</p>
<p><img alt="Diagram: OrderService in Ordering commits a successful payment and publishes OrderPaid after commit. OrderPaidListener in com.shop.listener receives it and calls LoyaltyService, which loads the account, doubles the points on the customer&rsquo;s birthday, updates the balance, saves, and publishes PointsEarned to email and analytics. A failed payment rolls back, so there is no OrderPaid and no points." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-event-flow.jpg"></p>
<p><code>earnForPaidOrder()</code> has to be public so the listener can call it. That also means a controller could call it and award points without a paid order. Step 5 closes that gap with a test.</p>
<h2 id="step-4-review-in-a-fresh-session">Step 4: Review in a fresh session</h2>
<p>Don&rsquo;t ask the session that wrote the code to review it. It has the same blind spots it had five minutes ago. Open a new session, give it the rules and the diff, and nothing else.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">You are reviewing a change to the Loyalty bounded context.
</span></span><span class="line"><span class="cl">Read com/shop/domain/loyalty/AGENTS.md, then run: git diff main...HEAD
</span></span><span class="line"><span class="cl">For each invariant and each &#34;Forbidden&#34; rule in AGENTS.md,
</span></span><span class="line"><span class="cl">answer: kept, broken, or not affected. For &#34;broken&#34;, quote the
</span></span><span class="line"><span class="cl">line. Then list any new terms in names or comments that are not
</span></span><span class="line"><span class="cl">in the Language section. Do not comment on style.
</span></span></code></pre></div><p>A reviewer with a checklist finds more than a reviewer with a vibe. That&rsquo;s true for people and for models.</p>
<h2 id="step-5-enforce-the-boundary-with-tests">Step 5: Enforce the boundary with tests</h2>
<p>Everything so far makes a good outcome more likely. None of it makes a bad outcome impossible. The next prompt, the next model or the next tired developer can still call <code>loyaltyAccountRepository</code> from checkout.</p>
<p><img alt="Diagram: five steps rising like stairs. Steps 1 to 4 are prompts, which are suggestions: Discover (glossary and leak list), Write it down (AGENTS.md per domain), Plan first (invariants before code), Fresh review (checklist from AGENTS.md). Step 5, Enforce (ArchUnit tests in the build), is the only guarantee. An arrow runs from &ldquo;a good outcome is more likely&rdquo; to &ldquo;a bad outcome fails the build&rdquo;." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-guardrails.jpg"></p>
<p>Prompts are suggestions, tests are guarantees. Turn the forbidden section of <code>AGENTS.md</code> into ArchUnit rules:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@AnalyzeClasses</span><span class="p">(</span><span class="n">packages</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;com.shop&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">importOptions</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ImportOption</span><span class="p">.</span><span class="na">DoNotIncludeTests</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">LoyaltyBoundaryTest</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">internalsStayInside</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">classes</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">resideInAnyPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty.entity..&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.domain.loyalty.repository..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeAccessed</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: use LoyaltyService&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">onlyServiceChangesAccount</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">methods</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">areDeclaredIn</span><span class="p">(</span><span class="n">LoyaltyAccount</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">and</span><span class="p">().</span><span class="na">haveNameMatching</span><span class="p">(</span><span class="s">&#34;set[A-Z].*&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeCalled</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty.service..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: invariant 3&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">onlyListenersEarnPoints</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">methods</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">areDeclaredIn</span><span class="p">(</span><span class="n">LoyaltyService</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">and</span><span class="p">().</span><span class="na">haveName</span><span class="p">(</span><span class="s">&#34;earnForPaidOrder&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeCalled</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.listener..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: invariant 2&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">domainsDoNotDependOnAppLayer</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">noClasses</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">dependOnClassesThat</span><span class="p">().</span><span class="na">resideInAnyPackage</span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.controller..&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;com.shop.service..&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.dto..&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;com.shop.listener..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;dependencies point one way: app layer -&gt; domain&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>(<code>classes</code>, <code>noClasses</code> and <code>methods</code> are static imports from <code>ArchRuleDefinition</code>.)</p>
<p>The <code>because()</code> text points back to <code>AGENTS.md</code>. When the AI breaks a rule, the failing build tells it which rule and where it&rsquo;s written. Most assistants will read that and fix the code on their own.</p>
<h2 id="takeaways">Takeaways</h2>
<ul>
<li>Treat the AI as a new team. It needs onboarding, not more detailed tickets.</li>
<li>Use the AI to discover the domain before you ask it to change it. The glossary and the leak list are useful even without AI.</li>
<li>Keep <code>AGENTS.md</code> next to the code it describes: language, invariants, public API, forbidden dependencies.</li>
<li>Ask for affected invariants before code, and review in a fresh session against the written rules.</li>
<li>Every rule you care about should end up as a test. Prompts are suggestions, tests are guarantees.</li>
</ul>
]]></content:encoded></item><item><title>Building an MCP Server in Java with Spring AI: Let Claude Code Use Your Database Without Seeing a Password</title><link>https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/</link><pubDate>Fri, 25 Sep 2026 14:46:28 +0000</pubDate><guid>https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/</guid><description>&lt;p>&lt;em>Four annotated methods, one security config, and no JSON-RPC code of your own.&lt;/em>&lt;/p>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-01.png">&lt;/p>
&lt;p>In my &lt;a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">previous article&lt;/a> I built an MCP server from scratch in Python. I wrote the JSON-RPC 2.0 message handling, declared tool schemas by hand and wired up the STDIO transport myself. It’s a good way to learn how the protocol works on the wire.&lt;/p>
&lt;p>Python isn’t the only option, though. Most of the systems I work on are Java and Spring, and that’s where the data lives. So this time I built the same kind of server in Java.&lt;/p></description><content:encoded><![CDATA[<p><em>Four annotated methods, one security config, and no JSON-RPC code of your own.</em></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-01.png"></p>
<p>In my <a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">previous article</a> I built an MCP server from scratch in Python. I wrote the JSON-RPC 2.0 message handling, declared tool schemas by hand and wired up the STDIO transport myself. It’s a good way to learn how the protocol works on the wire.</p>
<p>Python isn’t the only option, though. Most of the systems I work on are Java and Spring, and that’s where the data lives. So this time I built the same kind of server in Java.</p>
<p>It turns out you don’t need to implement JSON-RPC yourself. Spring AI has a Boot starter for MCP servers. It handles the protocol, the transport, schema generation and tool registration. You write ordinary Spring beans and add a few annotations.</p>
<p>The full code is on GitHub: <a href="https://github.com/SukachVitally/mcp-demo">SukachVitally/mcp-demo</a>.</p>
<h3 id="why-bother-the-server-is-theboundary">Why bother: the server is the boundary</h3>
<p>The business logic here is deliberately boring. It’s a task list: you create tasks, move them through statuses, and finish or cancel them. Swap in your own domain; the MCP part stays the same.</p>
<p>The point is how Claude Code reaches the data:</p>
<pre tabindex="0"><code>Claude Code ──HTTP + API key──▶ MCP server (Spring) ──JDBC──▶ PostgreSQL
</code></pre><ul>
<li><strong>Claude never sees database credentials.</strong> The server holds the connection. Claude holds only an API key that works for the MCP endpoint and nothing else.</li>
<li><strong>Claude can only do what you expose.</strong> There’s no SQL console. If you don’t write a delete_task tool, tasks can&rsquo;t be deleted, however the prompt is phrased.</li>
<li><strong>Your validation and transactions still apply.</strong> Every call goes through the same service layer as the rest of your application.</li>
</ul>
<p>Giving an agent a database URL and a password is quick, but you can’t take it back. An MCP server gives the agent a small, typed and auditable API instead.</p>
<h3 id="what-werebuilding">What we’re building</h3>
<p>A PostgreSQL table of tasks. Each task has a name and one of four statuses: NEW, IN_PROGRESS, DONE or CANCELLED. The server exposes four tools:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-02.png"></p>
<p>Stack: Java 25, Spring Boot 4, Spring AI 2.0 MCP server, PostgreSQL 18 with Liquibase, and Spring Security.</p>
<h3 id="step-1-dependencies">Step 1: Dependencies</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/build.gradle"><em>build.gradle</em></a></p>
<pre tabindex="0"><code>dependencies {
    implementation &#39;org.springframework.boot:spring-boot-starter-data-jpa&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-liquibase&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-webmvc&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-security&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-validation&#39;
    implementation platform(&#39;org.springframework.ai:spring-ai-bom:2.0.1&#39;)
    implementation &#39;org.springframework.ai:spring-ai-starter-mcp-server-webmvc&#39;
    implementation &#39;org.springaicommunity:mcp-server-security-spring-boot:0.1.14&#39;
    runtimeOnly &#39;org.postgresql:postgresql&#39;
}
</code></pre><p>Two lines do the MCP work:</p>
<ul>
<li>spring-ai-starter-mcp-server-webmvc is the MCP server over HTTP on Spring MVC. There&rsquo;s a -webflux variant for reactive apps, and a plain spring-ai-starter-mcp-server for stdio.</li>
<li>mcp-server-security-spring-boot from the <a href="https://github.com/spring-ai-community/mcp-security">spring-ai-community/mcp-security</a> project adds API-key and OAuth2 support on top of Spring Security. We&rsquo;ll come back to it.</li>
</ul>
<h3 id="step-2-configure-theserver">Step 2: Configure the server</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/resources/application.yaml"><em>application.yaml</em></a></p>
<pre tabindex="0"><code>spring:
  ai:
    mcp:
      server:
        protocol: STATELESS
        type: sync
        name: &#34;Task MCP demo&#34;
        instructions: &gt;-
          Manages a simple task list. Create tasks with add_task, look them up with get_task or
          get_task_list, and move them through the statuses NEW, IN_PROGRESS, DONE and CANCELLED
          with update_task_status.
        streamable-http:
          mcp-endpoint: /mcp
</code></pre><p>What these settings mean:</p>
<ul>
<li><strong>protocol: STATELESS</strong>: plain HTTP request and response, with no session kept between calls. Our tools never need to push anything back to the client, so we don&rsquo;t need sessions, and the server scales horizontally like any other REST service. Use STREAMABLE if you need server-to-client messages. The older SSE option is deprecated since Spring AI 2.0.</li>
<li><strong>type: sync</strong>: tools are ordinary blocking methods. With async, they return Reactor Mono/Flux types instead.</li>
<li><strong>instructions</strong>: sent to the client when it connects. It&rsquo;s the server&rsquo;s short explanation to the model of how the tools fit together. Treat it as part of the prompt.</li>
<li><strong>mcp-endpoint: /mcp</strong>: the URL that Claude Code will call.</li>
</ul>
<h3 id="step-3-business-logic-keep-itboring">Step 3: Business logic (keep it boring)</h3>
<p>Nothing here knows about MCP. It’s a normal JPA entity, repository and service:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/service/TaskService.java"><em>TaskService.java</em></a></p>
<pre tabindex="0"><code>@Service
@Validated
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class TaskService {
    public static final int NAME_MAX_LEN
GTH = 255;
    private final TaskRepository repository;
    private final TaskMapper mapper;
    @Transactional
    public TaskDto create(@NotBlank @Size(max = NAME_MAX_LENGTH) String name) {
        var entity = new TaskEntity();
        entity.setName(name);
        entity.setStatus(TaskStatus.NEW);
        return mapper.toDto(repository.save(entity));
    }
    @Transactional
    public TaskDto updateStatus(Long id, @NotNull TaskStatus status) {
        var entity = findEntity(id);
        entity.setStatus(status);
        return mapper.toDto(entity);
    }
    // get(id), getList(), findEntity(id) throws TaskNotFoundException ...
}
</code></pre><p>The service returns a small record, not the entity:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/dto/TaskDto.java"><em>TaskDto.java</em></a></p>
<pre tabindex="0"><code>public record TaskDto(Long id, String name, TaskStatus status) {}
</code></pre><p>That matters more than it looks. Whatever a tool returns is serialized and handed to the model, so the DTO decides exactly which fields leave your system.</p>
<h3 id="step-4-taskmcptool-the-actual-mcpserver">Step 4: TaskMcpTool, the actual MCP server</h3>
<p>This is the whole MCP layer:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/mcp/TaskMcpTool.java"><em>TaskMcpTool.java</em></a></p>
<pre tabindex="0"><code>@Component
@RequiredArgsConstructor
public class TaskMcpTool {
    private final TaskService service;
    @McpTool(name = &#34;add_task&#34;, description = &#34;Create a new task with status NEW and return it&#34;)
    public TaskDto add(@McpToolParam(description = &#34;Task name, 1-255 characters&#34;) String name) {
        return service.create(name);
    }
    @McpTool(name = &#34;get_task&#34;, description = &#34;Get a task by its id. Fails if the task does not exist&#34;)
    public TaskDto get(@McpToolParam(description = &#34;Task id&#34;) Long id) {
        return service.get(id);
    }
    @McpTool(name = &#34;update_task_status&#34;,
            description = &#34;Change the status of a task and return the updated task. Fails if the task does not exist&#34;)
    public TaskDto updateStatus(@McpToolParam(description = &#34;Task id&#34;) Long id,
                                @McpToolParam(description = &#34;New task status&#34;) TaskStatus status) {
        return service.updateStatus(id, status);
    }
    @McpTool(name = &#34;get_task_list&#34;, description = &#34;List all tasks&#34;)
    public List&lt;TaskDto&gt; getList() {
        return service.getList();
    }
}
</code></pre><p>Only a thin adapter: each method delegates to the service. Most of the work happens in the annotations.</p>
<h3 id="how-the-tools-get-registered">How the tools get registered</h3>
<p>The class is a plain @Component. When the application starts, Spring AI&rsquo;s annotation scanner finds every bean method annotated with @McpTool and registers it as an MCP tool. You don&rsquo;t need a registry, a ToolCallback list or any manual wiring. To add a tool, write another annotated method.</p>
<h3 id="mcptool-the-name-and-description-the-modelsees">@McpTool: the name and description the model sees</h3>
<ul>
<li><strong>name</strong> is the tool id the model calls. I use snake_case verbs (add_task, get_task_list) because that&rsquo;s the convention across MCP servers, and models pick such names up reliably. Without a name, the Java method name is used, and add on its own tells the model very little.</li>
<li><strong>description</strong> is the most important string in the class. It&rsquo;s the only thing the model reads when deciding which tool to call and what to expect back. Say what the tool does, what it returns and when it fails (&ldquo;Fails if the task does not exist&rdquo;). A vague description gives you a model that guesses.</li>
</ul>
<h3 id="mcptoolparam-the-schema-is-generated-foryou">@McpToolParam: the schema is generated for you</h3>
<p>Each parameter gets a description, and Spring AI builds a JSON Schema from the Java type. Here’s what the server actually returns for update_task_status when Claude Code asks for tools/list:</p>
<pre tabindex="0"><code>{
  &#34;name&#34;: &#34;update_task_status&#34;,
  &#34;description&#34;: &#34;Change the status of a task and return the updated task. Fails if the task does not exist&#34;,
  &#34;inputSchema&#34;: {
    &#34;type&#34;: &#34;object&#34;,
    &#34;properties&#34;: {
      &#34;id&#34;:     { &#34;type&#34;: &#34;integer&#34;, &#34;format&#34;: &#34;int64&#34;, &#34;description&#34;: &#34;Task id&#34; },
      &#34;status&#34;: { &#34;type&#34;: &#34;string&#34;,
                  &#34;enum&#34;: [&#34;NEW&#34;, &#34;IN_PROGRESS&#34;, &#34;DONE&#34;, &#34;CANCELLED&#34;],
                  &#34;description&#34;: &#34;New task status&#34; }
    },
    &#34;required&#34;: [&#34;id&#34;, &#34;status&#34;]
  }
}
</code></pre><p>Things to notice:</p>
<ul>
<li><strong>Long became</strong> <strong>integer with</strong> <strong>int64 format.</strong> You don&rsquo;t write any schema by hand.</li>
<li><strong>Parameters are required by default</strong> (required = true). Set @McpToolParam(required = false) for optional ones.</li>
<li><strong>The</strong> <strong>TaskStatus enum became a JSON</strong> <strong>enum.</strong> The model sees the four allowed values up front, so it can&rsquo;t invent a status like DELETED. If it tries, the call is rejected by schema validation before your method runs:</li>
</ul>
<pre tabindex="0"><code>Tool (update_task_status) input validation failed: ... /status: does not 
have a value in the enumeration [&#34;NEW&#34;, &#34;IN_PROGRESS&#34;, &#34;DONE&#34;, &#34;CANCELLED&#34;]
</code></pre><p>Use enums for anything with a fixed set of values. You get validation and documentation in one place.</p>
<h3 id="return-values-anderrors">Return values and errors</h3>
<p>You return a normal Java object, and Spring AI serializes it to JSON as the tool result. <code>TaskDto</code> and <code>List&lt;TaskDto&gt;</code> just work.</p>
<p>Exceptions work too. When TaskService throws TaskNotFoundException, the client doesn&rsquo;t get a stack trace or a broken JSON-RPC response. It gets a tool result with isError: true and the exception message as the text:</p>
<pre tabindex="0"><code>{ 
  &#34;content&#34;: [{ &#34;type&#34;: &#34;text&#34;, &#34;text&#34;: &#34;Task with id -1 is not found&#34; }], 
  &#34;isError&#34;: true 
}
</code></pre><p>That’s the behaviour you want: the model reads the message, understands what went wrong and can recover, for example by calling get_task_list to find the right id. Write exception messages for the model to read, not just for your logs.</p>
<p>The same applies to Bean Validation. A blank name fails @NotBlank in the service and comes back to the model as an error result, not a 500.</p>
<h3 id="a-tip-add-behaviour-hints">A tip: add behaviour hints</h3>
<p>If you look at the full tools/list response, every tool reports &ldquo;readOnlyHint&rdquo;: false, &ldquo;destructiveHint&rdquo;: true, including get_task_list. Those are the defaults. Clients such as Claude Code can use these hints to decide how cautious to be, so it&rsquo;s worth being honest about read-only tools:</p>
<pre tabindex="0"><code>@McpTool(name = &#34;get_task_list&#34;, description = &#34;List all tasks&#34;,
        annotations = @McpTool.McpAnnotations(readOnlyHint = true, 
                                              destructiveHint = false))
</code></pre><p>These are hints, not enforcement. What actually protects your data is the fact that the tool only reads.</p>
<h3 id="step-5-securityconfig-briefly">Step 5: SecurityConfig, briefly</h3>
<p>By default, an HTTP MCP endpoint is an unauthenticated JSON-RPC endpoint. Anyone who can reach /mcp can call your tools. The mcp-security library closes it with a few lines:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/config/SecurityConfig.java"><em>SecurityConfig.java</em></a></p>
<pre tabindex="0"><code>@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http,
                                            ApiKeyEntityRepository&lt;ApiKeyEntityImpl&gt; apiKeyRepository) {
        return http
                .authorizeHttpRequests(auth -&gt; auth.anyRequest().authenticated())
                .with(mcpServerApiKey(), apiKey -&gt; apiKey.apiKeyRepository(apiKeyRepository))
                .build();
    }
    @Bean
    ApiKeyEntityRepository&lt;ApiKeyEntityImpl&gt; apiKeyRepository(@Value(&#34;${app.mcp.api-key.secret}&#34;) String secret) {
        var key = ApiKeyEntityImpl.builder()
                .name(&#34;demo key&#34;)
                .id(&#34;demo&#34;)
                .secret(secret)
                .build();
        return new InMemoryApiKeyEntityRepository&lt;&gt;(List.of(key));
    }
}
</code></pre><ul>
<li>mcpServerApiKey() plugs API-key authentication into the normal Spring Security filter chain.</li>
<li>The client sends an X-API-key header in the form <code>&lt;id&gt;.&lt;secret&gt;</code>, so <code>demo.&lt;your secret&gt;</code> here. Requests without it get 401.</li>
</ul>
<h3 id="step-6-run-it-and-connect-claudecode">Step 6: Run it and connect Claude Code</h3>
<p>Start PostgreSQL and the app:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/docker-compose.yaml"><em>docker-compose.yaml</em></a><em>,</em><a href="https://github.com/SukachVitally/mcp-demo/blob/main/.env.tpl"><em>.env.tpl</em></a><em>,</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/README.md"><em>README</em></a></p>
<pre tabindex="0"><code>cp .env.tpl .env          # sets MCP_API_KEY_SECRET
docker compose up -d
./gradlew bootRun
</code></pre><p>Register the server with Claude Code:</p>
<pre tabindex="0"><code>claude mcp add --transport http todos http://localhost:8080/mcp \
  --header &#34;X-API-key: demo.mcp-demo-test-secret&#34;
</code></pre><p>Then ask in plain language:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-03.png"></p>
<p>“Add todo with name test” becomes an add_task call. &ldquo;Update task with id 1 to DONE&rdquo; becomes update_task_status with a valid enum value. Claude never saw a JDBC URL, a username or a password.</p>
<p>To inspect the server without Claude, use the MCP Inspector (npx @modelcontextprotocol/inspector). Choose the Streamable HTTP transport and add the same header.</p>
<h3 id="testing">Testing</h3>
<p>Because the server speaks standard MCP, the tests can use the official Java MCP client against a real server started by @SpringBootTest, with PostgreSQL in Testcontainers:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/test/java/org/example/mcpdemo/mcp/TaskMcpToolTest.java"><em>TaskMcpToolTest.java</em></a></p>
<pre tabindex="0"><code>var transport = HttpClientStreamableHttpTransport
        .builder(&#34;http://localhost:&#34; + port)
        .httpRequestCustomizer((builder, method, endpoint, body, context) -&gt;
                builder.header(&#34;X-API-key&#34;, &#34;demo.&#34; + API_KEY_SECRET))
        .build();
client = McpClient.sync(transport).build();
client.initialize();
var result = client.callTool(McpSchema.CallToolRequest.builder(&#34;get_task&#34;)
        .arguments(Map.of(&#34;id&#34;, -1L)).build());
assertThat(result.isError()).isTrue();
</code></pre><p>This covers the whole chain in one test: authentication, schema, serialization, error mapping and the database.</p>
<h3 id="takeaways">Takeaways</h3>
<ul>
<li><strong>You don’t write JSON-RPC in Java.</strong> spring-ai-starter-mcp-server-webmvc handles the protocol, the transport and tool discovery.</li>
<li><strong>An MCP tool is an annotated Spring bean method.</strong> @McpTool names and describes it, and @McpToolParam describes its inputs. The JSON Schema is generated from your Java types.</li>
<li><strong>Descriptions and error messages are prompts.</strong> The model reads them, so write them for the model.</li>
<li><strong>Use enums and DTOs</strong> to control what the model can send in and what it gets back.</li>
<li><strong>Secure the endpoint.</strong> API keys via mcp-security take ten lines, and OAuth2 is available when you need it.</li>
<li><strong>The MCP server is the security boundary.</strong> Claude Code works with your data through the operations you choose, never with your credentials.</li>
</ul>
<p>The Python version showed how MCP works on the wire. The Spring version shows how little code you need once a framework handles it. Take the repo, replace tasks with your own domain, and give your agent an API instead of a password.</p>
<p><strong>Links</strong></p>
<ul>
<li>Demo code: <a href="https://github.com/SukachVitally/mcp-demo">github.com/SukachVitally/mcp-demo</a></li>
<li>Spring AI MCP Server Boot Starter: <a href="https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html">docs.spring.io</a></li>
<li>MCP security for Spring: <a href="https://github.com/spring-ai-community/mcp-security/tree/main">github.com/spring-ai-community/mcp-security</a></li>
<li>Previous article, MCP in Python from scratch: <a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">MCP: The Protocol That Finally Taught AI to Stop Being Useless</a></li>
</ul>
]]></content:encoded></item></channel></rss>