AI Coding Assistants for Large Codebases and Monorepos

AI coding assistants work brilliantly on a 10k-line service and get noticeably dumber on a 500k-line monorepo. The reason is context: no model reads your whole repo, so every tool has a strategy for deciding which slice it sees. There are two dominant strategies — agentic search (the agent greps and reads the live tree, Claude Code’s approach) and embedding indexes (the tool pre-indexes your repo for semantic retrieval, Cursor’s approach). Both work at scale, but only if the repository itself is structured so an agent can find its way — and monorepos that mix application code with Terraform have some specific failure modes worth engineering around.

How do AI coding tools actually find context in a big repo?

Two mechanisms, different trade-offs. Agentic search means the model runs grep/glob/read in a loop against your actual working tree — nothing is pre-computed, so results are always current, but exploration burns context tokens. Embedding-based retrieval chunks and embeds the repo up front, then pulls semantically similar chunks at question time — recall is fast and cheap, but the index is a snapshot that can lag your branch.

	Agentic search	Embedding index
Example	Claude Code	Cursor’s codebase index
Freshness	Always current — reads the working tree	Index re-syncs; can trail rapid changes
Cost profile	Tokens spent exploring per task	Indexing up front, cheap retrieval after
Finds	Exact symbols, call sites, config keys	“Code that’s about X” even with fuzzy wording
Weakness	Deep exploration fills the context window	Retrieved chunks can miss cross-file causality

Anthropic’s Claude Code docs are explicit that the context window is the binding constraint — performance degrades as it fills — which is why their guidance leans on subagents that explore in a separate context and report back summaries. Cursor’s docs, meanwhile, describe both an embeddings index (chunks encrypted, filenames obfuscated, per their privacy notes) and a custom grep engine they claim outperforms ripgrep on large codebases. That convergence is the honest answer: at scale, good tools blend retrieval and live search. Our comparison of AI tools for Terraform and Kubernetes work covers which tools we reach for by task.

What breaks in a 500k-line monorepo mixing app and Terraform code?

The failure isn’t that the model can’t read the code — it’s that retrieval pulls the wrong code, and infra code makes that worse. Four patterns that show up repeatedly in large mixed repos:

• Cross-domain contamination. Ask about “the payments service config” and retrieval surfaces the Kubernetes manifest, the Terraform variables, the Helm values file, and the app’s own YAML — four things named config with different owners and blast radii. The agent edits the wrong one confidently.
• Module indirection defeats similarity search. Terraform’s semantics live in module composition: a root stack calling modules/rds with twelve variables. Embedding chunks of HCL are near-identical boilerplate, so semantic search struggles to distinguish staging from prod. Agentic search does better here because it can follow source = "../../modules/rds" references — but each hop costs tokens.
• State lives outside the repo. An agent can read every .tf file and still not know what’s deployed, because that truth is in remote state. This is the core reason we treat plan output as the interface, not the HCL — the argument in can AI agents safely run Terraform?
• Generated and vendored code poisons the index. Lockfiles, generated clients, .terraform/ provider caches — hundreds of thousands of lines that dilute retrieval quality unless explicitly excluded via .cursorignore or equivalent.

What repo structure actually helps agents?

Structure your monorepo so an agent can orient without reading it — the same discipline that helps a new hire. The highest-leverage moves, roughly in order:

• Layered instruction files. A short root CLAUDE.md or AGENTS.md (build commands, repo layout, “infra changes go through plan review”), plus per-package files with local conventions. Anthropic’s guidance is to keep these ruthlessly short — bloated files get ignored. We compare the formats in AGENTS.md vs CLAUDE.md vs Cursor rules.
• Hard directory boundaries. apps/, services/, infra/, modules/ — with Terraform never interleaved with app source. Boundaries let you scope an agent to a subtree and let ignore files exclude whole domains cleanly.
• Ignore files as first-class config. Exclude generated code, vendored deps, and .terraform/ from indexing. This is also your first line of defense for keeping secrets out of AI tools — tfvars and .env files should never be indexable.
• Fast, scoped verification. Per-package tests and terraform validate/plan that run in seconds. Agents iterate against checks; a 40-minute monorepo-wide CI run means no feedback loop.
• Consistent naming. grep-based search lives and dies on predictable names. payments-service appearing identically in the app dir, the Terraform workspace, and the Helm release is worth more than any indexing feature.

Which tool should a small team on a monorepo pick?

For a 5-25 engineer team, our default recommendation is agentic-search tools (Claude Code or similar) for infrastructure work, and either approach for app code — freshness matters more than recall when the cost of a wrong edit is a destroyed database rather than a failed test. Embedding-index tools like Cursor shine for day-to-day app development in large codebases, where “find me code like this” is the common query. Many teams run both, which is fine — as long as ignore rules and instruction files are shared, not per-developer.

Two closing notes. First, for bulk work — provider upgrades, module refactors across 40 stacks — the fan-out pattern (many scoped agent runs, one per stack) beats one giant session; that’s the subject of parallel AI agents for infrastructure migrations. Second, making a monorepo agent-legible is mostly unglamorous repo hygiene: boundaries, naming, ignore files, fast checks. It’s the kind of one-time structural work we do inside a DevOps retainer — and if you want a read on where your repo and infra stand today, start with a health check.