DEV Community: Duncan Brown

AI Works Better When Behaviour Is Explicit

Duncan Brown — Mon, 06 Apr 2026 16:53:29 +0000

AI coding assistants are generally quite good at producing code.

However, they are less reliable when they have to decide what that code should do.

In other words, they struggle less with syntax than with intent.

Given a clear description of behaviour, an assistant can often produce a reasonable implementation. Given an ambiguous one, it will still produce something — but that “something” may not align with what was actually intended.

It’s a consequence of how we describe systems, and not a failure of the model.

The Real Problem Is Ambiguity

In most codebases, behaviour is only partially explicit.

Some of it lives in:

method names
comments
documentation
tests
conversations between developers

The rest is assumed.

Those assumptions work reasonably well when the same people are working on the system and context is shared. They break down as soon as:

new developers join
features are modified across teams
systems grow in scope
or code is generated rather than written

AI coding assistants make the breakdown more visible.

They don’t share your assumptions.

They operate on what is written, not what is implied.

Try this experiment: pick an open-source project and scan its code, PRs, and tickets for the kinds of artifacts mentioned above.

Are you able to write a functional specification that perfectly describes the system’s intended behaviour? Do you think a coding agent would perform any better?

Where BDD Fits

Behaviour-driven development is often discussed as a testing technique.

More accurately, it is a way of making behaviour explicit.

A scenario like:

Given a document is submitted
When it is reviewed
Then it should receive a score between 0 and 100

doesn’t describe implementation.

It describes intent, and that distinction matters.

When behaviour is expressed this way:

there is less room for interpretation
there are fewer implicit assumptions
and there exists a clearer boundary between what the system does and how it does it

That clarity certainly benefits humans, but it also benefits systems that generate code.

Why This Matters for AI-Assisted Development

When behaviour is implicit, AI has to infer intent.

That inference is where things start to go wrong.

An assistant may:

implement the “most likely” interpretation
generalize beyond what was intended
introduce edge cases that were never discussed
or omit constraints that were never stated explicitly

The result often looks reasonable in isolation, but it may not match the actual expectations of the system.

When behaviour is expressed explicitly — for example, through Gherkin-style scenarios — that ambiguity is reduced.

The assistant no longer has to guess what the system should do.

It can focus on how to implement what has already been defined.

This shifts the problem from interpretation to execution as we move from an imperative style to a declarative style.

BDD as a Constraint System

In previous discussions, I’ve described architecture as a constraint system.

Patterns like:

bounded contexts
aggregates
dependency direction
ubiquitous language

all restrict how a system is allowed to evolve.

Behaviour-driven development introduces another form of constraint:

It constrains behaviour.

A well-defined set of scenarios limits:

what the system is expected to do
how it should respond under specific conditions
and what outcomes are considered valid

These constraints operate at a different level than architectural boundaries, but they serve the same purpose.

They reduce the space in which incorrect changes can occur.

For humans, this improves communication.

For AI-assisted workflows, it reduces guesswork.

Tooling, Not the Point

Frameworks like Cucumber or other Gherkin-based tools are often used to execute these scenarios.

That’s useful, but it’s not the most important part.

The primary value of BDD in this context is not test execution.

It’s the act of making behaviour explicit.

You can get much of the benefit even without a full BDD toolchain, as long as:

behaviour is clearly described
expectations are shared
and scenarios are treated as part of the system’s definition

The tooling helps enforce it, similarly to how we might use ArchUnit to enforce architectural constraints.

The clarity is what makes it work.

Where This Helps — and Where It Doesn’t

Making behaviour explicit improves outcomes, but it does not eliminate the need for discipline.

BDD does not:

define architectural boundaries
prevent poor domain modelling
or replace the need for governance

It complements those things.

It works best when combined with:

clear architectural constraints
a well-defined ubiquitous language
and enforcement mechanisms that keep the system aligned over time

Without those, even well-written scenarios can (and do) drift.

Closing Thoughts

AI coding assistants are not inherently unreliable.

As anyone who's used one knows, they are sensitive to ambiguity.

When intent is implicit, they infer.

When behaviour is explicit, they implement.

Behaviour-driven development is an excellent way to make that intent visible.

Not as a testing technique alone, but as a constraint on what the system is supposed to do.

In systems that evolve quickly — whether through teams, automation, or AI-assisted development — that constraint becomes increasingly valuable.

AI Governance Doesn’t Need to Start Big

Duncan Brown — Mon, 23 Mar 2026 15:46:20 +0000

I was recently contacted by a professional on LinkedIn about my experience with commercial AI governance platforms.

The assumption behind the question was clear: that “AI governance” is something that requires a formal product, a structured framework, or a sufficiently large organization before it becomes relevant.

In my experience, that assumption is backwards.

Governance doesn’t begin when you adopt a platform; rather, it begins the moment you introduce AI into a system.

The Common Assumption

There’s a tendency to think about governance as something that arrives later:

once the system becomes complex enough
once there are enough users
once risk becomes visible
once the organization can justify the investment

At that point, teams start evaluating:

governance frameworks
compliance tooling
vendor platforms

Until then, governance is often treated as optional, or deferred entirely.

The Problem With Waiting

The issue with this approach is not that governance tools are unnecessary.

It’s that delaying governance allows systems to evolve without constraints. Even a well-architected solution - which serves as a "front line" constraint - can allow AI features and integrations to drift in ways that aren't necessarily initially accounted for.

And once patterns are established — even informal ones — they tend to persist.

You start to see things like:

AI-related changes bypassing normal review processes
prompt or instruction updates made without traceability
unclear ownership of AI-driven behaviour
inconsistent handling of data boundaries or outputs

None of these decisions are individually catastrophic.

But they accumulate.

By the time governance is introduced formally, it’s often correcting an already established system rather than guiding its evolution.

Start Small, But Start Explicitly

Governance does not need to begin as a framework or a product.

It can begin as a small set of explicit practices.

For example:

Assign a clear owner for each AI feature
Require pull request review for prompt or instruction changes
Define unacceptable outputs before releasing a feature
Log prompts and outputs for later inspection
Establish basic rules for what data is allowed to reach the model

None of these require a platform.

None of them require a large organization.

But each one introduces a constraint, and those constraints shape how the system evolves (noticing a pattern here?).

Governance as an Iterative System

These practices don’t need to be complete from the start.

They can (and should) evolve.

As the system grows, you might add:

more structured evaluation processes
clearer data classification rules
formal review cadences
stronger enforcement through tooling

At some point, a governance platform may make sense.

But by then, it is supporting an existing set of practices rather than defining them.

That distinction matters.

A tool can reinforce governance, but it cannot replace it.

Where This Fits Architecturally

In previous posts, I’ve written about architectural constraints — boundaries, layering, and ubiquitous language.

Governance plays a similar role.

It constrains how a system is allowed to change.

Without governance, systems drift.

With even minimal governance, that drift slows down: not because change is prevented, but because change becomes deliberate.

A Practical Way to Think About Readiness

One of the reasons I built a small AI readiness assessment tool was to make these governance dimensions more visible.

Most teams can answer questions about models or infrastructure.

Fewer can answer questions about:

ownership
traceability
data boundaries
failure handling

Those are the questions that tend to matter later.

If you’re evaluating AI readiness, it’s worth starting there.

Closing Thoughts

AI governance doesn’t need to feel like a large, future initiative.

It can start with a handful of explicit rules.

The important part is not completeness.

It’s that the system begins with constraints.

From there, governance can evolve alongside the system itself, and if a formal governance product or framework becomes helpful when your system becomes sufficiently complex, its integration into that system becomes much smoother.

Architecture Is a Constraint System

Duncan Brown — Tue, 10 Mar 2026 14:58:17 +0000

TL;DR

Good architecture is about more than just structure: It’s about constraints that limit how a system can decay as it evolves.

Patterns from domain-driven design such as bounded contexts, aggregates, and ubiquitous language work because they restrict how change can occur.

When people talk about software architecture, the conversation usually centers on structure.

We draw diagrams showing layers, services, modules, and boundaries. We talk about patterns like ports and adapters or hexagonal architecture. The focus tends to be on how the system is arranged.

But arrangement is only the visible part of architecture.

The deeper role of architecture is to define how a system is allowed to evolve.

Every architectural choice introduces constraints: rules about which components may depend on others, how concepts are expressed in code, and where certain kinds of logic are permitted to live. These constraints rarely attract much attention when things are going well. They mostly become visible when they are violated. That's a big part of their job, after all.

Without them, systems still function. Code compiles. Features ship. But the system gradually becomes harder to reason about, especially for humans. Dependencies spread, terminology drifts, and the boundaries that once made the design understandable begin to blur.

Well-designed architecture slows that process down: Not by preventing change, but by narrowing the range of changes that are possible without deliberate effort. A good architecture also makes it easy to add to the system and evolve it.

This is why architectural discipline matters most when a system begins evolving quickly. The faster a system changes, the more valuable those constraints become.

Constraints in Practice

Architectural constraints often appear in patterns that experienced developers recognize immediately, even if we rarely describe them explicitly as constraints.

Consider dependency direction in a layered or hexagonal system: In a ports-and-adapters architecture, the domain model defines the core policy of the system, while infrastructure implements the mechanisms that support it. Dependencies flow inward toward the domain, not outward from it.

That rule is not just stylistic. It constrains how the system evolves. When infrastructure concerns leak into the domain layer — logging, persistence frameworks, messaging libraries, etc. — the domain model becomes coupled to its environment, something which any most architectures work to avoid. Over time, the domain stops representing the business and starts representing the technology stack. Whether in focused microservices or expansive monoliths, the result is the same: the domain stops representing the business.

Domain-driven design introduces several patterns that reinforce this same idea.

Bounded contexts constrain where particular models are allowed to exist. A concept that is meaningful in one context may not belong in another. Crossing that boundary without translation creates ambiguity. It also potentially allows for duplicated, unaligned implementations.

Anti-corruption layers (ACLs) provide another form of constraint: They prevent external models from directly shaping or unduly influencing the internal domain model, forcing integration to occur through a deliberate translation step. Without that boundary, external concepts tend to seep into the core model.

Aggregates also function as constraints. They define consistency boundaries within the domain, limiting where invariants must hold and how state changes are coordinated. This restricts how data can be modified and prevents uncontrolled coupling between entities.

Even a ubiquitous language acts as a constraint system. When domain terminology is shared between developers, domain experts, and stakeholders, the codebase becomes an executable form of the language of the business. Renaming or redefining those concepts becomes a deliberate architectural decision rather than a casual refactor.

None of these patterns exist merely to make diagrams "look neat."

They restrict how change can occur, and that restriction is precisely what makes systems of all sizes understandable over time.

When Constraints Are Missing

When these constraints are weak - or, worse, implicit - systems do not fail immediately.

They drift, as we've discussed in some of my earlier posts.

Bounded contexts begin to blur as concepts migrate between modules without translation. External models slowly reshape internal ones because no anti-corruption layer stands in the way. Aggregates lose their consistency boundaries as logic spreads across services. The ubiquitous language fragments as developers introduce new terms that appear clearer locally but weaken the shared vocabulary of the domain.

Each change is individually reasonable.

Taken together, they gradually dissolve the architecture.

This is why architectural discipline rarely fails all at once. Instead, it erodes through a sequence of small decisions that no one notices until the system becomes difficult to reason about.

At that point, the architecture no longer constrains the system’s evolution.

Instead, it merely documents what once existed.

Encoding Constraints

Conceptual patterns alone are rarely enough to preserve architectural intent over time.

Rather, they must be reinforced by artifacts and tooling that make those constraints explicit.

Some will argue that these practices amount to over-engineering, especially for smaller systems.

These arguments couldn't be further from the truth.

It's like having a disaster recovery plan: Too many businesses believe they don't really need one; that is, until their first data catastrophe.

Architectural artifacts provide the human-readable layer of governance. A specification document, a ubiquitous language definition, or a context map makes the intended structure of the system visible. These artifacts capture decisions that would otherwise live only in conversations or memory.

Tooling provides the enforcement layer and pays immediate dividends.

Static analysis rules, architectural tests, or module boundaries ensure that violations are caught early. Tools like ArchUnit (a favourite of mine) can verify dependency direction, preventing infrastructure concerns from leaking into the domain layer or enforcing separation between contexts.

Together, these layers create a system of overlapping constraints.

The artifacts describe the architecture.

The tooling defends it.

This combination makes architectural intent durable enough to survive the natural pressure of ongoing change.

This is the real (not-so-)secret sauce when it comes to software engineering.

Architecture and Change Velocity

Constraints matter most when systems begin to evolve quickly.

As systems grow and change accelerates, implicit assumptions begin to fail.

Features are added by new developers who were not present when the architecture was first established. Integrations multiply. Refactoring becomes more frequent. Small changes accumulate across multiple bounded contexts.

When this happens, architecture stops being a static description of the system and becomes a mechanism for governing its evolution.

The patterns described earlier — bounded contexts, anti-corruption layers, aggregates, ubiquitous language — are not simply modelling techniques. They are also constraints that limit how the system can change without deliberate effort.

Tooling and architectural artifacts reinforce those constraints.

Architectural tests prevent dependencies from drifting in the wrong direction. Explicit ubiquitous language definitions anchor meaning across teams. Context maps clarify where concepts are allowed to exist.

These mechanisms do not eliminate change -- they shape it, and that shaping becomes increasingly valuable as the rate of change increases.

Closing Thoughts

Software architecture is often described in terms of structure: layers, modules, services, and patterns.

In practice, its deeper role is to constrain the ways a system can decay.

When constraints are clear, enforced, and shared across the team, systems can evolve quickly without losing their integrity. When they are implicit, erosion becomes almost inevitable.

Domain-driven design provides many of the conceptual tools needed to establish those constraints. Tooling and governance practices help ensure they remain intact as systems grow.

Architecture, in this sense, is about preserving a system's ability to remain understandable as it changes, not just designing them.

This becomes even more important in environments where systems evolve rapidly — whether driven by larger teams, increased automation, or AI-assisted development.

Why Most Teams Overestimate Their AI Readiness (It’s an Architecture Problem)

Duncan Brown — Thu, 05 Mar 2026 19:06:02 +0000

Integrating an AI model into an application is relatively straightforward.

Building a system that can safely evolve once AI becomes part of it, however, is not.

When organizations talk about “AI readiness,” the conversation usually centers around questions like:

Which model should we use?
Which vendor should we choose?
How good are our prompts?
Can our infrastructure handle the load?

While those questions do matter, they rarely determine whether an AI-enabled system remains stable over time.

In practice, long-term success depends far more on the surrounding architecture and governance of the system itself.

AI readiness is more a question of architecture and not one of tooling.

TL;DR

AI readiness is often framed as a tooling problem; one of models, APIs, or infrastructure.

In practice, it’s usually a governance problem.

Systems that successfully ship AI features tend to have:

explicit architectural boundaries,
clear domain language,
operational guardrails,
and processes that can absorb increased change velocity.

Without those, AI not only adds capability, but it also accelerates architectural drift.

Integration Is the "Easy" Part

Most modern backend systems can integrate an AI model with relatively little effort. Third-party APIs and services have made sure of that.

You add an adapter, wire up an API call, and expose a new capability through the application layer.

Heck, you might even introduce a full-on Anti-Corruption Layer.

At that point, the system appears “AI-enabled.”

But integration success is not the same thing as production readiness.

Once AI becomes part of a system, the nature of the system itself changes.

AI features introduce new forms of behaviour that traditional application architectures were not designed to govern:

outputs that are probabilistic rather than deterministic
decisions that must be traceable after the fact
prompts and model configurations that evolve over time
operational guardrails that must be enforced outside the core domain model

These concerns expand the governance surface area of the system.
In other words, the system begins evolving faster.

And faster evolution exposes weaknesses in architectural discipline.

AI Readiness Is Governance Maturity

A system that is genuinely ready to support AI features tends to demonstrate several characteristics:

Architectural boundaries are explicit and enforceable.
Domain language is clearly defined and consistently applied.
Refactoring discipline is supported by automated tests.
Governance mechanisms exist to prevent silent structural drift.
Teams can increase change velocity without destabilizing the system.

These characteristics have little to do with AI itself: They are properties of a well-governed software architecture.

AI simply makes them non-optional.

Where Systems Actually Break

When problems appear, they rarely originate in the model itself.

They usually emerge in the surrounding system.

For example:

Architectural boundaries begin to erode as AI-related behavior spreads across layers.
Cross-cutting concerns such as logging, tracing, or validation leak into domain code.
Domain language becomes inconsistent as new abstractions appear.
Review processes struggle to keep up with change velocity.

None of these failures are caused by AI directly.

They are symptoms of insufficient governance, and AI increases the rate at which those weaknesses surface.

Evaluating Readiness

Because these factors are architectural rather than purely technical, they are often overlooked when organizations evaluate readiness.

More useful questions tend to look more like this:

Who is accountable for the behaviour of this AI feature?
What categories of data are allowed to reach the model?
Can the system reconstruct an AI-driven decision end-to-end?
How are unacceptable outputs defined and tested?
What happens operationally if the feature fails?

These questions are less about models and more about governance.

They determine whether the surrounding system can sustain AI behaviour safely over time.

Those governance dimensions — such as accountability, data boundaries, observability, guardrails, and incident response — are far more predictive of long-term success than model selection.

A Structured Assessment

To make these dimensions easier to reason about, I built a small readiness assessment tool that evaluates AI adoption through an architectural and governance lens.

The assessment uses a deterministic scoring model to evaluate areas such as:

architectural boundary discipline
governance maturity
semantic alignment
observability and auditability
tolerance for increased change velocity

Rather than focusing on vendor selection or model capabilities, the goal is to surface structural and governance risks that often remain implicit.

If you're curious, you can try the assessment here:

AI Feature Production Readiness Assessment

The goal isn’t to produce a definitive score; rather, it’s to make architectural and governance readiness visible before AI accelerates the system’s evolution.

Closing Thoughts

AI does not fundamentally change software architecture, but it does change the rate at which systems evolve.

When evolution accelerates, implicit rules become fragile, as I've discussed in a previous article.

In the AI era, readiness is less about models and more about governance.

Architectural discipline determines whether speed becomes progress — or erosion.

AI Coding Assistants and the Erosion of Ubiquitous Language

Duncan Brown — Fri, 27 Feb 2026 22:09:37 +0000

In my previous two posts, I’ve written about integrating AI into Spring Boot systems without collapsing architectural boundaries, and about how AI-assisted refactors can quietly erode layering.

There’s another form of drift that’s even subtler still:

Semantic drift.

AI coding agents don't just change structure faster. They change language faster.

Ubiquitous Language Is Structural, Not Cosmetic

In domain-driven design, ubiquitous language isn’t just naming preference.

It’s the shared vocabulary across:

Developers
Domain experts
Product owners
Stakeholders

When done well, the code mirrors the language of the business. This has the obvious benefit of allowing technical and non-technical people to describe and understand the same concepts with little friction.

The name of an aggregate, entity, value object, or concept is not arbitrary — it encodes meaning.

That meaning becomes part of the system’s architecture.

Meaning is easier to erode than structure.

Let's see how.

A Simple Example of Semantic Drift

Imagine a domain centred around document reviews.

public class Review {
    private Score score;
}

In the business, everyone says:

“Review”
“Score”

We'll assume for now that the definitions of those terms are implicit; that is, it's assumed that everyone "just knows" what someone is talking about when they use the words "Review" and "Score", and that there is no explicitly defined ubiquitous language.

Now imagine asking an AI assistant to “improve naming clarity", “refactor for readability", or even, "implement a more robust and comprehensive scoring system".

You might end up with:

public class Assessment {
    private Rating rating;
}

From a purely linguistic perspective, this looks reasonable.

From a domain perspective, however, it may not be, and in fact most likely is not.

If stakeholders still talk about “reviews” and “scores,” but the code now talks about “assessments” and “ratings,” the shared language has split.

Nothing breaks; tests still pass; layers remain intact.

But meaning has drifted. Developers begin to make use of these new terms, eschewing the "older" versions, even as those new terms begin to take on additional meanings.

Now imagine a meeting between the developers, management, and stakeholders. When one side refers to either set of terms, one of two outcomes is likely:

The other side(s) quietly assume that the use of the term is synonymous with their term, and so too is their understanding.
The other side(s) question the use of the term, and the side using the term does some vocal hand-waving and says, "They're pretty much the same thing," which may or may not be accurate.

Either way, the door has been opened for future issues that will likely compound over time.

(There's actually a third, correct way to handle the above scenario, and that is to actively question the use of the term and insist on establishing an explicit, mutually-understood definition and to add it to a shared ubiquitous language document.

Obvious - and frequently ignored.)

The Real Risk

Layering drift breaks structure.

Semantic drift breaks alignment.

A system can preserve its ports and adapters and still lose its conceptual integrity.

Once a ubiquitous language fragments - or is never formalized in the first place:

Discussions become translation exercises.
Onboarding slows down.
Invariants become harder to reason about.
Governance loses its anchor.
Refactoring becomes riskier because intent is no longer clear.
Assumptions and connotations make their way into code.

And AI accelerates this.

AI assistants frequently:

Introduce “more common” synonyms.
Replace domain-specific terms with generic ones.
Suggest loaded abstractions like Manager, Handler, or Processor.
Collapse business vocabulary into framework vocabulary.

As with AI-assisted refactors, none of these changes are malicious.

They might be locally optimal.

But neither structure nor semantics are local.

They are cumulative.

Making Ubiquitous Language Explicit

If structural boundaries need governance, so does language.

Ubiquitous language should live not only:

In conversations.
In someone’s head.
In scattered comments.

It should exist as a canonical artifact.

Although it may sound tempting, don't bury that artifact in AGENTS.md, and don't allow that "artifact" to be implied by class names alone.

Something like a dedicated spec.md or ubiquitous-language.md file. I prefer to put mine in a dedicated docs/ folder off the project root.

Ideally, it should be structured and machine-parseable. Even a YAML file is a good idea.

For example:

Review:
  definition: An evaluation of a submitted document.
  invariants:
    - Has exactly one Score.
    - References one Document.
  synonyms_disallowed:
    - Assessment
    - Evaluation

Score:
  definition: A normalized integer between 0 and 100 representing review quality.
  invariants:
    - Range: 0..100
  synonyms_disallowed:
    - Rating

This is not documentation for humans alone.

It can be:

Referenced during code review.
Used to validate naming conventions.
Fed into AI prompts as a constraint.
Parsed by tooling to generate glossaries.
Used by front-end interfaces to maintain consistency.

Once language is explicit, it can be protected.

The language must be versioned. Any proposed change to the language should go through an established workflow and agreed upon by all required parties. Rolling back should be as simple as rolling back to a previous commit. I cannot stress this enough.

Some additional guidelines for using your ubiquitous language artifact:

Ideally, keep it in a single shared repository and treat it as the sole source of truth. I prefer to keep mine in a backend application that has tasks for exposing and/or exporting the language for consumption by other projects.
It can (and should) also be updated as necessary.
Add a guardrail to your AGENTS.md to let the coding agent know not to introduce any new terms or concepts that aren't already a part of the ubiquitous language definition.
Have the agent confer with the developer should the agent feel a new term or concept should be used.
Tokenize the terms and verbiage of any user-facing interfaces (e.g. web apps) to draw from the ubiquitous language. A great bonus use of this is for hovering over domain terms as a form of embedded glossary.

Governance Protects Meaning

Architectural governance is not only about enforcing layers.

It is about preserving intent.

There are at least two dimensions to protect:

Structural boundaries (what depends on what).
Semantic boundaries (what things mean).

Structural governance might be enforced through:

ArchUnit rules.
Module boundaries.
Build-time checks.

Semantic governance requires:

Canonical definitions.
Explicit vocabulary.
Deliberate review of term changes.
Guardrails in AI-assisted workflows.

If AI is part of your development process, it must be aligned not only with your layering rules, but with your language.

AI cannot respect a domain vocabulary that is not formalized.

Closing Thoughts

Structural drift is quiet but visible.

Semantic drift is quieter.

Both compound over time.

If you care about architectural longevity in AI-assisted systems, governance must protect both structure and meaning.

Without that, speed quickly becomes erosion.

When AI Refactors Break Layering (And How to Prevent It)

Duncan Brown — Thu, 26 Feb 2026 23:38:22 +0000

In a previous post, I wrote about integrating AI into a Spring Boot system without compromising architectural boundaries: We can consider that the initial integration problem.

There’s a second, more subtle problem: AI-assisted refactoring changes the risk profile of cross-cutting modifications.

Not all “refactors” are created equal.

Classic refactoring — in the Fowler sense — is local, behaviour-preserving, and structural, e.g.

Extract method.
Rename class.
Move function.
etc.

Those are relatively safe when existing tests are solid.

(In fact, I'd argue that developers are unlikely to attempt a refactor of any import on a production codebase larger than a few classes without automated tests in place. If they value their sanity, at least.)

But many AI-generated “refactors” are not local or even of the Fowler variety.

They are often cross-cutting changes:

Add logging across the application.
Introduce tracing.
Add validation.
Add retries.
Add metrics.

These can and frequently do touch multiple layers at once.

And that’s where architectural boundaries quietly start to erode.

A Concrete Example: Logging Done “Everywhere”

Imagine you ask an AI assistant:

> Add structured logging to the application using SLF4J.

What often happens next is predictable.

You start seeing this appear across multiple classes:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

// Domain aggregate, entity, or value object
public class Review {

    private static final Logger log =
        LoggerFactory.getLogger(Review.class);

    ...
}

From the coding assistant’s perspective, this is a reasonable implementation.

From an architectural perspective, it’s a boundary violation.

Considering the case above, the domain model now depends on an infrastructure concern.

Nothing breaks immediately (most likely), but a rule has been silently crossed.

Now multiply that pattern across tracing, metrics, validation, or retries, and the boundaries/layering start to blur further.

This isn’t a malicious change; it’s just a locally optimal one in the "eyes" of the coding assistant.

It's clear, however, that, unchecked, those changes compound and create possible pitfalls in the future.

The Pattern Behind the Example

Logging is just one example.

As mentioned above, the same pattern shows up when you ask an AI assistant to:

Add metrics across the application.
Introduce tracing.
Add validation rules.
Implement retries or timeouts.

These are all cross-cutting concerns: They touch multiple layers at once.

An AI assistant, optimizing for task completion, will often choose the shortest path:

Import the library directly.
Add the dependency where it’s immediately needed.
Modify multiple classes in place.

From a purely functional perspective, these are reasonable.

From an architectural perspective, it’s risky, because architectural boundaries are rarely (if ever) encoded in the type system alone.

They exist as intent, and intent is fragile when it’s implicit.

("Making the implicit explicit," as Eric Evans suggests, is one of the greatest strengths of domain-driven design, in my professional opinion.)

If architectural boundaries exist only as convention, they will eventually be crossed.

Governance Is About Alignment, Not Rigidity

To be clear, architectural governance is not the same as business rule enforcement.

Domain invariants — things like scoring logic or validation rules — are enforced at runtime by the application itself. They belong within domain aggregate roots.

Architectural boundaries are notably different: They shape how the system is allowed to evolve.

If you’re using DDD or hexagonal architecture (and hopefully you are if you're reading this article), those boundaries are intentional and confer myriad benefits:

The domain does not depend on infrastructure.
Controllers do not bypass application use cases.
Infrastructure does not bleed upward.
Slices remain isolated.

Those "boundary rules" don’t enforce behaviour; rather, they enforce structure, and structure (along with sufficient coverage by automated tests) is what makes long-term refactoring safe.

When changes can be generated quickly — whether by a team of developers or a single developer using AI — I argue that implicit rules are not enough.

Governance needs to exist in more than one form, whether your goal is to leverage AI coding assistance or go "full human" mode:

Human-readable contracts (what the architecture allows).
Build-time enforcement (tests that fail on boundary violations).
AI-aware constraints (so automated edits respect the same rules).

The goal isn’t to create a straitjacket. It’s to ensure that the developer, the compiler, and any AI assistant are all operating under the same architectural intent.

The above makes the implicit explicit. Adding overlapping (but equally responsible) guardrails (automated tests, a well-defined AGENTS.md or CLAUDE.md file, etc.) is the best way to achieve this goal.

Closing Thoughts

Architectural governance isn’t about rigidity. At least, it doesn't have to be.

It’s about alignment — across developers, build tooling, and AI assistants.

When boundaries are explicit and enforceable, refactoring becomes safer and architectural drift slows dramatically.

(For those interested, I’ve packaged these ideas into a small Spring Boot baseline that demonstrates the pattern end-to-end. Details are available in my profile if you’re interested.)

I’ll be writing more on architectural governance and AI-assisted development in the coming weeks. If this topic resonates, feel free to follow along.

AI + Spring Boot: How to Avoid Architectural Drift

Duncan Brown — Mon, 23 Feb 2026 20:31:40 +0000

Over the past couple of years, I’ve watched a lot of teams add AI features to backend systems.

The pattern is predictable.

It starts small:

“Let’s just call OpenAI from this controller.”
“We’ll clean it up later.”

A few weeks later:

SDK types leak into the domain.
Prompt strings are scattered across services.
Tests start hitting real APIs.
Infrastructure concerns bleed into business logic.
The boundaries that once felt clear become blurry.

Nothing explodes immediately; it just becomes harder to reason about.

Teams move fast and often leave discipline for later (only for it to become technical debt).

While this isn't always a big deal, in my experience, it's bitten more teams in the rear end than not.

The Real Risk

AI integration isn’t inherently messy, but integrating it without structural discipline is.

Most examples online focus on:

How to call the API
How to parse JSON
How to stream responses

Very few focus on:

Where that logic belongs
How to preserve domain purity
How to keep tests deterministic
How to prevent provider lock-in
How to keep AI-assisted refactors from eroding structure

That’s where long-term problems start.

A Safer Pattern (DDD + Hexagonal)

If you’re using Spring Boot with DDD or hexagonal architecture (I argue DDD paired with an hexagonal architecture is rarely a bad idea), AI integration should respect the same boundaries as any other external dependency.

We don't need to follow strict DDD for less-complex systems, but, at a minimum:

The domain defines a port.
The application layer orchestrates use cases.
The infrastructure layer implements the adapter.
Profiles control whether you use:
- A stub (deterministic)
- A real provider (OpenAI, etc.)

For example:

// Domain port
public interface AiService {
    AiAnalysis analyzeDocument(DocumentContent content);
}

The domain depends on this interface — not on any SDK.

Then, in infrastructure:

// Infrastructure adapter
public class OpenAiAdapter implements AiService {

    @Override
    public AiAnalysis analyzeDocument(DocumentContent content) {
        // Call provider SDK
        // Parse structured JSON
        // Map to domain AiAnalysis
    }
}

The quick, immediate wins:

Controllers never call OpenAI directly.
The domain never imports SDK types.
Tests can swap in a stub implementation.

Perhaps most importantly, the integration stays contained.

Stub by Default

One pattern I’ve found especially valuable:

Make stub AI the default.

That means:

Unit tests are deterministic.
Local development does not require API keys.
You can simulate issue scenarios reliably.

Then enable the real provider via profile:

SPRING_PROFILES_ACTIVE=openai

This separates development discipline from production capability.

It may sound obvious, especially in the age of TDD, but I still see developers coupling specific AI providers (and, indeed, providers of various services) to their codebase right out of the gates, tests included.

AI-Assisted Development Needs Guardrails

There’s another layer most people ignore at their own peril.

Even if your architecture starts clean, AI coding assistants can gradually degrade it.

Without guardrails, tools will:

Introduce framework dependencies into the domain
Inline prompt strings in controllers
Refactor across layers
Create “utility” dumping-ground classes

The solution isn’t to stop using AI tools, especially when--targeted correctly--they can amplify your skillsets and productivity.

(As a small aside, I've found treating a coding agent as a smart "junior developer" of sorts to be the starting point of an effective mindset.)

It’s to make your architectural constraints explicit.

For example:

Domain purity rules
Ports & adapters boundaries
No SDK usage outside infrastructure
Deterministic testing requirements
Profile-based wiring constraints

Paired with something like ArchUnit (a personal favourite of mine), those constraints become build-time enforcement.

That dramatically reduces architectural drift.

Why I Built a Template Around This

I ended up building a Spring Boot template that demonstrates:

Vertical slice structure
DDD + hexagonal boundaries
AI behind a domain port
Stub AI by default
Profile-gated OpenAI integration
In-memory + Postgres adapters
Flyway migrations
ArchUnit enforcement
An AGENTS.md governance file designed for AI-assisted development

It’s intentionally minimal and doesn’t try to solve every problem.

What it does do is establish a disciplined baseline you can extend safely.

If you’re integrating AI into backend systems and care about architectural longevity, it may be useful to you, even in the age of vibe coding.

Feel free to leave any questions you might have in the comments! And if you think the template I put together might be of use to you, please let me know.