Maison

Skill

Outils de développement

deprecation-and-migration

addyosmani/agent-skills

Accompagne le processus de mise hors service des anciens systèmes, API ou fonctionnalités et de migration des utilisateurs vers des solutions de remplacement, notamment en proposant des cadres décisionnels, des modèles de migration et des stratégies de suppression.

...Développer tout

Heure mise à jour 3 septembre 2026

# documentation # migration # refactoring # feature flags # api design # deprecation # legacy code # strangler pattern

Obsolescence et migration

Présentation

Le code est un passif, pas un actif. Chaque ligne de code engendre des coûts de maintenance permanents : des bugs à corriger, des dépendances à mettre à jour, des correctifs de sécurité à appliquer et de nouveaux ingénieurs à former. La dépréciation consiste à supprimer le code qui ne justifie plus son existence, tandis que la migration est le processus qui permet de faire passer les utilisateurs de l’ancien système au nouveau en toute sécurité.

La plupart des équipes d’ingénierie sont douées pour créer des solutions. Rares sont celles qui savent les supprimer. Cette compétence comble cette lacune.

Quand l’utiliser

Pour remplacer un ancien système, une API ou une bibliothèque par un nouveau
Mettre fin à une fonctionnalité qui n’est plus nécessaire
Regrouper des implémentations redondantes
Supprimer du code obsolète dont personne n’est responsable mais dont tout le monde dépend
Planifier le cycle de vie d’un nouveau système (la planification de la dépréciation commence dès la phase de conception)
Décider s’il faut maintenir un système existant ou investir dans sa migration

Principes fondamentaux

Le code est un passif

Chaque ligne de code engendre un coût permanent : elle nécessite des tests, de la documentation, des correctifs de sécurité, des mises à jour des dépendances et une charge mentale pour toute personne travaillant à proximité. La valeur du code réside dans la fonctionnalité qu’il fournit, et non dans le code lui-même. Lorsque la même fonctionnalité peut être fournie avec moins de code, moins de complexité ou de meilleures abstractions, l’ancien code doit être supprimé.

La loi d’Hyrum rend la suppression difficile

Avec un nombre suffisant d’utilisateurs, chaque comportement observable devient une dépendance — y compris les bogues, les anomalies de synchronisation et les effets secondaires non documentés. C’est pourquoi la dépréciation nécessite une migration active, et pas seulement une annonce. Les utilisateurs ne peuvent pas « simplement changer » lorsqu’ils dépendent de comportements que le remplacement ne reproduit pas.

La planification de la dépréciation commence dès la phase de conception

Lorsque vous développez quelque chose de nouveau, posez-vous la question suivante : « Comment pourrions-nous supprimer cela dans trois ans ? » Les systèmes conçus avec des interfaces épurées, des indicateurs de fonctionnalité et une surface d’exposition minimale sont plus faciles à déprécier que ceux qui laissent transparaître des détails d’implémentation partout.

La décision de dépréciation

Avant de déprécier quoi que ce soit, répondez à ces questions :

1. Ce système apporte-t-il toujours une valeur unique ?
   → Si oui, conservez-le. Si non, passez à l’étape suivante.

2. Combien d’utilisateurs/de consommateurs en dépendent ?
   → Quantifiez l’ampleur de la migration.

3. Existe-t-il un remplacement ?
   → Si non, développez d’abord le remplacement. Ne mettez pas en obsolescence sans alternative.

4. Quel est le coût de la migration pour chaque consommateur ?
   → Si la migration est facilement automatisable, procédez-y. Si elle est manuelle et demande beaucoup d’efforts, comparez-la au coût de maintenance.

5. Quel est le coût de maintenance continu si l’on ne procède PAS à la dépréciation ?
   → Risque de sécurité, temps de travail des ingénieurs, coût d’opportunité lié à la complexité.

Dépréciation obligatoire ou recommandée

Type	Quand l'utiliser	Mécanisme
Recommandée	La migration est facultative, l'ancien système est stable	Avertissements, documentation, rappels. Les utilisateurs effectuent la migration selon leur propre calendrier.
Obligatoire	L'ancien système présente des failles de sécurité, freine le progrès ou son coût de maintenance est insoutenable	Date butoir stricte. L'ancien système sera supprimé à la date X. Fournir des outils de migration.

Optez par défaut pour une approche consultative. N’optez pour l’obligation que lorsque les coûts de maintenance ou les risques justifient d’imposer la migration. Une obsolescence obligatoire nécessite de fournir des outils de migration, de la documentation et une assistance — vous ne pouvez pas vous contenter d’annoncer une date butoir.

Le processus de migration

Étape 1 : Développer le système de remplacement

Ne procédez pas à la dépréciation sans disposer d’une alternative fonctionnelle. Le système de remplacement doit :

Couvrir tous les cas d’utilisation critiques de l’ancien système
Disposer d’une documentation et de guides de migration
Avoir fait ses preuves en production (et ne pas être simplement « théoriquement meilleur »)

Étape 2 : Annoncer et documenter

## Avis de dépréciation : OldService

**Statut :** Déprécié à compter du 01/03/2025
**Remplacement :** NewService (voir le guide de migration ci-dessous)
**Date de suppression :** Avis — pas encore de date butoir fixe
**Raison :** OldService nécessite une mise à l'échelle manuelle et manque d'observabilité.
            NewService gère ces deux aspects automatiquement.

### Guide de migration
1. Remplacez `import { client } from 'old-service'` par `import { client } from 'new-service'`
2. Mettez à jour la configuration (voir les exemples ci-dessous)
3. Exécutez le script de vérification de la migration : `npx migrate-check`

Étape 3 : Effectuez la migration de manière incrémentielle

Migrez les consommateurs un par un, et non tous en même temps. Pour chaque consommateur :

1. Identifiez tous les points de contact avec le système obsolète
2. Effectuez la mise à jour pour utiliser le système de remplacement
3. Vérifiez que le comportement correspond (tests, contrôles d’intégration)
4. Supprimez les références à l’ancien système
5. Assurez-vous qu’il n’y a pas de régressions

La règle du « churn » : si vous êtes propriétaire de l’infrastructure en voie de dépréciation, vous êtes responsable de la migration de vos utilisateurs — ou de la fourniture de mises à jour rétrocompatibles ne nécessitant aucune migration. N’annoncez pas la dépréciation en laissant les utilisateurs se débrouiller seuls.

Étape 4 : Supprimer l’ancien système

Uniquement une fois que tous les utilisateurs ont migré :

1. Vérifiez qu’il n’y a plus aucune utilisation active (métriques, journaux, analyse des dépendances)
2. Supprimez le code
3. Supprimez les tests, la documentation et la configuration associés
4. Supprimez les avis de dépréciation
5. Fêtez ça : supprimer du code est un accomplissement

Modèles de migration

Modèle « Strangler »

Faites fonctionner l’ancien et le nouveau système en parallèle. Acheminez le trafic progressivement de l’ancien vers le nouveau. Lorsque l’ancien système traite 0 % du trafic, supprimez-le.

Phase 1 : le nouveau système traite 0 %, l’ancien 100 %
Phase 2 : le nouveau système traite 10 % (test canari)
Phase 3 : le nouveau système traite 50 %
Phase 4 : le nouveau système traite 100 %, l’ancien système est inactif
Phase 5 : supprimer l’ancien système

Modèle d’adaptateur

Créez un adaptateur qui traduit les appels de l’ancienne interface vers la nouvelle implémentation. Les utilisateurs continuent d’utiliser l’ancienne interface pendant que vous migrez le backend.

// Adaptateur : ancienne interface, nouvelle implémentation
class LegacyTaskService implements OldTaskAPI {
  constructor(private newService: NewTaskService) {}

  // Ancienne signature de méthode, déléguée à la nouvelle implémentation
  getTask(id: number): OldTask {
    const task = this.newService.findById(String(id));
    return this.toOldFormat(task);
  }
}

Migration via les indicateurs de fonctionnalité

Utilisez des indicateurs de fonctionnalité pour faire passer les consommateurs de l’ancien au nouveau système un par un :

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

Code « zombie »

Le code « zombie » est un code dont personne n’est responsable, mais dont tout le monde dépend. Il n’est pas activement maintenu, n’a pas de responsable clairement identifié et accumule des failles de sécurité et des problèmes de compatibilité. Signes :

Aucun commit depuis plus de 6 mois, mais il existe des utilisateurs actifs
Aucun responsable ou équipe de maintenance désigné(e)
Des tests qui échouent et que personne ne corrige
Des dépendances présentant des failles de sécurité connues que personne ne met à jour
Une documentation faisant référence à des systèmes qui n’existent plus

Réponse : soit désigner un responsable et assurer une maintenance adéquate, soit le déprécier en mettant en place un plan de migration concret. Le code « zombie » ne peut pas rester dans les limbes : il faut soit y investir, soit le supprimer.

Justifications courantes

Justification	Réalité
« Ça fonctionne encore, pourquoi le supprimer ? »	Un code fonctionnel que personne ne maintient accumule une dette de sécurité et de la complexité. Les coûts de maintenance augmentent silencieusement.
« Quelqu'un pourrait en avoir besoin plus tard. »	Si on en a besoin plus tard, on pourra le recréer. Conserver du code inutilisé « au cas où » coûte plus cher que de le recréer.
« La migration coûte trop cher »	Comparez le coût de la migration au coût de maintenance sur 2 à 3 ans. La migration est généralement moins coûteuse à long terme.
« Nous le déprécierons une fois le nouveau système terminé »	La planification de la dépréciation commence dès la phase de conception. D’ici à ce que le nouveau système soit terminé, vous aurez d’autres priorités. Planifiez dès maintenant.
« Les utilisateurs migreront d'eux-mêmes »	Ce ne sera pas le cas. Fournissez des outils, de la documentation et des incitations — ou effectuez la migration vous-même (la « règle du taux de désabonnement »).
« Nous pouvons maintenir les deux systèmes indéfiniment. »	Deux systèmes faisant la même chose, c’est le double des coûts de maintenance, de tests, de documentation et d’intégration.

Signaux d’alerte

Systèmes obsolètes sans solution de remplacement disponible
Annonces de fin de vie sans outils de migration ni documentation
Une obsolescence « douce » qui fait l’objet d’avis depuis des années sans qu’aucun progrès n’ait été réalisé
Code « zombie » sans propriétaire ni utilisateurs actifs
Nouvelles fonctionnalités ajoutées à un système obsolète (il vaut mieux investir dans son remplacement)
Obsolescence déclarée sans évaluation de l’utilisation actuelle
Suppression de code sans vérifier qu’il n’y a aucun utilisateur actif

Vérification

Une fois la dépréciation terminée :

Le remplacement a fait ses preuves en production et couvre tous les cas d'utilisation critiques
Un guide de migration existe, avec des étapes concrètes et des exemples
Tous les consommateurs actifs ont été migrés (vérifié par les métriques/journaux)
L'ancien code, les tests, la documentation et la configuration ont été entièrement supprimés
Il ne reste aucune référence au système obsolète dans la base de code
Les avis de dépréciation ont été supprimés (ils ont rempli leur rôle)

Voir sur GitHub

---
name: deprecation-and-migration
description: Guides the process of deprecating old systems, APIs, or features and migrating users to replacements, including decision frameworks, migration patterns, and removal strategies.
---

# 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

```markdown
## 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.

```typescript
// 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);
  }
}
```

### Feature Flag Migration

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

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

## 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. |

## 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

## 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)