CLAUDE.md Progressive Disclosure: Load Only What Is Needed

CLAUDE.md progressive disclosure means keeping essential project instructions available at the start, then loading specialized guidance when the current task requires it. Use a short root file as a map, scoped rules for particular files, and explicit references or skills for occasional procedures.

This is useful when every small change otherwise begins with a large pile of unrelated instructions. Keep changing tasks and decisions in a work record such as fenbs, rather than continually appending yesterday’s progress to the root file. The context engineering collection explains the wider approach to selecting what an assistant needs.

How do you split instructions into useful layers?

1. Mark the instructions that apply to every task: boundaries, project orientation, and the checks relevant to completing work.
2. Group specialized guidance by the action or files that need it, such as changing a payment page or editing public copy.
3. Give each group a clear location and a trigger that tells Claude when to read it.
4. Remove copied history from the always-loaded file and preserve current project progress in its own record.
5. Try representative tasks and check that Claude reads the required guidance before making changes.

Start by moving one section, not by rebuilding the whole instruction system. Say your root file includes a lengthy release checklist. Keep the rule requiring approval for a release in the root; move the detailed procedure to a reference that is read when a release is requested.

The boundary must remain easy to discover. Moving a safety instruction into a document that Claude has no reason to open defeats the purpose. You are delaying detail while keeping the obligation and the route to it visible.

Which loading mechanisms actually defer the detail?

Anthropic’s instruction loading documentation↗ (opens in a new tab) distinguishes ordinary CLAUDE.md imports from instructions that load when relevant files are used. An import organizes text but also brings its content into context; it is not an on-demand lookup. A plain reference tells Claude where material is available without expanding it as an import.

A skill is a named set of instructions for a repeatable job. Claude Code’s skills documentation↗ (opens in a new tab) explains that its body loads when used. For placement and inherited instruction scope, consult the separate CLAUDE.md hierarchy guide.

What should the small root file actually say?

Write a map that connects a recognizable task to its next reading step. “More docs are somewhere in the repository” leaves the assistant to guess. “Before changing a billing page, read docs/billing-review.md” names both the trigger and the source.

# Project instructions

Use the repository package manager and existing scripts.
Ask a person before publishing or changing live customer data.

Before changing billing pages, read docs/billing-review.md.
Before editing public copy, read docs/editorial.md.
For a requested release, read docs/release-process.md first.

Read the current project decisions and task state before work.
Save results, checks, and remaining work before stopping.

Adapt the boundaries to your actual project. The example is a routing pattern, not a universal policy. Keep a short explanation of an unusual rule where it helps Claude apply the rule correctly, but leave the detailed procedure in its maintained reference.

Avoid a second copy of the same checklist in a skill and a reference document. Pick one maintained home and point to it. The CLAUDE.md examples provide other starting shapes; judge yours by whether it leads to the correct action.

How do you keep deferred instructions discoverable?

Use triggers people can recognize in a request. “For authentication changes” is more helpful than “advanced operations.” Put the path beside the trigger and explain when Claude should stop for human input. A good route removes an interpretation step.

Treat a missing document as missing guidance. Tell the assistant to report it instead of inventing the procedure. When you rename or move a reference, update its routes in the same change so new sessions do not follow an obsolete path.

Do not scatter one instruction across several partial files. The assistant should not have to assemble a release boundary from an editorial guide, an old task, and an example command. Keep the rule intact and place specialized explanations beneath it.

How can you verify the setup before relying on it?

Use a small test set: an unrelated copy change, a change that matches a scoped rule, and a request that requires a procedure. Ask Claude to identify the instructions it used before proposing edits. Inspect the files it actually read, rather than accepting a confident description of expected behavior.

Anthropic’s context cost guidance↗ (opens in a new tab) recommends moving specialized material out of always-loaded instructions. Measure your own setup where the interface exposes context information. Moving text without checking its loading behavior can leave the same material loaded through a different route.

Include a failure case: temporarily use a nonexistent reference in a disposable test setup and confirm the assistant reports the gap. If your instructions are present but ignored, the CLAUDE.md troubleshooting guide covers that different problem.

Where should current tasks and decisions live?

Separate stable working conventions from facts that change after each session. An open investigation, a failed check, and a pending design choice deserve an updated project record. Copying them into the root file turns short-lived status into something future sessions may mistake for a lasting instruction.

Keep a route to the current record and ask the assistant to read the relevant task before working. Record a lasting rule when a person makes that choice; preserve ordinary progress as progress. fenbs project context provides Rules, Where we left off, and task state for this purpose.

How to do this with fenbs

1. Create a free account, free for one person with no credit card, and add the project whose instructions you are simplifying.
2. Save the current task state and source references; record the rules and decisions a person has actually approved.
3. Connect Claude Code using its integration instructions over MCP, a standard way for an AI app to use an outside tool.
4. Keep a short repository instruction to read project context at the start and save checked results and next steps before stopping.

fenbs does not control Claude Code’s file-loading behavior. For a small repository with stable instructions and no ongoing handoffs, repository files may be sufficient. The separate Claude Code introduction explains the coding tool itself.