Modular Claude Code Configuration with @import and .claude/rules/

What modular Claude Code configuration solves

Modular Claude Code configuration is the answer to a problem every growing project eventually hits: the single CLAUDE.md that started as a tidy page of conventions has swollen into a sprawling document covering testing, API design, infrastructure, style, and a dozen other concerns. A file like that is hard to read, hard to review in a pull request, and, counterintuitively, less effective, because once a configuration file grows too long, important rules get lost in the noise and Claude starts skipping them.

Rather than living with one monolith, Claude Code gives you two mechanisms to break instructions apart while keeping them all active. The first is the @path import syntax, which lets one file reference others. The second is the .claude/rules/ directory, where you place separate markdown files, one per topic. Both let you compose a configuration out of small, single-purpose pieces, which is exactly the kind of apply-level skill task statement 3.1 expects you to demonstrate.

Importing files with the @path syntax

The import mechanism is deliberately simple. Anywhere inside a CLAUDE.md, you can reference another file by writing an @ followed by its path, and Claude expands that file inline when it loads your configuration. A line such as See @README.md for project overview and @package.json for available npm commands brings both of those files into context without you copying their contents into CLAUDE.md.

Paths can be relative or absolute. Relative paths resolve from the location of the file containing the import, not from your current working directory, which matters when an imported file itself imports more files. You can also import from your home folder with a ~/ path, a useful trick for sharing personal instructions across multiple git worktrees of the same repository. Imports nest: an imported file can import others, and Claude follows the chain recursively up to a maximum depth of four hops.

There is one behaviour you must commit to memory, because it is a favourite exam trap. Imported files are expanded and loaded into context at launch, just like the main file. Importing does not defer or shrink anything; the tokens are spent the moment the session starts. So @import is a tool for organising and de-duplicating instructions, not for reducing context usage. If your goal is to load instructions only when they are relevant, that is a different mechanism entirely, path-scoped rules.

Organising with the .claude/rules/ directory

The second mechanism is the .claude/rules/ directory. Instead of threading imports through one file, you create a folder of standalone markdown files, each covering a single topic with a descriptive name like testing.md, api-design.md, or security.md. Claude discovers every .md file in that directory recursively, so you can even nest subfolders such as frontend/ and backend/ to keep larger rule sets organised.

The loading behaviour is the key detail. A rule file with no special frontmatter is loaded at launch with the same priority as .claude/CLAUDE.md, so moving a section out of your main file and into .claude/rules/testing.md does not change whether it applies, only where it lives and how readable your configuration is. This is the clean way to keep the main CLAUDE.md short while still expressing detailed conventions. Rules can additionally be scoped to file paths with frontmatter so they only load when relevant, but that conditional behaviour is the subject of its own task statement; for modular organisation, the everyday win is simply one topic per file.

Choosing between imports and rules files

Both tools produce a modular configuration, so when do you reach for each? Imports shine when you want one file to remain the readable index that pulls in canonical sources, referencing an existing README, a contributing guide, or a shared instruction file, so you maintain the content in one place and reference it from another. The .claude/rules/ directory shines when the instructions are genuinely Claude-specific conventions that naturally cluster by topic, and you want each cluster to be its own reviewable file.

A practical rule of thumb: if the content already exists somewhere in the repo, import it; if it is new Claude guidance you are authoring, give it a home in .claude/rules/. Either way the outcome is the same, no single file grows unmanageable, and each piece can be edited and reviewed on its own. And in both cases the version-control rules from the previous knowledge point still apply: anything under the project directory, imports and rule files alike, is committed and shared with the team.

Refactoring a monolith in practice

The clearest way to internalise this is to watch a bloated configuration get untangled. The mechanical moves are small, but the judgement, what becomes an import versus a rule file, is the part the exam rewards.

Common misreadings to avoid

The two mistakes below are the ones that turn up most often when people first modularise their configuration.

How imports and rules sit within the hierarchy

Modular organisation does not replace the configuration hierarchy; it operates inside it. An imported file inherits the scope of whatever file imported it, so importing @docs/api.md into the project CLAUDE.md makes that content part of the shared, committed project scope, while importing it into your user file keeps it personal. The same is true of .claude/rules/ files committed under the project directory: they travel with the repository exactly as the project CLAUDE.md does. Splitting a configuration into pieces never silently changes who receives those pieces; the location of each file still decides its audience.

This is why modular organisation and version control reinforce each other rather than complicate each other. When you move a testing policy from a bloated CLAUDE.md into .claude/rules/testing.md, you have made the configuration more maintainable and left its sharing behaviour untouched, because the rules directory lives inside the same committed project. The mental checklist stays the same as for any single file: ask which scope the piece lives in, and therefore who will load it.

When one CLAUDE.md is still the right call

Modularity is a response to growth, not a goal in itself, so it is worth knowing when not to split. A small project whose entire configuration is a dozen lines of build commands and two conventions does not benefit from a rules directory; the indirection would cost more clarity than it buys. The threshold to watch is the same one that governs adherence: when a single file starts pushing past roughly two hundred lines, or when distinct topics begin crowding each other, that is the signal to break it apart.

The judgement the exam rewards is matching the structure to the size of the problem. Reach for imports when you are duplicating content that already lives elsewhere in the repo. Reach for .claude/rules/ when authored, Claude-specific guidance has grown into several genuinely separate topics. And leave a small configuration as one tidy file until it actually outgrows itself. Over-engineering a trivial setup is its own anti-pattern, just a quieter one than the monolith it tries to avoid.

Keep the structure honest as it changes

One last discipline keeps a modular configuration trustworthy: when instructions move between files, make sure the structure still reflects reality. A rule that is renamed or relocated should land in the file whose topic it matches, and a .claude/rules/ file that has quietly grown to cover three subjects is itself a small monolith waiting to be split again. Treating the configuration like code, reviewing it, refactoring it, and pruning stale entries as the project evolves, is what stops a tidy modular setup from drifting back into the very sprawl it was created to cure. The mechanics of importing a file or adding a rule are trivial; keeping the resulting structure faithful to how the project actually works is the part that takes ongoing care.

How this shows up on the exam

This knowledge point is tested at the apply level, meaning you will be handed a messy configuration and asked to reorganise it correctly, not merely define the terms. Two discriminators come up repeatedly. First, whether you know that imports load at launch and therefore do not save context, the trap that separates a surface understanding from a real one. Second, whether you reach for .claude/rules/ files to keep topics modular instead of piling everything into one document. Get those right and you can build a configuration that scales with the project, which is exactly the foundation the team-strategy knowledge point then puts to work.

Watch and learn

Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.

Official · Anthropic AcademyOpen full lesson in Academy

Adding context

Why watch: Pulling in additional files via imports keeps configuration modular instead of one giant file.

More videos for this concept

Adding context

Claude Code in Action · 5:14

This Memory System just 10x'd Claude Code

Jack Roberts

Master ALL 7 Levels of Claude Code Memory

Mark Kashef

Claude Code's Memory System: The Full Guide (Most Developers Miss 90% of This)

DIY Smart Code