Générer des feuilles de route
Une feuille de route est un plan que la personne suivante peut reprendre et exécuter sans avoir besoin de la conversation qui l'a produit. Elle dit ce que le projet essaie d'atteindre, dans quel ordre, comment chacun saura que chaque étape est terminée, et quelles questions restent ouvertes. Elle vit dans le dépôt à côté du code qu'elle décrit, donc elle est révisée et versionnée comme tout le reste.
Une feuille de route enregistre des décisions. Elle ne les prend pas. Lorsque quelque chose n'a pas été décidé, la feuille de route le dit.
Les règles du dépôt passent en premier
Avant d'écrire quoi que ce soit, recherchez les conventions propres au dépôt : AGENTS.md, CLAUDE.md, CONTRIBUTING.md, un schéma de documentation ou de wiki, et toute feuille de route existante. Elles décident où vont les feuilles de route, quelles métadonnées elles portent, comment les issues sont liées et quelles vérifications exécuter. En cas de conflit avec cette compétence, elles prévalent. Suivez le format d'une feuille de route existante plutôt que d'en introduire une seconde.
Flux de travail
1. Définir la demande
Déterminez laquelle de ces actions l'utilisateur souhaite, car chacune nécessite une quantité de travail différente :
- Nouvelle feuille de route : pour un projet, une fonctionnalité, une migration, un effort de test, etc.
- Mise à jour : ajouter ou modifier des éléments, réordonner des phases, enregistrer une décision.
- Rapprochement : aligner une feuille de route existante avec ce qui a été réellement livré.
- Révision : lire une feuille de route et signaler les lacunes, sans la réécrire.
2. Rassembler les preuves avant de demander
Lisez ce que le projet sait déjà : le code et les tests pertinents, les issues ouvertes et récemment fermées, les PR fusionnées et ouvertes, la documentation existante et l'historique des commits pour la zone concernée. Notez ce qui existe aujourd'hui, ce qui est déjà en cours et ce qui a été essayé auparavant.
Tout ce que vous pouvez apprendre de cette façon, ne le demandez pas à l'utilisateur.
3. Interroger sur les décisions importantes
Une feuille de route ne vaut que par les décisions qui la sous-tendent, et la plupart de celles-ci appartiennent à l'utilisateur. Posez des questions en courtes séquences plutôt qu'en une longue liste, et expliquez pourquoi une question est importante lorsque le compromis n'est pas évident. Bons sujets :
- Objectif : quel résultat rend cet effort utile, et comment saura-t-on qu'il est atteint ?
- Périmètre : qu'est-ce qui est explicitement exclu ? Qu'est-ce qui ne doit pas changer (API, formats de données, comportement) ?
- Contraintes : délais, versions, personnes, budget, plateformes.
- Priorités : si seulement la moitié de cela est livré, quelle moitié ?
- Risque : qu'est-ce qui est le moins compris, et faut-il s'y attaquer en premier ?
- Finition : quels tests, métriques ou révisions comptent comme une preuve ?
Proposez une recommandation lorsque les preuves le soutiennent. Laissez toujours l'utilisateur répondre « pas encore décidé ». Cette réponse va dans Décisions ouvertes, pas dans une supposition.
Pour une petite mise à jour, passez directement à l'écriture. Pour une nouvelle feuille de route, attendez-vous à deux ou trois séquences.
4. Choisir une structure
- Un fichier (
ROADMAP.md, ou un nom qui correspond au dépôt) pour la plupart des feuilles de route. - Un répertoire (
roadmaps/<slug>/README.mdplus des pages de support) uniquement lorsque le plan a besoin de longs documents de support, tels que des notes de recherche, une esquisse de conception ou des matrices de test, qui enterreraient les éléments de travail. La page principale possède toujours chaque identifiant d'élément de travail.
5. Rédiger
Utilisez le modèle ci-dessous. Règles pour le garder utile dans le temps :
- Identifiants stables. Donnez à chaque élément de travail un ID tel que
R-001. Ne renumérotez jamais et ne réutilisez jamais un ID. Le travail abandonné reste dans le fichier, marquéabandonné, avec la raison. - Les phases ont des critères de sortie. Chaque phase dit ce qui est vrai lorsqu'elle est terminée. Ordonnez les phases par dépendance d'abord, puis par risque, puis par valeur.
- Les critères d'acceptation sont vérifiables. Écrivez des critères que quelqu'un peut vérifier : un test qui réussit, une commande qui s'exécute avec succès, un nombre mesurable. Évitez des mots comme « robuste », « amélioré » et « propre ».
- Les dépendances sont explicites. Listez-les par ID. Signalez tout ce qui échappe au contrôle de l'équipe, comme un autre dépôt, un fournisseur ou une décision.
- Liez les preuves par URL complète ou chemin relatif au dépôt, afin que les liens survivent à une copie ailleurs.
- Décrivez le plan, pas la réunion. Au présent, état actuel. L'historique va dans le journal des modifications.
6. Vérifier
Avant de remettre le résultat :
- Chaque élément a un ID, un statut et au moins un critère d'acceptation.
- Chaque dépendance pointe vers un ID qui existe.
- Aucune phase ne dépend d'une phase ultérieure.
- Chaque question non décidée est dans Décisions ouvertes, pas cachée dans un élément.
- Les liens fonctionnent et les chemins de fichiers existent.
- Les vérifications de formatage et de documentation du dépôt passent.
- Le journal des modifications a une entrée pour ce changement.
7. Rapport
Dites à l'utilisateur ce que vous avez créé ou modifié, les décisions que vous avez enregistrées et les questions qui restent ouvertes.
Rapprocher une feuille de route de la réalité
Les feuilles de route dérivent à mesure que le travail est réalisé. Pour en rapprocher une :
- Listez les éléments qui ne sont pas
terminéouabandonné. - Pour chacun, recherchez les PR fusionnées, les issues fermées et le code qui satisfait ses critères d'acceptation.
- Marquez un élément
terminéuniquement lorsque chaque critère est rempli. Liez la preuve. - Si le travail a été livré différemment du plan, mettez à jour l'élément pour dire ce qui s'est réellement passé, et notez la différence dans le journal des modifications.
- Ajoutez tout nouveau travail que vous découvrez comme de nouveaux éléments avec de nouveaux ID.
- Résumez les modifications pour l'utilisateur. Demandez avant d'abandonner quoi que ce soit.
Réviser une feuille de route
Lorsqu'on vous demande uniquement de réviser, ne réécrivez pas. Rapportez, du plus important au moins important :
- objectifs ou phases sans moyen de savoir quand ils sont terminés ;
- éléments avec des critères d'acceptation vagues ;
- dépendances manquantes ou circulaires ;
- décisions présentées comme acquises que les preuves ne soutiennent pas ;
- éléments que le code ou le suivi des issues montre comme déjà terminés, ou non pertinents ;
- risques manquants : les parties les plus difficiles ou les moins comprises planifiées tard.
Modèle
# Feuille de route <Projet ou fonctionnalité>
**Objectif :** <le résultat, en une ou deux phrases>
**Statut :** <brouillon | actif | terminé | remplacé>
**Dernière mise à jour :** <AAAA-MM-JJ>
## Contexte
Pourquoi ce travail est important maintenant, ce qui existe aujourd'hui et liens vers les preuves.
## Périmètre
- **Inclus :** …
- **Exclu :** …
- **Ne doit pas changer :** …
## Légende des statuts
| Statut | Signification |
| -------------- | ------------------------------------------------ |
| `planifié` | Convenu, pas commencé |
| `en-cours` | Quelqu'un travaille dessus |
| `bloqué` | En attente d'une dépendance ou décision (dites laquelle) |
| `terminé` | Chaque critère d'acceptation rempli, avec preuve |
| `abandonné` | Ne se fait pas (dites pourquoi) |
## Phase 1 : <nom>
**Critères de sortie :** <ce qui est vrai lorsque cette phase est terminée>
### R-001 : <titre court>
- **Statut :** planifié
- **Pourquoi :** <le problème que cela résout>
- **Critères d'acceptation :**
- [ ] <déclaration vérifiable>
- **Dépend de :** <IDs, ou « aucun »>
- **Preuve :** <liens vers issue, PR ou fichier>
## Phase 2 : <nom>
…
## Décisions ouvertes
| ID | Question | Options | Bloque | Propriétaire |
| ----- | -------- | ------- | ------ | ------------ |
| D-001 | … | … | R-004 | … |
## Risques
| Risque | Probabilité | Impact | Atténuation |
| ------ | ---------- | ------ | ------------ |
## Journal des modifications
- <AAAA-MM-JJ> : <ce qui a changé et pourquoi>
Supprimez les sections qui ne s'appliquent pas. Une petite feuille de route peut se limiter à un objectif, une phase et un journal des modifications.
À ne pas faire
- Inventer une décision parce que la feuille de route semble incomplète sans elle.
- Ajouter des éléments génériques (« ajouter de la documentation », « améliorer les tests ») qui n'ont pas de résultat spécifique.
- Renuméroter les éléments ou supprimer ceux qui sont abandonnés.
- Marquer un travail
terminéà partir d'un seul titre de PR sans vérifier les critères. - Copier tout le contenu d'une feuille de route dans les issues, ou l'inverse. Liez plutôt.