CLAUDE.md @import is silently skipped when the path is followed by a colon or comma

Summary

An @path import in CLAUDE.md is silently skipped when the path is immediately followed by a : or ,. The file is never loaded, no warning is printed at startup, and nothing in the session indicates that a referenced instruction file is missing.

This is easy to hit, because writing a filename followed by a colon and then an explanation is a completely ordinary sentence:

The full workflow is described in @agent-workflow.md: when a step may be skipped, what belongs in each task, and what counts as evidence.

The docs state that imports work anywhere in the file, and the example itself puts two imports mid-sentence:

To pull in a README, package.json, and a workflow guide, reference them with @ syntax anywhere in your CLAUDE.md: `` See @README for project overview and @package.json for available npm commands for this project. ``

So mid-sentence placement is documented as supported. Nothing documents that trailing punctuation disables the import.

In my case a 242-line workflow file sat referenced in ~/.claude/CLAUDE.md for a long time and was never loaded into a single session. I only found out by accident.

Reproduction

D=$(mktemp -d)
cd "$D"
printf 'MARKER-ALPHA-COLON\n' > a-colon.md
printf 'MARKER-BRAVO-SPACE\n' > b-space.md
printf 'MARKER-CHARLIE-OWNLINE\n' > c-line.md
printf 'MARKER-DELTA-COMMA\n' > d-comma.md

cat > CLAUDE.md <<'EOF'
# Test

Variant A: the details are in @a-colon.md: and the sentence continues.

Variant B: the details are in @b-space.md and the sentence continues.

Variant D: the details are in @d-comma.md, and the sentence continues.

Variant C is on its own line below.

@c-line.md
EOF

claude -p "Look at your own context. Which of these four strings appear literally in it: MARKER-ALPHA-COLON, MARKER-BRAVO-SPACE, MARKER-CHARLIE-OWNLINE, MARKER-DELTA-COMMA? Answer with only the ones you actually see, then a line listing the ones you do not see. Do not use tools." < /dev/null

Actual output

MARKER-BRAVO-SPACE
MARKER-CHARLIE-OWNLINE

Not present:
MARKER-ALPHA-COLON
MARKER-DELTA-COMMA

Control run

To confirm the trigger is the punctuation and not the filename, I swapped which file gets the colon (a-colon.md followed by a space, b-space.md followed by a colon, d-comma.md followed by a space). The result flips exactly as the punctuation moves:

MARKER-ALPHA-COLON
MARKER-CHARLIE-OWNLINE
MARKER-DELTA-COMMA

Not present:
MARKER-BRAVO-SPACE

So: @file.md (space) loads, @file.md on its own line loads, @file.md: and @file.md, do not.

Expected

Either of these would fix it, and the second one matters most:

1. Stop the path at trailing punctuation, so @file.md: imports file.md. This matches what the docs promise and what people actually type.
2. Warn when an @ reference does not resolve to a readable file. Even if the parsing behaviour is intentional, a reference to a nonexistent path should not be silently discarded. There is currently no way to notice: /context shows the files that did load, and a file that was never parsed as an import simply is not there. The failure is invisible until you go looking for it.

Please also document the rule, whichever way it lands.

Environment

• Claude Code 2.1.227
• macOS 26.5