# Code Is Not Context: Designing a Context Architecture for Agents

This is the second article in a series about AI-friendly architecture. In the first article, I explained how AI is like a new person joining a company and trying to understand a system for the first time.

Now I want to explore an important part of this comparison: where does this person find the information they need?

## Code Is Only Part of the Story

When someone new joins a team, they usually start with the repository. That is where the services, endpoints, models, tests, and business rules are.

But code rarely answers everything.

It may show that a decision exists, but not explain why it was made. It may show that two services communicate, but not make it clear which service owns that responsibility. It may show a business rule, but not explain when it applies or what happens when it changes.

To truly understand a system, a person needs to combine several sources:

*   code;
    
*   documentation;
    
*   architectural decisions;
    
*   tickets and epics;
    
*   previous incidents;
    
*   dashboards and metrics;
    
*   conversations with team members.
    

The same is true for AI agents.

The problem is that, in many companies, this information exists but is not connected. The code is in a repository. The decisions are in a documentation tool. The tickets are in another system. The incidents are in an operations platform. And the most important context is still in the minds of a few people.

Having information is not the same as having context.

## What Is a Context Architecture?

I like to think of Context Architecture as a way to organize and connect the different sources of knowledge that explain a system.

It is not about creating one huge document with everything the company knows. It is also not about copying all the documentation into a vector database and waiting for the answer to appear.

It is about creating paths that help a person or an agent answer questions such as:

*   What is this service responsible for?
    
*   Which other systems depend on it?
    
*   Why was it built this way?
    
*   Which business rule is being used here?
    
*   How do we know that it is working correctly?
    
*   What happened the last time this part changed?
    

A well-designed context architecture does not remove the need for reasoning. It reduces the effort needed to find the right information.

## Context Does Not Need to Be in One Place

We may want to put everything in one place. We could create a big page called “How the Company Works” and expect everyone to find what they need there.

In practice, this document becomes outdated very quickly. It becomes hard to know what is still valid, who should update it, and which part applies to each situation.

Maybe it is better to think of context as a network:

![Context Architecture](https://cdn.hashnode.com/uploads/covers/67081fa628a6c4cdb75a7fc9/9fb6215a-d1db-49a0-bd1b-59c5db990aab.png align="center")

Each source can stay where it works best. What changes is that there are clear links between them.

A task should point to the affected domain. The domain should point to the services involved. The service should have its operational documentation. Important decisions should be recorded. Production signals should also be easy to find.

The goal is not to centralize knowledge. The goal is to make it easy to find.

## Example Structure

Let’s imagine a payments domain. The code may be in a repository, while the documentation, ADRs, and runbooks stay in the tools the team already uses:

![Distributed context: payments](https://cdn.hashnode.com/uploads/covers/67081fa628a6c4cdb75a7fc9/2b3eab9e-984a-4bb7-94c2-3ade8f135b7f.png align="center")

The repository’s `README.md` can explain the service’s responsibility and link to the `Architecture Hub`. The `context.md` page can describe business concepts and domain boundaries. ADRs can stay in an architecture tool, runbooks can stay in a documentation platform, and dashboards can stay in the observability tool.

The `links.md` file does not need to copy the content from these sources. It can work as a trusted index, with links to where each piece of information is stored.

An agent that receives a payments task does not need to read every file in the repository right away. It can start with the domain map, follow the links related to the task, and check each source at the right time.

The most important part of this structure is not putting everything in the same folder. It is making clear where each type of knowledge lives and how to reach it.

## Context Needs an Owner

Documentation without an owner usually becomes abandoned documentation.

If no one knows who should update a page, the page will become outdated. If an architectural decision does not say who made it and why, it may later look like a rule with no reason.

That is why a Context Architecture also needs to answer:

*   Who is responsible for this context?
    
*   When was it last updated?
    
*   Which system is the original source of this information?
    
*   How do we know that it is still valid?
    

People and AI agents both need this. An agent may find a useful page, but it still needs to check if the information is up to date, belongs to the right system, and is useful for making a decision.

Context without a clear validity signal can be as dangerous as having no context at all.

## The Role of Architectural Decisions

One of the most valuable sources of information about a system is the history of its decisions.

The current code shows the result of many choices. An ADR helps explain those choices.

It can record:

*   the problem that needed to be solved;
    
*   the options that were considered;
    
*   the criteria used to make the decision;
    
*   the trade-offs that were accepted;
    
*   the expected results.
    

Without this history, someone may look at an implementation and think that it could be much simpler. Maybe it could. But there may have been a constraint that is no longer visible in the code.

For an agent, this difference is very important. Without the context behind a decision, it may suggest a technically elegant change that does not fit a real business need or a known operational limit.

## Context Should Follow the Workflow

Another important point is that context should not be treated as a separate activity from development.

If documentation is updated only during one big review each year, it will fall behind. If ADRs are written only when someone remembers to write them, many important decisions will disappear. If incidents do not leave written lessons, the team will investigate the same problems again and again.

Context needs to be part of the normal workflow:

1.  A change starts with a task or an epic.
    
2.  The team identifies the affected domains and services.
    
3.  The important decisions are recorded.
    
4.  The documentation is updated together with the code.
    
5.  Observability shows what happens after the deployment.
    
6.  Incidents and lessons learned are added to the knowledge base.
    

This does not need to be a heavy process. The important thing is to create and maintain these links close to the moment when the knowledge is created.

## What Should a New Person Be Able to Do?

A good way to test this architecture is to choose a real task and imagine a new person trying to complete it.

Would this person be able to find out:

*   which part of the system needs to change;
    
*   who owns the domain;
    
*   which decisions limit the solution;
    
*   how to check that the change worked;
    
*   where to investigate if something goes wrong?
    

If the answer to all these questions is “you need to talk to someone,” there is an opportunity to improve the system’s context.

The same test can be used with an AI agent. The difference is that an agent will make it even clearer when important information depends on informal knowledge.

A simple way to measure this is to choose a small task and watch the steps needed to solve it. If someone needs to open several unrelated systems or ask another person before every decision, the problem is not only documentation. It is a context architecture problem.

## Context Architecture Is Not Bureaucracy

It is possible to turn this topic into another set of required processes. I do not think that is the goal.

The goal is not to write documentation just for the sake of writing it. The goal is to reduce the time people spend looking for answers and reduce their dependence on the people who were present when a decision was made.

A well-maintained context architecture helps with onboarding, incident investigation, feature planning, and system maintenance. AI agents simply make this need easier to see.

In the end, this is an old practice facing a new challenge: making system knowledge more explicit so that it does not stay in the memory of only a few people.

## Conclusion

Code explains how the system works at a specific point in time. Context helps explain why it works that way, what limits exist, and how it connects to the rest of the organization.

A Context Architecture does not need to put everything in one place. It needs to connect the right sources, make clear who owns each context, and make information easy to find.

When we do this, the system becomes easier to understand for people joining the team, for people investigating a problem, and for the agents working with us.

In the next article, I will talk about observability as a source of context. Logs, metrics, and traces are not only used to find errors. They also help explain how the system really behaves.