CLAUDE.md: How to Include and Reference Other Files

To include another file in CLAUDE.md, use an @path import in ordinary text; a Markdown link is a reference, not the same automatic loading instruction. Import stable instructions the session needs, then verify what loaded. fenbs can hold changing project decisions and progress so your instruction file does not become a copied session diary.

How do you add a working import?

1. Choose a small instruction file that applies to the project, such as a testing convention or shared safety rule.
2. Add an unquoted @path reference in CLAUDE.md, using a path relative to the file containing the import.
3. Start a fresh session from the intended directory and inspect the loaded memory files with /memory or /context.
4. Ask Claude to state one distinctive instruction from the included file before relying on it during a real change.

# Project instructions

Use the existing package manager and preserve user-authored files.

@docs/testing-rules.md
@docs/review-rules.md

Reference for optional background: [architecture](docs/architecture.md)

In the example, the first two document paths are imports; the architecture link is background to consult when relevant. The example is shown as a code block so you can copy its contents into a real file. Do not put a fence around the import lines inside that file.

Anthropic documents this syntax in Import additional files↗ (opens in a new tab). Keep the official page available when checking edge cases such as spaces, external paths, and nested imports instead of copying syntax from an old example.

How is an import different from a Markdown link?

An import asks the instruction loader to bring the referenced content into the session. A link gives the assistant a place to look; whether it reads that destination depends on the instructions, task, and available tools. A path written as inline code is also a literal reference rather than an import.

Make the choice explicit. “Read the architecture guide before changing a service boundary” tells the assistant when that reference matters. A bare link says much less. Conversely, importing a large architecture history forces unrelated sessions to carry material they may never need.

For the narrower question of using references as navigation, see CLAUDE.md references to other files. The practical import decision is whether the content must be loaded or can be consulted when the task calls for it.

Which directory and session does an include apply to?

Scope matters as much as syntax. A project instruction should serve the people working in that project; a personal preference should not quietly become a team-wide requirement. Check the starting directory and the applicable instruction files before assuming two developers received the same context.

Anthropic’s context guidance↗ (opens in a new tab) distinguishes personal and repository instruction locations. Keep shared imports in files the team can access, and avoid machine-specific absolute paths for a repository that colleagues run elsewhere.

For example, a root instruction file can point to a repository-owned test policy. A nested package can have specialized instructions for that package. Do not assume that a file existing somewhere beneath the repository means its contents have already reached the active session; test the scope in the directory where the work will happen.

When several applications or repositories are involved, see multiple-project CLAUDE.md organization. Keep the import you are testing small enough that its presence and purpose are easy to establish.

Why might a valid-looking include fail?

Check the source file as plain text first. Confirm the filename, capitalization, extension, and path from the including file. Then check whether the import was accidentally placed inside backticks, a fenced example, or quotes. Documentation often demonstrates syntax without activating it; copying the surrounding formatting can preserve that behavior.

• Use one straightforward import first. Add another only after the first is confirmed.
• Prefer a short path without spaces for an initial test. For an existing spaced path, follow the vendor’s documented escaping syntax.
• Check whether the target is inside the intended project and whether an external-import approval was required.
• Inspect both documents for contradictory instructions rather than assuming the included one overrides everything else.
• Repeat the check in a fresh session if you edited the files after the session started.

If the file is present but the assistant ignores the rule, distinguish loading from following. A visible instruction can still be vague or contradicted by another instruction. “Preserve the public response fields” is easier to verify than “be careful with compatibility.” Our CLAUDE.md troubleshooting guide covers that wider problem.

Also distinguish instructions from settings. Anthropic’s settings guide↗ (opens in a new tab) explains configuration files and their scope. A sentence in CLAUDE.md is not a replacement for an enforced permission setting, so do not treat an imported “never do this” sentence as a technical barrier.

What should you keep out of the import tree?

Keep long transcripts, duplicated manuals, and temporary progress out of always-needed instructions. Splitting a large file into several imported files improves organization, but the resulting material still needs to be read. Review what every session truly needs before adding another shared include.

Use instruction files for stable conventions and task references for changing work. A client’s approved decision, an unfinished check, and tomorrow’s next step need a record that can be updated and reviewed. Copying those items into several instruction files creates competing versions and makes an old checkpoint look authoritative.

That is where fenbs project context fits: keep current decisions and progress together, then ask a connected assistant to read the relevant record instead of importing a growing collection of session notes.

How to do this with fenbs

1. Create a free account and add the project whose changing context you want to preserve.
2. Record the person’s approved choices in Decisions and rules, and put current work and remaining checks into tasks.
3. Connect Claude Code through the integration guide using the browser sign-in, then ask it to read the project’s AI context before starting.
4. Keep CLAUDE.md focused on stable repository instructions. Save Where we left off in fenbs before stopping, and verify it when another session begins.

fenbs does not expand CLAUDE.md imports or repair a broken local path. A repository used entirely by one assistant may be well served by small instruction files alone. fenbs helps when current work needs to survive sessions or reach teammates using different AI apps.

Explore the context engineering hub for the broader practice. The useful test remains simple: can the assistant identify the instruction it loaded, find the source when needed, and state the current next action without inventing missing details?