Every core banking system you've worked on had exactly one client that mattered: your own front end, built by people who sat two desks away and could be pulled into a Slack thread when something looked wrong. Banking-as-a-Service inverts that. Now the client is a fintech program manager you've never met, integrating against your API on their own timeline, and the thing standing between their bug and your bank's balance sheet is whatever isolation you actually built — not whatever you assumed. This one's for the backend engineer being asked to open the core up. 

Embedded finance sounds like a product decision — a bank licenses its charter and infrastructure so a non-bank brand can offer cards, accounts, or payments under its own name. What it actually is, underneath the partnership deck, is a systems design problem: your ledger, your KYC pipeline, and your reconciliation process all need to serve multiple tenants who don't work for you, don't share your incident channel, and in some architectures don't even have direct visibility into whether their own numbers are correct. Get that architecture right and BaaS is a genuinely good distribution model. Get it wrong and you've built the exact shape of failure that took down one of the industry's largest middleware providers in 2024. 

The failure mode is a ledger problem before it's ever an API problem 

Synapse's collapse is worth understanding in technical terms, not just as a cautionary headline, because the root cause was architectural. Synapse operated as middleware between fintech apps and several partner banks, using "for benefit of" (FBO) omnibus accounts — one pooled account at the bank, holding funds for potentially thousands of end users, with Synapse's own systems tracking who owned what share of the pool. That per-user detail is what's sometimes called a shadow ledger: a secondary set of balances, held outside the bank's core, that the bank itself never directly reconciled against on any meaningful cadence. When Synapse failed, its partner banks lost access to Synapse's records and, with them, the only detailed account of which end user owned which slice of the pooled funds. The result was a reported $65–95 million shortfall between what the banks held and what was actually owed to end users, money that wasn't provably missing so much as unprovable, because no single system of record had ever been required to agree with the others in real time. 

The lesson isn't "don't use middleware". It's that a sub-ledger only deserves the name if it can reconcile back to the core ledger on demand. One assessment of multi-product ledger design puts it bluntly: a sub-ledger that can't reconcile back to the core on demand isn't a sub-ledger, it's a second source of truth, and a second source of truth is exactly what a regulated bank can't afford to discover it has, especially under stress, especially during a partner's bankruptcy, when "on demand" becomes "immediately, under a court's questioning." Any BaaS architecture where the bank's core isn't verifiably the reconciled system of record for every tenant's end-user balance is running the same risk Synapse's partner banks were running, just at whatever scale hasn't failed yet. 

Regulators have already drawn this conclusion. The OCC, Federal Reserve, and FDIC jointly issued a request for information in mid-2024 on bank-fintech arrangements specifically, following a wave of enforcement actions against banks whose fintech partnerships had outrun their risk management — the direction of travel is toward expecting banks to maintain their own verifiable records and direct oversight of end-user funds, not to rely on a partner's assurances that its books are correct. Building the ledger architecture to satisfy that expectation isn't a compliance checkbox layered on afterward. It's the schema design decision you make in week one. 

Tenant isolation: pick the failure mode you can live with 

Multi-tenant architecture has three broad shapes, and the tradeoff between them is really a tradeoff in blast radius. A standalone, single-tenant deployment per program gives the strongest isolation — one tenant's bug, load spike, or breach genuinely cannot touch another's data, because there's no shared infrastructure to leak across — at the highest operational and infrastructure cost. A database-per-tenant model keeps a single application layer but gives each tenant its own database, which is the pattern most SaaS platforms converge on as the practical balance: strong isolation, and a single-tenant restore or migration that can't accidentally touch anyone else's data. A pooled, shared-schema model with a tenant-discriminator column scales to the most tenants most cheaply, and it's also the pattern with the lowest isolation — a missing WHERE tenant_id = ? clause, a bug in the row-level filter, or a noisy tenant's query load is now everyone's problem. 

For anything touching customer funds — which, in a BaaS platform, is the entire point — the pooled discriminator model shouldn't be the default, and it's worth being explicit about why: the cost of the isolation failure is categorically different from a typical SaaS data leak. A cross-tenant bug in a project management tool shows the wrong task list to the wrong customer. A cross-tenant bug in a ledger shows the wrong balance, or worse, lets one program's transaction post against another program's funds. Schema-per-tenant or database-per-tenant should be the floor for ledger and account data specifically, even if lighter-weight shared infrastructure is acceptable for genuinely tenant-agnostic services like a public rates API. 

Hibernate ships native support for exactly this decision, through its MultiTenancyStrategy options — SCHEMA and DATABASE give you a real, separately-connected schema or database per tenant, resolved per request through a CurrentTenantIdentifierResolver; DISCRIMINATOR is the shared-schema, tenant-ID-column approach, and it's the one that depends entirely on every query, every JPA repository method, and every raw SQL statement correctly applying the tenant filter with no exceptions, forever, across every engineer who ever touches the codebase. That's not a criticism of the discriminator pattern in general — it's a real, legitimate architecture for the right workload — but for a ledger table, the failure mode of "someone shipped a query without the filter" is the kind of bug you want architecturally impossible, not merely code-reviewed against: 

public class TenantIdentifierResolver implements CurrentTenantIdentifierResolver<String> { 

    public String resolveCurrentTenantIdentifier() { 

        String tenantId = TenantContext.getCurrentTenant(); 

            throw new IllegalStateException( 

                "No tenant context set — refusing to resolve a default schema"); 

The line that matters most in that snippet isn't the resolver logic — it's the refusal to fall back to a default. A multi-tenant system that silently defaults to some tenant when the context is missing is a system that will eventually post one program's transaction into another program's schema during exactly the kind of request-scoped bug that's otherwise harmless in a single-tenant app. 

API design: the confused-deputy problem, again, with real money attached 

A BaaS API's tenants aren't just data boundaries, they're credential boundaries, and the same failure pattern that shows up in tool-server design shows up here: a shared, broadly-scoped service credential used across every partner integration means a bug or a compromised partner integration can act with the platform's full privilege instead of that one tenant's. Every program-level API key needs to be scoped narrowly to that program's own accounts and actions, validated on every request against the tenant context resolved from the credential itself — not from a parameter the caller supplies and the server trusts. If a request can specify which tenant's ledger to post against, rather than that being derived entirely from the authenticated caller's identity, you've built a confused deputy into the API surface, and it's only a matter of time before a client's bug or a malicious actor discovers it. 

Idempotency deserves the same weight it gets in any payment API, for the same reason: a partner integration retrying a failed account-opening or transfer call after a timeout has to be safe to retry, which means every mutating endpoint needs to accept and honor a client-supplied idempotency key, returning the original result on a repeat rather than executing the operation twice. And because BaaS partners build their own products against your webhooks — a card authorization, a KYC status change, a settlement completing — those webhooks need per-tenant signing secrets and replay protection, exactly because a fintech partner's own security posture isn't something you control, and a leaked webhook secret for one tenant shouldn't let anyone forge events for another. 

Rate limiting is the last piece, and it's worth framing the same way a bulkhead is framed in any resilience design: without a per-tenant cap, one partner's traffic spike — a marketing campaign that goes better than they expected, or a bug in their retry logic — degrades the API for every other partner sharing the same infrastructure. Isolating rate limits per program, not just globally, is what keeps one tenant's bad day from becoming every tenant's incident. 

Reconciliation is the product, not the afterthought 

Everything above is what keeps the ledger correct in the steady state. What actually would have caught Synapse-shaped drift early is treating reconciliation between the core ledger and any tenant-facing balance as a monitored, alerting system in its own right — not a nightly batch job whose failures get triaged whenever someone notices the report didn't run. Daily reconciliation is the documented minimum in most guidance on this; event-driven reconciliation, checking that every tenant-facing balance change has a matching, correctly-attributed core ledger entry within minutes rather than hours, is what actually catches drift while it's still a rounding error instead of a court filing. A reconciliation break should page someone the same way a failed payment does, because functionally, it's an early warning for the exact failure that turned a single middleware provider's mistake into a multi-bank, tens-of-millions-of-dollars mess that regulators are still writing guidance in response to. 

We've built ledger and account infrastructure for banks long before "embedded finance" was the term for it, and the discipline underneath a good BaaS platform isn't new — it's the same core-banking rigor around reconciliation, audit trails, and system-of-record integrity that regulated banking has always required, applied now to an API surface with tenants you don't manage instead of a front end your own team built. The architecture question was never really "how do we expose our infrastructure to partners." It was "how do we expose our infrastructure to partners without ever losing the ability to prove, on demand, whose money is whose." 

Embedded Finance and Banking-as-a-Service

Banking-as-a-Service turns your ledger into a multi-tenant system with partners you don't control. Here's the tenant isolation, API design, and reconciliation architecture that keeps it from becoming the next Synapse. 

Banking-as-a-Service turns your ledger into a multi-tenant system; tenant isolation, API design, and reconciliation architecture. 

The Technical Architecture Behind White-Label Banking 

Every Resilience4j tutorial demos the same failure: the downstream returns a clean 500, the circuit trips, everyone claps. That's not the incident that pages you at 2am. The one that does is the payment gateway that doesn't go down — it goes slow, 8 seconds instead of 200 milliseconds, still technically returning 200s, right up until your own connection pool is empty and it's your service that's down, not theirs. This one's for the backend engineer who's configured @Retry and @CircuitBreaker and assumed that was the hard part done. 

A payment gateway integration that only had to survive clean failures wouldn't need much resilience engineering — catch the exception, retry once, move on. What it actually has to survive is degradation: elevated latency, intermittent timeouts, a backend that's still accepting requests but taking four times as long to answer them. That's the case the annotation-level tutorials skip, and it's the case that turns a third party's bad afternoon into your own outage if the defaults are left as they are. 

The retry storm is the part your own retries cause 

Microsoft's Azure Architecture Center has a name for the specific failure this produces: the retry storm antipattern. The mechanism is simple and it's exactly what an unbounded or naive retry policy produces — a downstream service becomes slow or partially unavailable, clients retry, the flood of retries adds load to a service that was already struggling, recovery gets actively prevented rather than assisted, and the failure cascades outward instead of staying contained. The antipattern isn't retrying — it's retrying without a cap on attempts, without backoff, without jitter, and without anything watching the aggregate picture across all your callers at once. 

For a payment gateway specifically, the cascade has a second stage that's easy to miss until it's happened once: your own thread pool and HTTP connection pool are shared resources. A gateway call that hangs for 8 seconds instead of failing fast doesn't just make that one request slow — it holds a connection and a thread for 8 seconds that an unrelated request, one that has nothing to do with payments, might also be waiting on. Enough slow gateway calls piling up and your service isn't degraded because the gateway is degraded. It's degraded because you ran out of threads, and the gateway's problem became every endpoint's problem. That's the actual shape of "cascading into a full outage" — not a single dramatic failure, but resource exhaustion accumulating quietly until something unrelated tips over. 

A circuit breaker tuned for slow, not just down 

The default Resilience4j circuit breaker configuration will catch a gateway that returns errors. It won't catch one that's just slow, unless you explicitly tell it to — and "slow but technically successful" is the more common failure mode against a real payment gateway than a clean outage. CircuitBreakerConfig exposes slowCallDurationThreshold and slowCallRateThreshold specifically for this: calls that take longer than the duration threshold count as slow calls, and if the proportion of slow calls crosses the rate threshold, the circuit opens — independently of whether those calls technically succeeded. 

      slidingWindowSize: 60          # evaluate the last 60 seconds of calls 

      minimumNumberOfCalls: 20       # don't judge on a handful of requests 

      failureRateThreshold: 50       # open if ≥50% of calls fail outright 

      slowCallDurationThreshold: 2s  # anything over 2s counts as "slow" 

      slowCallRateThreshold: 50      # open if ≥50% of calls are slow 

      permittedNumberOfCallsInHalfOpenState: 5 

TIME_BASED over COUNT_BASED matters here specifically because gateway call volume isn't constant — a count-based window sized for peak traffic will take far too long to react during a quiet period, and one sized for quiet periods will trip on normal peak-hour variance. A time-based window judges the gateway on what actually happened in the last 60 seconds, regardless of how many calls that was. The 2-second slow-call threshold isn't arbitrary either — it should be your own p99 latency budget for a checkout flow, not the gateway's advertised SLA; the circuit breaker's job is protecting your service's user experience, not grading the vendor. 

A retry policy that doesn't add fuel to the fire 

The instinct to add maxAttempts: 5 because "the gateway is sometimes flaky" is exactly how a retry storm gets built one config value at a time. Cap attempts low — two or three, not five — and never retry without backoff: 

        - java.net.SocketTimeoutException 

        - org.springframework.web.client.HttpServerErrorException 

        - com.oceanobe.payments.exceptions.DeclinedTransactionException 

ignoreExceptions deserves as much attention as retryExceptions for a payment integration specifically — a card decline or an invalid-request error is not a transient failure, and retrying it doesn't just waste a call, it can retry a business decision that was already correct the first time. Only timeouts and 5xx-class failures belong in the retry path. 

Exponential backoff configured through YAML alone still has a gap worth knowing about: it produces the same wait sequence for every instance of your service, which means if you're running a fleet of pods and the gateway degrades, every pod's retries land in near-synchronized waves — a smaller, self-inflicted version of the same thundering-herd problem the circuit breaker is there to prevent. Genuine jitter needs the programmatic config: 

IntervalFunction backoffWithJitter = IntervalFunction.ofExponentialRandomBackoff( 

RetryConfig retryConfig = RetryConfig.custom() 

    .intervalFunction(backoffWithJitter) 

The randomization factor is what breaks the synchronization across your own fleet — each pod's retries land at a slightly different offset instead of in lockstep, which is the difference between a brief load spike on the gateway and a self-inflicted thundering herd hitting it in unison. 

The aspect-order trap that skews the circuit breaker's own math 

Here's the one that catches teams who've configured everything above correctly and still see the circuit breaker behave strangely: Resilience4j's default aspect ordering places @Retry outside @CircuitBreaker. That's documented, reproducible behavior, not a hypothetical — Resilience4j's own default aspect order values put Retry at a lower precedence number than CircuitBreaker, which makes Retry the outer wrapper. The practical effect: when a call fails and gets retried three times, the circuit breaker sees three separate failures, not one logical operation that failed and was retried. A single degraded request gets recorded as three data points against your failureRateThreshold, silently skewing the exact statistic the circuit breaker's open/close decision depends on. 

The fix is two explicit properties, flipping which aspect wraps which: 

 With CircuitBreaker as the outer aspect, it evaluates once per logical call — closed means the whole retry sequence is allowed to run and only the final outcome counts toward the failure rate; open means the retry sequence never starts at all, and none of those three attempts touch the network. That second part is the one that actually matters for a retry storm: get the order wrong, and a circuit that's already open still lets every retry attempt independently hit CallNotPermittedException inside the retry loop — cheap locally, but it means your retry policy and your circuit breaker aren't actually coordinated, they're just coincidentally stacked. 

Bulkheads: bounding the blast radius when the circuit hasn't tripped yet 

A circuit breaker protects you once it's decided the gateway is bad. Before that threshold is crossed — while calls are slow but not yet slow or frequent enough to open the circuit — a bulkhead is what stops those in-flight calls from consuming every thread your service has: 

A thread-pool bulkhead gives gateway calls their own isolated executor, capped independently of whatever pool serves the rest of your application — so ten hung gateway calls cost you ten threads from a dedicated pool of ten, not ten threads out of the pool your account-balance endpoint also depends on. That isolation is what actually delivers on "stop a slow gateway from cascading into a full outage": the circuit breaker decides when to stop calling the gateway at all, but the bulkhead is what keeps a gateway that's merely slow — not yet slow enough to trip the breaker — from taking the rest of your service down with it in the meantime. 

What this looks like end to end, and why the wiring order is the whole point 

Composed correctly — CircuitBreaker outermost, Retry inside it, Bulkhead governing the underlying thread pool the calls actually run on — the failure sequence during a real gateway degradation looks like this: calls start taking 3-4 seconds instead of 300ms; the bulkhead caps how many of those slow calls can be in flight at once, so the rest of your service keeps its own thread pool; the circuit breaker's sliding window accumulates slow-call and failure data across genuine logical operations, not inflated retry counts; once the slow-call rate crosses the threshold, the circuit opens and every subsequent call fails fast locally, with zero additional load reaching the gateway, for the entire waitDurationInOpenState window; after that window, a handful of half-open probe calls test whether the gateway has recovered before the circuit fully closes again. Compare that to the unconfigured default: retries stacking on top of retries across every pod, each one counted wrong by a breaker that isn't actually coordinated with them, threads exhausting from a shared pool, and a vendor's bad five minutes turning into your own outage that lasts considerably longer than five minutes. 

One more thing worth building alongside all of this, specific to payments: none of this retry discipline is safe unless the calls being retried are actually idempotent. A payment gateway integration that retries a charge request without an idempotency key isn't protecting against failure — it's risking a duplicate transaction on top of it. Adyen's own API guidance is the pattern worth following regardless of which gateway you're integrating: a client-generated UUIDv4 idempotency key on every payment request, held valid for at least a week, so that a retried request after a timeout returns the original result instead of processing the charge a second time. Resilience4j controls when and how often you retry. It has no opinion on whether retrying is safe — that's a contract your integration has to establish with the gateway independently, and skipping it turns your resilience configuration into a mechanism for reliably duplicating charges instead of reliably avoiding downtime. 

We've built enough payment integrations to have learned this the unglamorous way: the configuration that survives a real incident isn't the one that looks complete in a demo, it's the one where circuit breaker, retry, and bulkhead were wired with an explicit understanding of which one wraps which, and where "safe to retry" was answered before "how many times to retry" was. 

Resilience4j in Production 

Resilience4j circuit breakers, bulkheads, and retry config for payment gateways: stop a slow (not down) gateway from cascading into your outage.

Circuit Breakers and Retry Storms Against Third-Party Payment Gateways 

Every MCP tutorial ends the same way: a weather tool, a curl command, a green checkmark. None of them tell you what changes when the tool you're exposing isn't getWeather(city) but initiatePayment(accountId, amount), sitting behind a Spring Boot service your bank already trusts with real money. This one's for the Java engineer who's been asked to turn that service into something an LLM agent can call — and needs the parts the tutorial skipped. 

Spring AI's MCP support is genuinely good — annotation-driven tool registration, auto-configured transports, sync and async server types out of the box. It's also, by default, a POST /mcp endpoint with no authentication in front of it, happy to hand an LLM agent a JSON-RPC interface to whatever you've annotated. That's fine for a demo. It's not a production posture for a bank, and the gap between the two isn't something the starter closes for you — it's the actual engineering work. What follows is that work, done once so your team doesn't have to rediscover each piece the hard way. 

Transport: the spec has already moved past what most people ask for 

MCP originally shipped with HTTP+SSE as its remote transport, and if you're planning a build around SSE, it's worth knowing that the protocol has moved on. The 2025-03-26 MCP spec revision deprecated HTTP+SSE in favor of Streamable HTTP, for reasons that show up quickly once you try to run SSE at scale: the original transport needed two separate endpoints — one to receive server-sent events, one to post client messages — which forces awkward coordination between connections that are supposed to represent one logical session. Long-lived SSE connections are resource-intensive to hold open across a fleet of instances, there's no built-in way to resume a dropped connection mid-stream, and the transport doesn't get the benefits newer HTTP versions offer. Streamable HTTP fixes this by consolidating everything onto a single endpoint that upgrades to streaming only when a response actually needs it, with the resumability and bidirectional communication SSE never had. 

Spring AI supports both, and the choice is a one-line config change, not an architectural one — which is exactly why it's worth getting right the first time: 

        type: SYNC              # or ASYNC, for reactive tool implementations 

        protocol: STREAMABLE    # SSE | STREAMABLE | STATELESS 

spring-ai-starter-mcp-server-webflux or -webmvc gets you either transport; the property is what switches it. Default to STREAMABLE for anything new — it's the current spec's baseline, and it's what any MCP client built against a recent SDK will expect. Keep an SSE-configured instance around only if you have a specific client you don't control that hasn't upgraded yet, and treat it as a compatibility shim with a retirement date, not the primary interface. STATELESS is worth a specific look for a banking backend beyond either of those: it drops server-side session state entirely, which is what actually lets a tool server scale horizontally behind a standard load balancer without sticky sessions — a constraint most core banking infrastructure already has opinions about. 

Tool registries: curate the surface, don't just annotate what exists 

The annotation model makes exposing a method almost too easy: 

    @McpTool(name = "get_transaction_status", description = 

        "Look up the status of a previously submitted transaction by ID.") 

            @McpToolParam(description = "Transaction ID", required = true) String txId, 

            McpSyncRequestContext requestContext) { 

        String callerToken = (String) requestContext.transportContext() 

        return transactionService.getStatus(txId, callerToken); 

 That's the right shape for a read-only tool. The trap is treating @McpTool as a convenient way to expose whatever's already sitting in a @Service class, one annotation at a time, until the tool registry has quietly become a mirror of your entire internal API surface. An MCP tool server for a banking backend should be built the way you'd build any other external-facing interface: a deliberate facade, narrower than what's behind it, where every tool is something you'd be comfortable explaining to an auditor as "yes, we intentionally let an LLM call this." That's the same ports-and-adapters instinct Java teams already apply at other integration boundaries — the tool registry is a boundary too, and it deserves the same discipline, not an exemption because the caller happens to be a model instead of another service. 

Two things follow from treating it that way. First, tool descriptions are part of your attack surface, not documentation — the entire tool schema, including parameter descriptions, is something a model reads and can be manipulated by, so it needs the same review as production copy, not whatever text was fastest to write. Second, per-request authorization has to run on the caller's actual identity, not the tool server's own service credential. The McpTransportContext pulling an Authorization header out of the incoming request, shown above, is what makes that possible — extract the caller's token at the transport layer and thread it into every downstream call, rather than letting the tool server hold one broadly-scoped credential and trust the agent to only ask for what it should. That distinction is what security guidance calls the confused deputy problem: a tool server that acts with its own privilege instead of enforcing the caller's is a privilege escalation waiting for the first agent session that gets manipulated into asking for something it shouldn't. 

Secrets handling: nothing hardcoded, nothing shared, nothing standing 

MCP's own security guidance is direct about where credentials go wrong in practice: tokens shared across servers instead of scoped per server, secrets sitting in plaintext config instead of a real secret store, long-lived personal-access-token-style credentials instead of short-lived ones scoped to a session. For a banking backend, none of that is a new problem — it's the same secrets-management discipline your existing services already answer to, and there's no reason the MCP boundary should get a pass. 

Concretely, that means: back tool-server credentials with whatever secret store your bank already runs (Vault or equivalent), not environment variables baked into a container image; use the MCP authorization flow — OAuth with PKCE, scoped narrowly per tool server rather than one shared client credential across every MCP server in your fleet — instead of static API keys; bind session identity to the actual authenticated user (user_id:session_id, validated on every request) so a session token can't be replayed against a different caller's context; and apply resource limits — rate limits, quotas, timeouts — per session, the same way you'd throttle any other client of a payments API. None of this is exotic. It's the standard OAuth-and-secrets-manager posture your team already runs elsewhere, applied to a new front door instead of invented from scratch for this one. 

The default-open trap is worth calling out explicitly, because it's the one every team hits once: Spring AI's own documentation states plainly that its HTTP-based transports expose an unauthenticated JSON-RPC endpoint by default, and that you must put a security boundary — Spring Security, or the community mcp-security project — in front of it before it's reachable beyond localhost. A tool server that works perfectly in local dev, behind no auth, is not a tool server that's ready to point at a payments service. That gap between "the demo works" and "this is safe to expose" is exactly where these projects lose weeks if it isn't planned for from the first sprint. 

The tool boundary needs the same guardrail discipline as any other AI-facing surface 

We've written before about why free text should never be the thing that moves money in an LLM-backed banking chatbot — the same principle applies at the tool server, just one layer earlier. A get_transaction_status tool is safe to let an agent call autonomously. An initiate_transfer tool is not, regardless of how well-scoped its OAuth token is — it needs an explicit human-approval step before execution, not just before the UI renders the result, and that approval has to be enforced by the tool server itself, not left to whatever the client application chooses to do with the response. Log every invocation — full parameters, caller identity, timestamp — into the same audit pipeline your other regulated systems already feed, for the same reason we've argued a DORA-grade audit trail needs to be independent of the system it's describing: "the agent called it and got a 200" is not an answer your risk function will accept for how a transfer happened, any more than "the model generated it and the tests passed" is an answer for how a line of production code came to exist. 

None of this is a reason to avoid building the tool server. It's the reason to build it deliberately: Streamable HTTP as the default transport, a curated tool registry instead of an annotated mirror of your service layer, caller-scoped credentials instead of one shared token, and a security boundary in front of the endpoint before anything beyond localhost can reach it. We've spent years putting Java backends in front of systems where a mistake shows up as a wire transfer, not a stack trace. An MCP tool server is a new kind of front door into that backend. It doesn't get to skip the discipline the rest of the door already has. 

Building a Production-Grade Tool Server for Banking Backends 

Spring AI makes exposing a tool server easy. Making it production-grade for a banking backend is different work. Here's the transport, tool registry, and secrets-handling patterns that close the gap.

Spring AI + MCP make a tool server easy. Production-grade for a banking backend needs real transport, registry, and secrets patterns.

Spring AI + MCP 

Most of the engineers staffed onto a COBOL modernisation project don't read COBOL — they read Java, and they've been handed an AI assistant and told it closes the gap. It closes some of it. This one's for the Java engineer holding the bridge, who needs to know exactly which parts of that gap an LLM actually closes, and which parts it will confidently paper over if nobody stops it. 

Anthropic's announcement that Claude Code can analyse and document COBOL codebases — mapping dependencies, flagging risk, translating logic into modern languages, modernisation in "quarters rather than years" instead of the usual multi-year programme — moved IBM's stock down over 13% in a single day. That reaction tells you something true: the market believes AI-assisted legacy modernisation is now real enough to threaten the economics of staying on the mainframe. It doesn't tell you whether the code an LLM writes on your core banking ledger is safe to ship, and those are two different questions. The demo that impresses a room is a self-contained COBOL program with clean copybooks. The core your bank actually runs is forty years of paragraphs, GOTOs, and copybooks written by people who left before you were hired, none of it designed to be read out of context. 

Reading isn't understanding, and the failure mode is invisible until it isn't 

What LLMs are genuinely good at against real COBOL is close to what they're good at against any unfamiliar codebase: tracing program flow, mapping which paragraphs call which, pulling a plausible-sounding business rule out of an undocumented subroutine, and turning that into fluent documentation a Java team can actually read. What they're weak at is the thing that matters most on a core banking system — resolving a data structure's true shape when the answer lives somewhere the model didn't look. 

Here's the shape of the failure, as described in accounts from teams doing exactly this kind of migration: an AI system translated a COBOL financial module to Java. It compiled. It passed the unit tests the same AI had written for it. In production, it corrupted a database on the first live wire transfer. The root cause was a field — call it TRN-LIMIT — defined thousands of lines earlier in a copybook, carrying a REDEFINES clause that let the same memory reinterpret as a different data type depending on a runtime condition. The model read TRN-LIMIT where it was used, in the transaction paragraph, and treated it as a plain numeric field, because that's what it looked like locally. It never resolved the REDEFINES chain back to its actual definition — not because it couldn't, but because a RAG-style retrieval step finds text that's semantically similar to what you asked about, and a REDEFINES clause buried in an unrelated copybook doesn't read as similar to a payment paragraph. It reads as unrelated, right up until it's the thing that decides how the bytes get interpreted. 

That's the failure mode worth designing prompting patterns around: not the model being wrong about something it looked at, but the model being confidently right about something it never looked at, because nothing forced it to look. A COBOL codebase's real structure — copybook inheritance, REDEFINES, OCCURS DEPENDING ON, 88-level condition names — isn't always where the paragraph you're translating happens to be. Treating it like a self-contained unit of text, which is exactly what a chat-style prompt or an IDE-scoped Copilot completion implicitly does, is where these projects go wrong. 

Prompting patterns that assume the model can't see what you haven't shown it 

The fix isn't a smarter model. It's context discipline that doesn't rely on the model finding what it needs on its own. 

Enumerate the copybook chain before you ask for a translation, and paste all of it in. Before asking Claude or Copilot to translate a paragraph, walk every COPY statement it depends on and every REDEFINES on every field it touches, and put the full text of that chain in context — not a summary, not "here's the copybook it probably needs." If a field is redefined three copybooks away from where it's used, that redefinition has to be physically present in the prompt, because retrieval won't reliably surface it and the model has no way to ask you for it. 

Ask for a data dictionary before you ask for code. Two-step prompting beats one-step here: first, have the model enumerate every field the paragraph touches — its PICTURE clause, its REDEFINES if any, its 88-level condition names — as a table, before it writes a single line of Java. Reviewing that table against the copybook is fast for a human who doesn't read COBOL fluently; reviewing generated Java line-by-line for the same errors is not. If the model's data dictionary is wrong, you've caught the TRN-LIMIT-shaped bug before it became a bridge. 

Generate characterization tests before translation, not from the translation. A model asked to translate a paragraph and then write tests for its own output will write tests that confirm what it believes the paragraph does — which is exactly the confidence that missed the REDEFINES clause in the first place. Instead, ask it to generate golden-master tests from the existing COBOL behavior against representative input data, run against the current system, before any Java exists. The Java bridge then has to match a behavior captured independently of the model's own understanding, not a test suite the model wrote to agree with itself. 

Never let a model choose between double and BigDecimal. COBOL's COMP-3 packed decimal fields carry an exact scale and precision from the PICTURE clause — that's the entire reason COBOL is still running the general ledger. A model translating that field to a Java double or float isn't simplifying, it's silently introducing floating-point rounding into money math. The prompting pattern here is a standing instruction, not a per-task one: every numeric field maps to BigDecimal with scale and rounding mode taken explicitly from the source PICTURE clause, and the model has to state the PICTURE clause it read for each field so a reviewer can check the mapping against the copybook rather than trusting the narrative. 

Flag control flow instead of "cleaning" it. A GOTO or PERFORM ... THRU that looks dead in isolation can be what sequences an overnight batch job. Ask the model explicitly to flag every GOTO, ALTER, and PERFORM ... THRU it encounters and explain what it thinks controls it, rather than quietly restructuring the paragraph into cleaner-looking Java — a model instructed to simplify will simplify, including the parts it didn't understand were load-bearing. 

Use the bridge, not the rewrite, as the default prompting target 

The safest place to point an LLM on a legacy core isn't "rewrite this business logic in Java." It's the adapter layer around it. Java-calling-COBOL over JNI is a well-documented, mechanical pattern — a native method declared with the Java_classname_methodname convention, two hidden JNI arguments the COBOL side receives from the runtime, the compiled COBOL loaded as a shared library via System.loadLibrary(). That's exactly the kind of boilerplate-heavy, well-specified integration code LLMs are reliable at, because it's mechanical translation against a documented interface, not an inference about what forty-year-old business logic was supposed to mean. 

Prompt pattern (bridge generation, not logic translation): 

"Generate a JNI adapter that calls COBOL program PYMT100 from 

Java. Native method signature: calculateSettlement(BigDecimal 

amount, String currencyCode) returning SettlementResult. Do not 

reimplement PYMT100's internal logic — the COBOL program remains 

the source of truth for the calculation. Map COMP-3 fields per 

the attached copybook PYMT100-COPY.cpy exactly as specified; 

flag any field where the copybook doesn't fully determine scale 

That's the strangler-fig pattern applied to prompting: Java owns orchestration, the COBOL program stays authoritative for the calculation it was already trusted with, and the AI-generated surface area is the boring, verifiable adapter code rather than a reimplementation of business logic nobody's fully documented. It also changes what "AI-assisted modernisation" means as a phased programme — you can ship the bridge and start decommissioning around it long before anyone reimplements the underlying paragraph in Java, and the highest-risk translation work only happens once, deliberately, with a subject-matter expert in the loop, instead of as an implicit side effect of every prompt. 

Copilot and Claude earn different roles in this split. Copilot's inline, IDE-scoped suggestions are well suited to the adapter and boilerplate layer — small, well-specified completions reviewed in place, paragraph by paragraph. Claude's larger context window and agentic tooling are better matched to the analysis phase — ingesting a full copybook chain, producing the dependency map and data dictionary, flagging the REDEFINES and the GOTOs before a human decides what's safe to touch. Neither belongs unsupervised in the paragraph that calculates interest. 

Traceability is the part that makes this auditable, not just accurate 

Everything above produces a review burden, and the review burden is the point — but it only works if it's checkable after the fact, not just at merge time. Annotate every AI-generated line with where it came from: a source comment referencing the exact COBOL program and line range it was translated from, not just a commit message. Log the prompt, the context that was actually supplied, and the output together, so that eighteen months later, when an auditor or a regulator asks how a specific line of Java came to exist, the answer is a record instead of a reconstruction. We've written before about what DORA's operational resilience testing actually expects of an audit trail — evidence independent of the system it's describing, not a belief about what probably happened. AI-assisted migration on a regulated core needs exactly that same discipline, because "the model generated it and the tests passed" is not an answer a regulator, or a bank's own risk function, will accept for how a payment calculation changed. 

None of this makes COBOL-to-Java migration fast in the way the headlines promise. It makes the parts of it that are genuinely mechanical fast — and it keeps the parts that aren't mechanical in front of a human who can read a copybook, instead of letting an LLM's fluency stand in for understanding it never actually had. On a core that moves real money, that trade is the whole point. 

Claude and Copilot on Legacy Cores  

Claude and Copilot can read COBOL. Reading isn't understanding — here are the prompting patterns that keep a COBOL/Java bridge safe to ship.

Prompting Patterns for COBOL/Java Bridges 

Ship a React Native banking app in one country and accessibility, localisation are two checklist items. Ship the same codebase into eight countries and they become a combinatorics problem: every screen, times every locale, times every screen reader, times every release. This one's for the React Native developer who owns that matrix and has stopped pretending a human can hold all of it in their head. 

A single-market app can get away with a manual accessibility pass before each release and a translator who reads the diff. A multi-country banking app on one React Native codebase can't — not because the team got lazier, but because the surface area grew multiplicatively while the review capacity stayed the same. Two hundred screens across a core banking app, six markets, VoiceOver and TalkBack, and a release cadence measured in weeks, not quarters, is not a QA checklist anymore. It's a coverage problem, and coverage problems are exactly where it makes sense to put an LLM to work — not to write the app, but to keep watch over what a human reviewer can no longer see all of. 

The deadline that already passed, and the one that's about to move 

The European Accessibility Act has applied to consumer banking services since 28 June 2025, and it doesn't grandfather existing apps — a banking app that launched in 2020 has to be fully accessible for any use after that date, the same as one shipped last month. There's no broad transition period for digital services; the narrow exceptions in the Act cover things like pre-existing B2B service contracts and legacy self-service terminals, not a mobile banking app your retail customers use today. If your app serves consumers in the EU, this isn't a future compliance project. It's already the legal baseline. 

What's about to change is which baseline. The harmonised standard behind the EAA, EN 301 549, is still on v3.2.1 and WCAG 2.1 AA as of today. Version 4, currently in draft, moves the reference standard to WCAG 2.2 AA and is expected to be cited in the EU Official Journal around October 2026 — a few weeks out from whenever this piece is read. Two of the six new WCAG 2.2 criteria land directly on banking UI: Target Size, which sets a minimum touch-target size that a lot of dense transaction-list and confirmation-button designs quietly violate, and Accessible Authentication, which prohibits login or step-up flows that rely on a cognitive function test — memorising or transcribing an OTP — without an alternative like copy-paste or a password manager. If your OTP screen currently expects someone to hold a six-digit code in their head while switching apps, that's the exact pattern the new criterion targets. 

None of that is enforced identically across markets, either. The EAA is a directive: the technical standard is harmonised, but each member state transposes it into national law with its own enforcement body and penalty regime — Germany's BFSG is one visible example. A multi-country app isn't meeting one accessibility bar; it's meeting one technical standard under several different national enforcement regimes at once, which is one more reason a manual, country-by-country audit doesn't scale as a review process. 

Where React Native's accessibility API actually breaks down at scale 

React Native gives you the primitives — accessibilityLabel, accessibilityRole, accessibilityHint, accessibilityState — and they work well when a developer remembers to use them correctly on every interactive element. The failure mode isn't ignorance of the API; open-source guides like Nearform's React Native AMA document the patterns clearly enough. The failure mode is that correctness is a per-component, per-PR discipline, and at 200+ screens across a team that rotates and ships weekly, discipline degrades quietly. A toggle ships without an accessibilityState update on press. An icon-only button ships with no label at all. A custom component wraps a Pressable and inherits none of the accessibility props the design system intended. Each one is a one-line fix. Finding them all, before release, across every screen and every locale, is the part that doesn't scale linearly with headcount. 

This is where an LLM earns its place in the pipeline — as a coverage layer over a PR diff, not as the thing writing the label. Wired into CI against the JSX AST of changed files, it can flag a TouchableOpacity with no accessibilityLabel, a custom toggle missing accessibilityState, or an image with an alt-equivalent that just repeats the filename — and propose a specific fix rather than a generic warning. Research on LLM-generated accessible UI code backs up what you'd expect from using these models directly: they're reliable on standard patterns like semantic roles and basic labels, and much weaker on custom components, dynamic content announcements, and focus management inside modals — one benchmark found only about a third of AI-generated sortable tables correctly announced state changes. The gap matters less for what it says about the model and more for what it implies about the workflow: treat the output as a flagged draft requiring review, never as a merge-ready fix, and the same research found that prompts anchored to a specific WCAG success criterion — "this needs an accessibilityState update per SC 4.1.2," not "make this accessible" — measurably improve what comes back. Deterministic tooling still does the enforcement; eslint-plugin-react-native-a11y catches the mechanical cases (missing labels on touchables, images without alt text) reliably and cheaply. The LLM's job is the harder-to-rule-ify layer on top: is this label actually descriptive, does this hint add real information, does this custom component's role match what it does. 

Localisation has the same shape, and the two problems compound each other 

A multi-country banking app's i18n surface isn't just translated strings — it's currency and date formatting per locale, pluralisation rules that don't map cleanly from English, interpolation placeholders that have to survive translation intact, and string length expansion that varies wildly by language. German banking terminology in particular runs 30–40% longer than the English source string, and that's not a cosmetic problem — a label that truncates on a small screen doesn't just look wrong, it silences the screen reader reading it or turns a clear call-to-action into an ellipsis. Localisation and accessibility bugs aren't two separate backlogs on a banking app; a truncated German label is both at once. 

The same coverage-layer approach applies. An LLM reviewing a locale-key diff can catch what a translation memory tool won't: a missing key that silently falls back to the source language in production, an interpolation placeholder ({{amount}}, {{accountLastFour}}) that survived in one locale file but got flattened into plain text in another, or a string that's technically translated but uses consumer-facing phrasing where the source string was written for a KYC or compliance screen and needed the formal register a given market's banking terminology expects. It can also flag, before a string ever reaches a device, which translated strings are likely to overflow a given layout given that locale's typical expansion ratio — catching the German-label problem in CI instead of in a screenshot review three sprints later. 

CI flag on PR #4127 (ro-RO, de-DE locale diff): 

de-DE: "transfer.confirm.button" translated but exceeds button's 

  maxLines(1) budget at 98th-percentile string length (+34% vs en-US 

  source). Suggest: shorten label or increase touch target per WCAG 

  2.2 SC 2.5.8 minimum size — current button clips to 38x38pt. 

ro-RO: "otp.hint" interpolates {{expirySeconds}} — key present in 

  en-US and de-DE, missing in ro-RO. Falls back to source string 

Both: flagged for native-speaker + a11y review before merge. 

What AI should never be the last reviewer of 

The guardrail matters as much as the capability. Interest rate disclosures, consent language, KYC copy, anything a national regulator would read as the actual legal text of the product — that copy gets written and reviewed by a native-speaking compliance reviewer in that market, full stop. What the LLM is good for is making sure that copy exists in every locale it needs to, that it hasn't silently regressed, and that the button it sits in doesn't clip it — not authoring the copy itself. The distinction is the same one that shows up anywhere AI touches a regulated pipeline: use it to raise coverage and catch drift, keep a human accountable for anything a regulator, a screen reader, or a customer in a market you don't personally read the language of would actually rely on. 

Testing like the market surveillance authority will 

EAA enforcement doesn't run against your English staging build. A national market surveillance authority testing a banking app for compliance will test the actual deployed app, in the actual local language, with the actual assistive technology customers in that country use — which means your own test matrix needs to mirror that, not substitute an English-only VoiceOver pass and call the rest "covered by translation." A coverage matrix generated per screen, per locale, and per platform — and kept honest by the same CI layer that flags missing labels and overflowing strings — is what makes "we tested it" mean the same thing in Bucharest and Berlin, instead of meaning "we tested the English version and hoped." 

We've built and shipped React Native banking apps that run across multiple markets on one codebase, and the lesson that stuck is a boring one: neither accessibility nor localisation breaks because a team doesn't care. It breaks because a per-PR discipline doesn't scale to a multi-country release matrix, and nobody notices the gap until either a regulator or a customer does. An LLM in that pipeline isn't a replacement for an accessibility specialist or a native-speaking reviewer — it's the coverage net that makes sure the specialist's judgment gets applied to every screen, in every market, every single release, instead of whichever ones a human had time to click through before the deadline. 

Accessibility and Localisation at Scale for Multi-Country Banking Apps 

Accessibility and localisation don't scale linearly across a multi-country React Native banking app. Here's how AI can generate and validate a11y and i18n coverage before a regulator — or a customer — finds the gap.

AI can generate and validate a11y and i18n coverage across multi-country React Native banking apps — before a regulator or customer finds the gap.

React Native + LLMs 

Ask most frontend teams where LLM guardrails live and you'll get the same answer: the backend. Prompt engineering, retrieval pipelines, output classifiers, tool-call permissions — all backend concerns, all somebody else's problem. That's true right up until the moment a hallucinated fee amount renders in a chat bubble with the same visual authority as a verified balance, or a cleverly worded paste triggers an action nobody asked for. At that point it's not a backend incident. It's whatever the customer saw on their screen, and the screen was built by the frontend team. 

The 2026 revision of the OWASP LLM Top 10 reframes the whole problem usefully: stop trying to make the model perfect, and instead build the system around it so that when it fails — and it will — nothing important breaks. That's a containment argument, and containment doesn't stop at the API boundary. For a banking chatbot, the UI is the last layer standing between a model's mistake and a customer's money or trust. It deserves to be treated as a guardrail layer in its own right, not just a rendering target for whatever the backend decided to send. 

The response you render is untrusted input, not a trusted answer 

It's easy to treat an LLM's output as first-party content, because it comes from your own backend, over your own API, wrapped in your own response schema. Treat it that way and you inherit whatever the model produces, including content an attacker steered it into producing. OWASP's 2026 list still ranks improper output handling as a live risk category precisely because teams keep making this mistake: rendering model output as if it were safe just because it arrived through a trusted pipe. 

In practice, that means the chat UI needs the same discipline you'd apply to any user-generated content, applied to every model response: 

Render responses through a constrained markdown renderer with an explicit tag allowlist — no raw HTML, no dangerouslySetInnerHTML-equivalent without sanitization (DOMPurify or an equivalent), no inline styles or event handlers surviving the render pass. 

Treat links in model output as suggestions, not destinations. A prompt-injected model can be steered into recommending a link that looks like your own domain. Resolve links server-side against an allowlist before the client ever makes them clickable, rather than trusting whatever markdown the model emitted. 

Apply a strict Content-Security-Policy as a second layer, not a substitute for sanitization — CSP catches what sanitization missed, it shouldn't be the only thing standing between a malformed response and script execution. 

None of this is exotic frontend security. It's the same discipline you'd apply to any untrusted content pipeline. The only thing that changed is the source now writes fluent, plausible-looking prose instead of obviously malformed input, which makes it easier to forget the discipline applies at all. 

The context you assemble is part of the attack surface, not just what the user typed 

Prompt injection doesn't only arrive as a message the user types directly. Once your chatbot pulls in pasted text, uploaded statements, or retrieved account content as part of the payload sent to the model, every one of those becomes a channel an attacker can use — and a lot of that assembly happens client-side, in the same code that builds the request. 

A customer pasting a "helpful" snippet from a phishing email, a scanned statement with injected text in a hidden layer, or a support macro copied from a forum post can all carry instructions the model will treat as part of its context unless something marks them as untrusted before they leave the browser. A few defenses belong here, not in the backend: 

Delimit and tag anything the client assembles from user-supplied or fetched content — wrap it clearly as data, not instruction, before it's added to the outgoing payload, so the backend's prompt structure can treat it accordingly. 

Normalize input before it's sent: strip zero-width characters, bidirectional-override marks, and other invisible-unicode tricks that are a known way to hide injected instructions inside otherwise unremarkable pasted text. 

Flag large pastes or file uploads to the user before they're sent — not as a security theater warning, but because it's a real moment to catch "wait, I didn't mean to paste that whole email thread" before it becomes model context. 

The backend can and should defend against injection too. But it can only defend against what actually reaches it in a recognizable form — the client is the only layer that sees the content in its original shape, before assembly, and it's the only layer that can flag it before it's flattened into an opaque prompt. 

Free text should never be the thing that moves money 

Excessive agency — a model taking an action beyond what was actually warranted — climbed to the #3 risk in the 2026 OWASP list, and for a banking chatbot it's the single most consequential failure mode. The backend should absolutely scope what any tool call is allowed to do. But the UI has its own version of that responsibility: never let a model's free-text output directly trigger a transfer, a limit change, or a card action. The model should propose a structured, schema-validated action object, and the UI should render that proposal as an explicit confirmation the customer has to approve — not infer intent from prose and act on it. 

Model output (rejected by the client if malformed): 

  "recipient_account": "RO49AAAA1B31007593840000", 

- Validate against the action schema before rendering anything. 

- Render a confirmation card with the parsed fields, not the model's 

- Route to step-up authentication (SCA) before submission if the 

  schema flags it — the model doesn't get to decide this is skippable. 

This does double duty. It's a hard technical guardrail against a hallucinated or injected action executing silently, and it's a UX moment where a hallucinated amount or wrong recipient becomes visible to the one person positioned to catch it before it becomes a real transaction — the customer looking at the confirmation card. 

Make groundedness visible, not just true 

A well-built retrieval pipeline reduces hallucination on the backend. It doesn't help the customer if the UI presents every sentence the model produces with identical visual authority, whether it's a fact pulled straight from a fee schedule or a plausible-sounding number the model generated to fill a gap. If the backend can tag which claims are grounded in a retrieved source and which aren't, the frontend is where that distinction actually reaches the person who needs it. 

Concretely: render source-grounded claims with a visible citation — a reference chip linking to the actual policy document or account record it came from — and treat ungrounded statements differently, whether that's softer visual styling, an explicit "verify with an advisor" affordance, or declining to render a specific number at all if it isn't traceable to a source. A customer can't apply judgment to a hallucination that looks identical to a verified fact. Giving them that visual distinction is a guardrail as much as a UX nicety. 

Telling the customer they're talking to AI stopped being optional two weeks ago 

Article 50 of the EU AI Act — the transparency obligation requiring that users be informed they're interacting with an AI system, "at the latest at the time of the first interaction," unless it's already obvious — took effect on 2 August 2026. For a banking chatbot, this isn't a checkbox you can satisfy with a line in the terms of service. It has to be clear and distinguishable at the point of interaction, which puts it squarely in frontend scope: a persistent, accessible label on the chat interface, not a disclaimer a customer has to go looking for. It's also a reasonable moment to reinforce the same message the rest of this piece is about — the customer should understand they're talking to a system that can be wrong, at the exact point they're deciding whether to trust what it just told them. 

We've written before about what DORA's threat-led penetration testing actually demands of an architecture — live-production testing, no advance notice to the team being tested. A conversational banking UI is exactly the kind of surface that testing will probe, and it's worth holding the frontend to that standard before an external red team does it for you. Render fuzzing with malformed markdown, injected script tags, and unicode obfuscation tricks belongs in the same test suite as your component snapshots. The confirmation-card flow deserves adversarial test cases specifically designed to check that a malformed or partially-valid action object gets rejected rather than rendered with best-effort guessing. If your QA process trusts the model to always produce well-formed output, you've already found the gap an attacker will. 

None of this replaces backend-side guardrails — retrieval grounding, output classifiers, tool-call scoping all still matter, and matter first. But the frontend is where a model's failure becomes a customer's experience, and increasingly, where regulation expects that failure to be visibly and honestly presented rather than smoothed over. Building banking software has always meant treating the interface as part of the control environment, not just the presentation layer on top of it. LLMs haven't changed that. They've just given the interface a new kind of failure to contain. 

Guardrails in the UI Layer 

Guardrails for LLM banking chatbots don't stop at the backend. Here's the frontend's role in containing hallucination, prompt injection, and excessive agency before they reach the customer.

Guardrails for LLM banking chatbots; frontend's role in containing hallucination, prompt injection, and excessive agency before they reach the customer.

Client-Side Defenses for LLM-Backed Banking Chatbots 

I used to write requirements the way most BAs do: prose paragraphs, a table of acceptance criteria, and a quiet trust that whoever picked up the ticket would fill the gaps sensibly. That trust was well placed with a developer — they'd ask in standup, ping me on Slack, or just apply the same domain judgment I'd apply if I were coding it myself. An AI agent doesn't do that. It reads what's on the page, makes a confident decision about everything that isn't, and ships it. That single difference is rewriting what a good spec looks like. 

Requirements haven't changed. What's changed is who — or what — reads them first. When a developer picked up a ticket, the spec was a starting point for a conversation. When an agent picks up the same ticket, the spec is the conversation, and whatever it doesn't say gets decided by a model with no stake in getting it right and no instinct to ask. For a BA, that's not a tooling change. It's a change to the actual skill. 

The gap a developer used to fill silently, an agent fills with a guess 

Every requirements doc has gaps — not from carelessness, but because some things are genuinely easier to say in a hallway than in a ticket, and because a competent developer fills them in automatically from context you both share. "Handle the error case sensibly." "Match the existing pattern." "Obviously this should be idempotent." A developer reads those and reaches for the same domain knowledge you have. An agent reads them and reaches for whatever's statistically plausible, which is not the same thing, and it won't flag the difference before shipping it. 

This is the part that catches BAs off guard the first time: the failure mode isn't the agent refusing to proceed on an ambiguous requirement. It's the agent proceeding confidently, producing something that compiles, passes the tests it wrote for itself, and does the wrong thing — because the wrong thing was a perfectly reasonable reading of an underspecified sentence. A human reviewer used to be your safety net for that kind of gap. With agent-generated code shipping faster and in higher volume, you can't rely on review to catch every one of them. The spec has to close the gap before the agent gets there. 

From prose requirements to acceptance criteria that map to tests 

The most direct fix is also the most mechanical one: write acceptance criteria in a constrained syntax that maps one-to-one onto a test case, instead of a sentence that admits more than one reading. EARS (Easy Approach to Requirements Syntax) has become the practical standard for this, precisely because it's restrictive enough to force the ambiguity out during writing rather than during code review. Five patterns cover almost everything a BA needs: 

Ubiquitous:        The system shall [always-true behavior]. 

Event-driven:       When [trigger occurs], the system shall [response]. 

State-driven:        While [condition holds], the system shall [behavior]. 

Writing Specs an Agent Can Execute  

Acceptance criteria need to change when an AI agent, not a developer, is the one building from your spec. 

All News

Categories

All News

Categories

Do you want to read more?

Subscribe now for our bimonthly newsletter!