Six months into AI-assisted development, something predictable happens. 

The team has gotten good at prompting. The spec workflow is running. Output quality is solid. Then the codebase crosses a threshold — too many files to reference manually, too many interdependencies to hold in a session — and the approach that worked at month two stops working at month six. 

Watch what happens next. A developer opens a new session and spends the first ten minutes re-explaining the codebase. Here is the architecture. Here are the core services. Here is how this project connects to the legacy system. They did the same thing yesterday. They will do it again tomorrow. It feels necessary because nothing else has been set up. This is what treating context like a prompt tip looks like in practice — not a technique, a tax. Paid every session, by every engineer, forever. 

The instinct when this gets painful is to dump more context into the window. Feed it the whole repo. Give it everything and let it find what it needs. 

That instinct is wrong. And the teams that figure out why are operating at a different level than the ones that don't. 

What Happens When You Feed the Whole Codebase In 

It's not that it fails immediately. That's what makes it a slow trap. 

When you load a large codebase into the context window, the model has access to everything. But having access to everything is not the same as reasoning well about any specific part of it. As the context grows, attention becomes diffuse — the model has to work across a larger space and the signal-to-noise ratio drops. Output quality degrades — not dramatically, not in ways that are obviously wrong, but in ways that accumulate. References that aren't quite accurate. Patterns that don't match the actual codebase conventions. Suggestions that would have been correct three months ago, before the architecture evolved. 

You also pay for it directly. Token consumption scales with context size. A team feeding a large legacy codebase into every session is burning tokens on content the model doesn't need for the task at hand. 

There's a better architecture. Most teams haven't built it yet because it requires treating context as an engineering concern rather than a session habit. 

Two Context Strategies, Frequently Confused, Doing Different Jobs 

On a recent project, the team had a lengthy debate about two approaches that appeared, from a distance, to be solving the same problem: indexing the local codebase versus retrieving external documentation. 

The confusion is understandable. Both involve making more information available to the model. Both reduce hallucination and improve output quality. But they're solving different problems at different layers. 

Local code indexing crawls the project codebase, creates a structured index, caches it, and makes it queryable. Instead of loading files into the context window manually, the model queries the index and retrieves only what's relevant to the task. It's the answer to: "how do I make a large local codebase navigable without loading all of it at once?" Tools like Codebase Memory MCP implement this approach. 

External documentation retrieval fetches third-party library APIs, framework references, and coding standard definitions from outside the project. When working with a library whose documentation has changed since the model's training cutoff, this approach retrieves current documentation and makes it available in the session. It's the answer to: "how do I make sure the model knows what this external dependency actually does today?" Tools like Context 7 implement this approach. 

Different jobs. Both useful. The mistake is treating them as interchangeable, or assuming one covers what the other does. 

The practical decision: for the active project, where OpenSpec (the open-source spec framework from Fission-AI) already provides structured context around the current build, local code indexing is most valuable for referenced codebases — the legacy systems, the shared services, the external applications that the current build touches but doesn't own. That's where the indexing layer pays off most immediately. 

What the Team Actually Found 

When a developer on one of our client projects applied local code indexing to a legacy codebase, the practical result was what the theory predicted: code output was correct, token consumption dropped, and the model was able to answer questions about the indexed codebase without being given the files directly. 

The honest tradeoff: the initial indexing run is slow. For a large, long-lived codebase, it takes time to build the index. Once built and cached, queries are fast — but the first run is a real time cost. The index also needs to be refreshed when the referenced codebase changes significantly; it's not a set-and-forget system. 

That tradeoff is worth making. The alternative — manually referencing files at the start of each session, re-establishing the same context repeatedly — costs more time in aggregate and produces less consistent output. The indexing cost is one-time. The manual referencing cost is every session, compounding across every engineer on the team. 

A lead on the project flagged it in a team session: one developer was repeating the same codebase references at the start of every Claude session, re-explaining the same architecture, re-establishing the same context. It was a habit that felt necessary because nothing else had been set up. Once the indexing layer exists, the habit becomes the fallback — not the default. 

Precision of Context, Not Volume of Context 

The indexing layer solves the codebase problem. But the broader principle extends further. 

The Figma integration the team runs is a useful parallel. When developers pull from Figma to implement UI components, the default approach — providing a Figma URL and asking Claude to interpret it — produces output that's close but rarely production-ready. Manual pixel corrections are inevitable. 

The fix isn't more prompting. It's more precise context. When developers provide the exact Figma node ID — copied directly from the browser URL — rather than a page-level link, accuracy improves substantially in practice. The model isn't working harder. It's working with less ambiguity. 

This is the same principle as codebase indexing, applied to design assets. In both cases, the failure mode isn't that AI can't do the task — it's that the input is imprecise enough that the model has to guess. Guesses are fine for drafts. They're not fine for production. 

Context architecture is the discipline of making the input precise. Not larger — precise. The right information, at the right granularity, at the right moment in the task. 

Where OpenSpec Sits in This Stack 

For teams running OpenSpec, it's worth being explicit about how these layers interact — because the relationship isn't obvious from the outside. 

OpenSpec is the context layer for the active build. It defines what's being built, how it connects to the system, and what the implementation should look like. When Claude is doing development work on a current feature, the spec provides the reference frame. The developer doesn't need to index the current project — the spec is the project's structured representation. 

Local code indexing is the context layer for referenced systems. The legacy application being migrated. The shared service library. The external codebase that the current build calls into but doesn't own. For these, there's no OpenSpec — they exist before the spec-first workflow. Indexing them is how you give the model navigable access to systems it can't reason about from a spec alone. 

External documentation retrieval is the context layer for third-party dependencies. Libraries, frameworks, APIs. Things that exist outside both the current build and the referenced systems. 

Three layers. Three different jobs. The mistake is expecting any one of them to cover all three. 

The Skill Gap That's Opening Right Now 

Prompt engineering was the skill gap of 2024. Teams that figured out how to give Claude clear, structured instructions outperformed teams that didn't. The gap was real and the payoff was fast. 

Context architecture is the skill gap that's opening now. 

The teams investing in it are building indexing layers for their legacy codebases, maintaining precision in their Figma integrations, separating external documentation retrieval from local code navigation, and treating the context stack as a piece of infrastructure rather than a session habit. 

The teams that haven't started think context management is a prompt tip — something you handle at the start of each session with a few well-chosen instructions. They're right that it's manageable now. They'll find out it doesn't hold when the codebase scales. 

The compounding nature of this is what makes it urgent. An indexing layer built today improves every session for every engineer from now on. The cost of building it is fixed. The return is ongoing. Teams that delay are not just missing the benefit — they're compounding the cost of the alternative. 

Prompt engineering was last year's skill gap. Context architecture is this year's. The teams building it now won't need to explain why later. 

CIQ builds and operates AI-assisted development practices for enterprise engineering teams. If your team is hitting the context ceiling — sessions that reset, token costs that scale, output quality that degrades as the codebase grows — this is exactly what we help engineering teams build.