全部インデックスするか、全部読ませるか − マルチリポジトリ開発でAIに仕様書を渡すジレンマA practical examination of the trade-offs between full codebase indexing and…

When teams adopt AI coding assistants like Cursor across several repositories at once, they quickly run into a deceptively simple question: should the assistant index the entire codebase, or should relevant specification documents be fed directly into the model's context window for each task? The choice matters because it shapes accuracy, cost, and day-to-day workflow in ways that compound as a project grows, and there is no single answer that fits every team.

The first approach is full codebase indexing. Cursor, like several competing tools, builds a semantic index of a repository by splitting files into chunks, generating vector embeddings, and storing them so the assistant can retrieve the most relevant snippets when a developer asks a question. In a multi-repository setup this means each repo, and potentially a shared specification repo, is embedded and searchable. The main advantage is coverage: the model can surface code or documentation the developer did not explicitly point to, which is valuable when responsibilities are spread across many services and no single person holds the full picture. The trade-off is that retrieval is only as good as the chunking and ranking. Specification documents that describe cross-cutting behavior can be split awkwardly, and the retriever may return fragments that lose the surrounding intent. Indexing also introduces maintenance overhead, since embeddings must be refreshed as code changes, and large monorepos or many linked repositories can strain what the index practically covers.

The second approach is direct context injection, where the spec document is placed straight into the prompt, often by referencing a file or pasting the relevant section. This gives the model the complete, ordered text of the specification rather than retrieved fragments, which tends to improve fidelity when a task depends on precise requirements, edge cases, or naming conventions defined in the document. The obvious constraint is the context window. Even with models that now advertise large windows, filling the prompt with entire specifications across multiple repositories consumes tokens, raises per-request cost, and can dilute the model's attention. Practitioners frequently observe that models handle information near the beginning and end of a long prompt more reliably than material buried in the middle, an effect commonly described in research as a tendency to lose track of the middle. So more context is not automatically better.

In practice the two strategies are not mutually exclusive, and the more interesting question is how to combine them. A common pattern is to rely on indexing for broad code discovery while injecting the authoritative specification directly for the specific feature being built. Cursor supports mechanisms that make this hybrid workable, including rules files that persist project conventions, the ability to reference specific files with @-style mentions, and configuration that scopes what the assistant should treat as relevant. Teams working across repositories sometimes maintain a dedicated documentation or spec repository so that the source of truth is versioned and can be pulled into context deliberately rather than discovered by chance.

This tension reflects a broader industry shift toward what is loosely called context engineering, the discipline of deciding what information an AI system sees and when. Retrieval-augmented generation, the technique underlying most indexing features, was designed precisely to keep prompts small while still grounding answers in a larger corpus. Newer developments push in both directions at once. Emerging standards such as the Model Context Protocol aim to give assistants structured access to external sources, while agentic coding tools increasingly fetch files on demand rather than pre-loading everything. Comparable tools including GitHub Copilot, Continue, and Sourcegraph's Cody wrestle with the same retrieval-versus-injection balance, which suggests the trade-off is fundamental rather than specific to any one product.

For teams making the decision, a few factors appear to be decisive. Indexing tends to reward large, sprawling codebases where discovery is the bottleneck and where specifications are stable. Direct injection tends to reward tasks that hinge on exact requirements, or situations where the spec changes faster than an index can be refreshed. Cost sensitivity, the reliability of the retriever, and how disciplined the team is about maintaining documentation all shift the balance. The pragmatic takeaway is to treat indexing and injection as complementary tools, measure accuracy on real tasks rather than assuming one is superior, and revisit the choice as models, context windows, and tooling continue to evolve.