migration-claude-md

name

migration-claude-md

description

Classifies each section of a target project's bloated `CLAUDE.md` into the three-tier context model and proposes moves to path-scoped rules or context entries, keeping only always-load behavior in `CLAUDE.md`. Use when asked to "slim CLAUDE.md", "migrate CLAUDE.md to rules", "rebalance CLAUDE.md", or when a project's `CLAUDE.md` has grown large. Do NOT move `docs/` files (that is `migration-context`) and do NOT auto-execute. Proposal only.

Claude md migrate

Rebalance a large CLAUDE.md so only always-load behavior stays in it, path-scoped behavior becomes a rule, and domain narrative becomes a context entry. Every move is a proposal the user applies by hand.

Guards

• If no CLAUDE.md exists at pwd, stop: ❌ No CLAUDE.md found at the project root.
• If CLAUDE.md has fewer than three ## sections, stop: ✅ CLAUDE.md is already lean. Nothing to rebalance.

Step 1: discover

Run these in parallel from pwd:

• Read CLAUDE.md
• ls .claude/rules/ 2>/dev/null: existing rule subdirs and numbers for placement
• ls .claude/context/ 2>/dev/null: existing context entries for conflict checks
• aitk claude seeds list --json 2>/dev/null: the base seed set. Read the CLAUDE.md entry's content as the always-load baseline. Skip this input when aitk is not installed.

Step 2: classify each section

Split CLAUDE.md by ## heading. Score each section against this order:

1. Always-load. Stays in CLAUDE.md. Signals: cross-cutting behavior that applies every session, output and formatting rules, project-wide invariants, conventions with no file scope. A section that matches the seed baseline is always-load by definition. Keep it and propose no move.
2. Path-scoped. Propose a rule. Signals: behavior that only applies when working in a folder (frontend/, backend/) or on a file type, framework-specific conventions, "when editing X do Y" phrasing. Derive the glob from the named scope.
3. Domain narrative. Propose a context entry. Signals: prose describing how a system or domain is built, decisions, gotchas, structure. Not do-or-do-not rules.
4. Mixed. Both rule and narrative in one section. Flag as "needs manual split". Do not propose a single target.

Step 3: resolve targets

For each section proposed for a move:

• Path-scoped: propose .claude/rules/<subdir>/<n>-<slug>.md with a paths: glob. Pick the subdir and a free number the way create-rule does. If .claude/rules/<subdir>/ already holds a rule on the topic, mark as "conflict" and skip.
• Domain narrative: propose .claude/context/<domain>.md. If the entry already exists, propose appending rather than creating.

Step 4: output

Print one grouped proposal block. Omit empty groups.

## Keep in CLAUDE.md

- `## <heading>` (<one-line reason: always-load behavior>)

## Extract to a path-scoped rule

- `## <heading>` → `.claude/rules/<subdir>/<n>-<slug>.md`, paths `<glob>` (<reason>)

## Extract to a context entry

- `## <heading>` → `.claude/context/<domain>.md` (<reason>)

## Needs manual split

- `## <heading>` (rule and narrative mixed)

## Conflicts

- `## <heading>` → `.claude/rules/<subdir>/<n>-<slug>.md` already exists. Skipping.

## Reminder

Scaffold each rule with create-rule and follow .claude/standards/rule.md.
Follow .claude/standards/context.md for each new context entry.
Run aitk indexes regen after adding context entries.

If every section classified as always-load, output: ✅ CLAUDE.md holds only always-load behavior. No moves proposed.

Do not edit CLAUDE.md, and do not create the rule or context files. The user reviews the proposal, then applies each move by hand.