Que fait Concevoir avant de construire ?
Les agents sont rapides pour implémenter et mauvais pour remarquer qu'une conception se dégrade. La solution est de se mettre d'accord sur les décisions avant que le code n'existe, afin que chaque PR soit rapide à examiner car elle correspond à ce qui a déjà été approuvé. Vous rédigez chaque étape ; l'utilisateur la révise et l'approuve.
1. Dimensionner le travail et choisir les étapes
| Travail | Étapes |
|---|---|
| Fonctionnalité moyenne, refactorisation contenue | conception programmatique → tranches |
| Grosse fonctionnalité, refactorisation transversale | architecture → conception programmatique → tranches |
| Nouveau projet, multi-dépôt, ou problème flou | produit → architecture → conception programmatique → tranches |
Dites en une ligne quelle taille vous avez choisie et pourquoi. L'utilisateur peut ajouter ou sauter des étapes.
2. Rassembler le contexte d'abord
Avant de rédiger quoi que ce soit : lisez docs/README.md et la documentation vivante vers laquelle il pointe, tous les designs ouverts dans docs/designs/, le code pertinent et l'historique Git de la zone concernée. Pour les choix entre outils ou approches, faites des recherches (docs, benchmarks, problèmes connus) et donnez des options concrètes avec leurs sources. Ne concevez pas à partir d'hypothèses.
3. Exécuter chaque étape
Créez le fichier de conception docs/designs/YYYY-MM-DD-<slug>.md à partir de template.md (mettez d'abord en place la structure docs/ à partir des règles globales si le dépôt ne l'a pas). Pour chaque étape, lisez son fichier d'étape ci-dessous (dans le dossier de cette compétence), rédigez cette section du fichier de conception, puis arrêtez-vous :
product.md: problème, utilisateurs, comportement, hors périmètrearchitecture.md: composants, contrats, modèle de données, contraintesconception-programmatique.md: types, signatures, structure des fichiers, flux d'appelstranches.md: ordre de construction, dépôts, PRs, et la vérification pour chaque tranche
Lors de l'arrêt, montrez à l'utilisateur :
- un diagramme si cela aide, ainsi qu'un court résumé (pas tout le document collé dans le chat)
- les décisions que vous avez prises et les questions en suspens, numérotées pour qu'il puisse répondre « 2 : oui »
Ne commencez pas l'étape suivante tant que l'utilisateur n'a pas approuvé celle-ci. S'il change quelque chose, mettez à jour le fichier de conception, pas seulement le chat.
4. Construire tranche par tranche
Après l'approbation du plan de tranches :
- Construisez une tranche à la fois ; chacune se termine par la réussite de sa vérification convenue et la preuve en est montrée.
- Une PR (ou un commit, si l'utilisateur n'utilise pas de PR) par tranche, décrite selon les règles globales.
- Si l'implémentation montre que la conception est erronée, arrêtez-vous et proposez la modification de la conception au lieu de vous en écarter silencieusement. Mettez à jour le fichier de conception lorsqu'un changement est convenu.
- Cochez les tranches dans le fichier de conception au fur et à mesure qu'elles sont livrées, afin qu'une session ultérieure puisse reprendre à partir de là.
5. Terminer
Lorsque la dernière tranche est livrée, réintégrez le résultat pour que la documentation vivante reste la source de vérité :
- Mettez à jour
docs/product.md,docs/architecture.mdet toute documentation thématique du dépôt (pas les fichiers d'étape de cette compétence) pour décrire le système tel qu'il est maintenant, en suivant les règles d'écriture de documentation des règles globales. - Ajoutez tout terme nouveau ou spécifique au projet dans
docs/glossary.md. - Transformez chaque décision importante en une note
docs/decisions/NNNN-<slug>.md. - Marquez le fichier de conception comme terminé et ajoutez-le à
docs/README.md. Ne le réécrivez pas par la suite. - Montrez à l'utilisateur ce qui a changé dans la documentation vivante.