Créer un plan technique détaillé

  • 12 minutes

Une spécification définit ce que vous devez construire. Un plan technique définit comment vous le construisez. Cette unité couvre les techniques de planification avancées pour les scénarios de brownfield d’entreprise.

Examiner les principes fondamentaux du plan

Le fichier plan.md sert de document de conception, ce qui permet de combler l’écart entre les exigences de haut niveau dans spec.md et les tâches concrètes d’implémentation qui suivent. Un plan technique complet contient :

  • Vue d’ensemble de l’architecture : vue d’ensemble de la façon dont les composants interagissent.
  • Pile technologique et décisions clés : documentation explicite des choix technologiques avec des justifications.
  • Séquence d’implémentation : progression logique des étapes d’implémentation.
  • Vérification de la Constitution : vérification explicite que les solutions proposées respectent les principes du projet.
  • Hypothèses et questions ouvertes : documentation des hypothèses et questions non résolues.

Avec ces principes fondamentaux à l’esprit, examinons les considérations avancées relatives à la planification pour le développement d’entreprise.

Séparation des enjeux - spécifications vs plan

La séparation des préoccupations entre la spécification et le plan technique est cruciale. Bien que la spécification reste stable et axée sur « quoi », le plan peut évoluer à mesure que vous expérimentez des approches « comment » différentes.

Supposons que votre spécification nécessite une fonctionnalité de chargement de document pour un portail d’employés interne. La spécification définit les exigences de l’utilisateur : limites de taille de fichier, formats pris en charge, commentaires de chargement et contrôles d’accès. Le plan technique traduit ces exigences en décisions architecturales concrètes : le service de stockage Azure à utiliser, la structure de l’API, le mécanisme d’authentification à implémenter et la validation des fichiers. Si vous décidez de passer d’une technologie à une autre, comme le passage du Stockage Blob Azure vers Azure Files, vous mettez à jour plan.md tandis que spec.md reste largement inchangé. Les exigences relatives aux fonctionnalités ne sont pas modifiées ; seule l’approche d’implémentation est modifiée.

Examiner la structure et le contenu du plan

Un plan technique complet contient plusieurs sections clés qui définissent collectivement votre approche d’implémentation.

Vue d’ensemble de l’architecture

La vue d’ensemble de l’architecture fournit une vue d’ensemble de la façon dont les composants interagissent. Pour la fonctionnalité de chargement de document, l’architecture peut décrire :

« Implémentez un nouveau point de terminaison d'API back-end /api/documents/upload pour gérer le téléversement de fichiers à parties multiples. » Le serveur frontal React inclut un nouveau composant DocumentUpload avec un sélecteur de fichiers et un indicateur de progression. Lorsqu’un utilisateur sélectionne un fichier, le serveur frontal valide la taille et le type avant le chargement. Le serveur principal reçoit le fichier, le valide à nouveau, le stocke dans stockage Blob Azure et enregistre les métadonnées dans la base de données SQL. Une fois le chargement réussi, le serveur frontal actualise la liste des documents pour afficher le nouveau fichier. »

Ce résumé établit le flux global sans plonger dans les détails au niveau du code. Il garantit que tout le monde comprend les principaux composants et leurs interactions.

Pile technologique et décisions clés

Le plan documente explicitement les choix technologiques et les raisonnements. Cette section empêche toute confusion future quant à la raison pour laquelle des bibliothèques ou services spécifiques ont été sélectionnés.

Exemples de décisions technologiques :

  • Back-end : API web .NET 8 avec le SDK Azure.Storage.Blobs v12 pour les opérations d’objet blob.
  • Front end : React 18 avec le composant Upload d’Ant Design pour la cohérence de l’interface utilisateur.
  • Authentification : utilisez un jeton d’ID Microsoft Entra existant à partir du contexte d’authentification du portail.
  • Stockage : conteneur Stockage Blob Azure nommé employee-documents.
  • Base de données : étendre une base de données SQL existante avec une table DocumentMetadata (colonnes : ID, UserId, FileName, BlobUrl, UploadDate, FileSize).

Chaque décision doit s’aligner sur les exigences de spécification et les principes de constitution. Si votre constitution impose « Utiliser des services Azure pour toutes les ressources cloud », le plan sélectionne explicitement Stockage Blob Azure et fait référence à ce principe.

Séquence d’implémentation

Le plan décrit l’ordre des étapes d’implémentation. Bien qu’elle ne soit pas aussi granulaire que la liste des tâches générée ultérieurement, cette séquence fournit une progression logique de l’installation à la fin.

Séquence d’implémentation classique pour la fonctionnalité de chargement de document :

  1. Mise à jour du schéma de base de données : créez une table DocumentMetadata avec des index et des contraintes appropriés.
  2. Développement d’API back-end : implémentez l'endpoint POST /api/documents/upload avec validation des fichiers, intégration du stockage d’objets blob et persistance des métadonnées.
  3. Création de composants frontaux : composant Build DocumentUpload avec sélection de fichiers, validation côté client et affichage de progression du chargement.
  4. Intégration : associez le composant frontal à l’API principale, gérez les réponses et mettez à jour la liste des documents.
  5. Renforcement de la sécurité : implémentez la validation du type de fichier côté serveur, les limites de taille et les vérifications d’authentification.
  6. Gestion des erreurs : ajoutez des messages d’erreur complets pour les échecs côté client et côté serveur.
  7. Test : créez des tests unitaires pour les méthodes d’API et les tests d’intégration pour le flux de chargement.

Cette séquence garantit que les éléments fondamentaux (schéma de base de données) existent avant que les composants dépendants (API qui écrit dans la base de données) soient implémentés. Chaque étape s’appuie sur le travail précédent, ce qui réduit la probabilité de problèmes d’intégration.

Vérification de la Constitution

Le plan comprend une section de vérification qui vérifie explicitement les solutions proposées contre la constitution. Cette vérification empêche la dérive architecturale et garantit la cohérence avec les principes du projet.

Si votre constitution inclut « Tous les stockages de données doivent utiliser les services Azure » et « Les API doivent valider les entrées sur le client et le serveur », confirme la section de vérification du plan :

  • « L’utilisation du Stockage Blob Azure répond aux exigences des services Azure. »
  • « L’implémentation de la validation dans les deux composants React (client) et l’API .NET (serveur) s’alignent sur le principe de sécurité de défense en profondeur. »
  • « L’exigence d’authentification Microsoft Entra ID est remplie à l’aide du contexte d’authentification du portail existant. »

Cette vérification sert de point de contrôle. Si le plan propose quelque chose qui enfreint la constitution, l’IA l’signale généralement, ou vous remarquez lors de l’examen. La résolution des conflits de constitution au cours de la phase du plan empêche le remaniement plus tard.

Hypothèses et questions ouvertes

Les plans bien construits documentent les hypothèses et les questions non résolues. Cette transparence vous aide à identifier les problèmes potentiels avant le début de l’implémentation.

Exemples d’hypothèses :

  • « Supposons que le conteneur Stockage Blob Azure « employee-documents » existe et qu’il est configuré pour l’accès privé. »
  • « Supposons que la base de données SQL existante dispose d’une capacité de stockage suffisante pour les métadonnées. »
  • Considérons que l’analyse antivirus des fichiers téléversés n'est pas prévue pour cette itération.

Exemple de questions ouvertes :

  • « Les administrateurs doivent-ils avoir la possibilité de supprimer les documents chargés d’autres utilisateurs ? »
  • « Avons-nous besoin de la journalisation d’audit pour toutes les tentatives d’accès aux documents ? »
  • « Le système doit-il envoyer des notifications par e-mail lorsque des documents sont chargés ? »

Documenter ces hypothèses et questions empêche le glissement de portée et garantit que les parties prenantes prennent des décisions importantes avant le début du codage. Si une hypothèse s’avère incorrecte pendant l’implémentation, vous pouvez mettre à jour le plan en conséquence.

Générer un plan à l’aide de /speckit.plan

GitHub Spec Kit génère des plans via la /speckit.plan commande dans GitHub Copilot Chat. Cette commande utilise spec.md et constitution.md comme entrées pour produire une conception technique complète.

Avant d’appeler la commande, tenez compte de l’autre contexte dont l’IA a besoin. Vos contraintes de code, de technologie et d’infrastructure existantes influencent tous le plan. Fournir ce contexte à l’avance produit des résultats plus précis et actionnables.

Pour la fonctionnalité de chargement de document dans un scénario de portail d’employés interne, vous pouvez fournir un contexte semblable à ceci :

« Le portail existant utilise un serveur frontal React avec un back-end d’API web .NET 8. Nous devons intégrer la fonctionnalité de téléversement dans cet ensemble technologique. Utilisez Stockage Blob Azure pour la persistance des fichiers. Exiger l’authentification d’ID Microsoft Entra pour toutes les opérations de chargement. Le portail dispose déjà d’une base de données SQL disponible pour le stockage des métadonnées. »

Ce contexte guide l’IA pour générer un plan qui s’adapte de manière transparente à votre architecture existante, plutôt que de proposer une solution greenfield qui ne s’aligne pas sur votre pile technologique actuelle.

Appeler la commande de planification

Ouvrez GitHub Copilot Chat dans Visual Studio Code et entrez /speckit.plan. Si l’IA demande plus d’informations, fournissez votre contexte architectural. GitHub Copilot traite la spécification, la constitution et votre contexte supplémentaire pour générer plan.md.

La phase de planification peut prendre un moment, car l’IA considère différentes approches, les vérifie contre votre constitution et structure la sortie dans un document de conception cohérent.

Examiner et valider le plan

La génération d’un plan n’est que la première étape. La révision critique garantit que le plan est précis, complet et aligné sur les besoins de votre projet.

Vérifier la couverture des exigences de spécification

Comparez systématiquement le plan par rapport à spec.md. Chaque exigence de la spécification doit être mappée à une approche d’implémentation dans le plan.

Par exemple, si spec.md nécessite « Afficher un message d’erreur pour les fichiers dépassant 50 Mo », le plan doit décrire où et comment cette validation se produit. Si le plan omet cette validation, le plan est incomplet ou la spécification a besoin d’une clarification.

Vérifier l’alignement avec les normes techniques

Assurez-vous que les choix technologiques du plan s’alignent sur les normes et les meilleures pratiques de votre organisation. Si votre équipe standardise sur des bibliothèques ou des modèles spécifiques, le plan doit refléter ces préférences.

Questions à prendre en compte :

  • L’architecture proposée s’adapte-t-elle aux systèmes existants ?
  • Les bibliothèques sélectionnées sont-elles approuvées pour être utilisées dans votre environnement ?
  • Les choix technologiques sont-ils conformes aux stratégies de sécurité et de conformité organisationnelles ?
  • Existe-t-il des modèles établis pour des fonctionnalités similaires qui doivent être suivis ?

Pour la fonctionnalité de chargement de document dans un environnement Azure, vérifiez que le stockage Blob Azure est un service approuvé, que l’approche d’authentification s’aligne sur les normes d’identité d’entreprise (telles que l’utilisation de l’ID Microsoft Entra) et que le schéma SQL proposé suit les conventions d’affectation de noms de base de données.

Valider l’adhésion à la constitution

Le plan devrait inclure une vérification explicite selon laquelle les solutions proposées sont conformes aux exigences de constitution. Passez en revue attentivement cette section de vérification pour vous assurer qu’aucun principe n’est violé.

Si votre constitution requiert « Tous les secrets doivent être stockés dans Azure Key Vault », et le plan propose de stocker des chaînes de connexion stockage Azure dans appsettings.json, un conflit existe. Le plan doit être révisé pour récupérer des chaînes de connexion à partir de Key Vault au moment de l’exécution.

Les violations constitutionnelles détectées lors de la planification sont faciles à corriger. Les violations constitutionnelles détectées lors de l’examen du code ou du déploiement de production sont coûteuses et perturbatrices.

Itérer et affiner le plan

Les plans nécessitent souvent un affinement après la génération initiale. Ne vous attendez pas à la perfection lors de la première tentative. Utilisez les fonctionnalités de clarification de GitHub Copilot pour améliorer la qualité du plan.

Résoudre les ambiguïtés et les lacunes

Si le plan contient des instructions vagues telles que « implémenter la gestion des erreurs appropriée », appuyez sur des informations spécifiques. Quelles erreurs peuvent se produire ? Comment chaque erreur doit-elle être gérée ? Quelles informations d’erreur doivent être enregistrées et affichées aux utilisateurs ?

Utilisez GitHub Copilot Chat pour poser des questions de suivi : « Quelles erreurs spécifiques le point de terminaison de chargement doit-il gérer ? » ou « Que se passe-t-il si le Stockage Blob Azure n’est pas disponible ? » L’IA peut développer des sections vagues en spécifications concrètes.

Valider la faisabilité technique

Vérifiez que l’architecture proposée est techniquement réalisable en fonction de vos contraintes. Si le plan propose de charger des fichiers de 50 Mo de manière synchrone via une API web avec un délai d’expiration de 30 secondes, un problème existe. Les fichiers dont la taille est supérieure à 50 Mo peuvent nécessiter des chargements en bloc ou des délais d’expiration accrus.

Consultez les membres de l’équipe qui ont une expertise pertinente. Si le plan propose des modifications de schéma de base de données, passez en revue avec un administrateur de base de données. S’il nécessite de nouvelles ressources Azure, vérifiez auprès des ingénieurs de l’infrastructure que l’approvisionnement est possible.

Prendre en compte les exigences non fonctionnelles

Assurez-vous que le plan répond aux exigences non fonctionnelles de la spécification : performances, sécurité, scalabilité, facilité de maintenance, accessibilité.

Pour le chargement du document, vérifiez que le plan inclut :

  • Performances : à quelle vitesse un chargement doit-il être terminé ? Quel est le volume maximal de chargement simultané ?
  • Sécurité : Comment les fichiers sont-ils analysés pour les programmes malveillants ? Comment l’accès est-il contrôlé ? Où sont stockés les journaux d’audit ?
  • Scalabilité : Comment le système gère-t-il un volume de chargement accru ? Quelles sont les limites de capacité de stockage ?
  • Facilité de maintenance : Comment les fichiers chargés sont-ils nettoyés lorsque les employés quittent l’organisation ?
  • Accessibilité : l’interface utilisateur de chargement répond-elle aux normes AA (Web Content Accessibility Guidelines) 2.1 ?

Si le plan omet l’une de ces considérations, ajoutez-les explicitement. Les exigences non-fonctionnelles deviennent fréquemment des pensées après coup pendant la mise en œuvre si elles ne sont pas traitées lors de la planification.

Évaluer la faisabilité et l’exhaustivité

Évaluez si le plan fournit des conseils suffisants pour l’implémentation. Les plans trop vagues (« Implémenter le chargement de fichiers ») ne sont pas utiles. Les plans trop prescriptifs (« Utiliser exactement 47 lignes de code ») sont trop contraignants.

Le bon niveau de détail fournit une direction claire sans supprimer toute flexibilité. Le plan doit répondre aux questions suivantes :

  • Quels composants doivent être créés ou modifiés ?
  • Comment ces composants interagissent-ils ?
  • Quelles technologies et bibliothèques sont utilisées ?
  • Qu’est-ce que l’ordre d’implémentation ?
  • Quelles sont les étapes de vérification qui garantissent l’exactitude ?

Si vous ne pouvez pas imaginer comment implémenter la fonctionnalité à partir du plan, elle a besoin de plus de détails. Si le plan se sent comme s’il écrivait le code pour vous, il peut être trop détaillé.

Identifier les éléments manquants

Recherchez les lacunes dans le plan. Les omissions courantes sont les suivantes :

  • Gestion des erreurs : Comment le système gère-t-il les défaillances réseau, les erreurs de stockage ou les problèmes de base de données ?
  • Considérations relatives aux performances : Existe-t-il des préoccupations concernant la vitesse de chargement, les utilisateurs simultanés ou les limites de stockage ?
  • Stratégie de test : Quels tests doivent être écrits pour valider l’implémentation ?
  • Approche de restauration : si le déploiement provoque des problèmes, comment rétablir les modifications ?

Résolvez ces lacunes en modifiant manuellement plan.md ou en fournissant plus de contexte et en régénérant les sections pertinentes.

Régénérer avec un contexte raffiné

Si le plan initial rate sa cible, fournissez un contexte plus spécifique et réinitialisez. Par exemple, si le plan suggère d’utiliser une nouvelle base de données, mais que vous devez utiliser une base de données existante, précisez : « Utilisez la base de données EmployeePortal existante. Ajoutez une table DocumentMetadata à cette base de données plutôt que de en créer une nouvelle. »

Régénérez le plan /speckit.plan en incorporant ce contexte mis à jour. L’IA ajuste l’approche en conséquence.

Modifier manuellement le plan

Étant donné que plan.md est un fichier Markdown, vous pouvez le modifier directement. Si l’IA suggère une approche qui est de 90% correcte mais nécessite des ajustements mineurs, modifiez le fichier plutôt que de régénérer tout.

Par exemple, si le plan propose un nom de conteneur blob spécifique, mais que votre organisation a des conventions de nommage, mettez à jour directement le nom du conteneur dans plan.md.

Collaborer avec les membres de l’équipe

Dans les environnements d’équipe, partagez plan.md pour révision. Un développeur ou un architecte senior peut valider les décisions architecturales avant le début de l’implémentation. Cette évaluation par les pairs identifie les problèmes que les vérifications automatisées pourraient manquer.

La révision d’équipe génère également une compréhension partagée. Lorsque plusieurs développeurs travaillent sur une fonctionnalité, l’examen du plan permet de s’assurer que tout le monde connaît l’approche et peut identifier les conflits potentiels avec d’autres travaux en cours.

Documenter les décisions architecturales

Les plans doivent non seulement documenter ce que vous allez créer, mais pourquoi vous avez fait des choix architecturaux spécifiques pour aider les futurs développeurs à comprendre le contexte de décision.

Alternatives d’enregistrement prises en compte

Lorsque vous choisissez entre plusieurs approches viables, documentez les alternatives que vous avez prises en compte et la raison pour laquelle vous en avez sélectionné un sur d’autres.

Pour le stockage de fichiers, vous pouvez envisager trois approches :

  • Stockage Blob Azure : sélectionné pour sa rentabilité, sa scalabilité et son intégration à l’environnement Azure existant.
  • Azure Files : rejeté en raison d’un coût plus élevé pour le stockage de fichiers volumineux et la surcharge de protocole SMB (Server Message Block) inutile.
  • SQL Database FILESTREAM : rejeté pour éviter d’augmenter la taille et la complexité de la base de données.

Cette documentation empêche les futurs développeurs de s’interroger sur la raison pour laquelle des approches plus simples n’ont pas été utilisées. La justification de la décision est conservée au lieu de perdre du temps.

Capturer des hypothèses

Les plans font des hypothèses sur les systèmes, l’infrastructure et les contraintes organisationnelles existantes. Faites ces hypothèses explicites.

Exemples d’hypothèses pour le chargement de document :

  • Le conteneur Stockage Blob Azure employee-documents est approvisionné par l’équipe d’infrastructure avant le début du développement.
  • L’authentification du portail existante fournit des jetons d’ID Microsoft Entra validés qui peuvent être approuvés pour l’identification de l’utilisateur.
  • La base de données SQL dispose d’une capacité suffisante pour une autre table de métadonnées sans nécessiter d’extension de stockage.
  • L’infrastructure réseau prend en charge les chargements HTTP de 50 Mo sans restrictions de proxy ou de pare-feu.

Si une hypothèse s’avère incorrecte pendant l’implémentation, vous pouvez revoir le plan et ajuster en conséquence. Les hypothèses documentées rendent l’analyse d’impact simple lorsque les circonstances changent.

Planifier l’évolution future

Réfléchissez à l’évolution de la fonctionnalité et assurez-vous que votre architecture prend en charge les extensions probables.

Pour le chargement de documents, les exigences futures potentielles peuvent inclure :

  • Prise en charge d’autres types de fichiers au-delà de PDF et DOCX.
  • Implémentation du partage de fichiers entre les employés.
  • Ajout du contrôle de version de document.
  • Activation des chargements en bloc de plusieurs fichiers.
  • Intégration de l’analyse antivirus

Si votre architecture rend ces extensions difficiles, déterminez si l’ajustement de la conception initiale est justifié. Vous n’implémentez pas les fonctionnalités futures maintenant, mais vous évitez de vous enfermer dans des situations inextricables qui rendent les changements futurs difficiles.

Partager et gérer le plan pendant l’implémentation

Le plan devient votre référence tout au long de l’implémentation. Les développeurs doivent consulter régulièrement le plan pour s’assurer que leur code s’aligne sur l’architecture documentée.

Partager le plan avec les parties prenantes

Après avoir finalisé le plan, partagez-le avec les parties prenantes pertinentes pour la validation :

  • Gestionnaires de produits : vérifiez que le plan fournit toutes les spécifications requises.
  • Équipe de sécurité : Vérifiez que les contrôles de sécurité répondent aux normes organisationnelles.
  • Équipe d’infrastructure : vérifiez que les ressources Azure proposées peuvent être approvisionnées et configurées.
  • Équipe d’architecture : Valider l’alignement avec les principes de l’architecture organisationnelle.

Cet examen des parties prenantes intercepte les problèmes avant le début de l’implémentation. Si les commentaires de l’équipe de sécurité révèlent que l’authentification proposée est insuffisante, vous mettez à jour le plan avant d’écrire du code.

Mettre à jour le plan selon les besoins

Les plans sont des documents vivants. Lorsque vous découvrez lors de l’implémentation qu’une approche ne fonctionne pas comme prévu, mettez à jour le plan pour refléter la nouvelle approche.

Si vous envisagez de stocker la progression du chargement dans le navigateur localStorage, mais découvrez que cela provoque des problèmes en mode de navigation privée, mettez à jour le plan d’utilisation de l’état en mémoire à la place. Documentez pourquoi le changement était nécessaire afin que le raisonnement soit conservé.

Conservez plan.md synchronisée avec l’implémentation réelle. Lorsque le plan et le code diffèrent, le plan perd la valeur en tant que documentation de référence.

  • Les approches de sécurité répondent-ils aux exigences organisationnelles ?
  • La conception du schéma de base de données suit-elle les conventions d’affectation de noms ?

Si le plan suggère d’utiliser une base de données, mais que votre portail existant en contient déjà une, c'est probablement excessif. Si le plan propose une technologie que votre équipe évite, documentez pourquoi ou ajustez le plan.

Pièges de planification courants à éviter

Évitez ces erreurs courantes lors de la création et de l’examen des plans :

  • Ignorer la phase de planification : passer directement de la spécification au code sans plan augmente le risque d’erreurs architecturales. Le temps investi dans la planification paie des dividendes en empêchant le remaniement.

  • Acceptation des plans sans révision : les plans générés par l’IA sont des points de départ, et non des conceptions finales. Passez toujours en revue critiquement et vérifiez par rapport à votre contexte spécifique.

  • Implémentation trop contraignante : les plans doivent guider, et ne dictent pas tous les détails. Laissez la place aux développeurs pour prendre les décisions tactiques appropriées lors de l’implémentation.

  • Ignorer les conflits de constitution : si le plan enfreint les principes de constitution, traitez immédiatement le conflit. Ajustez le plan pour respecter ou mettre à jour la constitution si le principe a besoin d’une révision.

  • Oublions de mettre à jour les plans : lorsque l’implémentation révèle de nouvelles informations, mettez à jour plan.md. Les plans obsolètes trompent les développeurs futurs et réduisent la valeur de votre documentation.

Résumé

Le plan technique transforme votre spécification en architecture actionnable. Générez des plans à l’aide de /speckit.plan en fournissant un contexte approprié sur votre pile technologique et votre infrastructure. Passez en revue les plans de manière critique pour s’assurer qu’ils couvrent toutes les exigences de spécification, s’alignent sur votre constitution et fournissent des conseils de mise en œuvre suffisants. Utilisez le plan validé pour guider la génération et l’implémentation des tâches. Traitez plan.md comme un document vivant qui évolue avec votre compréhension et fournit un contexte précieux pour l’ensemble du cycle de vie du développement.