Modular CLAUDE.md with @imports and .claude/rules/

1.Why one big CLAUDE.md stops working

Teams tend to keep adding to the project CLAUDE.md until it covers everything: style, testing, API design, deployment, every package. The documentation gives a size target, and that target has a cost behind it. A long file takes up context in every session and makes Claude follow it less reliably.

There are two separate tools for modularity, and they do different jobs. @imports keep the files tidy and reusable, but everything they reference is still loaded at launch. Path-scoped rules in .claude/rules/ also save context, because each one loads only when Claude works with files that match it. Whichever you use, group instructions under headers and bullets, because organized sections are easier for Claude to follow than dense paragraphs.

Sources1

2.The @import syntax

Inside a CLAUDE.md, @ followed by a path pulls that file's contents in. You can import inline in a sentence or as a list item. A path starting with ~ points into your home directory, which lets a committed project file reference a personal file that each developer keeps for themselves.

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

# Individual Preferences
- @~/.claude/my-project-instructions.md

If an import points at a file outside your working directory, Claude Code asks you to approve external imports. The most common real-world use is a repository that already has an AGENTS.md shared with other AI coding tools. You don't need to duplicate it. Import it, then add the Claude-specific lines below the import.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The difference between an import and an instruction written in words matters. A sentence like "read AGENTS.md first" doesn't load anything. Claude sees the file only if it decides to open it. The @AGENTS.md import guarantees the content is loaded, and keeping that import never causes Claude to read AGENTS.md twice.

Sources1

3.Per-package CLAUDE.md files in a monorepo

In a monorepo, the root CLAUDE.md holds what applies everywhere, such as coding standards and commit conventions. Each package then gets its own CLAUDE.md for the conventions of its stack.

Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example `api: add rate limiting`.
Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.

A per-package file lives alongside its code, so the people who own that directory maintain its conventions, and the instructions are versioned with the code. Because import syntax works in any CLAUDE.md, a package maintainer can use @ to pull in only the shared standards files that apply to their package. For example, the API package's CLAUDE.md might import an API-conventions document that the web package has no use for. The sources show the per-package files and the import syntax separately, not one combined example. The pattern simply relies on the maintainer knowing which standards their package needs. If there are packages you never work in, claudeMdExcludes can skip their CLAUDE.md files altogether.

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

Sources2

4.Topic files in .claude/rules/

Instead of one long file, .claude/rules/ holds one markdown file per topic. The documentation's example has code-style.md, testing.md and security.md next to the main .claude/CLAUDE.md. Rules files are committed like CLAUDE.md, and a user-level ~/.claude/rules/ exists for personal rules. A rule without frontmatter applies broadly. Adding a paths: field restricts it to files that match the given globs.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

---
 ? :
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Rules and per-directory CLAUDE.md files overlap, so choose deliberately.

Sources13

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Breaking CLAUDE.md into @imported files shrinks what loads into context at launch.Why is that wrong?

   Imported files load at launch too. Only path-scoped rules defer loading until Claude works with matching files.

   Covered in Why one big CLAUDE.md stops working

2. 2.Writing "read AGENTS.md" in CLAUDE.md is as good as importing it.Why is that wrong?

   A reference in words only works if Claude decides to open the file. An @AGENTS.md import loads it reliably and never causes a double read.

   Covered in The @import syntax

Practise it for real

Replace part of a long CLAUDE.md with a path-scoped rule and confirm what loads

1. 1.Create .claude/rules/api.md with paths: frontmatter set to "src/api/**/*.ts" and move your API instructions into it

   Why: Path-scoped rules load only when Claude works with matching files

   You should see: The API instructions are no longer part of the project CLAUDE.md

2. 2.Start a session and run /context, checking the list under Memory files

   Why: /context shows which memory files actually loaded

   You should see: Your project CLAUDE.md is listed. If a file you expected is missing, Claude can't see it

3. 3.Run /memory

   Why: It lists memory file locations across user and project scopes and lets you open each one

   You should see: You can tell user-level files from project-level files and open either in your editor