Forget massive context: build smarter architecture

There is a strange assumption hiding inside the way we talk about AI coding assistants: 

“just give the model more context”

It sounds reasonable.

• If the model doesn't understand the codebase, give it more files.
• If it doesn't understand the architecture, give it more documentation.
• If it makes the wrong change, include more history.
• If it misses a dependency, dump the repository into the prompt.

But there is a problem!

More context is not the same thing as more understanding.

And as AI-assisted software development matures, the distinction is going to become one of the most important architectural considerations in engineering teams.

The future isn't about building systems that can shove an entire codebase into an AI model.

It is about building systems that find, compress, prioritize, and verify the right context.

That is a very different problem.

The “big context” window trap!

Imagine you have a 2-million-line enterprise application.

A developer asks an AI coding agent: “add support for a new payment provider”

The agent potentially needs to understand:

1. payment interfaces
2. authentication
3. database models
4. retry policies
5. webhook handling
6. background jobs
7. logging
8. monitoring
9. configuration
10. tests
11. deployment
12. security policies
13. existing providers
14. architectural conventions

So the instinct is: Give it everything.

But imagine doing the same thing with the human engineer. You wouldn't hand them two million lines of code and say “understand this.”

You would say:

“Here is a payment module. Here is how the providers are registered. Here is the interface. Stripe is the closest existing implementation. These are the tests. Here is the deployment constraint.”

In other words, experienced engineers don't operate the maximum context. They operate with relevant context.

AI systems need the same architectural advantage.

Context is becoming an architectural resource

For years, we treated architecture primarily as a way of managing:

• compute
• memory
• latency
• storage
• network boundaries

Now there is another resource to think about: machine-readable context.

Your architecture determines how easily an AI system can answer questions such as: 

• Where does this behavior live?
• Which component owns this decision?
• What is safe to change?
• What must remain backward compatible?
• Which implementation is canonical?
• Which tests define the expected behavior?
• Which documentation is actually authoritative?

That means architectural quality increasingly has a second audience: humans and machines.

And these audiences have surprisingly similar preferences. Both perform better when systems have:

• clear boundaries
• meaningful names
• small modules
• explicit contracts
• predictable conventions
• discoverable dependencies
• authoritative documentation

Good architecture has always reduced cognitive load for humans. Now it can reduce context load for machines too.

Stop thinking “more context.” Start thinking “Context Engineering”

A useful model is: Context = retrieval + compression + prioritization + validation

Suppose an agent needs to modify an order-processing workflow. Instead of supplying the entire repository, give it a context package:

Task
 └── "Add cancellation support"
 
Relevant architecture
 ├── OrderService
 ├── OrderStateMachine
 └── CancellationPolicy
 
Reference implementation
 └── RefundWorkflow
 
Contracts
 ├── Order API
 └── Event schema
 
Tests
 ├── cancellation tests
 └── refund tests
 
Constraints
 ├── existing API cannot change
 └── cancellation must be idempotent

That is dramatically more useful than:

Here is the repository. Good luck.

The interesting architectural question becomes:

How can our systems automatically assemble that package?

That is where things get interesting.

Design codebases for retrieval

A codebase should not merely be executable. It should be navigable.

Consider these 2 functions: 

def process(data):

And

def calculate_refundable_order_amount(order, refund_policy):

Humans can eventually figure out what the first function does. An AI system has a much easier starting point with the second. 

Names become metadata. Directories become metadata. Interfaces become metadata. Tests become metadata. Commit history becomes metadata. Architecture decision records become metadata. This doesn't mean writing code for an AI. It means recognizing something we should have recognized anyway: ambiguity is expensive. 

Make boundaries explicit

One of the worst things you can give an AI agent is a codebase where everything talks to everything. 

Imagine: 

Controller
↓
Service
↓
Helper
↓
Another Helper
↓
Global Utility
↓
Database

Except the “helper” also calls another service, which publishes an event, which triggers a background job, which updates the original entity. Good luck. 

A human engineer needs a significant mental reconstruction to understand the flow. An AI agent does too. Clear boundaries make context smaller. For example:

API
↓
Application Service
↓
Domain
↓
Repository

Now each layer answers a different question. The agent can reason locally before reasoning globally. That's a huge advantage.

Build “Context Hubs”

Every major subsystem should have a small, authoritative entry point. Think of it as a README for machines and humans. For example:

/payments
README.md
architecture.md
contracts/
providers/
tests/

The README might answer:

Purpose:
Handles payment authorization and capture.
Entry point:
PaymentService
Important invariants:
- Payment IDs are immutable.
- Authorization is idempotent.
- Provider failures must not alter order state.
Canonical implementation:
providers/stripe.py
Related tests:
tests/payments/

Now an agent doesn't need to discover all of that from 47 files. You have created a context hub. The best context hubs are intentionally boring. That is a compliment!

Treat documentation like an API

Most engineering documentation fails because it describes what the system used to be.

AI agents need documentation that explains what the system means now.

A useful architecture document should answer:

Why does this component exist? What does it own? What does it not own? What assumptions does it make? What must never change?

The last question is particularly valuable. 

Consider: “Do not call the payment provided directly from controllers”.

That's far more useful than three paragraphs explaining the payment architecture. It gives an agent a constraint. Constraints are powerful because they reduce the solution space.

Keep context fresh

Here's an uncomfortable truth: Still documentation can be worse than no documentation.

Suppose your architectural document says: orders are persisted in PostgreSQL. But six months ago the team introduced an event-sourced order history.

An AI agent retrieves the document and confidently builds against the old model.The problem wasn't that the model lacked context. It had incorrect context.

So teams should start thinking about documentation freshness the same way they think about dependency freshness. A simple rule: If a piece of documentation influences engineering decisions, it should have an owner and a freshness signal.

Even a tiny header helps:

Owner: Payments Team
Last reviewed: 2026-07-18
Canonical code: /payments
Status: Active

Give agents “Representative Examples”

An EA system often learns faster from a good example than from a giant rule book. Suppose your team has a preferred pattern for adding API endpoints. Don’t merely document the pattern. Point the agent to the best existing implementation.

For new authenticated endpoints,
use OrdersController.create()
as the reference implementation.

This is powerful because the example contains dozens of implicit conventions:

• naming
• error handling
• validation
• logging
• authorization
• testing
• response formatting

Architecture reviews should include a new question

Traditional architecture reviews ask:

• Is this scalable?
• Is this secure?
• Is this maintainable?
• Is this reliable?
• Is this observable?

Add another: Can an AI agent understand and safely modify the system without reconstructing the entire architecture?

That question doesn't mean architecture should be optimized for AI at the expense of humans.

Quite the opposite.

If the answer is yes, your system probably has:

• good boundaries
• explicit contracts
• discoverable ownership
• coherent naming
• useful tests
• current documentation

 Those are characteristics humans appreciate too.

The new architecture skill: context budgeting 

I think engineering teams will increasingly develop something that looks like a context budget.

For a given task:

Task
↓
Identify subsystem
↓
Retrieve architecture
↓
Retrieve constraints
↓
Retrieve canonical examples
↓
Retrieve relevant tests
↓
Make change
↓
Validate against invariants

The goal isn't: “how much can we put into the model?” The better question is: “What is the smallest context package that lets the system make a correct decision?”

That’s a much healthier optimization target.

A practical checklist:

Before handing an AI agent a non-trivial task. Ask:

 Architecture:

• Is the owning subsystem obvious?
• Are boundaries explicit?
• Is there a canonical implementation?

 Documentation:

• Is there one authoritative source?
• Is it current?
• Does it explain constraints and invariants?

 Code:

• Are names meaningful?
• Are dependencies discoverable?
• Are important behaviors covered by tests?

 Context:

• Can irrelevant files be excluded?
• Can related examples be retrieved?
• Can architectural constraints be supplied automatically?

Validation:

• Can the agent run targeted tests?
• Can architectural invariants be checked?
• Can humans quickly review the resulting change?

If most answers are “yes”, your codebase is already becoming AI-native without needing to rewrite it for AI.

The overarching idea

The next generation of software architecture wants to just be about making software easier to run. It will also be about making software easier to understand. For humans, that means lower cognitive load. For AI agents, that means lower context load. And those two goals are surprisingly aligned. So don't ask:

How do we fit our entire codebase into the model?

Ask: How do we redesign our systems so the right 1% of the code is easy to find?

That's the architectural problem worth solving.

‍