Context Locality: Vertical Architecture Matters More With AI

I saw a tweet a while back that went something like:

Humans like lots of small files. AI prefers one big file. Therefore: architecture is optional now.

It stuck with me because it's exactly backwards.

AI doesn't want one big file. It wants coherent, nearby context. Humans want that too — we just compensate with intuition ("it's probably in Billing/"). AI tools don't have that luxury. They need the structure to be obvious.

If anything, AI makes architecture more important. The cost of unclear boundaries and scattered code has always been there, but now it's amplified because AI tools will confidently build on top of a bad foundation.

What I mean by context locality

Context locality is how much relevant information is reachable from where you're working, without jumping around and guessing.

If an AI tool has to bounce across files, folders, and modules to understand a single feature, it will either miss something, waste its context window navigating, or just hallucinate what it thinks should be there.

This isn't an argument for fewer files. It's an argument for keeping related things together and making the structure legible.

Vertical slices over horizontal buckets

This is the big one. The classic layered approach — controllers in one folder, services in another, repositories in another — has always been a bit annoying to work with. You touch one feature and you're jumping across four folders.

With AI in the mix, it gets worse. An AI working on "create order" needs to understand the full flow: the endpoint, the handler, the validation, the data access, the tests. If those live in five different places organized by technical layer, the tool has to piece together which files belong to the same feature.

Vertical slices fix this:

Features/
  Orders/
    CreateOrder/
      CreateOrderCommand.cs
      CreateOrderHandler.cs
      CreateOrderValidator.cs
      CreateOrderTests.cs
    UpdateOrder/
      ...

Everything for one feature lives together. An AI (or a human) can look at one folder and understand the full picture. No scavenger hunt.

Clean module boundaries pay off more now

In modular codebases, I've seen services that import contracts from seven different modules to do their job. Humans can muddle through that. AI tools really struggle — they'd need to load and understand all seven modules to make a safe change.

The fix is the same as it's always been: reduce the surface area. Hide complexity behind focused interfaces. Keep contracts self-contained so modules aren't secretly coupled to each other.

// This service reaches into 7 modules — hard for anyone to reason about
public class OrderEmailService(ISender sender, IEmailClient emailClient) { }

// Better: one dependency that encapsulates the data gathering
public class OrderEmailService(IOrderEmailDataProvider dataProvider, IEmailClient emailClient) { }

These are patterns we've known about forever — dependency inversion, interface segregation, bounded contexts. The difference is that AI makes the cost of not doing them more visible and more immediate.

Composition over inheritance (still)

Deep inheritance chains across files are another pain point. If Order extends AggregateRoot which extends Entity, that's three files to understand one class. AI tools often don't follow the full chain, so they miss base class behavior and write broken code.

Keep hierarchies shallow. Prefer composition. This has been good advice for decades — it just matters more now.

Put documentation where the work happens

Most teams have architecture docs buried in a docs/ folder somewhere. Nobody reads them, and AI tools definitely won't find them when working in src/Modules/Notifications/.

A short README at the module root goes a long way:

# Notifications Module

Handles real-time updates via SignalR. Consumes integration events
from other modules and pushes updates to connected clients.

## Event flow
Orders -> OrderStatusChanged -> Notifications -> SignalR -> UI

Not a novel. Just enough to orient. This is architecture that's discoverable.

The point

None of these ideas are new. Vertical slices, clean boundaries, composition over inheritance, colocated docs — we've been talking about these patterns for years.

What's changed is the feedback loop. With AI tools in your workflow, bad structure hurts faster and more visibly. A messy codebase doesn't just slow down developers — it produces worse AI-generated code, more hallucinations, and more time spent fixing the output.

Good architecture has always been worth it. AI just makes that harder to ignore.