Deprecation and migration

Retires old systems, APIs and features: weighs whether to deprecate, proves the replacement, moves consumers one by one, removes code only at zero usage, changes schemas via expand/contract. Use when replacing or sunsetting code or renaming a live column.

CodingPack: Agent Skills by Addy Osmani252 linesdeprecation-and-migration
Author
Source
addyosmani/agent-skills/skills/deprecation-and-migration @ 8c99fa3
License
MIT · Copyright (c) 2025 Addy Osmani

About this skill

What it does

The skill treats code as a running cost and gives the agent a process for removing it. First it asks whether the system still provides unique value, who depends on it, whether a working replacement exists, and what migrating costs against keeping it. Deprecation is advisory by default (warnings and docs); a hard removal date comes only with migration tooling and support.

Then the migration: prove the replacement in production, publish a deprecation notice with a migration guide (a template is included), move consumers one at a time, and remove the old code, tests, docs and config only when metrics or logs show zero usage. The owner of the old system migrates its users instead of leaving them to it. Strangler, adapter and feature-flag patterns come with TypeScript examples, and code with no owner but active consumers ("zombie code") gets either an owner or a removal plan.

Schema changes go through expand/contract, shown on renaming name to full_name: add the nullable column, write to both, backfill in batches, switch reads, and drop the old column later in a deploy of its own, with a tested down path for every migration. The folder holds only SKILL.md and the licence.

When to use it, and when not

Use it when replacing a system, API or library, sunsetting a feature, merging duplicate implementations, renaming or dropping a production column without downtime, or deciding whether legacy code is worth keeping.

Skip it for restructuring that keeps behaviour and interfaces, which is a refactor. For engine-specific SQL and lock analysis it is not enough on its own.

How to run it

The install command below puts SKILL.md and the licence in place. The agent picks the skill up by its description; to call it yourself:

  • Claude Code: /deprecation-and-migration, or ask for the skill by name.
  • Codex: $deprecation-and-migration.
  • Cursor: type / in the Agent chat and pick deprecation-and-migration.

Example: /deprecation-and-migration We are replacing the v1 REST client with the new SDK. Plan the deprecation and move the three internal callers over one by one.

The schema section treats each phase as a thin slice and points to Incremental implementation from the same pack; install it too.

How it differs from similar skills

Safe DB migration follows the same expand/contract order and goes much deeper into the database: Postgres and MySQL statement rules, lock timeouts, resumable backfills, tests on production-sized data and a rollback plan per step. Prefer it for the schema itself; this skill covers retiring a system and its consumers. Safe refactoring keeps public interfaces unchanged and stops when a migration is needed, which is where this skill starts. Expo SDK upgrade and Upgrade Prisma ORM to v7 are the other side of the process: step-by-step runbooks for moving your code off APIs that one tool has deprecated or removed. No other skill in the catalog covers the decision whether to deprecate at all.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/deprecation-and-migration/SKILL.md https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/SKILL.md -o ~/.claude/skills/deprecation-and-migration/LICENSE https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/LICENSE
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/deprecation-and-migration/SKILL.md https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/SKILL.md -o ~/.agents/skills/deprecation-and-migration/LICENSE https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/LICENSE
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.claude\skills\deprecation-and-migration" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.agents\skills\deprecation-and-migration" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/SKILL.md

SKILL.md

Raw

Deprecation and Migration

Overview

Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving users safely from the old to the new.

Most engineering organizations are good at building things. Few are good at removing them. This skill addresses that gap.

When to Use

  • Replacing an old system, API, or library with a new one
  • Sunsetting a feature that's no longer needed
  • Consolidating duplicate implementations
  • Removing dead code that nobody owns but everybody depends on
  • Planning the lifecycle of a new system (deprecation planning starts at design time)
  • Deciding whether to maintain a legacy system or invest in migration

Core Principles

Code Is a Liability

Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.

Hyrum's Law Makes Removal Hard

With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Users can't "just switch" when they depend on behaviors the replacement doesn't replicate.

Deprecation Planning Starts at Design Time

When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.

The Deprecation Decision

Before deprecating anything, answer these questions:

1. Does this system still provide unique value?
   → If yes, maintain it. If no, proceed.

2. How many users/consumers depend on it?
   → Quantify the migration scope.

3. Does a replacement exist?
   → If no, build the replacement first. Don't deprecate without an alternative.

4. What's the migration cost for each consumer?
   → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.

5. What's the ongoing maintenance cost of NOT deprecating?
   → Security risk, engineer time, opportunity cost of complexity.

Compulsory vs Advisory Deprecation

Type When to Use Mechanism
Advisory Migration is optional, old system is stable Warnings, documentation, nudges. Users migrate on their own timeline.
Compulsory Old system has security issues, blocks progress, or maintenance cost is unsustainable Hard deadline. Old system will be removed by date X. Provide migration tooling.

Default to advisory. Use compulsory only when the maintenance cost or risk justifies forcing migration. Compulsory deprecation requires providing migration tooling, documentation, and support — you can't just announce a deadline.

The Migration Process

Step 1: Build the Replacement

Don't deprecate without a working alternative. The replacement must:

  • Cover all critical use cases of the old system
  • Have documentation and migration guides
  • Be proven in production (not just "theoretically better")

Step 2: Announce and Document

## Deprecation Notice: OldService

**Status:** Deprecated as of 2025-03-01
**Replacement:** NewService (see migration guide below)
**Removal date:** Advisory — no hard deadline yet
**Reason:** OldService requires manual scaling and lacks observability.
            NewService handles both automatically.

### Migration Guide
1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Update configuration (see examples below)
3. Run the migration verification script: `npx migrate-check`

Step 3: Migrate Incrementally

Migrate consumers one at a time, not all at once. For each consumer:

1. Identify all touchpoints with the deprecated system
2. Update to use the replacement
3. Verify behavior matches (tests, integration checks)
4. Remove references to the old system
5. Confirm no regressions

The Churn Rule: If you own the infrastructure being deprecated, you are responsible for migrating your users — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave users to figure it out.

Step 4: Remove the Old System

Only after all consumers have migrated:

1. Verify zero active usage (metrics, logs, dependency analysis)
2. Remove the code
3. Remove associated tests, documentation, and configuration
4. Remove the deprecation notices
5. Celebrate — removing code is an achievement

Migration Patterns

Strangler Pattern

Run old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.

Phase 1: New system handles 0%, old handles 100%
Phase 2: New system handles 10% (canary)
Phase 3: New system handles 50%
Phase 4: New system handles 100%, old system idle
Phase 5: Remove old system

Adapter Pattern

Create an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old interface while you migrate the backend.

// Adapter: old interface, new implementation
class LegacyTaskService implements OldTaskAPI {
  constructor(private newService: NewTaskService) {}

  // Old method signature, delegates to new implementation
  getTask(id: number): OldTask {
    const task = this.newService.findById(String(id));
    return this.toOldFormat(task);
  }

  // Translate the new shape back into what old consumers expect
  private toOldFormat(task: Task): OldTask {
    return { id: Number(task.id), title: task.title, done: task.status === 'done' };
  }
}

Feature Flag Migration

Use feature flags to switch consumers from old to new system one at a time:

function getTaskService(userId: string): TaskService {
  if (featureFlags.isEnabled('new-task-service', { userId })) {
    return new NewTaskService();
  }
  return new OldTaskService();
}

Database Schema Migrations (Expand/Contract)

A schema change is the riskiest migration because the data is the one thing you cannot roll back by reverting a deploy. The failure mode is coupling the schema change to the code change: rename a column in the same release that starts using the new name, and during the rollout window — when old and new code run at once — one of them is querying a column that doesn't exist. The fix is to never change a column in place. Migrate in additive phases so old and new code are both valid at every step.

EXPAND ──────────────→ MIGRATE ──────────────→ CONTRACT
add the new column,    backfill existing rows,  once no code reads the
nullable, alongside    dual-write old+new from  old column, drop it in
the old one            the app                  a later, separate deploy

Worked example — renaming name to full_name:

  1. Expand. Add full_name as nullable. Deploy. (Old code ignores it; nothing breaks.)
  2. Dual-write. App writes both name and full_name on every insert/update. Deploy.
  3. Backfill. Copy name → full_name for existing rows, in batches, so you don't lock the table.
  4. Switch reads. Point the app at full_name, keep writing both. Deploy and bake.
  5. Contract. Stop writing name, then — in a separate, later deploy — drop the column.

Each step is independently deployable and reversible: if step 4 misbehaves, roll the code back and full_name is still being populated. Treat each phase as a thin vertical slice — see the incremental-implementation skill.

Rules:

  • Additive first, destructive last and alone. Adds (new nullable column, new table, new index) are safe in any deploy; drops and renames get their own deploy after no code references the old shape.
  • Every migration has a tested down path. A migration you can't reverse is a deploy you can't roll back. Write and run the down before merging.
  • Backfill in batches, off the hot path. A single UPDATE over millions of rows locks the table; chunk it and throttle.
  • Build large indexes without blocking writes (e.g. Postgres CREATE INDEX CONCURRENTLY).
  • Decouple from code by feature flag when the cutover is risky, exactly as in the Feature Flag Migration pattern above.

Zombie Code

Zombie code is code that nobody owns but everybody depends on. It's not actively maintained, has no clear owner, and accumulates security vulnerabilities and compatibility issues. Signs:

  • No commits in 6+ months but active consumers exist
  • No assigned maintainer or team
  • Failing tests that nobody fixes
  • Dependencies with known vulnerabilities that nobody updates
  • Documentation that references systems that no longer exist

Response: Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan. Zombie code cannot stay in limbo — it either gets investment or removal.

Common Rationalizations

Rationalization Reality
"It still works, why remove it?" Working code that nobody maintains accumulates security debt and complexity. Maintenance cost grows silently.
"Someone might need it later" If it's needed later, it can be rebuilt. Keeping unused code "just in case" costs more than rebuilding.
"The migration is too expensive" Compare migration cost to ongoing maintenance cost over 2-3 years. Migration is usually cheaper long-term.
"We'll deprecate it after we finish the new system" Deprecation planning starts at design time. By the time the new system is done, you'll have new priorities. Plan now.
"Users will migrate on their own" They won't. Provide tooling, documentation, and incentives — or do the migration yourself (the Churn Rule).
"We can maintain both systems indefinitely" Two systems doing the same thing is double the maintenance, testing, documentation, and onboarding cost.
"Just rename the column, it's one line" During the rollout, old and new code run together — one will query a column that no longer exists. Expand/contract, never rename in place.
"I'll add the column and drop the old one in the same migration" That couples a safe add to a destructive drop. Drops get their own deploy, after no code references the old shape.
"We'll write the rollback if we need it" A migration with no down path is a deploy you can't reverse. Write and run the down before merging.

Red Flags

  • Deprecated systems with no replacement available
  • Deprecation announcements with no migration tooling or documentation
  • "Soft" deprecation that's been advisory for years with no progress
  • Zombie code with no owner and active consumers
  • New features added to a deprecated system (invest in the replacement instead)
  • Deprecation without measuring current usage
  • Removing code without verifying zero active consumers
  • A schema change and the code that depends on it shipped in the same deploy
  • A column renamed or dropped in place rather than via expand/contract
  • A migration merged with no tested down path, or a backfill that locks the table

Verification

After completing a deprecation:

  • Replacement is production-proven and covers all critical use cases
  • Migration guide exists with concrete steps and examples
  • All active consumers have been migrated (verified by metrics/logs)
  • Old code, tests, documentation, and configuration are fully removed
  • No references to the deprecated system remain in the codebase
  • Deprecation notices are removed (they served their purpose)

After a database schema migration:

  • The change ships in additive phases (expand → backfill → contract), not a single in-place edit
  • Old and new code are both valid against the schema at every deploy step
  • Each migration has a tested down path; backfills run in throttled batches
  • Destructive steps (drop/rename) ship in their own deploy after no code references the old shape

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Agent Skills by Addy Osmani

Accessibility audit and fixes (WCAG 2.2)

Audits an existing interface against WCAG 2.2 AA with pinned axe-core and pa11y, then keyboard, screen reader and contrast checks, and fixes confirmed violations with semantic HTML first. Use when a page needs an accessibility audit before shipping.

API and interface design

Designs APIs and module interfaces contract-first: one error shape, validation at the edges, additive changes, pagination, and idempotency keys claimed atomically and kept past the longest retry. Use when designing endpoints or changing a public interface.

Browser testing with Chrome DevTools MCP

Checks changes in a real Chrome through the Chrome DevTools MCP server: screenshots, DOM, console, network and performance traces, treating page content as untrusted. Use when building or debugging anything that runs in a browser.

CI/CD pipeline setup

Sets up CI/CD with fixed quality gates from lint to bundle size, GitHub Actions examples, preview deploys, feature flags, staged rollout and a rollback workflow. Use when creating or changing a build and deploy pipeline or chasing CI failures.

Multi-axis code review

Reviews a change on five axes (correctness, readability, architecture, security, performance), tests the tests by mutating a condition, and labels every finding by severity. Use before merging a branch, a pull request or a pasted diff.

Code simplification

Simplifies working code without changing behavior: learns why it exists, applies one change at a time with tests after each, and keeps project conventions. Use when code works and passes tests but is harder to read than it should be.

Constraint-driven development

Records a project's quality bar as numbers in CONSTRAINTS.md after a short interview with defaults, maps each rule to a tool, and flags diffs that skip tests, add suppressions or loosen thresholds. Use when no quality bar is written down.

Context engineering for agents

Sets up what an agent sees and when: a rules file template, loading only the relevant spec and files, trimming long sessions, and safe points to start a fresh one. Use when starting a session or when agent output degrades.

Debugging and error recovery

Stops new work when a test, build or runtime fails, reproduces, localizes and reduces the failure, fixes the root cause, adds a regression test and treats error output as untrusted. Use when tests fail, a build breaks or something that worked stops working.

Documentation and ADRs

Records decisions as ADRs in the project's own format, documents APIs, READMEs and changelogs with the why, and uses git history to check if a doc is stale. Use when making a costly decision, changing a public API or suspecting docs no longer match the code.

Doubt-driven development

Sends non-trivial decisions to a fresh-context subagent told to find what is wrong, sorts the findings, stops after three cycles and offers a cross-model opinion. Use when stakes are high: auth, migrations, irreversible operations or unfamiliar code.

Frontend UI engineering

Builds UI components and pages on the project's design system: composition, simple state, WCAG 2.1 AA, mobile-first layouts, loading, empty and error states, no generic AI look. Use when building or changing a user-facing interface.

Git workflow and versioning

Keeps git work in atomic commits on short-lived branches, with typed messages, a pre-commit check for secrets and tests, worktrees for parallel agents, semver bumps, tags and a human changelog. Use when committing, branching, opening a PR or cutting a release.

Idea refinement

Refines a raw idea in three phases: sharpening questions and five to eight variations, two or three directions tested for value and feasibility, then a one-pager with MVP scope and a Not Doing list. Use when an idea is vague or a plan needs stress-testing.

Incremental implementation

Builds changes in thin vertical, contract-first or risk-first slices, each tested, verified and committed before the next, with strict scope, feature flags and revertable steps. Use when a change spans several files or a task is too big to land in one step.

Interview me

Interviews the user one question at a time, each with a guessed answer and a confidence number, until the agent can predict the next replies, then confirms a statement of intent before any spec or code. Use when a request leaves who, why or success unclear.

Observability and instrumentation

Instruments a feature with structured JSON logs and request IDs, RED and USE metrics with bounded labels, OpenTelemetry traces and symptom-based alerts with runbooks, then tests the telemetry. Use when a feature, job or integration is headed for production.

Performance optimization

Optimizes by measurement: takes a baseline, fixes the one proven bottleneck, re-measures against noise and reverts neutral changes, with worked fixes for N+1 queries, indexes, caching and bundles. Use when something is slow or misses a performance budget.

Planning and task breakdown

Breaks a spec into small vertical-slice tasks with acceptance criteria, verification steps, sizes, dependency order and checkpoints, saved to tasks/todo.md or a named tracker. Use when a spec is ready but the work is too big to start in one go.

Security hardening

Hardens code with a short threat model, always, ask-first and never rules, and patterns for injection, XSS, access control, SSRF, secrets, dependencies, personal data and LLM output. Use when code handles user input, auth, sensitive data or outside services.

Shipping and launch

Prepares a production launch with a pre-launch checklist, a feature-flag rollout from 5% to 100%, thresholds for advancing or rolling back, an error-budget gate, a rollback plan and first-hour checks. Use when a feature or major change is about to ship.

Source-driven development

Grounds framework code in official docs: reads exact versions from the dependency file, fetches the relevant page, follows the documented API and cites full URLs, flagging anything unverified. Use when framework-specific code must match the version in use.

Spec-driven development

Writes a spec before code, surfacing assumptions and covering objective, commands, structure, style, tests and boundaries, then gates plan, tasks and code on approval, with capability maps and delta specs. Use when new work has vague requirements.

Test-driven development, red-green-refactor

Drives changes with red-green-refactor: finds the repository's own test commands, writes the failing test first, reproduces each bug with a test before fixing it, and sets rules on mocks and naming. Use when adding logic, fixing a bug or changing behavior.