Split a long CLAUDE.md into small files with @ imports

A CLAUDE.md tends to grow. Build commands, code style, testing rules, release steps, and soon it's 200 lines that Claude Code skims instead of follows. You don't have to pick between short and complete: CLAUDE.md can pull in other files with @ imports.

How it works

Any line in CLAUDE.md can reference another file with @path. Claude Code reads the imported file as if its text were written there. Paths can be relative to the file that does the importing, or start with ~ for your home folder.

A short root file:

# Project notes

- Run `npm test` before saying a change is done.
- Never edit files under `vendor/`.

Testing details: @docs/claude/testing.md
Release steps: @docs/claude/release.md
API style guide: @docs/claude/api-style.md

Each imported file stays focused on one topic, so it's easy to review in a pull request and easy to keep current.

Personal notes without touching the team file

Imports also work for things only you care about. Add a line like this to the project CLAUDE.md:

My local preferences: @~/.claude/my-project-notes.md

Teammates who don't have that file aren't affected, and your notes never land in git.

Tips

• Keep the root file to the rules that matter on every task. Move reference material into imports.
• Imports can nest, but keep it shallow so you can still tell where a rule came from.
• Text inside code spans and code blocks isn't treated as an import, so writing @scope/package in a snippet is safe.
• Run /memory in Claude Code to see which memory files are loaded.

A ready-made short CLAUDE.md, shared permissions, a risky-git hook and a read-only reviewer subagent all ship in Vildanden Agent Config. The free sample is enough to get started today.