principle-migrate-callers-then-delete-legacy-apis
cursor/plugins
Migrate callers and delete legacy APIs in one refactor wave instead of maintaining compatibility layers.
What is principle-migrate-callers-then-delete-legacy-apis?
This principle guides refactoring internal APIs by migrating all callers and removing the old API simultaneously, rather than preserving backward compatibility. Apply when the project can absorb coordinated breaking changes and no external users depend on the legacy interface.
- Inventory all callers of the legacy API before refactoring
- Migrate callers to the new API design in a single coordinated wave
- Delete the old API immediately after migration completes
- Update tests to assert the new contract and remove pre-refactor implementation tests
- Treat temporary adapters as exceptional and time-boxed, not default architecture
How to install principle-migrate-callers-then-delete-legacy-apis
npx skills add https://github.com/cursor/plugins --skill principle-migrate-callers-then-delete-legacy-apisHow to use principle-migrate-callers-then-delete-legacy-apis
- 1.Identify the legacy API and all internal callers that depend on it
- 2.Plan the migration scope and timeline for updating all callers
- 3.Update callers to use the new API design
- 4.Update or remove tests that only protect pre-refactor implementation details
- 5.Delete the legacy API and verify no references remain
- 6.Deploy the changes as a single coordinated refactor wave
Use cases
- Simplifying internal API surfaces during major refactors
- Removing deprecated internal endpoints when all callers can be updated together
- Cleaning up dual-path complexity that slows development velocity
- Consolidating multiple versions of the same internal service
- Eliminating adapter layers that exist only for backward compatibility
- Backend engineers refactoring internal APIs
- Platform teams managing shared internal services
- Architects designing API migration strategies
- Teams working on codebases without external API consumers
principle-migrate-callers-then-delete-legacy-apis FAQ
Only in exceptional, time-boxed cases. If external users or long-term integrations depend on the legacy API, maintain compatibility. Otherwise, migrate and delete in the same wave to avoid dual-path complexity.
This principle assumes the project can absorb coordinated breaking changes. If callers are distributed across teams or systems that can't align, reconsider whether a temporary adapter is necessary—but set a hard deadline for removal.
Delete tests that only protect pre-refactor implementation details. Keep tests that verify business logic, but rewrite them to assert the new contract.
Use code search, grep, or static analysis tools to find all references to the legacy API. Document the list and assign migration tasks before starting the refactor.
Full instructions (SKILL.md)
Source of truth, from cursor/plugins.
name: principle-migrate-callers-then-delete-legacy-apis description: "Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserving compatibility layers." disable-model-invocation: true
Migrate Callers Then Delete Legacy APIs
When we decide a new API is the right design, migrate callers and remove the old API in the same refactor wave instead of preserving compatibility layers.
Rule:
- Do not keep legacy API paths only because internal callers still exist
- Inventory callers, migrate them, and delete the old API immediately
- Treat temporary adapters as exceptional and time-boxed, not default architecture
- Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details
When this applies:
- No external users depend on backward compatibility
- The project can absorb coordinated breaking changes
- The new API is part of a simplification or refactor initiative
Keeping both old and new APIs creates dual-path complexity, slows cleanup, and makes the codebase feel append-only.
Related skills
More from cursor/plugins and the wider catalog.
principle-minimize-reader-load
Reduce code complexity by minimizing reader cognitive load—collapse unnecessary layers and shrink mutable state.
principle-model-the-domain
Encode domain logic in structures instead of scattered conditionals and repeated assumptions.
principle-never-block-on-the-human
Proceed with reversible work without asking permission; reserve confirmation for irreversible actions only.
principle-outcome-oriented-execution
Prioritize end-state correctness over intermediate stability during planned rewrites and migrations.
principle-prove-it-works
Verify task completion by checking real artifacts, not proxies or self-reports.
principle-redesign-from-first-principles
Redesign existing systems as if new requirements were foundational, not bolted-on.