Importing Files into CLAUDE.md with @

As a project grows, one CLAUDE.md can get crowded. Instead of stuffing everything into a single file, you can import other files with an @path reference.

How the import works

Inside CLAUDE.md, an @path line pulls in another file. The path is relative to the file doing the importing. This lets you split guidance into focused pieces and keep the main file readable:

# CLAUDE.md

## Overview
This is the payments service. Core rules below; see linked docs for detail.

## Detailed guides
@docs/api-conventions.md
@docs/testing-guide.md

When Claude loads CLAUDE.md, it follows those references and reads the linked files too. The main file stays a short table of contents; the depth lives in separate documents.

Why split things out

Imports keep your top-level memory lean while still giving Claude the full picture. A long testing guide or a detailed style doc does not belong in the middle of your core rules — it buries them. Move it into its own file and link it instead.

It also helps sharing. A doc like docs/api-conventions.md can be useful on its own for people reading the repo, and importing it means there is one copy to maintain, not two that drift apart.

A note on paths

Because paths are relative to the importing file, keep that in mind when you move files around. If CLAUDE.md sits at the repo root, @docs/testing-guide.md points at docs/ beside it. Get the relative path right and the import resolves cleanly every launch.