The Problem AI Cannot Solve Alone: Context

Imagine hiring an extraordinarily talented architect who can only see one corridor of the building at a time.

They can analyze that corridor with remarkable precision. But they cannot see the floor above. They do not remember yesterday's decision about the foundations. They have no way of knowing that the pipe they are recommending already exists behind the opposite wall.

That is close to what happens when an AI agent works without enough context from a software project.

When AI lacks project context, it rarely fails loudly. It generates a reasonable-looking solution that compiles, passes tests, and is wrong in ways the team may not discover for weeks.

The industry has recently given this discipline a name: context engineering. It is the practice of deliberately deciding what information reaches the model—architecture, conventions, prior decisions, relevant code—at the moment it makes a decision. Alongside spec-driven development, it has become one of the two defining practices of AI-assisted engineering: the specification says what to build; context engineering ensures the agent knows the world it is building in. Neither works without the other.

The memory that keeps emptying

Every AI system can process only a finite amount of information at one time. That boundary is usually described as the context window. Everything outside that window is effectively unavailable to the model at the moment it makes a decision.

Context windows have grown dramatically, and it is tempting to conclude that the problem will simply disappear. It will not. A larger window changes how much you can include; it does not decide what you should include. Filling a huge window with an undifferentiated dump of the repository dilutes the signal the model needs, and no window will ever contain the decisions that were never written down. The constraint that matters is not the size of the window but the quality of what enters it.

For small projects, the limitation can be manageable. The codebase is compact enough that an engineer can hold most of it in their own head and notice when an AI-generated choice does not fit.

As the system grows, the available context represents a smaller fraction of the whole. The agent may still solve the task directly in front of it. But a locally sensible decision can contradict an architectural choice made elsewhere, duplicate an existing abstraction, or create a dependency that no one intended.

The problem is not necessarily that AI becomes less capable in a large project. It is that the same capability is operating with less information about what it is building.

What context loss looks like in a real codebase

The symptoms are remarkably consistent—and by now, measurable at industry scale. GitClear's analyses of AI-heavy repositories show sharply rising code duplication and code churn,exactly the pattern you would expect when capable agents repeatedly work without a shared view of the whole.

Duplicated code

The agent implements a function that already exists because it did not know where to find it. The project now contains two or three versions of the same behavior, each slightly different and none clearly canonical.

Dead code

A fragment generated during one session is never properly integrated, or it is replaced in a later session without anyone noticing. The repository keeps growing, but not everything inside it still has a purpose.

Structural antipatterns

The AI solves the requested task in a way that conflicts with architectural decisions made in earlier sessions.Each solution appears reasonable in isolation, while the system gradually fragments.

Progressive loss of control

Implicit decisions accumulate.Every new change requires more investigation. Eventually, no one can explain why the system looks the way it does, and engineers become afraid to modify areas they do not fully understand.

This is architectural drift:structural incoherence accumulated across development sessions that were each operating against an incomplete description of the system.

It is also, according to the analysts, where the entire technical-debt problem is heading. Gartner predicts that by 2027, architectural technical debt—debt that cuts across systems and layers rather than living inside any single module—will account for 80% of all technical debt, and that by 2028 AI will create more architectural debt than it solves. Code-level debt is increasingly something agents can fix. Architectural debt is precisely what they cannot see, because it requires the system-wide context this article is about.

An incomplete specification plus a fast AI agent is a building with undocumented foundations, constructed at industrial speed. Every room passes inspection. The building fails at the joints.

Context is an engineering artifact

Teams often treat context as something people simply have. A senior engineer remembers why a library was chosen. A tech lead knows which workaround exists because they were in the meeting. A developer knows which helper to reuse because they wrote it two years ago.

That model was already fragile. AI makes the fragility visible.

If the information required to make a safe change lives only in someone's memory, it is not available to the next engineer, the next agent session, or the team six months from now.Preserving context must become part of how the system is built, not a separate documentation task that happens when there is time.

Practical ways to preserve context between sessions

1. Give every session a reliable starting point

Files such as AGENTS.md, CLAUDE.md, or project rules for the team's chosen tool can provide a baseline that the agent reads at the start of each session. They should contain the project architecture, coding conventions, established patterns, known constraints, and antipatterns to avoid.

This file should not attempt to describe the entire codebase. Its job is to give the agent the rules of the environment: how this team works, what must remain consistent, and where to look for deeper information.

2. Maintain a current project state

A simple status.md or state.mdcan record what happened during the latest session: what changed, which decisions were made, what remains open, and what was considered and rejected.

Think of it as the note a surgeon leaves for the next shift. It does not replace the medical record. It makes the transition safe.

3. Make the codebase searchable by meaning

In a large repository, text search alone is not always enough. Tools that combine semantic code search with dependency analysis can help an agent answer questions such as 'How does authentication work in this system?' or 'Which components depend on this service?' even when the relevant files use different terminology.

The point is not to put the entire repository into the context window. It is to retrieve the right portion of the repository for the decision at hand. This is the heart of context engineering: curation, not accumulation.

4. Preserve decisions, not just activity

A chronological session log is useful, but it is not enough. Teams also need durable records of the decisions that shape the system: the option selected, the alternatives rejected, the constraints involved, and the consequences of the choice.

That is where Architecture Decision Records become especially valuable. They allow both humans and AI agents to understand the intention behind the code, rather than attempting to infer it from the implementation.

5. Create checkpoints before context disappears

Long sessions often involve compression, summaries, or a transition to a new session. Before that happens, the agent should capture the current state, unresolved questions, decisions, and next steps. Whether the team uses a dedicated memory tool or a simple repository file matters less than making the checkpoint habitual.

A minimum context system for an AI-assisted team

A practical starting point does not need to be sophisticated. It can consist of five elements:

●       A short project instruction file that every AI session reads.

●       A declared architecture and a map of the main modules.

●       Architecture Decision Records for non-obvious choices.

●       An updated project-state file at the end of meaningful sessions.

●       A retrieval mechanism that helps engineers and agents find relevant code and dependencies.

None of these practices eliminates the context-window limitation. The goal is not to make memory infinite. It is to maximize the quality of the information that enters the window and preserve the knowledge that would otherwise disappear between sessions.

One honest caveat. These five practices are the knowledge layer of AI-assisted engineering—and only that layer. As agents run longer and more autonomously, teams also need an operational layer around them: orchestration of multi-step and multi-agent work, verification loops that check output against the specification before it lands, guardrails such as permissions, sandboxing, and cost budgets, and observability that leaves a trace of what an agent actually did and why. A team that solves memory but not guardrails has an agent that remembers everything and can still do anything. This series focuses on the knowledge layer because it is the one most teams skip and the one everything else depends on—an agent with perfect guardrails and no context is safely wrong. But it does not standalone, and it is not meant to.

The real risk is silent incoherence

AI-generated code is easy to review when it fails immediately. The dangerous cases are the ones that look fine: the implementation works, the tests are green, and the structural cost is postponed.

A codebase does not usually become impossible to maintain because of one dramatic decision. It gets there through dozens of locally reasonable choices made without a shared view of the whole.

AI can accelerate those choices. The responsibility of the engineering team is to make sure it also inherits the system's intent.

The objective is not to help AI remember everything. It is to make sure the system never depends on something important that nobody wrote down.

‍

Let's talk

Would a new engineer (or AI agent) understand why your system is built the way it is? If you're not sure,we can explore it in a short discovery call. VAIRIX's diagnostic framework examines this directly: we sample recent merged changes and trace whether the decisions behind them are recoverable without their authors—revealing where context is being preserved and where critical knowledge is quietly getting lost.

‍