Claude Code repository context should tell the agent what is unusual, important, and easy to get wrong in your .NET solution. It should not restate every file in the repository or prescribe a generic architecture that the application does not use.
A useful context file answers concrete questions. Which solution entry point matters? Where are package versions owned? Which tests exercise real HTTP behavior? What must remain unchanged when an endpoint is edited? The more those answers point to maintained evidence, the less Claude Code has to guess.
Information checked October 9, 2026. Instruction-loading and memory behavior below were checked against current official documentation; the sample files and commands were not exercised.
Claude Code context is not configuration enforcement
The official memory documentation calls CLAUDE.md and auto memory context mechanisms, not enforced configuration. Instructions influence what Claude tries to do. They do not independently determine what its tools can access.
That distinction is the foundation of repository context. “Do not apply migrations” is an important instruction, but it is not the same as withholding database credentials or enforcing a runtime permission rule. Similarly, a preferred test command does not mean that command was actually executed.
The official permissions documentation identifies runtime-enforced allow, ask, and deny rules. These have a different responsibility from architecture notes and coding conventions. Keeping the responsibilities separate prevents a Markdown file from being described as a security boundary it cannot provide.
Context also differs from evidence. A note that the project targets a particular framework can become stale. The project and SDK-selection files are stronger evidence of the current state. A good instruction tells the agent where to check, rather than encouraging it to treat an old statement as unquestionable truth.
For example, write “Read the target frameworks from the affected project files before using framework-specific APIs.” That survives a framework upgrade better than a duplicated version number scattered through several instruction documents.
Begin with the solution's actual shape
A .NET repository may contain several applications, reusable libraries, test projects, build scripts, and central configuration files. The initial context should explain the meaningful relationships without presenting a universal template.
Identify the maintained solution entry point, whether that is a conventional solution file, a .slnx file, or a repository script. Name application boundaries and test locations. Distinguish a shared library from a host project because their dependency and initialization responsibilities differ.
Then identify version ownership. SDK selection, target frameworks, shared build properties, and package-management files each answer different questions. A package reference without an inline version may be correct when a central file owns it. An agent that does not inspect that ownership can introduce a conflicting version simply to make its sample resemble a familiar tutorial.
Avoid listing every current package in prose. That duplicates maintained manifests and makes drift likely. Instead, instruct the agent to inspect the appropriate manifest before introducing a dependency or using an API whose availability matters.
This is particularly relevant when a task resembles a published example such as an ASP.NET Core agent client. The example's integration choices do not establish the choices already approved for your repository.
Give Claude Code a concise root instruction file
The current memory documentation recommends keeping CLAUDE.md short, targeting under 200 lines, and moving narrowly relevant guidance into path-scoped rules or task procedures. That is an editorial recommendation for context quality, not an assurance that a 199-line file will be followed perfectly.
A root file should establish the repository map, stable constraints, and verification policy. This fictional CLAUDE.md example points to maintained files rather than asserting unverified versions:
## Repository map
- Read OrderService.slnx for the solution membership.
- Read global.json and affected project files before choosing .NET APIs.
- Read Directory.Packages.props before changing package references.
- API code is under src/OrderService.Api.
- HTTP contract tests are under tests/OrderService.Api.IntegrationTests.
## Change boundaries
- Preserve authentication, tenant filtering, and response contracts.
- Follow nearby endpoint and test patterns.
- Do not change packages, schemas, or deployment configuration without approval.
- Report conflicts between these notes and executable repository files.
## Verification
- Builds and tests run only in the approved remote validation environment.
- Report the revision, command, result, and skipped coverage.
- Do not claim unexecuted examples passed.
The filenames are illustrative and must be replaced with the repository's actual entry points. The example tells Claude Code where to look and what to preserve. It does not execute checks, block tools, or guarantee the application follows those conventions.
Notice the difference between stable and volatile content. “Preserve tenant filtering” is a stable contract. “The current API package is version X” is a volatile fact best read from the manifest. That distinction reduces maintenance work without sacrificing useful guidance.
Understand what Claude Code loads at launch
According to the current memory page, Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and ancestor directories. Discovered content is concatenated, not treated as a simple replacement hierarchy. Parent content appears before more local content, and local notes are appended at their directory level.
This means a nested instruction does not erase an earlier instruction simply because it is closer to the edited file. Contradictory guidance still exists in the context. The same official page warns that contradictory instructions may be followed inconsistently.
Subdirectory instruction files load on demand when Claude reads, writes, or edits files there under the documented conditions. That is useful for large solutions: API-specific rules need not occupy every session that only touches a utility library.
Working directory therefore affects both discovery and launch context. A session started inside a test project can see ancestor instructions, but it may not begin with all the sibling application context that the task requires. Start from the intended repository boundary and name the affected areas.
The page documents /context as a way to inspect loaded memory files. Use it as a loading check, not proof of adherence. Seeing a filename in context establishes availability; reviewing the actual diff establishes whether the resulting change respected it.
Handle AGENTS.md using current Claude Code behavior
Many repositories already use AGENTS.md as a shared instruction source. Current official documentation says direct AGENTS.md loading requires Claude Code version 2.1.277 or later and has availability conditions. This differs from older advice that always required a wrapper.
The default documented setting reads AGENTS.md when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it. When those files exist, the default instead reads the Claude instruction files. A personal CLAUDE.local.md can therefore change which shared instructions load.
Do not conclude that both files always load because both are present. Check the current AGENTS.md loading rules and inspect the session's loaded context. The documented Project instructions setting can select both-file behavior, but that setting and its plugin identifier are version-sensitive.
For environments that cannot load AGENTS.md directly, the docs describe an explicit import from a neighboring CLAUDE.md:
@AGENTS.md
## Claude-specific context
Use the repository's existing test fixtures rather than inventing a new harness.
An import is different from the sentence “read AGENTS.md.” The current docs explain that a prose request only makes the content available if Claude decides to open the file, whereas the import is expanded as part of loading.
The tradeoff is compatibility versus duplication. A small import can support older or constrained sessions without copying policy text. Two independently maintained policy files may drift and contradict each other. Prefer one maintained source where the repository already has one.
The memory page also recommends the import approach over a symlink for Windows collaborators because symlink creation and checkout behavior have additional requirements. Do not introduce a symlink solely to avoid a one-line import.
Scope Claude Code rules to the code that needs them
The official memory documentation describes .claude/rules/ Markdown files and YAML paths frontmatter. Rules without paths load unconditionally; path-specific rules load when matching files are accessed through the documented tools.
This supports a useful distinction in a .NET solution. Endpoint guidance can emphasize HTTP contracts and authorization. Infrastructure guidance can emphasize persistence mappings. Test guidance can describe real fixtures and assertion patterns.
Here is a fictional rule for API code:
---
paths:
- "src/OrderService.Api/**/*.cs"
---
## Endpoint contracts
- Preserve route-group authorization and tenant scoping.
- Use the existing error-response format.
- Inspect query binding before changing validation defaults.
- Update the corresponding HTTP contract tests for observable changes.
The pattern uses the glob syntax documented for Claude rules, not a Windows shell command. A scoped rule reduces irrelevant context, but it should not hide a fundamental repository-wide constraint such as a prohibition on production writes.
Do not put a complex execution procedure into every rule. The rule's responsibility is to identify the local convention. Repeated workflows can be maintained separately, while actual execution permissions remain runtime configuration.
Understanding middleware versus endpoint processing is one example of context worth applying to API paths. It helps prevent a handler change from becoming an accidental request-pipeline rewrite.
Describe tests by what they prove
“Use xUnit” is less useful than explaining which fixtures exercise which contracts. A solution can have isolated unit tests, component tests, real HTTP tests, and browser tests, even when several use the same test framework.
Point Claude Code to an existing representative test for the changed behavior. An endpoint validation task should inspect tests that send requests through the application, not just tests that call a helper directly. Conversely, a pure calculation may not need a full HTTP fixture.
The unit and integration strategies for modular systems provide useful vocabulary for those boundaries. Repository instructions should then identify the real projects and fixtures used locally.
State execution constraints explicitly. If validation runs remotely, instructions should say where evidence comes from and what the handoff must contain. Claude Code should not silently convert “run the tests” into “write a plausible test command in the report.”
Failure-path context is especially valuable. The processing-pipeline test examples show why rejection, faults, and cancellation need distinct assertions. A generic “add coverage” instruction does not communicate those contracts.
Keep task-specific details in the task
Stable instructions should not accumulate every issue's acceptance criteria. A temporary endpoint task belongs in the prompt or task specification, with exact input boundaries and preserved behavior.
For example, a task can specify that pageSize=0 must produce the existing 400 response, an omitted value must keep the existing default, and no query should execute for rejected input. Those details are useful now. They do not belong in every future session about the repository.
Ask Claude Code to identify uncertainty before editing. If two tests imply different defaults, the answer should name the contradiction rather than choose one silently. If implementing the task requires an unapproved dependency, it should stop at that boundary and explain why.
Context is most effective when the output is inspectable. Ask Claude Code for an affected-file set, a trace from request input to service, and a mapping between acceptance criteria and tests. These are concrete artifacts a reviewer can challenge.
Do not confuse Claude Code auto memory with team policy
The current memory documentation describes auto memory as notes Claude writes, with machine-local storage and a shared directory across worktrees of the same repository. It is not a substitute for a reviewed instruction file in source control.
The documented startup limit is the first 200 lines or 25 KB of MEMORY.md, whichever comes first. Topic files load on demand. Therefore, a remembered detail buried outside the startup index should not be assumed to be present in every new conversation.
Auto memory can preserve preferences and corrections, but team policy needs an explicit owner and review path. Important constraints should not depend on whether one developer's machine happened to accumulate a particular note.
Be equally careful with stale notes. If memory says a test requires one service while the maintained fixture now uses another, inspect the fixture. Correct the note instead of changing working code to match outdated context.
For comparison of repository techniques across tools, custom agents and skills in another terminal workflow can help distinguish reusable procedures from basic instructions. Do not copy product-specific loading assumptions between systems.
Frequently asked questions
Should CLAUDE.md contain the whole architecture?
No. Keep a concise map and stable constraints, then link or import maintained documentation where appropriate. Duplicating every detail makes stale guidance more likely.
Does the nearest instruction file override its parent?
The current docs describe concatenation, not simple replacement. More local content appears later, but conflicting instructions still need resolution rather than an assumed override rule.
Does Claude Code read AGENTS.md automatically?
Current versions support direct loading under documented conditions. Version, plugin availability, and the presence of Claude instruction files affect behavior. Inspect current docs and loaded context.
Can a local instruction file hide shared AGENTS.md context?
Under the documented default, a CLAUDE.local.md in the working directory or above can cause Claude instruction files to load instead. Check the Project instructions setting or use the documented import arrangement.
Are path-scoped rules permission controls?
No. They provide context when matching files are accessed. Runtime permissions, constrained credentials, and execution boundaries have separate responsibilities.
What is the most useful .NET-specific context?
The real solution map, version ownership, package conventions, representative tests, and preserved contracts. Useful context points to evidence and avoids inventing a standard layout.
Good context reduces guessing
Claude Code repository context is a small, maintained explanation of what the solution means and where authoritative facts live. It is not a second build system or a guarantee of compliance.
When instructions are concise, loading behavior is understood, and tasks name observable contracts, generated changes become easier to review. The result is clearer evidence about the repository, not greater confidence without evidence.