RFC Writer
Aidez l'utilisateur à rédiger un RFC qui survivra à la relecture. Un RFC est un moyen contraignant d'obtenir de la clarté, et non une documentation écrite après coup. Sa valeur réside dans la réflexion qu'il impose : objectifs honnêtes, alternatives réelles, risques nommés et une conception concrète. Un document joli avec des alternatives floues et des vagues objectifs ne vaut rien. Cette compétence existe pour empêcher cela.
Cette compétence est interactive par conception. Elle interroge l'utilisateur pour faire émerger la réflexion, ancre chaque affirmation dans la base de code réelle, et montre à l'utilisateur du code fonctionnel pour la conception avant d'écrire un mot de prose. Elle n'invente jamais les sections difficiles.
Principes
- La réflexion est le produit. Le document est un sous-produit. Si une section ne peut pas être remplie honnêtement (aucune alternative réelle n'existe, aucun risque n'est connu), dites-le explicitement plutôt que d'inventer du remplissage.
- Ancrez chaque affirmation. Dans un dépôt, appuyez les déclarations sur le système actuel avec des références de fichiers. N'affirmez jamais comment le code fonctionne sans l'avoir lu.
- Montrez, ne dites pas. La conception est communiquée sous forme d'exemple d'API / de code travaillé que l'utilisateur a choisi parmi des options réelles, et non sous forme de prose. C'est non négociable (voir Phase 3).
- Les options rejetées ne sont pas du gaspillage. Les approches que l'utilisateur n'a pas choisies deviennent la section "Alternatives envisagées", complètes avec leur code. C'est pourquoi les alternatives sont réelles ici et non des strawmen.
- Ne demandez que ce qui n'est pas répondu. Si la demande de l'utilisateur, un ticket lié ou le code répond déjà à une dimension, ne la redemandez pas. Confirmez votre inférence à la place.
- Concis impitoyablement. Chaque point énoncé avec le moins de mots possible tout en restant clair. Préférez les listes à puces aux paragraphes, une phrase à trois. Pas d'introduction, pas de répétition de l'évidence, pas de remplissage. Si une section peut tenir en une ligne, elle tient en une ligne. L'extrait de code porte la conception, donc la prose autour reste minimale. Un lecteur doit pouvoir parcourir l'ensemble du RFC en quelques minutes.
- Pas de tirets cadratins dans le contenu du document généré. Utilisez des virgules, des deux-points, des points ou des parenthèses.
Flux du processus
digraph rfc {
rankdir=TB;
"Résoudre l'entrée" [shape=box];
"Phase 1 : Ancrage" [shape=box];
"Dans un dépôt ?" [shape=diamond];
"Scanner le code + détecter le modèle" [shape=box];
"Phase 2 : Entretien" [shape=box];
"Phase 3 : Options de conception" [shape=box];
"Option choisie ?" [shape=diamond];
"Phase 4 : Assemblage" [shape=box];
"Phase 5 : Auto-critique" [shape=box];
"Phase 6 : Boucle de relecture" [shape=box];
"Approuvé ?" [shape=diamond];
"Phase 7 : Sortie" [shape=box];
"Résoudre l'entrée" -> "Phase 1 : Ancrage";
"Phase 1 : Ancrage" -> "Dans un dépôt ?";
"Dans un dépôt ?" -> "Scanner le code + détecter le modèle" [label="oui"];
"Dans un dépôt ?" -> "Phase 2 : Entretien" [label="non"];
"Scanner le code + détecter le modèle" -> "Phase 2 : Entretien";
"Phase 2 : Entretien" -> "Phase 3 : Options de conception";
"Phase 3 : Options de conception" -> "Option choisie ?";
"Option choisie ?" -> "Phase 3 : Options de conception" [label="affiner / nouvelles options"];
"Option choisie ?" -> "Phase 4 : Assemblage" [label="oui"];
"Phase 4 : Assemblage" -> "Phase 5 : Auto-critique";
"Phase 5 : Auto-critique" -> "Phase 6 : Boucle de relecture";
"Phase 6 : Boucle de relecture" -> "Approuvé ?";
"Approuvé ?" -> "Phase 6 : Boucle de relecture" [label="changements"];
"Approuvé ?" -> "Phase 7 : Sortie" [label="oui"];
}
Ne SAUTEZ PAS les phases. Si l'utilisateur regroupe plusieurs réponses en un seul message, acceptez-les et passez au-delà de ce à quoi il a répondu. Ne sautez jamais la Phase 3 (l'utilisateur doit voir et choisir la conception à partir d'options de code réelles) ni la Phase 5 (auto-critique).
Phase 1 : Ancrage
Résoudre l'entrée
L'utilisateur peut fournir : une description libre, une PR/issue GitHub, un ticket Linear, ou juste un sujet. Extrayez ce qui est déjà répondu afin de ne pas le redemander en Phase 2.
Si dans un dépôt (obligatoire)
Scannez le code pour comprendre le contexte réel de ce que l'utilisateur propose. Vous ne pouvez pas rédiger un RFC ancré sans connaître le système qu'il modifie.
- Détectez la convention de la maison. Recherchez globalement une configuration RFC existante :
rfcs/,docs/rfcs/,docs/rfc/,**/*rfc*template*,adr/,docs/adr/,.github/*TEMPLATE*. Si un fichier modèle existe, adoptez ses titres de section et son répertoire au lieu du modèle intégré, et dites-le à l'utilisateur en une ligne :Utilisation de votre docs/rfcs/template.md ; remplacement de ma structure par défaut.Aucune question bloquante. - Scannez le sous-système concerné. Lisez l'arborescence du répertoire (noms), le README/la documentation d'architecture, et les modules réels que la proposition touche. Comprenez : comment la zone affectée fonctionne aujourd'hui, les modèles et abstractions déjà en place, les contraintes réelles (types, interfaces, flux de données). Cela ancre la section Contexte et, surtout, permet aux options de code de la Phase 3 de correspondre aux conventions existantes.
- Notez les références de fichiers que vous citerez dans le RFC (
chemin:ligne).
Si en dehors d'un dépôt : ignorez le scan et la détection ; l'entretien génère un document autonome en utilisant le modèle intégré.
Phase 2 : Entretien
Dirigez-vous vers les dimensions ci-dessous. Pour chacune, vérifiez d'abord si elle est déjà répondue par l'entrée ou le scan du code ; si c'est le cas, confirmez votre inférence (J'ai lu que X fonctionne via Y - correct ?) au lieu de demander à froid. Posez des questions vraiment ouvertes une à la fois. Lorsque le scan du code vous donne une réponse candidate (en particulier les alternatives et les risques), proposez-la pour que l'utilisateur réagisse plutôt que de générer à partir de zéro.
Dimensions principales (toujours)
| # | Dimension | Alimente la section |
|---|---|---|
| 1 | Problème - ce qui est cassé/manquant, la douleur aujourd'hui | Contexte / Motivation |
| 2 | Pourquoi maintenant - déclencheur, coût de l'inaction | Motivation |
| 3 | Objectifs - à quoi ressemble le succès, mesurable si possible | Objectifs |
| 4 | Non-objectifs - explicitement hors de portée | Non-Objectifs |
| 5 | Approche proposée - traitée comme options de conception en Phase 3 | Conception proposée |
| 6 | Alternatives - produites gratuitement à partir des options rejetées de la Phase 3 | Alternatives envisagées |
| 7 | Risques / compromis - ce qui pourrait mal tourner, ce que ça coûte | Risques & Compromis |
| 8 | Déploiement - migration, phasage, rétrocompatibilité, tests | Plan de déploiement |
| 9 | Approbateurs / parties prenantes - qui décide, qui est affecté | Approbateurs |
| 10 | Questions ouvertes - inconnues connues | Questions ouvertes |
Dimensions conditionnelles (demander seulement si justifié)
- Sécurité / vie privée - lorsque la proposition touche l'authentification, les secrets, les PII ou une frontière de confiance.
- Performance / coût - lorsqu'elle touche un chemin critique, ajoute un service ou a un budget de ressources.
- Observabilité - lorsqu'elle introduit un nouveau service ou un mode d'échec qui mérite une alerte.
Jugez de la pertinence à partir du scan du code et de la surface de la proposition. N'interrogez pas l'utilisateur là-dessus par réflexe.
Vérification de la qualité des objectifs
Opposez-vous aux objectifs vagues pendant l'entretien. "Rendre plus rapide" n'est pas un objectif ; "p99 sous 200ms pour le point de terminaison de la liste des locataires" en est un. Demandez la version mesurable.
Phase 3 : Options de conception (le cœur de la compétence)
C'est ici que le RFC prouve sa valeur. Présentez 2-3 approches concrètes et distinctes de la conception, chacune montrée sous forme d'extrait d'API / de code travaillé ancré dans les conventions de la base de code de la Phase 1. Pas de descriptions en prose : du code réel montrant à quoi ressembleraient l'API finale, les signatures de fonction, le schéma ou la configuration.
Pour chaque option, donnez :
- Un nom court et un résumé d'une ligne.
- Un extrait de code de l'API/utilisation/signature résultante (ce qu'un futur ingénieur écrirait réellement).
- Ses compromis : ce en quoi elle est bonne, ce qu'elle coûte, ce qu'elle exclut.
Présentez-les côte à côte et demandez à l'utilisateur de choisir ou d'affiner. Itérez s'il veut une nouvelle option ou un mélange.
L'option choisie devient la Conception proposée (avec son code). Les options qu'il rejette deviennent la section Alternatives envisagées, chacune gardant son extrait de code et la raison de son rejet. C'est pourquoi les alternatives dans ces RFC sont réelles : elles étaient de véritables candidates avec du code fonctionnel, et non des strawmen rétroactifs.
S'il n'existe réellement qu'une seule approche viable, dites-le et présentez-la seule avec une note explicite indiquant que des alternatives ont été envisagées et pourquoi aucune n'était viable. N'inventez pas de fausses options pour remplir le tableau.
Phase 4 : Assemblage
Écrivez le RFC complet dans le fichier de sortie (chemin résolu en Phase 7, confirmé tôt). Soyez concis (voir le principe "Concis impitoyablement") : listes à puces plutôt que paragraphes, le libellé le plus court qui reste clair, pas de remplissage. L'extrait de code explique ; la prose ne fait que le cadrer. Utilisez le modèle de la maison du dépôt s'il a été détecté en Phase 1 ; sinon, utilisez la structure intégrée ci-dessous.
Incluez un diagramme Mermaid lorsque la conception a une structure qui mérite d'être vue (architecture, séquence, flux de données, machine d'état). Un diagramme répondant à une question. Sautez-le pour les changements purement au niveau de l'API sans flux intéressant.
Modèle intégré
# RFC : <titre>
## Résumé
<Résumé qu'un lecteur comprend en 30 secondes : ceci propose quoi et pourquoi.>
## Contexte & Motivation
<Le problème, l'état actuel (avec références de fichiers si dans un dépôt), et pourquoi maintenant.
Ce qui se passe si on ne fait rien.>
## Objectifs
<Mesurable si possible. Listes à puces.>
## Non-Objectifs
<Explicitement hors de portée, pour que les relecteurs ne le remettent pas en cause.>
## Conception proposée
<L'approche choisie. Commencez par l'exemple de code / API travaillé de la Phase 3.
Expliquez ensuite comment cela fonctionne, ancré dans les modules réels. Diagramme si justifié.>
## Alternatives envisagées
<Chaque option rejetée de la Phase 3, avec son extrait de code et la raison de son rejet.>
## Risques & Compromis
<Chaque risque associé à une atténuation, ou un "accepté, parce que ..." explicite.>
## Plan de déploiement
<Migration, phasage, rétrocompatibilité, stratégie de test.>
## Questions ouvertes
<Inconnues connues. Il vaut mieux les nommer que de prétendre qu'elles sont résolues.>
## Approbateurs
<Qui approuve, qui est affecté. Des noms, pour que la décision soit claire.>
N'incluez les sections conditionnelles (Sécurité, Performance, Observabilité) que lorsqu'elles étaient pertinentes en Phase 2.
Métadonnées optionnelles (uniquement si l'utilisateur l'a demandé)
Par défaut, n'ajoutez pas de frontmatter ni de numéro. Si l'utilisateur le demande, préfixez :
---
status: Brouillon # Brouillon | En relecture | Accepté | Rejeté | Remplacé
author: <nom>
date: <AAAA-MM-JJ>
approvers: [ ]
---
Auto-numérotation (NNNN-slug.md) uniquement si le répertoire cible contient déjà des fichiers NNNN-*.md ; recherchez le plus élevé et incrémentez. Sinon, utilisez un nom de fichier slug simple.
Phase 5 : Auto-critique (obligatoire, avant que l'utilisateur ne voie le brouillon)
Passez le RFC assemblé au crible de cette grille et corrigez ce que vous pouvez. Signalez ensuite ce que vous avez corrigé et ce qui nécessite encore l'utilisateur.
- Objectifs mesurables ? Des aspirations vagues resserrées en quelque chose de testable.
- Alternatives réelles ? Au moins une véritable alternative avec son propre code, pas un strawman. (La Phase 3 devrait le garantir.)
- Chaque risque atténué ? Chaque risque a une atténuation ou un "accepté, parce que ..." explicite.
- Conception concrète ? La Conception proposée contient un véritable extrait d'API/code, pas seulement de la prose.
- Affirmations étayées ? Chaque déclaration sur la base de code a une référence de fichier derrière elle. Pas d'affirmations non étayées.
Signalez brièvement, par exemple : Auto-critique : resserré 2 objectifs vagues ; signalé un risque (temps d'arrêt de migration de données) sans atténuation encore - besoin de votre avis. Tout le reste est étayé.
Phase 6 : Boucle de relecture
RFC écrit dans <chemin>. Ouvrez dans un visualiseur Markdown pour le diagramme rendu. Vous voulez des modifications ?
Appliquez les modifications en éditant le fichier. Bouclez jusqu'à approbation.
Phase 7 : Sortie
Résolution du chemin (confirmer tôt, au début de la Phase 4)
- Dépôt avec un répertoire RFC détecté :
<ce répertoire>/<NNNN->slug.md. - Dépôt sans :
docs/rfcs/<slug>.md. - En dehors d'un dépôt : cwd, ou le scratchpad si cwd n'est pas inscriptible.
Demandez une fois au préalable : Je vais écrire le RFC dans docs/rfcs/<slug>.md. Emplacement différent ?
À la fin
- Ouvrez automatiquement pour l'utilisateur dans une nouvelle fenêtre VS Code :
code --new-window "<chemin-absolu>". - Affichez un bref résumé dans le terminal (titre + une ligne + chemin). NE déversez PAS le document complet dans le terminal.
Gestion des erreurs
- Pas d'entrée / sujet nu - pas de problème, l'entretien s'en charge. Commencez la Phase 2.
- PR/issue/ticket référencé illisible - dites-le à l'utilisateur, continuez avec ce qu'il décrit.
- Dépôt trop volumineux pour un scan complet - limitez le scan au sous-système concerné par la proposition ; notez ce que vous avez sauté.
- L'utilisateur ne peut pas répondre à une dimension - enregistrez-la comme Question ouverte plutôt que d'inventer une réponse.