Migrating to RuleSync: From Files to Managed Rulesets
Import scenarios: migrating from manual management (you have CLAUDE.md files in repos, maintained manually — import into RuleSync for centralized management), onboarding an existing organization (the org has been using AI rules without RuleSync — import their existing rules to start with their current conventions, not from scratch), restoring from backup (importing a previously exported ruleset — restoring after data loss or rolling back a problematic change), and importing community templates (bringing a community-shared template into RuleSync for customization and distribution).
The import advantage: before import, rules are: scattered across repos (each CLAUDE.md maintained independently), unversioned (changes are tracked only in git, not in a rule-specific version history), and untracked (no centralized view of which repos have which rules). After import into RuleSync: rules are centralized (one source of truth), versioned (every change tracked with version numbers), distributed (synced to all assigned projects automatically), and tracked (adoption dashboard shows which repos are current).
The import principle: import preserves your existing rules exactly as they are. RuleSync does not modify, reformat, or restructure imported rules. The import: is the starting point. After import: you manage, version, and distribute through RuleSync. The rules: unchanged in content, improved in management. AI rule: 'Import is lossless. Your rules go in exactly as they are. RuleSync adds: versioning, sync, and tracking — without changing the rule content.'
Step 1: Import a Single Rule File
Dashboard import: Rulesets → New Ruleset → Import from File. Upload: a CLAUDE.md, .cursorrules, or any .md file. RuleSync: reads the file content and creates a new ruleset with the imported rules as the initial version (v1.0.0). Enter: the ruleset name, description, and type (base, technology, or project). The imported ruleset: immediately available for editing, publishing, and distribution. Total time: 1 minute.
CLI import: rulesync import --file ./CLAUDE.md --name 'My Project Rules' --type technology. The CLI: creates the ruleset in the RuleSync dashboard from the local file. Use: when importing from a project directory (the CLAUDE.md is already on disk). The CLI import: faster for developers who prefer the terminal. Multiple files: run the import command for each file (one import per ruleset).
Post-import verification: after importing, open the ruleset in the dashboard editor. Verify: the content matches the original file (formatting preserved, sections intact, no missing rules). Test: pull the imported ruleset to a project (rulesync pull) and verify the generated CLAUDE.md matches the original. If identical: the import was lossless. If different: investigate (usually a minor formatting difference in the Markdown parser). AI rule: 'Always verify after import. The import should be lossless — the generated output should match the original input.'
50 repos, each with an identical CLAUDE.md (copy-pasted). Importing each: creates 50 rulesets with the same content. Managing: 50 rulesets instead of 1. Updates: must be applied 50 times. Deduplicate: identify that all 50 are identical. Import once: create one ruleset. Assign to all 50 repos. Updates: applied once, synced to 50. The 10-minute deduplication: saves hours of ongoing management.
Step 2: Bulk Import from Multiple Repos
For organizations with rules in many repos: a bulk import workflow. Step 1: collect all CLAUDE.md files from your repos. Script: for each repo in the manifest, clone and copy the CLAUDE.md to a local directory named by the repo. Step 2: analyze the collected files. Are they identical (one shared set of rules copied to each repo)? Similar with variations (a common base with per-repo customizations)? Or completely different (each repo has unique rules)? The analysis: determines the import strategy.
Import strategy for identical rules: import once as a single ruleset. Assign to all repos. The repos: now share one centralized ruleset instead of duplicated copies. Import strategy for similar-with-variations: import the common base as a base ruleset. For each repo's unique rules: create a project-level ruleset with the variations. Assign both (base + project) to each repo. Import strategy for completely different rules: import each repo's rules as a separate project-level ruleset.
Deduplication: if multiple repos have the same rules (copy-pasted CLAUDE.md), the import: should create one shared ruleset, not 50 identical rulesets. Compare the collected files: identical files → one import, assigned to all. Similar files: diff to identify the shared base and the per-repo variations. The deduplication: a one-time effort that produces a clean, centralized rule library instead of a cluttered collection of duplicates. AI rule: 'Deduplicate before importing. One shared ruleset assigned to 50 repos: cleaner than 50 identical rulesets.'
Before migration: developers have a CLAUDE.md in their repo. The AI reads it. Code follows the rules. After migration: developers have a CLAUDE.md in their repo (generated by rulesync pull instead of manually written). The AI reads it. Code follows the rules. The content: identical. The developer's workflow: unchanged. They may not even notice the migration happened — which is the goal. The management mechanism changed. The developer experience: unchanged.
Step 3: The Complete Migration Workflow
The migration from manual to RuleSync-managed rules: Phase 1 — Import (1 day): collect all CLAUDE.md files, analyze and deduplicate, import into RuleSync as rulesets (base + technology + project), and assign rulesets to projects. Phase 2 — Verify (1 week): run rulesync pull in each project. Compare the generated CLAUDE.md against the original. Verify they match. Fix any discrepancies. Phase 3 — Switch (1 day): update CI pipelines to use rulesync pull --check (verify freshness). Update the postinstall hook to use rulesync pull (automatic sync). The projects: now managed by RuleSync.
The switchover: the moment when the project's CLAUDE.md is managed by RuleSync instead of manually. Before: the CLAUDE.md is hand-edited and committed directly. After: the CLAUDE.md is generated by rulesync pull from the centralized ruleset. The switch: should be invisible to developers (the file content is the same — only the management mechanism changed). Communicate: 'Our AI rules are now managed by RuleSync. The rules themselves have not changed. Run rulesync pull to sync.'
Rollback: if the migration causes issues (the generated CLAUDE.md differs from the original, or rulesync pull breaks in certain environments): rollback by reverting to the original CLAUDE.md (git revert the generated file). Investigate the issue. Fix. Re-attempt the migration. The rollback: always possible because the original files are in git history. AI rule: 'The migration is reversible at every stage. The original files are in git. The import does not modify the originals. If anything goes wrong: revert and investigate.'
The import: copies the rule content into RuleSync. The pull: generates a CLAUDE.md from the imported content. But: the Markdown parser may handle edge cases differently (nested lists, code blocks, special characters). If the generated output differs from the original: the AI may behave differently after the migration. The verification: diff the original CLAUDE.md against the rulesync pull output. If identical: safe to switch. If different: investigate the parsing difference and fix before switching.
Import Summary
Summary of importing rules into RuleSync.
- Scenarios: manual migration, organization onboarding, backup restoration, community template import
- Dashboard: upload a CLAUDE.md/.cursorrules/.md file → creates a versioned ruleset. 1 minute
- CLI: rulesync import --file ./CLAUDE.md --name --type. For terminal-native workflows
- Bulk: collect files from all repos → analyze (identical, similar, different) → deduplicate → import
- Deduplication: identical files → one shared ruleset. Similar → base + project variations
- Migration: import (1 day) → verify (1 week) → switch (1 day). Total: ~2 weeks for full migration
- Switchover: invisible to developers. Same rules, different management mechanism
- Rollback: always possible. Original files in git. Import does not modify originals