This is the first article in a series about AI-friendly architecture, a way of thinking about systems, context, and tools so that AI agents can work more effectively with real-world software.
Maybe the best way to think about an AI working in your system is to imagine a new person entering the company.
They don’t know the domain yet, they don’t know which services exist, they don’t understand past decisions, and they don’t know where to find the answers. To start contributing, they need to go a onboarding process.
This person may try to figure things out. They may also ask someone more experienced. But when knowledge is well documented, they can find the answers on their own and move forward with greater autonomy.
Something similar happens with AI agents. The more an agent depends on a specific person, informal context, or the memory of someone who already knows how to perform a task, the worse it performs.
The goal of an AI-friendly architecture is to make this knowledge more explicit, accessible, and easier to navigate. Not only for AI, but also for anyone new joining the team.
Over the past few years, the way we build software has changed considerably. First, we learned how to scale systems. Then, we learned how to modularize code. Later, we started separating responsibilities, distributing services, and organizing teams around context. Now we are entering a new phase: creating software that is not only used by people, but can also be understood by AI agents.
This may seem subtle at first, but it changes quite a lot. An agent does not understand your system in the same way an experienced developer does. It needs signals, context, structure, and paths for discovery. If that context is not well organized, AI can still help, but it will work with more noise, more trial and error, and less precision.
The problem is not a lack of intelligence
When an AI makes a mistake while analyzing a system, the most common explanation is usually: “the model is not good enough.” Sometimes that is true. But many failures happen for another reason: the system was designed for people who already know the context, not for agents that need to discover it.
An in-house developer knows:
where the relevant documentation is;
which decisions were recorded in old ADRs;
which service owns each responsibility;
where to look in the event of an incident;
which metrics indicate that something is actually wrong.
By default, an agent does not know any of this. It can figure out some things on its own, but it still needs clear context. When context is scattered, hidden, or inconsistent, the quality of the response declines as well.
Code Is Not Enough Context
There is a common trap: assuming that because AI can read code, it already understands the system.
But code is only part of the story.
Code shows the implementation. It does not necessarily show:
why that decision was made;
which business problem it solves;
which trade-offs were accepted;
which parts are sensitive;
what has already been tried and discarded;
how the system behaves in production.
In practice, a mature system exists in more places than the repository. It lives in documentation, observability, incidents, tickets, architectural decisions, dashboards, and the team’s collective memory. The challenge now is to transform this knowledge into something an AI can navigate.
Architecture That Agents Can Understand
If I had to summarize the central idea of this article in one sentence, it would be this:
AI-friendly architecture is the discipline of organizing systems so that agents can discover, correlate, and apply context with minimal friction.
This does not mean exposing everything to AI. On the contrary, it means making context:
more accessible;
more structured;
more reliable;
more connected;
more verifiable.
In other words, having information is not enough. Information needs to be discoverable and combinable.
What This Changes in Practice
An AI-friendly system tends to have a few characteristics:
Living documentation
Documentation cannot be a graveyard of outdated pages. It needs to be part of the system and keep up with relevant changes.Recorded decisions
Architecture without history becomes guesswork. ADRs, RFCs, and decision notes help the agent understand the “why,” not just the “how.”Observability as a source of truth
Logs, traces, and metrics are not only used to operate the system. They also help explain its behavior.Context organized by domain
Not all knowledge needs to live in the same place. Each context can have its own documentation, rules, and reference points.Tools connected to the workflow
The agent needs access to systems that actually tell the story of the software: observability tools, backlogs, repositories, incidents, and deployments.
The Old Way of Organizing Software
This conversation reminds me a lot of the evolution of microservices.
In the past, we tried to put everything into large and centralized systems. Over time, we learned that it made more sense to separate things by domain, responsibility, and context. Not because splitting things up is elegant, but because smaller systems with clear boundaries are easier to understand and evolve.
Now the question is similar:
If we have learned to decompose systems by context, why do we continue delivering context to AI in massive blocks?
Maybe the next evolution is this: not only decomposing services, but also decomposing the knowledge that powers agents.
The Role of Skills
This is where an important piece comes in: skills.
A skill is a way of packaging specialized context. Instead of giving the agent an ocean of generic information, you provide clear, well-bounded blocks of knowledge.
Think of examples such as:
a skill for Datadog;
a skill for Argo;
a skill for Databricks;
a skill for New Relic;
a skill for incident investigation;
a skill for performance analysis;
a skill for production changes.
The idea is not to make the agent know everything at the same time. It is to allow it to activate the right context at the right time.
This reduces noise and increases precision. Instead of trying to read everithing the agent works with context that is more specific and focused on the problem.
A Simple Example
Imagine that an incident has started affecting an API’s latency. Without an AI-friendly architecture, the agent may still try to help, but it will depend heavily on luck:
looking for logs in the wrong places;
interpreting dashboards without knowing which metrics matter;
wasting time on irrelevant paths;
suggesting generic hypotheses.
With better-organized context, the workflow changes:
The agent identifies the affected service.
It consults the domain documentation.
It correlates observability signals.
It finds the related architectural decisions.
It focuses the investigation on the most likely hypotheses.
The benefit here is not that AI performs magic. It is that the system is prepared for AI to work with less friction and greater precision.
What Is Worth Starting Now
If you want to get started in a practical way, I would suggest four areas of focus:
review the system’s most important documentation;
record architectural decisions more consistently;
improve operational clarity through observability;
separate contexts that are currently too mixed together.
You do not need to transform everything at once. In fact, the best approach may be to start with the areas where the team struggles most: incidents, onboarding, and changes in critical areas.
Conclusion
Software that is ready to be understood by AI is not software “built for robots.” It is software with context that is clearer, more accessible, and more useful to anyone or anything that needs to understand the system quickly.
At its core, the idea is simple: if architecture helps people make better decisions, it can also help agents make better decisions.
And maybe this is the next major evolution of software architecture: not just systems that scale, but systems that can be quickly understood by humans and agents working together.
This was only the beginning. In the next article, I will discuss why code is not enough context and how to design a Context Architecture for agents by connecting code, documentation, architectural decisions, and business knowledge.
Comments