CLAUDE.md Syntax & Imports — Claude Cert Academy

CLAUDE.md Syntax & Imports

CLAUDE.md files inject persistent context into every Claude Code session. They are read at startup and at every tool-use boundary, so changes take effect immediately without restarting.

Scope Hierarchy

Claude Code loads CLAUDE.md files in order from broadest to narrowest scope. Each layer can add, specialize, or override guidance from the layer above it.

• 1. Global — ~/.claude/CLAUDE.md. Applies to all projects for this user. Use for personal preferences, global tooling, and machine-specific config.
• 2. Project root — <repo>/CLAUDE.md. Applies to all sessions in this repository. Commit this file. Use for team conventions, tech stack, CI commands.
• 3. Subdirectory — any subdirectory may contain its own CLAUDE.md. Applies when Claude Code is working in or below that directory. Use for module-specific rules.
• 4. Inline (system prompt injection) — content passed via --system or SDK system param. Highest precedence, overrides all file-based CLAUDE.md.

Narrower scopes do not replace broader ones — all applicable CLAUDE.md files are concatenated and injected together. Conflicts are resolved in order: inline > subdir > project > global.

@import Syntax

Use @import to split a large CLAUDE.md into focused files without losing coverage.

# CLAUDE.md
@import docs/testing-conventions.md
@import docs/api-style-guide.md

## Project Overview
This is the payments service...

• Path is relative to the file containing the @import directive.
• Imports are resolved at startup (not lazily). All imported content counts toward context window usage.
• Recommended: keep each imported file under 500 lines to avoid crowding lesson/tool context.
• Circular imports are not detected and will cause duplicate content — avoid them.
• Import depth: avoid more than 2 levels of nesting (@import A, A imports B, B imports C is fragile).

Rule Writing Patterns

Effective CLAUDE.md rules are specific, testable, and explain the why.

# Good: specific, testable, explains why
## Testing
- Always use `pytest` (not `unittest`) — project uses fixtures that require pytest plugins.
- Run `pytest -x` to stop on first failure during development.
- Test files go in `tests/` mirroring `src/` structure: `src/auth.py` → `tests/test_auth.py`.

# Why: comment pattern for non-obvious rules
- Do NOT import from `src/internal/` in tests.
# Why: internal/ is scheduled for deletion in Q3; tests that use it will break at the rename.

# Bad: vague, untenable
## Testing
- Write good tests.
- Be careful with internal modules.

File-Path-Scoped Rules

Prefix rules with a glob pattern to make them apply only when Claude is working on matching files.

# For src/api/**:
- All handlers must validate input with Zod before accessing req.body.
- Return errors as { error: string, code: string } — never throw.

# For migrations/**:
- Migrations are append-only. Never modify an existing migration file.
- Always add a comment with the date and author on line 1.

Common Anti-Patterns

• Vague rules — 'be careful with databases' tells Claude nothing actionable. Write 'never DROP TABLE without a preceding backup step in the same migration.'
• Circular imports — @import A from B and @import B from A duplicates content and bloats context.
• Personal preferences in team CLAUDE.md — the team file is committed and shared. Put personal style prefs in ~/.claude/CLAUDE.md.
• Extremely large single CLAUDE.md — files over ~2000 lines consume significant context window at session start. Break up with @import.
• Missing # Why: comments — rules without rationale get silently ignored or misapplied when context suggests a different approach.

Case-Sensitivity Note

On Linux filesystems the filename is case-sensitive. The file MUST be named exactly CLAUDE.md (all caps). claude.md, Claude.md, and CLAUDE.MD will not be loaded. macOS is case-insensitive by default, so this only bites teams who dev on Mac and deploy/test on Linux.

Continue to Claude Cert Academy