Progressive Context with @Imports
A lean CLAUDE.md that uses @path/to/file imports to pull in docs, architecture decisions, and git workflows on demand rather than inline.
Description
Claude Code supports @path/to/import syntax in CLAUDE.md to reference external files. Imported files can recursively import others, up to 5 levels deep. This lets you keep CLAUDE.md lean (under 100 lines) while making detailed documentation available when Claude needs it. Example: the root CLAUDE.md references @docs/architecture.md and @docs/git-workflow.md. Claude loads these into context as needed. The key advantage over inline content: you avoid bloating every session with docs that only matter for specific tasks. Personal overrides work too: @~/.claude/my-project-instructions.md lets individual team members add preferences without modifying the shared file.
Who is this for
Growing teams where CLAUDE.md is getting too long but restructuring into per-package files is overkill.
Why files are split this way
Inline documentation in CLAUDE.md eats context window tokens on every session, even when irrelevant. @imports let Claude pull in detailed docs only when the conversation needs them. Architecture docs are referenced often but change rarely. Git workflows matter only during commits. Testing patterns matter only during test writing. Imports match docs to their moment of relevance.
What changed from the previous setup
An increasingly bloated CLAUDE.md with inline architecture docs, git workflows, and testing patterns loaded on every session.
Related patterns
Universal AGENT.md with Symlinks
One AGENT.md file as the single source of truth, with symlinks to CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md.
Spec-Driven AI Development
Separates what to build (SPEC.md) from how the AI should work (CLAUDE.md). Specs define features and constraints, CLAUDE.md defines workflow and conventions.
Multi-Editor Frontend Setup
Frontend-optimized AI config covering design system tokens, component conventions, and testing patterns across Cursor, Copilot, and Claude Code simultaneously.