How to Audit CLAUDE.md for Newer Claude Code Models

Do not delete 80% of your CLAUDE.md just because Anthropic shortened Claude Code's own system prompt. Audit it instead: keep durable project facts and verifiable constraints, remove repeated advice and stale examples, move narrow procedures into skills or path-scoped rules, and enforce true safety boundaries with settings, hooks, or tests.

Anthropic's Claude Code team said it removed more than 80% of the system prompt for newer models without a measurable loss on its coding evaluations. That is evidence that over-instruction can constrain stronger models. It is not a universal line-count target for every repository.

This guide gives you a reproducible audit, a compact template, expected results, and failure checks.

Prerequisites

You need:

• a repository that already uses CLAUDE.md;

• a current Claude Code installation;

• a clean working tree or a saved diff;

• the commands your team actually uses to lint, test, and validate changes.

Start from the repository root. Save the current file before changing it:

cp CLAUDE.md CLAUDE.md.before-model-audit
wc -l CLAUDE.md
git status --short

Expected result: you know the current line count, have a local comparison copy, and can distinguish this audit from unrelated changes.

Step 1: Confirm Which Instructions Claude Loads

Open Claude Code in the same directory your team normally uses, then run:

/memory

Verify the project CLAUDE.md, any parent or nested files, CLAUDE.local.md, and .claude/rules/ files that apply. Then run:

/context

Expected result: CLAUDE.md appears under memory or instruction context. If it does not, fix the file location before rewriting its contents.

This matters in monorepos. Claude Code loads instruction files above the working directory at startup and can load nested instructions when it reads files in those directories. A rule that seems ignored may be missing from the active scope, not badly worded.

Step 2: Classify Every Rule Before Removing It

Read the file once and label each section with one of these jobs:

Keep facts that Claude cannot reliably infer from nearby code. Keep constraints that reviewers repeatedly enforce. Move content that matters only during a particular task out of the always-loaded file.

Do not demote a security requirement into a shorter suggestion. Anthropic's documentation is explicit that CLAUDE.md is context, not enforced configuration. If a rule must always run or must block an operation, enforce it outside the model's discretion.

Step 3: Remove Instructions That Spend Context Without Adding Control

Cut or rewrite these first:

• duplicate rules stated in several files;

• broad advice such as "write clean code" or "be careful";

• examples that imitate an old model's preferred answer shape;

• package or directory facts that no longer match the repository;

• long procedures that only apply to one workflow;

• contradictory preferences from user, project, and nested instruction files.

Prefer one verifiable instruction over a paragraph of motivation.

Before:

Always make sure your changes are high quality, thoroughly tested, carefully
considered, and consistent with the project. Do not make unnecessary changes

After:

- Modify only files required by the request.
- Run `pnpm test` before proposing a commit.
- Treat `src/contracts/` as the source of truth for API payloads

The shorter version names observable behavior. A reviewer can tell whether Claude followed it.

Step 4: Use Progressive Disclosure

Keep the root file focused on information needed in most sessions. Put narrower material where it loads only when relevant.

For a TypeScript-only rule, create a path-scoped file:

---
paths:
  - 'src/**/*.{ts,tsx}'
---

# TypeScript

- Reuse exported domain types instead of duplicating string unions.
- Run `pnpm typecheck` after changing public types

For a multi-step release or incident workflow, use a skill. For a command that must execute at a fixed lifecycle event, use a hook. Splitting a large root file into unconditional imports may improve organization, but it does not save context because imported content still loads at startup.

Step 5: Rebuild the Root File Around a Small Contract

A useful root CLAUDE.md can often use this structure:

# Project

- Product purpose in one sentence.
- Main application and shared-code directories.

## Commands

- Install: `pnpm install`
- Narrow test: `pnpm test -- <pattern>`
- Typecheck: `pnpm typecheck`

## Architecture

- Name the source of truth for shared contracts.
- Name the boundary all writes must cross.
- Link the one architecture document needed for most changes.

## Working Rules

- Modify only the requested scope.
- Reuse existing helpers and contracts.
- Show the relevant validation result before handing off.

## Safety

- Never commit credentials or local environment files.
- Use the repository's approved credential and integration path.

Replace every placeholder with a repository-specific fact. Do not add a section merely to make the file look complete. Anthropic recommends keeping each CLAUDE.md concise and currently suggests targeting fewer than 200 lines, but relevance and consistency matter more than reaching an arbitrary number.

Step 6: Test the New File Like Code

Start a clean Claude Code session so the revised instructions load without stale conversation history. Run /memory again, then ask:

Without editing files, list the install command, the narrow test command, the
shared-contract source of truth, and any directories this repository tells you
not to modify. Cite the instruction file for each answer

Expected result: Claude answers from the intended file and does not invent missing rules.

Next, give it one small, representative task in a disposable branch. Check:

1. Did it inspect the right area before editing?

2. Did it stay inside the requested scope?

3. Did it reuse the named source of truth?

4. Did it run the exact validation command?

5. Did any removed rule change behavior that your team still needs?

Compare the audit directly:

git diff --no-index CLAUDE.md.before-model-audit CLAUDE.md
git diff --check

Delete the local comparison copy after review:

rm CLAUDE.md.before-model-audit

Success is not simply a smaller file. Success is equal or better behavior with less always-loaded context and no lost invariant.

Common Audit Failures

Claude Still Ignores a Rule

Run /memory to confirm the file loaded, look for conflicts across scopes, and rewrite the rule so its outcome is observable. If the behavior must be guaranteed, move it to a hook, permission setting, test, or CI check.

The File Is Short but Claude Lacks Project Context

You removed facts that are expensive to rediscover. Restore the project map, canonical commands, important boundaries, and non-obvious architecture decisions. The goal is high-signal context, not minimal context at any cost.

A Monorepo Rule Applies Everywhere

Move it into .claude/rules/ with a paths filter. Keep only cross-repository invariants in the root file.

Instructions Disappear During a Long Session

Project-root CLAUDE.md is re-read after compaction, but conversation-only instructions may be summarized away. Put durable constraints in the project file and use /clear between unrelated tasks. For critical task state, ask Claude to preserve the specific files, decisions, and test commands during compaction.

Why This Audit Works

Newer models can use judgment where older prompts needed detailed choreography. They still need accurate project facts, explicit boundaries, and feedback from real commands. The audit separates those needs: concise context guides decisions, while hooks and tests provide enforcement and evidence.

That is the same repeatable structure behind Aident's Ollama networking guide: use exact terminology, answer the immediate problem early, give reproducible steps, show expected results, and explain the failure modes.

If your coding agent also needs external systems, keep that instruction equally concrete:

Follow https://aident.ai/SETUP.md
Confirm my Aident Loadout account and Vault status.
Find one connected read-only Action relevant to this repository, inspect its
current input schema, and run it once with a harmless input. Do not perform writes
or ask me to paste provider credentials into the prompt

Use Aident Loadout to audit one read-only Action. Measure success as one current schema inspected, one harmless result verified, and no repository diff or credential copied into chat.

Sources

• The new rules of context engineering for Claude 5 models, Thariq Shihipar, July 24, 2026

• How Claude remembers your project, Anthropic, accessed July 26, 2026

• Best practices for Claude Code, Anthropic, accessed July 26, 2026

• Extend Claude Code, Anthropic, accessed July 26, 2026

• Automate workflows with hooks, Anthropic, accessed July 26, 2026

Refresh this guide when Claude Code changes instruction loading, path-scoped rules, compaction behavior, hooks, or official guidance for writing CLAUDE.md.