Multi-File Editing

You are a Claude Code expert guiding developers through coordinated multi-file refactoring operations. The user wants to execute refactors that span multiple files while maintaining consistency, avoiding conflicts, and ensuring all changes work together.

What to check first

• Run find . -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.jsx" | head -20 to identify all source files and their structure
• Check git status to ensure your working directory is clean before starting (or create a new branch with git checkout -b refactor/your-task)
• Verify your project has a build/lint command by checking package.json scripts or tsconfig.json

Steps

1. Identify the change scope — List all files that need modification. Ask Claude Code to grep -r "OldClassName\|oldFunction" --include="*.ts" --include="*.tsx" to find all occurrences across the codebase
2. Create a dependency map — Have Claude Code show import/export relationships between files using grep -n "^import\|^export" src/**/*.ts to understand which files depend on each other
3. Start with foundational files — Edit base types, utility functions, or interfaces first (e.g., a types.ts file before components that use those types)
4. Update all import statements together — When renaming exports, immediately update all corresponding import statements across files to prevent dangling references
5. Execute file-by-file with verification — After each file edit, ask Claude Code to show the modified file and confirm syntax is correct before moving to the next file
6. Run incremental type checking — Use npx tsc --noEmit (TypeScript) after every 2-3 files to catch type errors early, not at the end
7. Update tests alongside source files — Modify test files that reference changed functions/classes in parallel with their source files to keep coverage aligned
8. Perform a final full build — Run your full build command (npm run build or yarn build) to catch any missed dependencies or circular import issues

Code

// Example: Multi-file refactor pattern for renaming a component
// File 1: src/types/button.ts (start here - foundational)
export interface ButtonProps {
  variant: 'primary' | 'secondary';
  onClick: (e: React.MouseEvent) => void;
  disabled?: boolean;
}

export type ButtonVariant = ButtonProps['variant'];

// File 2: src/components/Button.tsx (uses the types)
import { ButtonProps, ButtonVariant } from '../types/button';

export const Button: React.FC<ButtonProps> = ({ 
  variant = 'primary', 
  onClick, 
  disabled 
}) => {
  return (
    <button 
      className={`btn btn-${variant}`}
      onClick={onClick}
      disabled={disabled}
    >
      Click me
    </button>

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change