K3.1.2 Task 3.1

Mentioning a File Is Not the Same as Loading It

Writing “Follow our standards in docs/coding-style.md” inside CLAUDE.md is just text. Claude reads the sentence but does not open the file. To actually load external content into context, use the @import syntax: @docs/coding-style.md.

This single distinction — text reference versus @import — is the source of most “Claude ignores our guidelines” reports.

How @import Works

Place @filepath anywhere in CLAUDE.md. Claude Code resolves the path relative to the project root and loads the file content into context alongside the rest of CLAUDE.md.

# Project Standards

@docs/coding-standards.md
@docs/testing-guide.md
@docs/security-policy.md

Claude sees the combined content as if it were all inline. The main CLAUDE.md stays short and readable. The referenced files stay where they naturally live — in docs, in wiki exports, wherever the team already maintains them.

Why Monolithic CLAUDE.md Is an Anti-Pattern

An 800-line CLAUDE.md with everything inline works technically. But when 8 developers all edit the same file, merge conflicts pile up. One team measured 12 CLAUDE.md merge conflicts per month before restructuring.

After splitting into a 120-line CLAUDE.md with 6 @import references, merge conflicts dropped to 2 per month. Guideline adherence stayed at 94% — proof that @import delivers content to Claude identically to inline text. The only thing that changed was maintainability.

The refactoring path is straightforward: extract each section into its own file, replace the inline content with @filepath, commit. No migration tool, no rebuild step, no cache to clear.

User-Level Paths: @~/.claude/...

The @import syntax supports ~/ paths. @~/.claude/team-preferences.md resolves to each developer’s home directory.

This creates the same “works on my machine” trap as user-level CLAUDE.md itself. Existing team members who created the file see it work. A new hire who never created the file gets nothing — the import silently resolves to empty. If the referenced file must exist for everyone, it belongs in the project repo, not in user home directories.

This pattern also shows up in cross-domain scenarios. A project’s .mcp.json might use ${GITHUB_TOKEN} for MCP server authentication while CLAUDE.md uses @import to reference a local setup guide. Both depend on local resources — environment variables and local files. A new developer who hasn’t configured either gets both failures simultaneously, for the same root cause: missing local setup.

Over-Importing Defeats the Purpose

An architect once proposed: “Every subdirectory CLAUDE.md should cross-import all the others, so Claude always has complete context.”

With 12 subdirectories and 3000 combined lines, this loads backend API rules when editing frontend UI code. It loads infrastructure Terraform rules when writing unit tests. The directory-level hierarchy exists to scope rules to where they are relevant. Cross-importing everything undoes that scoping and wastes context tokens on noise.

The correct approach: @import only genuinely shared standards. If coding-style.md and security.md apply everywhere, import them from the root CLAUDE.md. If backend-api.md only matters for backend code, keep it in the backend directory’s CLAUDE.md or in a path-scoped rules file.

Combining @import with .claude/rules/

For selective loading — global standards always, area-specific standards conditionally — use two mechanisms together:

  1. Root CLAUDE.md with @import for standards that apply everywhere (coding style, security policy).
  2. .claude/rules/ files with paths frontmatter for standards that apply only to specific file types or directories.
# Root CLAUDE.md
@docs/coding-standards.md
@docs/security-policy.md
# .claude/rules/backend-api.md
---
paths:
  - "src/api/**"
---
[Backend API conventions here]

Global standards load for every edit. Backend rules load only when editing src/api/ files. No duplication, no irrelevant context, no conditional comment hacks.

Things That Do Not Exist

  • HTML-style <include src="..."/> — Not a CLAUDE.md feature. Use @filepath.
  • YAML imports: frontmatter in CLAUDE.md — YAML frontmatter is for .claude/rules/ path configuration, not for CLAUDE.md imports.
  • Comment-based conditional loading (<!-- backend only -->) — All @imported content loads unconditionally. Conditional scoping comes from file placement and paths globs.
  • Import depth limits — There is no silent cutoff at 2 levels or any other depth.
  • Cache or index rebuild — @import resolves at load time each session. No cache to clear, no rebuild command to run.

One-liner: @filepath loads the file into context — a plain text mention does not — and the difference between the two explains most “Claude ignores our guidelines” issues.