Refactor Instructions

Refactor Instructions

Refactor monolithic instruction files into a minimal root, scoped .claude/rules/ files, and reference docs.

Why this matters

• The root file loads on every request. A bloated file steals tokens from the actual task and pushes the agent past its effective instruction budget (~150–200 rules before attention drops).
• .claude/rules/ files with paths: globs load only when matching files are touched — scoped rules keep the base context lean without losing coverage.
• Stale docs poison context. File paths rot fastest — describe capabilities, not structure.
• Instruction files grow as balls of mud when rules are added reactively after every agent misstep. Small and focused beats comprehensive.

Process

1. Detect scope. If a path argument was given ($ARGUMENTS), use that file as the target. Otherwise, use AskUserQuestion to ask which scope to refactor: project-level .claude/CLAUDE.md, user-level ~/.claude/CLAUDE.md, or both. Then scan for CLAUDE.md, AGENTS.md, and .claude/rules/*.md at the chosen scope. In monorepos, also check **/CLAUDE.md. If both CLAUDE.md and AGENTS.md exist with different content, surface this — they may want a symlink. Determine docs location: use existing docs/ if present at repo root, else default to .claude/docs/. When working at project level, also read ~/.claude/CLAUDE.md and ~/.claude/rules/*.md read-only for contradiction checking.

2. Read every target file in full — root files and every .claude/rules/ file — before proposing anything. Do not rely on skimming.

3. Find contradictions. Check across all sources: root vs rules, rules vs rules, project-level vs user-level. List every conflicting pair. For each, use AskUserQuestion to ask which version to keep. Do not silently pick.

4. Identify essentials for the root. Keep only what applies to every single task:

   • One-sentence project description (anchors the agent's role)
   • Package manager, only if non-default (pnpm, yarn, bun, uv, etc.)
   • Non-standard build / typecheck / test commands
   • Truly universal rules (e.g., "never commit to main")
   • Domain concepts that differ from common usage (e.g., "organization" means X, not Y) — these are more stable than file paths and worth keeping

5. Classify remaining content. For each extracted section, decide the destination:

   • packages/<pkg>/CLAUDE.md — rules scoped to one package with its own conventions (different stack, commands, or domain). Loads lazily when Claude touches that package.
   • .claude/rules/<domain>.md — short, actionable rules that cross packages or file types. For each, recommend whether to add paths: frontmatter (lazy) or leave without (always loaded), with a one-line rationale.
   • docs/<TOPIC>.md — longer reference material, domain knowledge, examples, guides.
   • Delete — see step 7.

6. Audit existing rules files. For each .claude/rules/ file already present, check:

   • Redundancy with the root file or other rules
   • Vague or unactionable content
   • Missing paths: globs that should be scoped
   • Overly broad globs that defeat lazy loading
   • Merge or split opportunities

7. Flag for deletion. Mark instructions (in root, rules, or docs) that are:

   • Redundant — the agent already knows this (e.g., "write readable code")
   • Too vague to be actionable
   • Inferable — agents discover project structure on their own; codebase overviews and architecture descriptions trigger extra exploration without improving accuracy
   • Structural — file paths, directory layouts, or architectural maps that rot and mislead
   • Over-directive — imperative instructions that force unnecessary work (e.g., "always run the full test suite", "review all related modules") without scoping when they apply

8. Propose the structure before writing. Output:

   • The new minimal root file (with links)
   • Each .claude/rules/ file with its proposed frontmatter
   • Each docs file's content
   • A deletion list with a one-line rationale per item

   Use AskUserQuestion to present all proposed rules with their glob recommendations in a single table — confirm or override in one pass. Then use AskUserQuestion to confirm the full plan before writing anything to disk.

9. Write the files once approved. Rules files use this frontmatter format:

   ---
   paths:
     - "src/api/**/*.ts"
     - "**/*.test.{ts,tsx}"
   ---
   

   Omit paths: for rules that should always load. In the root, use imperative prose ("To X, do Y"); reserve ALL-CAPS for true absolutes.

Where each rule belongs

Monorepos

Sub-folder CLAUDE.md files load lazily — only when Claude touches a file in that directory. They merge with the root at their scope, which makes them ideal for package-specific conventions. But the laziness is not free maintenance.

Create a sub-folder CLAUDE.md when the package genuinely diverges from the root: different stack, different commands, package-specific gotchas, or critical domain invariants.

Do not create one when the package follows the same conventions as the rest of the repo, or when the content would just restate what Claude can infer from package.json, file extensions, or the code. Adding a file "for symmetry" creates a maintenance surface that rots faster than it helps.

Keep each sub-folder file under ~100 lines; 200 is the hard ceiling. Past it, extract reference material to docs/ or split cross-cutting rules into .claude/rules/ with scoped globs.

Sub-folder CLAUDE.md vs .claude/rules/ with globs:

• Sub-folder wins when a whole package has coherent, team-owned conventions.
• Rules with globs win when the rule is cross-cutting (testing, API design, logging) and applies by file type across packages.
• They complement each other — most monorepos want both.

Don't document package directory layouts in the root. Sub-folders load lazily when touched; the root doesn't need to list them. Claude can ls the monorepo faster than it can misread a stale inventory.

Avoid

• Documenting file-system paths in the root — they rot.
• Forceful tone ("ALWAYS", "NEVER", caps) for rules that don't truly need emphasis.
• Auto-regenerating the root via init scripts — generated files prioritize comprehensiveness over restraint.
• Ignoring the AGENTS.md ↔ CLAUDE.md symlink option when the repo is used by multiple agents.
• Writing files before the user has approved the proposed structure.
• Creating rules files that duplicate what is already in the root.
• Modifying user-level ~/.claude/rules/ when operating at project scope.
• Using overly broad globs (e.g., **/*) that defeat lazy loading.
• Splitting a single coherent rule across multiple files.
• Creating a sub-folder CLAUDE.md for every package in a monorepo — only add one when the package genuinely diverges from the root.
• Listing monorepo package directories in the root CLAUDE.md — structural maps rot, and sub-folder files already load lazily when Claude touches them.