Auditing Repository Instructions for Clarity and Consistency

Good to see you again. In the previous lesson, you built a task-to-model routing matrix so that model choice reflects reasoning depth, relevant context, latency, and cost rather than habit. That policy only works as well as the instructions and repository context supplied to the model.

This lesson focuses on auditing a repository instruction file such as CLAUDE.md. You will identify four reliability problems: ambiguity, stale guidance, conflicting rules, and unverifiable commands. The aim is not to write a longer “AI manual.” It is to keep only precise, current guidance that prevents real mistakes in a particular repository.

---

Treat repository instructions as fallible operational documentation

A repository instruction file is persistent context, not a compiler setting or a policy engine. It can guide Claude Code toward the right commands, conventions, and hazards, but it does not enforce them. If the file is unclear, outdated, or overloaded, it can create the same wrong behavior in every new session.

For the .NET, Node.js, Elasticsearch, and Kubernetes work you described, the highest-value content is usually information the model cannot safely infer by scanning one or two files:

• the exact test, lint, build, and local-run commands;
• an architectural constraint with a concrete consequence;
• a repository-specific trap, such as an Elasticsearch mapping migration process;
• a boundary around consequential actions, such as cluster changes or production data access;
• a workflow convention that differs from normal tool defaults.

A statement such as “write maintainable code” adds little: different people and models can interpret it differently. A statement such as “For changes under services/search-api/, run the targeted integration suite from the repository root and report any failing test names before proposing a merge” establishes a scope, an action, and observable evidence.

The Claude Code documentation frames CLAUDE.md as persistent repository context, while also emphasizing that it should remain concise and contain guidance that broadly applies.

A useful audit principle follows:

A rule earns its place when it prevents a plausible, costly mistake that the model could otherwise make, and when a reviewer can tell whether it was followed.

That principle applies to repository instructions for any assistant, even if another tool calls the file AGENTS.md, a rule file, or workspace guidance.

---

First, identify the instructions that actually apply

Do not audit the root CLAUDE.md in isolation. A task may be influenced by global instructions, a repository file, a nested file, imported content, and path-scoped rules. An apparent contradiction often turns out to be a rule that applies only to a different service. Conversely, an instruction that looks correct in the root may be overridden or diluted by related content loaded for a particular directory.

For a representative task in each major area of a complex repository, build a small instruction-scope map:

Target task or path	Instruction sources to inspect	What to establish
.NET API change	Global instructions, repository root, API or service subdirectory rules	Build and targeted-test commands; architectural and API compatibility constraints
Node.js application change	Global instructions, repository root, application-specific rules	Package manager, workspace command syntax, typecheck and test workflow
Elasticsearch mapping or query change	Root instructions plus search-specific guidance	Mapping/versioning process, test fixtures, rollback or compatibility requirements
Kubernetes or deployment work	Root instructions plus infrastructure-specific rules	Allowed environments, review requirements, validation commands, prohibited write actions

In Claude Code, use /context during such a task and inspect the Memory files list. This answers a basic but essential question: was the instruction file actually loaded? A well-written rule cannot influence a session if it is outside the active scope.

The supplied CLAUDE.md hierarchy diagram illustrates the intended shape: broad guidance may apply everywhere, project instructions apply within a repository, and conditional rules add specialized requirements only for relevant work. Its example domains are machine learning and ETL, but the same structure is useful for a mixed .NET, Node.js, and infrastructure repository.

The goal is relevance, not fragmentation. A root file should carry broad project rules. Guidance that applies only when editing Helm charts, TypeScript tests, or Elasticsearch configuration should normally be scoped to that work rather than loaded for every small task.

The official memory documentation explains why this matters: these files consume context, ambiguous and conflicting rules are not reliably resolved by the model, and very large files reduce adherence.

A practical size guideline is to target fewer than 200 lines per CLAUDE.md. This is not an invitation to use 199 lines. It is a warning that every globally loaded line competes with the code, ticket, tests, logs, and conversation needed for the current task. Imports may organize content, but imported content still consumes context when loaded.

---

The four defects an audit must find

An audit is easier when each finding has a precise category. A single line may have more than one defect.

Defect	Diagnostic test	Typical consequence
Ambiguous	Could two competent engineers interpret it differently and both claim compliance?	The model chooses a plausible but unwanted interpretation
Stale	Does it disagree with current code, scripts, CI, dependencies, architecture, or policy?	The model is actively directed toward an obsolete workflow
Conflicting	Do two rules that can apply to the same task require incompatible actions?	The model chooses arbitrarily, asks unnecessary questions, or follows the more salient wording
Unverifiable	Is there no observable command, artifact, test, diff, or report that can demonstrate compliance?	The instruction produces confident but uncheckable claims

Ambiguity: replace values with operational meaning

Consider these lines:

- Test changes thoroughly.
- Keep Elasticsearch queries efficient.
- Update deployment configuration carefully.

Each expresses a reasonable intention but provides no reliable action. “Thoroughly,” “efficient,” and “carefully” hide the actual decisions: which test suite, what query constraints, which deployment environment, and what evidence is required.

A stronger version might be:

- For changes under services/catalog-api/, run the targeted unit-test command and the API integration-test command documented in package scripts; report any failures before requesting review.
- For search queries, include a representative query fixture and verify the expected result ordering against the local test index.
- Do not execute cluster-changing commands. For deployment changes, provide the rendered manifest diff and wait for explicit human approval before applying it.

These examples illustrate the pattern, not commands to copy verbatim. Your audit must confirm the real scripts, directories, environments, and approval process in each repository.

A reliable rule normally specifies these elements:

1. Scope or trigger: when and where does it apply?
2. Required or prohibited action: what must the assistant do or avoid?
3. Artifact or constraint: what file, API, environment, or invariant is involved?
4. Evidence: what command output, test result, diff, or report demonstrates compliance?
5. Failure behavior: should the assistant stop, report a failure, or request approval?

Not every rule needs all five. “Never commit credentials” is already clear and broadly verifiable through review and secret scanning. A multi-step operational instruction, however, usually needs more precision.

Stale guidance: a correct rule can decay into harmful context

Stale content is worse than absent content because it pushes the model in a wrong direction. Common examples include:

• a command using npm after a repository moved to pnpm workspaces;
• a .NET target framework, test project, or solution path that no longer exists;
• guidance to use an obsolete Elasticsearch client version or deprecated query pattern;
• a deployment instruction referring to a retired namespace, Helm chart, or CI job;
• directory descriptions copied from an early repository layout;
• an architectural explanation now contradicted by the code.

Do not label a line stale merely because it is old. Verify it against authoritative current evidence, in roughly this order:

1. executable package scripts, solution files, project files, and build configuration;
2. CI workflows and deployment configuration;
3. current code and tests;
4. actively maintained operational documentation;
5. a designated repository owner when the evidence remains inconclusive.

Some content is not exactly stale but is still a removal candidate. If Claude can reliably discover a directory layout, dependency version, or standard convention from the repository, it often should not occupy permanent instruction space. The /doctor checkup can propose trimming material it considers derivable from the checked-in codebase; treat its suggestions as review input, not as proof that a rule is unimportant.

Conflicting rules: compare applicability, not just wording

A conflict exists only when two rules can both apply and prescribe incompatible behavior. These are common in layered repositories:

Root instruction:
- Run the full test suite before every commit.

Service instruction:
- Do not run the full suite locally; run only targeted tests to keep development fast.

The defect may be direct, or it may be a missing distinction between two stages of work. A clearer policy separates local iteration from a merge-quality gate:

- During local iteration, run the targeted tests for the changed service.
- Before requesting review, run the repository validation command specified for the changed service, or report why it cannot run locally.
- CI remains the required full-suite gate; do not claim the full suite passed unless its result is available.

Other high-risk conflicts include:

• “Never modify migration files” alongside “add a migration for every schema change.”
• “Use the shared client wrapper” alongside a child rule requiring direct use of a vendor SDK.
• “Do not make environment changes” alongside “deploy when the change is ready.”
• “Do not remove tests” alongside “delete obsolete tests.”

Resolve conflicts by doing one of the following:

• remove the obsolete rule;
• narrow one rule’s scope;
• express the sequencing explicitly;
• state the exception and the approval needed to use it;
• move the requirement to deterministic enforcement when it is non-negotiable.

Do not rely on a model to infer which conflicting line is more important.

Unverifiable commands: distinguish a request from enforcement

A command can look concrete while still being untestable:

- Run all relevant checks.
- Ensure the deployment is safe.
- Verify the migration works.
- Before every commit, format all changed files.

The first three lack a named check and expected evidence. The last is clearer, but it still assumes the model will always notice the lifecycle point and execute the action.

For a command-oriented rule, audit these details:

Check	Example of a weak instruction	What a reviewable instruction adds
Working directory	“Run tests”	Repository root or service directory
Exact command	“Run relevant checks”	The current script or dotnet command
Scope	“Test the app”	Affected service, project, or test category
Success condition	“Verify it works”	Exit success plus a named expected test or artifact
Failure behavior	“Fix problems”	Report failing checks; do not claim completion
Authority boundary	“Deploy when ready”	Whether preparation is allowed, who approves, and whether execution is prohibited

If something must happen after every file edit or before every commit, written guidance alone is the wrong control. Use a formatter, linter, CI check, pre-commit mechanism, or Claude Code hook where appropriate. The instruction file can tell the assistant how to work with that mechanism, but the mechanism supplies deterministic enforcement.

This is particularly important for Kubernetes. A CLAUDE.md line should never be treated as the authorization system for a cluster-changing kubectl or Helm action. Permissions, environment boundaries, and approval controls must exist independently of model instructions.

---

Perform a repeatable audit with an instruction ledger

Avoid editing the file line by line based only on instinct. First turn its content into a small ledger of atomic rules. A bullet containing several obligations should become several rows.

ID	Source and scope	Atomic rule	Finding	Evidence checked	Resolution	Validation
T-01	Root, all paths	“Test changes thoroughly”	Ambiguous	No named scripts or success condition	Replace with scoped commands	Ask for a targeted-change plan
T-02	services/orders, .NET only	“Use .NET 7”	Possibly stale	Current project target framework	Update or remove	Build the affected project
T-03	Root plus service rule	Full suite required; full suite prohibited locally	Conflict	Both apply to service edits	Separate local and CI stages	Check both tasks are unambiguous
T-04	Infrastructure scope	“Deploy when ready”	Unverifiable and unsafe	No environment or approval boundary	Replace with prepare-and-approve rule	Confirm no write command is proposed

The ledger provides three benefits:

• It makes scope visible, which is essential in monorepos and multi-service repositories.
• It preserves an evidence trail for changes to shared AI guidance.
• It prevents a broad cleanup from accidentally deleting a valuable hard-won caveat.

Use this audit sequence.

1. Inventory the loaded instruction surface

Choose three representative tasks: one .NET service change, one Node.js change, and one Elasticsearch or Kubernetes-related change. For each, use /context to record the memory files loaded, then locate imports, nested instruction files, and conditional rules that could apply.

Record files that are present but not loaded separately. Their content may still be useful, but it cannot explain current model behavior in that task.

2. Extract and classify each rule

For every instruction, write its operative verb and scope. For example, split:

- Use the shared HTTP client, preserve backwards compatibility, and run the API tests.

into three rows. The first concerns implementation architecture, the second concerns a compatibility constraint, and the third concerns validation. They have different evidence sources and often different scopes.

Mark each row as one of:

• command or validation;
• code convention;
• architecture decision;
• safety or authorization boundary;
• workflow or repository etiquette;
• project-specific gotcha;
• explanatory or derivable background.

The last category deserves special skepticism. It is frequently where copied architecture overviews and stale dependency lists accumulate.

3. Verify against the repository, not memory

For each command, check that it exists and can be invoked from the stated location. For each stack or architecture claim, inspect the current source of truth. For each safety rule, confirm that the actual tool permissions, CI controls, and deployment process support it.

When a rule has no identifiable owner or source, label it unverified, not automatically false. Remove it only when it is contradicted, redundant, or cannot be justified by a real recurring failure mode.

4. Rewrite only the failing rule

Preserve the intended policy while changing the smallest amount necessary. This makes the revision easy to review and reduces the risk of introducing new conflict.

A good rewrite often converts a vague intention into a compact conditional statement:

When modifying files under apps/admin-api/:
- Run the documented targeted test and typecheck commands from the repository root.
- Do not alter generated client files directly; update the source specification and regenerate them.
- If the required local dependency is unavailable, report the blocked validation instead of claiming tests passed.

Notice what this does not include: a tutorial on the API, a full directory tree, or generic encouragement to write clean code.

5. Test the revised guidance with a small canary task

Use a realistic but low-risk prompt, such as planning a change to a known endpoint or explaining the validation required for a changed test file. Confirm that Claude:

• identifies the applicable rule;
• chooses the correct current command;
• recognizes a prohibited action or approval boundary;
• reports uncertainty instead of inventing successful validation.

Behavioral testing is evidence, not a guarantee. Keep automated tests, code review, CI, permission boundaries, and deployment controls in place.

---

Make the file maintainable after the first cleanup

An instruction file should be version-controlled and reviewed like other operational documentation. The audit is not a one-time migration because repositories, tool behavior, build commands, and team practices all change.

A low-friction maintenance policy is enough:

Event	Update or audit action
A model repeats a repository-specific error	Add a short rule only after identifying the real cause and a precise preventive action
A command, framework version, or CI workflow changes	Update or remove the corresponding instruction in the same change set
A new service or infrastructure area is introduced	Add focused, path-scoped guidance rather than expanding the root file indiscriminately
A rule is repeatedly ignored	Check scope and conflicts first; then shorten or clarify it; use deterministic tooling if the action is mandatory
Monthly or milestone review	Re-run the ledger audit, inspect recent AI-related rework, and prune derivable or obsolete content

A useful admission test for every new line is:

• What recurring mistake does this prevent?
• Is the guidance specific to this repository?
• Can the model determine when it applies?
• Can an engineer verify compliance?
• Is a formatter, hook, test, permission control, or CI check a better solution?

If the answer to the final question is yes, keep the instruction short and move enforcement into the appropriate deterministic system.

---

You can now audit a repository instruction file systematically rather than treating it as a collection of helpful notes. Start by mapping what actually loads, reduce each statement to an atomic rule, verify it against current repository evidence, and classify ambiguity, staleness, conflict, and unverifiability separately. Clear, scoped instructions improve AI-assisted work; enforceable automation protects the boundaries that instructions alone cannot.

Next, you will build an evidence-first context packet: selecting the code, tests, tickets, documentation, and operational data that a model needs for a particular task without flooding its context window.