Multi-File Editing Advanced

Multi-file editing is Cursor's killer feature. Using Composer, you can describe a change that spans multiple files and Cursor will make all the edits for you — updating interfaces, implementations, tests, and imports in a single operation.

When to Use Multi-File Editing

Scenario Example Files Affected
Add a feature Add user profile editing API route, component, types, tests
Rename/refactor Rename UserService to AccountService Service file, all imports, tests, docs
Add a field Add "phone" to user model Type, schema, API, form, validation
Change patterns Switch from callbacks to async/await All files using the old pattern
API changes Update REST endpoints to new versioning Routes, controllers, client SDK, docs

Effective Multi-File Prompts

Composer Prompt 
# Adding a complete feature
Add a "forgot password" feature:
1. Add a POST /api/auth/forgot-password endpoint in @src/api/auth.ts
2. Create an email template in @src/emails/forgot-password.html
3. Add a ForgotPassword React component in @src/pages/
4. Add the route to @src/App.tsx
5. Add types to @src/types/auth.ts
6. Use the existing email service pattern from @src/services/email.ts
Composer Prompt 
# Refactoring across files
Refactor the database access layer:
- Extract all direct database calls from @src/api/ route handlers
- Create a new @src/repositories/ folder with repository classes
- Each repository should have CRUD methods
- Update all API routes to use repositories instead of direct DB calls
- Follow the pattern: UserRepository, PostRepository, etc.

Reviewing Multi-File Changes

When Composer proposes changes to multiple files, review carefully:

  1. Check the file list

    Verify that Composer is modifying the right files. If it is touching files it should not, reject and refine your prompt.

  2. Review each diff

    Click through each file's diff. Pay attention to imports, type changes, and any removed code.

  3. Accept incrementally

    You can accept changes file by file. Accept the ones that look correct and reject the ones that need work.

  4. Test after accepting

    Run your tests and type checker after accepting changes to catch any issues early.

Tips for Multi-File Success

Multi-File Editing Tips:
  • List affected files explicitly — Do not rely on Composer to find them all; use @-mentions
  • Break large changes into steps — Instead of one massive prompt, do 2-3 focused Composer operations
  • Use numbered instructions — Structured prompts with numbered steps produce more reliable results
  • Reference existing patterns — "Follow the pattern in @existing-file.ts" gives Composer a template
  • Use Claude Sonnet or Opus for complex changes — Switch to a more capable model for multi-file refactors

Common Pitfalls

Pitfall Solution
Missing imports Always check that new imports are added to each modified file
Type mismatches Run TypeScript type checker after accepting to catch errors
Incomplete changes If Composer misses files, run a second pass: "Are there other files that need updating for this change?"
Over-editing If Composer changes more than intended, be more specific about scope in your prompt

Try It Yourself

Use Composer to add a new field to an existing data model in your project. Track how many files need to change and whether Composer catches them all. Practice reviewing and selectively accepting diffs.

Next: Best Practices →
← Code Generation Best Practices →