Sharpyard
← Back to the blog

June 21, 2026

How to use Claude Code on a large C# solution without blowing the context window

Practical checklist for keeping Claude Code focused on a multi-project .NET solution: per-directory CLAUDE.md files, subagent fan-out, Roslyn MCP, and session discipline.

A large C# solution and a context-window-limited AI agent have a tension that is worth understanding before you hit it. The agent is most useful when it can reason about the code it is changing; it becomes a liability when it starts guessing because it has read too much of the wrong code. This post is a practical checklist for keeping Claude Code on track across a multi-project .NET solution.

Why does Claude Code struggle on a big .sln?

Context window and irrelevant projects loaded. That is the one-sentence answer. A modern enterprise .NET solution may have dozens of projects: API, background workers, domain library, infrastructure adapters, integration tests, unit tests, shared kernel, legacy compatibility shims. If the agent reads all of them to answer a question about OrderService, it burns most of its context budget on code that will not change. By the time it gets to the part it needs, the window is crowded and its reasoning degrades.

The failure mode is not usually a hard error - it is subtle drift: the agent proposes a change that would have been right for a different project in the solution, or it misses a convention that is documented but buried under the noise of unrelated files.

How do I keep the agent in context on a multi-project solution?

This is a checklist, not a theory. Apply each item in order of cost.

1. One task per session; fresh context per change. Do not carry a session across multiple unrelated tasks. The context window is a shared resource; each task should start clean. This is the cheapest fix and the one most people skip.

2. Scope to the relevant projects, not the whole .sln. Tell the agent “work in src/Billing/ and src/Shared/Contracts/” rather than pointing it at the solution root. The fewer projects it reads upfront, the more budget it has for the code that matters.

3. Write per-directory CLAUDE.md files. A root CLAUDE.md maps the whole architecture. Each project or domain folder gets its own CLAUDE.md that describes that project’s role, its conventions, and what the agent should and should not touch. When the agent enters src/Billing/, it reads that file first and knows the rules before touching anything.

4. Fan out exploration with subagents. When you need a solution-wide answer - “which projects reference ILegacyPaymentGateway?” - spawn a subagent for the search. The subagent reads broadly, distills the answer to a compact summary (one to two paragraphs), and returns it to your main session. Your main context gets the answer, not the thousands of lines of grep output.

5. Use a Roslyn MCP for just-in-time semantic lookups. Instead of asking the agent to read every file that might reference a symbol, give it a Roslyn MCP server that can answer “find all callers of OrderService.Save” on demand. The agent calls the tool when it needs the answer and gets a precise result. This replaces large upfront reads with small, targeted queries.

How do per-directory CLAUDE.md files help?

A per-directory CLAUDE.md answers the question Claude Code asks when it enters a project folder: “what are the rules here?” Without it, the agent falls back to guessing from file names and code patterns, which works until it does not.

A good per-project CLAUDE.md for a .NET project is short - around 30 to 60 lines. It covers:

  • Role: “This is the HTTP adapter. It has no business logic. Controllers are thin; all decisions happen in domain services.”
  • Key conventions: “Nullable enabled. File-scoped namespaces. Records for all DTOs. No static methods.”
  • What to run: “dotnet test src/Billing.Tests/ to verify; dotnet build src/Billing/ to check compilation.”
  • What not to touch: “Do not add NuGet packages here. Infrastructure dependencies are wired in src/Infrastructure/.”

That 30-line file saves the agent from a dozen mistakes per session on a project it has not seen before in this context window. The cost is writing it once and updating it when conventions change.

When should I fan out with subagents?

Fan out when the work is exploratory and you want the answer, not the search. Specific triggers:

  • Dependency audit: which projects are on old package versions, and which have vulnerable dependencies? Let a subagent crawl every *.csproj and return a table. Your session gets the table.
  • Test coverage gap map: which public services in src/Domain/ lack a corresponding test file in src/Domain.Tests/? A subagent maps this and returns a list.
  • Cross-project symbol search: where is this type used across the solution? A subagent with the Roslyn MCP runs the query and returns the call sites.
  • Parallel project analysis: if you need to understand two independent domain areas to plan a refactor, spawn one subagent per domain, let them run simultaneously, and read their summaries side by side.

The rule: if gathering the raw data would cost more than a few hundred tokens of main-session context, it belongs in a subagent. Your main session should receive structured answers, not raw search results.

FAQ

Why does Claude Code lose context on a large C# solution? Because a multi-project .sln can easily exceed the agent’s effective context window when all projects are read at once. Irrelevant projects consume token budget that should go to the code you are actually changing, and the agent starts making decisions with incomplete information as the window fills up.

What is the single most effective way to keep Claude Code on track with a large solution? Scope every session to the relevant projects, not the whole solution. Combined with a root CLAUDE.md that maps the architecture and per-directory CLAUDE.md files that describe each project’s role, the agent gets the context it needs without reading everything.

How many CLAUDE.md files should a large solution have? One at the repo root and one per project or domain folder that has distinct conventions - typically 3 to 8 files for a real enterprise solution. More than that and maintenance becomes the cost.

When should I use subagents on a large solution? When the task is exploratory or can run in parallel - a dependency audit, a cross-project dead-code search, mapping test coverage gaps. A subagent distills its findings to a compact summary before returning, so the intermediate work does not land in your main context.

Does the dotnet-claude-starter repo demonstrate these patterns? Yes. The repo is a deliberately small example whose discipline - pinned SDK, warnings-as-errors, thin slices, a root CLAUDE.md - is the same discipline that scales. The README explains how to extend each pattern to a larger solution.

The production foundation

The patterns here keep an agent productive on a large solution. Sharpyard is the production .NET 10 and Angular SaaS starter with the full operating layer (root CLAUDE.md, per-project CLAUDE.md files, MCP config, contract tests) wired throughout - so the discipline is already in place when you clone it. Join the waitlist for the founding price.

The full AI-native .NET SaaS starter kit.

Join the waitlist