migration-guide

To split a large CLAUDE.md file, identify large sections that would benefit from separation, move that content into topic-specific files under a dedicated .claude/rules directory, and update the original CLAUDE.md with references to the new files.

You should migrate CLAUDE.md content into a separate rules directory when the file becomes unwieldy and hard to maintain, allowing you to keep a concise overview in CLAUDE.md while storing detailed topic-specific guidelines externally.

The best way to organize .claude/rules files during a documentation refactor is to group content by topic, create dedicated rules files for each identified large section, and use simple Markdown guidance with YAML frontmatter where appropriate.

Moving CLAUDE.md rules into .claude/rules assumes a repository structure with a memory optimizer plugin. You can then separate topic-specific rules and update references in the original CLAUDE.md to point to the new files.

Yes, you can keep a concise overview in CLAUDE.md after moving guidelines to .claude/rules by removing the migrated content from the main file and replacing it with references that point to the newly created topic-specific rules files.

Your CLAUDE.md becomes hard to maintain as project guidelines grow because all rules accumulate in a single file. Migrating content into a dedicated rules directory improves maintainability by splitting large sections into focused topic-specific files.