Working with Large Projects

On a 200-file project, you can be sloppy — dump a folder into context, describe the task loosely, and the agent will muddle through. On a 20,000-file monorepo, sloppiness gets expensive: context fills with irrelevant code, answers get vaguer, costs climb, and long sessions degrade. The fix is not a bigger model; it’s context discipline. This page collects the strategies that keep Nexgile Code sharp on large codebases — most of them features you already have, aimed deliberately.

Scope requests narrowly

The single highest-leverage habit. One task, one deliverable, with the territory named:

Add rate limiting to the public API endpoints in src/api/routes/public/.
Use the existing RateLimiter class from src/lib/rate-limiter.ts.
Don't touch the internal routes.

beats “add rate limiting to the API” every time — the agent starts in the right directory, reuses the right abstraction, and knows where the boundary is. Constraints (“don’t touch X”) are as valuable as instructions. See Typing Your Requests.

Point, don’t dump: precise @ mentions

@ mentions pre-load content into the task — which is exactly why folder mentions (@/src/services/) are dangerous on big projects: they pull in everything underneath. Prefer:

• @/src/services/billing/invoice.ts — the two or three files that matter
• @problems — the Problems panel instead of pasting error walls
• @git-changes — your working diff, for “review what I’ve done” tasks
• a commit hash — for “explain this regression” tasks

If @ file search struggles to find files in a huge repo, note it indexes up to 10,000 files by default (nexgile-code.maximumIndexedFilesForFileSearch in VS Code settings) — raise it for giant monorepos.

Let the index do the finding

On large projects, codebase indexing changes the discovery step from “list and read directories until something looks relevant” to one semantic query. Set it up once (Qdrant + an embedding provider), and the agent finds “where invoice totals are computed” in seconds without reading forty files into context. You can also scope searches (“search only packages/billing”) to keep results tight. If you set up nothing else from this page, set up indexing.

Plan in Architect, build in Code

New tasks start in Architect mode by default — on a large codebase, use that deliberately rather than switching straight to Code. Architect can read everything and edit only Markdown, which makes it a safe scout: have it explore, then produce a concrete plan — files to touch, order of operations, risks. Review the plan (this is where you catch “wait, that module is deprecated”), then let it switch to Code for implementation. The expensive exploration happens once, and the implementation task starts already knowing where to cut. See Using Modes.

Encode the architecture in rules files

Anything you find yourself re-explaining — layering rules, naming conventions, “all DB access goes through the repository classes” — belongs in rules files, injected into every prompt automatically:

• .nexgilerules or a .nexgile/rules/ directory at the project root for team conventions
• .nexgilerules-<mode-slug> for mode-specific guidance (e.g., test conventions for Tester)
• AGENTS.md, generated by the built-in /init command, which analyzes the codebase and writes concise agent rules for you — an excellent starting point on a project the agent hasn’t seen

On large projects rules files do double duty: they make output consistent and they save the agent from spending context rediscovering your conventions each task.

Partition work with subtasks

For jobs that genuinely span many areas — “migrate all services off the legacy logger” — use subtasks. Each child task gets a fresh context window scoped to its slice, does its work, and reports a summary back to the parent; the parent never carries the full detail of every slice. Orchestrator mode automates this pattern: it breaks the job down and delegates, keeping only coordination state itself. Fresh context per slice is precisely what large projects need.

Tune context management for marathon sessions

Long sessions on big codebases fill the context window; Context Management is the pressure valve:

• Auto-condensing summarizes older turns in place when context usage crosses a configurable threshold. It ships at 100% (condense only when effectively full); for marathon sessions on a big repo, lower the threshold to around 70–80% so condensing happens before quality degrades. Consider a cheaper model profile just for condensing.
• Caps limit how many open tabs (default 20) and workspace files (default 200) are included in context — lower them if your editor sessions run hot.
• Long terminal output spills to disk automatically rather than flooding context (Terminal & Shell Integration).

Watch the context gauge in the task header; repeated condensing in one task is a signal to split the work (below).

Cut the noise with .nexgileignore

Large repos carry dead weight the agent should never read: build output, generated code, fixtures, vendored bundles. List them in .nexgileignore (workspace root, gitignore syntax) and they disappear from file reads, searches, and the semantic index — smaller context, faster discovery, cheaper indexing, all from one file.

Match the model to the mode

API configuration profiles let each mode pin its own provider + model. On a large project the spread pays off:

• Ask / Architect — a cheap, fast model is fine for Q&A and planning drafts
• Code / Debug — your strongest model, where edit quality matters
• Condensing — a dedicated budget profile keeps summarization from burning premium tokens

Combined with allowedMaxCost per task (Command Guardrails & Limits), this keeps big-repo work predictable on cost.

Monorepo tips

• Open the package, not the universe. If today’s work lives entirely in packages/billing, open that folder as the workspace root. Rules and .nexgileignore at that root apply cleanly, file search and indexing scope down, and the agent can’t wander into unrelated packages.
• When you must work repo-wide, lean harder on everything above: path-scoped semantic searches, explicit directory boundaries in requests, and rules that spell out the package structure.
• For simultaneous work on multiple packages or branches, use worktrees — one window and one agent session per stream, fully isolated.

When to split into multiple tasks

A task that’s been condensed several times, or whose todo list has grown items unrelated to the original request, is past its best. Finish the current deliverable, then start fresh: a new task begins with a clean context window, and two sentences of your own summary (“We just refactored the invoice service onto the new logger; next, do the same for payments”) transfer everything the next task needs. Task history keeps the old conversation searchable — nothing is lost, and both tasks run sharper than one bloated session would.

Related

• Codebase Indexing & Semantic Search — set up meaning-based discovery
• Context Management — condensing, caps, and context health
• Rules Files & AGENTS.md — encode conventions once
• Subtasks & Todo Lists — partitioning big jobs
• Worktrees — parallel streams in isolated directories
• .nexgileignore & Protected Files — trimming what the agent sees