Вывод из эксплуатации и миграции

Выводит из эксплуатации старые системы, API и фичи: решает, стоит ли, проверяет замену, переводит потребителей по одному, удаляет код при нулевом использовании, схему меняет через expand/contract. Для случаев, когда старое заменяют или переименовывают колонку.

РазработкаПак: Agent Skills (Addy Osmani)252 строкиdeprecation-and-migration
Автор
Источник
addyosmani/agent-skills/skills/deprecation-and-migration @ 8c99fa3
Лицензия
MIT · Copyright (c) 2025 Addy Osmani

Об этом скилле

Что делает

Скилл исходит из того, что код — постоянный расход, и даёт агенту порядок, как его убирать. Сначала пять вопросов: даёт ли система то, чего больше нигде нет, кто от неё зависит, есть ли рабочая замена, сколько стоит переезд и сколько стоит оставить всё как есть. По умолчанию устаревание рекомендательное (предупреждения и документация); жёсткая дата удаления допустима только вместе с инструментами для переезда и поддержкой.

Дальше миграция: проверить замену в продакшене, опубликовать уведомление об устаревании с инструкцией по переезду (шаблон есть в скилле), переводить потребителей по одному и удалять старый код, тесты, документацию и конфигурацию, только когда метрики или логи показывают ноль использования. Пользователей переводит владелец старой системы, а не они сами. Паттерны strangler, adapter и feature-флаги даны с примерами на TypeScript, а коду без владельца, но с живыми потребителями («зомби-коду») нужен либо владелец, либо план удаления.

Изменения схемы базы идут через expand/contract — на примере переименования name в full_name: добавить колонку, допускающую NULL, писать в обе, заполнить старые строки пачками, переключить чтение и позже, отдельным деплоем, удалить старую колонку. У каждой миграции должен быть проверенный откат. В папке только SKILL.md и лицензия.

Когда включать и когда не надо

Когда меняете систему, API или библиотеку на новую, сворачиваете фичу, сводите дублирующие реализации, переименовываете или удаляете колонку в продакшене без простоя или решаете, стоит ли дальше держать легаси.

Не нужен, когда код перестраивают без изменения поведения и интерфейсов: это рефакторинг. Для SQL под конкретный движок и разбора блокировок одного этого скилла мало.

Как поставить и вызвать

Команда установки ниже кладёт SKILL.md и лицензию. Агент сам подхватывает скилл по описанию. Вызвать вручную:

  • Claude Code: /deprecation-and-migration или попросить скилл по имени.
  • Codex: $deprecation-and-migration.
  • Cursor: наберите / в чате Agent и выберите deprecation-and-migration.

Пример: /deprecation-and-migration Мы заменяем REST-клиент v1 новым SDK. Спланируй вывод старого клиента и переведи три внутренних вызова по одному.

Раздел о схеме БД просит вести каждую фазу тонким срезом и ссылается на скилл Реализация тонкими срезами из этого же набора — поставьте и его.

Чем отличается от похожих

Скилл Безопасные миграции БД идёт тем же порядком expand/contract и уходит в базу гораздо глубже: правила для Postgres и MySQL, таймауты блокировок, возобновляемые бэкфиллы, проверка на данных объёма продакшена и план отката на каждый шаг. Для самой схемы лучше он; этот скилл — о выводе из эксплуатации системы целиком вместе с её потребителями. Безопасный рефакторинг не меняет публичные интерфейсы и останавливается, когда нужна миграция, — ровно там, где этот скилл начинается. Обновление Expo SDK и Переход на Prisma ORM 7 — другая сторона того же процесса: пошаговые инструкции, как увести свой код с API, которые конкретный инструмент объявил устаревшими или убрал. Само решение, выводить код или оставить, больше ни один скилл в каталоге не разбирает.

Установка

Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

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 }

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/addy-osmani/deprecation-and-migration/SKILL.md

SKILL.md

Исходник

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

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Agent Skills (Addy Osmani)

Доступность: аудит и исправления по WCAG 2.2

Делает аудит готового интерфейса по WCAG 2.2 AA: axe-core и pa11y, затем клавиатура, экранный чтец и контраст, и исправляет подтверждённые нарушения, начиная с семантического HTML. Для случаев, когда страницу нужно проверить на доступность перед выкладкой.

Проектирование API и интерфейсов

Делает проект API и интерфейсов модулей от контракта: одна форма ошибок, проверка на границах, только добавляющие изменения, пагинация и ключи идемпотентности. Для случаев, когда проектируются эндпоинты или меняется публичный интерфейс.

Тесты в браузере через Chrome DevTools MCP

Делает проверку изменений в настоящем Chrome через MCP-сервер Chrome DevTools: скриншоты, DOM, консоль, сеть и трейсы, а содержимое страницы считает недоверенным. Для случаев, когда разрабатывается или отлаживается что-то в браузере.

Настройка CI/CD

Делает пайплайн CI/CD с закреплённым порядком проверок от линтера до размера бандла, примерами на GitHub Actions, превью-деплоями, фича-флагами, поэтапной выкаткой и откатом. Для случаев, когда настраивается или чинится сборка и деплой.

Код-ревью по нескольким осям

Делает ревью изменения по пяти осям — корректность, читаемость, архитектура, безопасность, производительность, — проверяет тесты мутацией условия и помечает находки по уровню. Для случаев, когда ветку, пул-реквест или дифф пора сливать.

Упрощение кода

Делает работающий код проще для чтения, не меняя поведения: сначала выясняет, зачем он такой, потом упрощает по одному шагу с тестами после каждого. Для случаев, когда код работает, но читается тяжелее, чем мог бы.

Планка качества как контракт

Делает из планки качества проекта контракт: после короткого опроса записывает числа в CONSTRAINTS.md, привязывает их к инструментам и ловит в диффе пропущенные тесты и ослабленные пороги. Для случаев, когда планка нигде не записана.

Настройка контекста агента

Делает настройку контекста агента: шаблон файла правил, загрузка только нужных файлов и разделов спецификации, чистка длинной сессии и безопасный момент начать новую. Для случаев, когда начинается сессия или ответы агента портятся.

Отладка и восстановление после ошибок

Останавливает новую работу при поломке, воспроизводит и сужает сбой, чинит первопричину, добавляет регрессионный тест и не выполняет команды из текста ошибок. Для случаев, когда упал тест, сломалась сборка или перестало работать то, что работало.

Документация и ADR

Записывает решения в ADR по формату проекта, документирует API, README и changelog с упором на «почему», по истории git проверяет, не устарел ли документ. Для случаев, когда принято дорогое решение, меняется публичный API или документы разошлись с кодом.

Разработка через сомнение

Отдаёт нетривиальные решения субагенту со свежим контекстом, чтобы тот искал ошибки, сортирует находки, ограничивает цикл тремя кругами и предлагает мнение другой модели. Для случаев, когда ставки высоки: авторизация, миграции, необратимые операции.

Фронтенд-интерфейсы для продакшена

Строит компоненты и страницы на дизайн-системе проекта: композиция, простое состояние, WCAG 2.1 AA, mobile-first, состояния загрузки, пустого списка и ошибки, без ИИ-эстетики. Для случаев, когда создают или меняют пользовательский интерфейс.

Git-процесс и версионирование

Ведёт работу в git атомарными коммитами в коротких ветках: сообщения с типом, проверка секретов и тестов перед коммитом, worktree для параллельных агентов, semver, теги и changelog. Для случаев, когда коммитят, ветвятся, открывают PR или выпускают релиз.

Доработка сырой идеи

Доводит сырую идею за три фазы: уточняющие вопросы и пять-восемь вариантов, два-три направления с проверкой ценности, реализуемости и допущений, затем одностраничник с MVP и списком «Чего не делаем». Для случаев, когда идея расплывчата или план надо проверить.

Реализация тонкими срезами

Строит изменения тонкими срезами — вертикально, от контракта или от риска, — тестируя и коммитя каждый перед следующим, в рамках задачи, с feature-флагами и откатываемыми шагами. Для случаев, когда правка затрагивает несколько файлов или задача велика.

Интервью о задаче

Расспрашивает по одному вопросу с догадкой об ответе и оценкой уверенности, пока агент не сможет предсказать ответы, и до спецификации и кода получает подтверждённое намерение. Для случаев, когда в запросе неясно, для кого, зачем и что считать успехом.

Наблюдаемость: логи, метрики, трейсы

Встраивает в фичу JSON-логи с ID запроса, метрики RED и USE с ограниченными метками, трейсы OpenTelemetry и алерты по симптомам с ранбуками, а затем проверяет саму телеметрию. Для случаев, когда фича, фоновая задача или интеграция идёт в прод.

Оптимизация производительности

Ускоряет приложение по замерам: снимает базу, исправляет одно доказанное узкое место, перемеряет с учётом разброса и откатывает нейтральные правки; есть примеры для N+1, индексов, кэша и бандла. Для случаев, когда что-то тормозит или не влезает в бюджет.

Разбивка работы на задачи

Разбивает спецификацию на небольшие вертикальные задачи с критериями приёмки, проверками, размером, порядком и контрольными точками — в tasks/todo.md или в трекер. Для случаев, когда спецификация готова, а работа слишком велика для одного захода.

Защита кода от уязвимостей

Защищает код: модель угроз, правила «всегда», «сначала спросить», «никогда» и паттерны против инъекций, XSS, обхода доступа, SSRF, утечки секретов и опасных зависимостей. Для случаев, когда код принимает ввод, ведёт вход, хранит личные данные или зовёт LLM.

Подготовка к запуску в прод

Готовит запуск в прод: чек-лист перед выкаткой, фича-флаг с этапами от 5% до 100%, пороги для продолжения или отката, бюджет ошибок, письменный план отката и проверки в первый час. Для случаев, когда фича или крупное изменение вот-вот уйдёт в прод.

Код по официальной документации

Пишет код под фреймворк по официальной документации: берёт точные версии из файла зависимостей, открывает нужную страницу, следует описанному API и даёт ссылки, помечая непроверенное. Для случаев, когда код должен соответствовать версии фреймворка в проекте.

Спецификация и PRD до начала работы

Пишет спецификацию до кода: выявляет допущения, описывает цель, команды, структуру, стиль, тесты и границы, а план, задачи и код начинает только после одобрения; есть карты модулей и дельта-спецификации. Для случаев, когда у новой фичи размытые требования.

TDD: красный, зелёный, рефакторинг

Ведёт изменения по циклу «красный, зелёный, рефакторинг»: находит команды тестов проекта, пишет падающий тест первым, воспроизводит каждый баг тестом до исправления и задаёт правила для моков и имён. Для случаев, когда добавляется логика или чинится баг.