claude-code - 💡(How to fix) Fix [DOCS] Contradictory guidance on whether @imports reduce context consumption [1 participants]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/memory#import-additional-files

Section/Topic

"Import additional files" and "Write effective instructions"

Current Documentation

The "Write effective instructions" section says:

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If your instructions are growing large, split them using imports or .claude/rules/ files.

The "Import additional files" section says:

Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.

What's Wrong or Missing?

These two statements are contradictory. The first implies that splitting instructions into @ imports helps reduce context consumption (it's listed as a solution for files that "consume more context"). The second confirms that imports are eagerly expanded at launch, meaning they don't reduce context at all.

This is further confirmed by #11759, where lazy loading for @ imports was requested and closed as "not planned."

Users reading the size guidance may split their CLAUDE.md into @ imports expecting context savings, only to find the total context usage is unchanged.

Suggested Improvement

Clarify that @ imports help with organization and maintainability, not context reduction. For example:

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If your instructions are growing large, use path-scoped .claude/rules/ files to load instructions conditionally. You can also split files using imports for better organization, though imported content is still loaded into context at launch.

Impact

Medium - Makes feature difficult to understand

Additional Context

The practical alternatives for reducing context are:

• .claude/rules/ with paths: frontmatter (conditional loading)
• Keeping CLAUDE.md minimal with prose pointers to separate docs that Claude reads on demand when needed