How to Organize a Large CLAUDE.md File with @import, Rules, and /memory

I've written in the past about how Claude Code memory works, the Claude Code context window, and, more recently, the Claude Code hierachy, and yet I continue to see post after post on social media about large CLAUDE.md files. I am hopeful this Claude Code tutorial on memory will give you some insight on how to make your CLAUDE.md file way more efficient so that you're a meaner, leaner, Claude Code machiner. Let's get started.

One of the first rules of the CLAUDE.md file is to keep it under 500 lines. It says so right there in the official Anthropic documentation. And it's not just because it's more efficient. You also preserve tokens that way, but that's a post for another time.

I was recently in contact with someone who was stuffing their CLAUDE.md file with a compressed version of their entire session context hoping Claude would have a better memory. More context may only make Claude's memory worse. If it's that important for Claude to remember, use Claude Code's auto memory or use a hook.

But if you're like me and you like to stay organized, Claude Code offers a couple of ways to help: @imports and rules.

@Imports

Imports aren't just cars fresh off the boat from an assembly line in Japan. They also help to keep your CLAUDE.md file organised by allowing you to reference external files. Let's take a look at the syntax:

@./uppercasefiles/IMPORT THE-FILE-YOU-WANT-TO-REFERENCE-IN-YOUR-CLAUDE-MD-FILE.md

@./lowercasefiles/THIS-FILE-MUST-BE-IN-THE-WRONG-FOLDER.md

(Super long and uncomfortably uppercase file names not required.)

Instead of cramming the contents of these two files into your CLAUDE.md, you can simply reference them, which makes your CLAUDE.md file way easier to read and navigate.

Rules

Rules are a slightly more complicated, but more flexible alternative, to using the @Import statement.

Rather than referencing external files via @import in CLAUDE.md, create a rules folder called .claude/rules/. In this folder, place individual topic-specific markdown files. Claude Code will automatically discover them recursively, which means you can have subfolders inside .claude/rules/ containing markdown files that will also be discovered without registration.

Rule Types

There are two different rule types, which is what makes this more complicated than using an @Import, but may prove to be beneficial to you.

Global Rules

Global rules are prompt-based markdown files

• Contain no YAML frontmatter.
• Strictly prompt-based files.
• Always loaded by CLAUDE.md.

Example global rule called FORMATTER.md:

- Always use four spaces instead of tab
- Use long variable names instead of abbreviations
- Use camel case

This global rule would always be loaded by Claude Code and would apply across every file in your problem for which the rules are applicable.

User rules can also be stored in user scope under ~/.claude/rules, but if there's a conflict, the project scope rule will override the user rule.

Path-Scoped Rules

Path-scoped rules are prompt-based markdown files. The advantage to using path-scoped rules is that they save context and they're only loaded when the file being worked on by Claude Code matches the designated paths in the frontmatter.

• Must contain paths frontmatter.
• Only works for glob, not grep.
• They only load when a file matching the path(s) is being worked on.
• They are only loaded on-demand by Claude Code.

Example path-scoped rule called FORMATTER.md:

---
paths:
  - "frontend/*.js"
  - "backend/**/*.html"
---

All Javascript variables must use camelcase.
All HTML files must contain the site first in the title tag.

In the example above, this rule would only be loaded if a file ending in js located in the frontend folder was being worked on or any file ending in html in any folder under backend was being worked on. Otherwise, this rules file will be ignored and not added to your context, which saves you space and tokens.

/memory

And the last topic for this article is the /memory command. If you're encountering issues with Claude Code not following an instruction, calling the /memory command will tell you which configuration files are currently loaded into context and you will be given the option to edit them from a menu.

❯ /memory

─────────────────────────────────────────────────────────────────────── Memory

Auto-memory: on

❯ 1. User memory Saved in ~/.claude/CLAUDE.md 2. Project memory Saved in ./CLAUDE.md
3. Open auto-memory folder

There are a couple of ways in which the /memory command is useful:

• If you want to know which config files are loaded into context in case a prompt is working as expected.
• If you want to be able to quickly modify any config files loaded into context.

Conclusion

The CLAUDE.md file is much more than a markdown file. It is the mechanism that controls what is loaded into your session context. It can do that by referencing external files via an @Import statement or through the use of global or path-scoped rules, which may help you to keep your context size to a minimum. CLAUDE.md is able to be stored in individual project folders, in user scope, project scope, or any combination of the three. If you're unsure of which configuration files are being loaded into your context, the /memory command will allow you to not only see them, but to modify them quickly and easily through a menu system.

Preparing for the CCA exam? Start with our overview: What Is Anthropic's Claude Certified Architect Exam?