Plans de rédaction

Présentation

Rédigez des plans de mise en œuvre exhaustifs en partant du principe que l'ingénieur ne connaît absolument pas notre base de code et a des goûts discutables. Documentez tout ce qu'il doit savoir : les fichiers à modifier pour chaque tâche, le code, les tests, la documentation qu'il devra peut-être consulter, ainsi que la manière de tester le tout. Présentez-lui l’ensemble du plan sous forme de tâches faciles à gérer. DRY. YAGNI. TDD. Commits fréquents.

Partez du principe qu’il s’agit d’un développeur compétent, mais qui ne connaît pratiquement rien à notre ensemble d’outils ni à notre domaine d’activité. Partez du principe qu’il ne maîtrise pas très bien la conception de tests efficaces.

Annoncez dès le début : « J’utilise la compétence « writing-plans » pour créer le plan de mise en œuvre. »

Contexte : si vous travaillez dans un arborescence de travail isolée, celle-ci doit avoir été créée via la compétence « superpowers:using-git-worktrees » au moment de l’exécution.

Enregistrez les plans dans : docs/superpowers/plans/AAAA-MM-JJ-.md

• (Les préférences de l’utilisateur concernant l’emplacement des plans remplacent cette valeur par défaut)

Vérification de la portée

Si le cahier des charges couvre plusieurs sous-systèmes indépendants, il aurait dû être décomposé en cahiers des charges de sous-projets lors de la phase de brainstorming. Si ce n’est pas le cas, suggérez de le diviser en plans distincts — un par sous-système. Chaque plan doit aboutir à un logiciel fonctionnel et testable en soi.

Structure des fichiers

Avant de définir les tâches, identifiez les fichiers qui seront créés ou modifiés et la fonction de chacun d’entre eux. C’est à ce stade que les décisions de décomposition sont finalisées.

• Concevez des unités aux limites claires et aux interfaces bien définies. Chaque fichier doit avoir une responsabilité bien précise.
• Vous raisonnez mieux sur du code que vous pouvez appréhender dans son contexte d’un seul coup, et vos modifications sont plus fiables lorsque les fichiers sont ciblés. Privilégiez les fichiers plus petits et ciblés aux fichiers volumineux qui en font trop.
• Les fichiers qui évoluent ensemble doivent rester ensemble. Effectuez le découpage en fonction des responsabilités, et non selon les couches techniques.
• Dans les bases de code existantes, respectez les modèles établis. Si la base de code utilise de grands fichiers, ne la restructurez pas de manière unilatérale ; en revanche, si un fichier que vous modifiez est devenu trop lourd à gérer, il est raisonnable d’envisager de le scinder.

Cette structure détermine la décomposition des tâches. Chaque tâche doit produire des modifications autonomes qui ont un sens en elles-mêmes.

Dimensionnement des tâches

Une tâche est la plus petite unité disposant de son propre cycle de test et méritant d’être soumise à un nouveau relecteur. Lorsque vous définissez les limites d’une tâche : intégrez les étapes de mise en place, de configuration, de création d’infrastructure et de documentation dans la tâche dont le livrable en a besoin ; ne divisez que lorsque un relecteur pourrait valablement rejeter une tâche tout en approuvant celle qui la jouxte. Chaque tâche se termine par un livrable testable de manière indépendante.

Granularité des tâches en petites unités

Chaque étape correspond à une action (2 à 5 minutes) :

• « Écrire le test qui échoue » - étape
• « L’exécuter pour s’assurer qu’il échoue » – étape
• « Implémenter le code minimal pour que le test réussisse » – étape
• « Exécuter les tests et s'assurer qu'ils réussissent » – étape
• « Valider » – étape

En-tête du document de plan

Chaque plan DOIT commencer par cet en-tête :

# [Nom de la fonctionnalité] Plan de mise en œuvre

> **Pour les travailleurs agents :** COMPÉTENCE SECONDAIRE OBLIGATOIRE : utilisez les superpouvoirs :subagent-driven-development (recommandé) ou superpouvoirs :executing-plans pour mettre en œuvre ce plan tâche par tâche. Les étapes utilisent la syntaxe des cases à cocher (`- [ ]`) pour le suivi.

**Objectif :** [Une phrase décrivant ce que cela permet de créer]

**Architecture :** [2 à 3 phrases sur l’approche]

**Stack technologique :** [Technologies/bibliothèques clés]

## Contraintes globales

[Les exigences du cahier des charges applicables à l’ensemble du projet — versions minimales, limites de dépendances,
règles de nommage et de rédaction, exigences de plate-forme — une ligne par élément, avec les valeurs exactes
copiées mot pour mot depuis le cahier des charges. Les exigences de chaque tâche incluent implicitement
cette section.]

---

Structure de la tâche

### Tâche N : [Nom du composant]

**Fichiers :**
- Créer : `chemin/exact/vers/fichier.py`
- Modification : `chemin/exact/vers/fichier.py existant:123-145`
- Test : `tests/chemin/exact/vers/test.py`

**Interfaces :**
- Utilise : [ce que cette tâche utilise des tâches précédentes — signatures exactes]
- Produit : [ce dont dépendent les tâches suivantes — noms exacts des fonctions, types de paramètres
  et de retour. Le développeur d’une tâche ne voit que sa propre tâche ; ce
  bloc lui permet de connaître les noms et les types utilisés par les tâches voisines.]

- [ ] **Étape 1 : Écrire le test qui échoue**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Étape 2 : exécutez le test pour vérifier qu'il échoue**

Exécution : `pytest tests/path/test.py::test_name -v`
Résultat attendu : ÉCHEC avec le message « fonction non définie »

- [ ] **Étape 3 : écrivez une implémentation minimale**

```python
def function(input):
    return expected
```

- [ ] **Étape 4 : Exécuter le test pour vérifier qu’il réussit**

Exécution : `pytest tests/path/test.py::test_name -v`
Résultat attendu : PASS

- [ ] **Étape 5 : Valider**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: ajout d'une fonctionnalité spécifique"
```

Pas d’espaces réservés

Chaque étape doit contenir le contenu réel dont un ingénieur a besoin. Voici des erreurs de planification — ne les écrivez jamais :

• « À déterminer », « À faire », « À implémenter plus tard », « Compléter les détails »
• « Ajouter une gestion des erreurs appropriée » / « ajouter une validation » / « gérer les cas limites »
• « Écrire des tests pour ce qui précède » (sans code de test réel)
• « Comme pour la tâche N » (répéter le code — l’ingénieur risque de lire les tâches dans le désordre)
• Étapes décrivant ce qu’il faut faire sans montrer comment (des blocs de code sont requis pour les étapes de programmation)
• Références à des types, fonctions ou méthodes non définis dans aucune tâche

À retenir

• Indiquez toujours les chemins d’accès exacts aux fichiers
• Code complet à chaque étape — si une étape modifie le code, indiquez le code
• Commandes exactes avec le résultat attendu
• DRY, YAGNI, TDD, commits fréquents

Auto-révision

Une fois le plan complet rédigé, relisez le cahier des charges avec un regard neuf et vérifiez que le plan y correspond. Il s’agit d’une liste de contrôle que vous effectuez vous-même — et non d’une tâche confiée à un sous-agent.

1. Couverture du cahier des charges : parcourez rapidement chaque section/exigence du cahier des charges. Pouvez-vous identifier une tâche qui la met en œuvre ? Répertoriez les éventuelles lacunes.

2. Analyse des espaces réservés : recherchez dans votre plan les signaux d’alerte — n’importe lequel des schémas mentionnés dans la section « Pas d’espaces réservés » ci-dessus. Corrigez-les.

3. Cohérence des types : les types, les signatures de méthodes et les noms de propriétés que vous avez utilisés dans les tâches suivantes correspondent-ils à ce que vous avez défini dans les tâches précédentes ? Une fonction appelée clearLayers() dans la tâche 3 mais clearFullLayers() dans la tâche 7 constitue un bug.

Si vous constatez des problèmes, corrigez-les directement dans le code. Inutile de relire le code : corrigez simplement et passez à la suite. Si vous identifiez une exigence du cahier des charges pour laquelle il n’existe pas de tâche, ajoutez la tâche correspondante.

Transfert de l’exécution

Après avoir enregistré le plan, proposez un choix d’exécution :

« Plan terminé et enregistré dans docs/superpowers/plans/.md. Deux options d’exécution :

1. Pilotée par des sous-agents (recommandée): je lance un nouveau sous-agent par tâche, je vérifie entre chaque tâche, itération rapide

2. Exécution en ligne — Exécuter les tâches dans cette session à l’aide de `executing-plans`, exécution par lots avec points de contrôle

Quelle approche ? »

Si l'option « Pilotée par des sous-agents » est choisie :

• COMPÉTENCE SECONDAIRE REQUISE : Utiliser « superpowers:subagent-driven-development »
• Un sous-agent distinct par tâche + révision en deux étapes

Si l’option « Exécution en ligne » est choisie :

• COMPÉTENCE SECONDAIRE REQUISE : Utiliser les superpouvoirs : exécution-de-plans
• Exécution par lots avec points de contrôle pour révision