Split a Bloated CLAUDE.md With Three Questions

The root CLAUDE.md of a project starts with a few lines and grows from there: global commands, service-layer rules, a full release procedure, and a troubleshooting note from one failed test last week.

The result is that even a small page change makes Claude Code read content that has nothing to do with the task. Worse, some of the "rules" in the file are only text, and nothing actually enforces them.

Cleaning it up is hard because every item is useful. You hesitate to delete any of it, and you are not sure where it belongs. Put an item in the wrong place and either a rule that should load never does, or a constraint that should survive quietly disappears during the split.

The file gets shorter and less reliable.

What works is asking three questions about each item before you move it:

• which tasks or paths it applies to
• whether it is a fact, a rule, or a multi-step method
• whether the model needs to understand it or a program has to enforce it

The answers point to different homes: the root file, rules with path conditions, auto memory, a Skill, or a Hook. The five mixed items above get sorted one by one, and along the way you see how paths loads rules on demand, how vague rules become executable ones, and how three scenarios show whether the cleanup worked.

01 Ask three questions before layering

These questions show which layers one topic needs. For example, "confirm verification status before committing" is a working rule. How to collect that status is a procedure. Actually blocking a bad commit is a gate. Write the three roles down separately instead of copying the same text into all of them.

02 What belongs in the root CLAUDE.md

CLAUDE.md holds project instructions and working agreements for Claude Code. The root file suits information that should hold in every session and materially affects what Claude does:

• common build, test, lint, and dev commands;
• key directories and project-wide architecture boundaries;
• code style, naming conventions, and explicit prohibitions;
• environment requirements that are easy to miss but often affect execution;
• verification principles for after changes and before commits;
• Compact Instructions that say what state to preserve when compacting.

Detailed API manuals, long business background, and rarely used migration notes can usually stay behind a pointer and be read on demand. Check each item: if you removed it or moved it later, would everyday tasks lose necessary direction? Reference material can keep a pointer. A serious global restriction stays even if it's rarely needed. If this is your first root file, start with How to give Claude Code rules as a beginner.

Trim by necessity and treat line count as a rough guide. Information visible in the code can be brief, while hidden environment conditions and cross-module boundaries deserve a clear statement.

Written rules shape behavior through context, so they are agreements at the instruction level. A ban on editing sensitive files here states the working boundary. To enforce an access limit, you need permissions or another control that covers the action.

03 Write rules that can be executed

A rule should point to observable behavior. For example:

Write high-quality code.

"High-quality" has no standard that fits this project. A concrete dependency constraint does:

When modifying `server/` or `domain/`, preserve the dependency direction: API -> services -> ports <- adapters. Files in `domain/` must not import `adapters/`.

With the scope and the forbidden dependency direction stated, an import check can verify compliance. An abstract syntax tree (AST) check on TypeScript can detect those imports as well. What matters is that the rule has observable evidence behind it.

Likewise, replace:

Pay attention to tests.

with:

After changing the course schema, run the project's required course-validation command and schema tests covering the affected fields.

Now the trigger and the action are clear. In a real repository you still need to add the verified command and test entry point, because "run the relevant tests" can send the executor to the wrong scope.

If you keep correcting the same mistake, it may deserve to be written down. Decide the scope first, then choose between the root instructions and a local rule. Recheck as the project changes: once an old command is deleted, a rule that names it won't run, however forceful the wording.

04 Load rules on demand with paths

.claude/rules/ splits instructions into topic files, and paths decides whether a rule loads by file path. Moving a file into this directory doesn't make it load on demand. That depends on paths. According to the official Memory documentation, rules without paths load at the start of the session.

This layout, for example, organizes files by topic first, which keeps them maintainable:

CLAUDE.md
  Enduring project-wide working agreement

.claude/rules/server.md
  Service-layer code boundaries

.claude/rules/course.md
  Course-file rules

.claude/rules/frontend.md
  Frontend component and style rules

To make the service rule load only when relevant paths appear, add a YAML condition at the top of server.md. Here is a complete small example:

---
paths:
  - "server/**/*.ts"
  - "domain/**/*.ts"
---

# Service and Domain Rules

- Keep domain logic independent of adapters.
- Do not import adapters from domain files.

The path patterns select TypeScript files under server/ and domain/, and Claude loads the rule when it reads a matching file. Path-based loading only supplies the instructions. A gate on tool calls is configured separately. If a directory is renamed or an extension changes, update the patterns too.

After the move, check the actual loading in one session that matches the paths and one that doesn't, using /context and the read records. Lower usage only shows that less is loaded. Whether the condition is right takes a second check: the rules that should load are reachable, and unrelated detail stops showing up.

05 Separate experience from official rules

Auto memory saves preferences and experience gathered during work, such as "this kind of local test needs Redis" or "the user likes to see a plan first."

Experience carries environment and time conditions, so confirm it before it becomes project policy. A local test failing because Redis wasn't running supports only that observation. Once you confirm it's a shared team dependency, write it into the official testing guide. Before you fix anything in place, check its scope and whether it still holds.

Once memory enters the context, the model still has to interpret it, so memory is an instruction, just like CLAUDE.md. Enforcement takes the matching controls. When you promote an experience, confirm who is bound and under what conditions, then turn it into the right kind of rule, and keep a single version of it in a single place. For sensitive accounts or environments, record only what is authorized and necessary. Credentials have no place in experience notes.

06 Preserve key state through compaction

Verbal agreements in a long session can vanish in a summary. Compact Instructions are guidance written in CLAUDE.md that helps the model decide what to keep first. They are only guidance, and the model still decides what actually survives.

## Compact Instructions

Preserve in priority order:

1. Architecture decisions and reasons.
2. Modified files and key changes.
3. Current verification status.
4. Open risks, TODOs, and rollback notes.
5. Verification commands, exit states, key errors, unrun checks, and full log locations.

The order puts decisions and their reasons first, because losing a reason invites repeating a rejected approach. Changes and verification state come next, because the receiver needs to know what's done and what's unproven. Risks, next steps, and rollback notes follow, since they decide how to continue and recover.

For tool results, keep the conclusion, the exit status, the key errors, and the location of the raw log. Before shrinking thousands of lines of test output to "tests passed," confirm which tests passed and which didn't run. Otherwise compaction turns a local result into a sweeping claim.

"Keep what's important" gives no selection standard, so list the state by task. For important decisions, failed attempts, or complicated rollbacks, write a reviewable HANDOFF.md first. Details on writing one are in Claude Code session getting messy? Clear or compact

07 How rules, procedures, and gates fit together

A standing rule might read:

Confirm test and lint status before committing.

It states a working requirement for committing. A release-check Skill organizes how to gather that evidence, such as checking the branch, tests, version, and changelog, and sorting results into passed, failed, not run, and blocked. When the checks finish, committing or publishing still needs separate authorization.

A Hook performs a specific action at events it actually covers, such as checking a protected operation before a tool call or running a formatter after an edit. Each of the three describes its own part and points to the shared procedure.

To apply these ideas, choose the right event and the right target. A PreToolUse check on the commit command Claude Code is about to run covers only that one path. Git commits from another terminal need a Git or CI check that covers that range. If every commit path has to run the check, use one that covers that scope. A formatter after a file edit already runs after the fact.

That puts each layer in its place. The rule states the lasting requirement, the Skill gathers and interprets evidence, and the Hook runs a programmatic action at events it covers. They can all point to the same check script or convention, so that no copy drifts into a slightly different standard.

08 Back to the five items

Judge each item by when it's needed, then decide where it goes:

The fourth item is last week's experience. First check whether the current tests still depend on Redis and in which environment, then decide how to keep it. The nature of a piece of information changes as facts are confirmed, and its place may change with it.

Before moving anything, preserve what each requirement means. After the move, remove the duplicate text from the old location. Other places can keep a pointer to the source, with one version of each standard. For example, the root file says to verify status before committing, the Skill describes only how to collect that status, and the Hook runs only the check it owns. All three share one definition of "passed."

Also watch for task triggers that path loading misses. Suppose a user asks for a pre-release check, and the whole session never reads some source directory. The paths rule for that directory may never get a chance to load. Let the release Skill or a global entry point point to the standards it needs. File matching covers file scenarios, and a task entry point covers the question of what kind of work is being done.

09 Check the migration with three scenarios

When the cleanup is done, test it against three scenarios:

1. A routine page change. Check that the global working principles are visible and no service-layer detail loads.
2. Reading a domain file. Confirm the path rule loads and the import prohibition is stated in full.
3. Starting a release check. Confirm the procedure's entry point can reach the verification requirements, without relying on reading one particular directory.

These scenarios check whether rules are reachable and whether they apply to the task. Once a rule is loaded, you still verify that actions follow it. Markdown text is only instruction, and access control is configured separately.

Suppose a directory moves from domain/ to src/domain/. The rule text can be perfectly correct while its path condition goes stale, so the rule never gets its chance to load, and fixing the condition is enough. Or suppose the root file says "tests must pass before release" while a local note allows ignoring test failures. That is a conflict of meaning, and a person decides which one holds.

Whether a migration worked comes down to three things: the necessary constraints are kept, the relevant tasks can reach their requirements, and the duplicate standards are collapsed into one. A shorter file is one result of that work, and it doesn't replace those three checks.