Créer une constitution avec des principes, des contraintes et des normes

  • 10 minutes

La constitution est la base du développement piloté par les spécifications avec GitHub Spec Kit. Cette unité explore comment créer des constitutions efficaces pour les scénarios de développement d’entreprise.

Examiner les principes fondamentaux de la constitution

Un dossier de constitution capture les principes, contraintes et normes non négociés qui régissent votre projet. Il sert également de garde-fou pour le développement assisté par l’IA. Lorsque l’agent génère des spécifications, des plans, des tâches ou du code, il fait référence à la constitution pour vérifier que les propositions sont conformes à vos normes.

Parmi les principaux avantages d’une constitution bien définie, citons :

  • Mise en œuvre de la cohérence : garantit l’alignement avec les décisions architecturales sur de longs projets et plusieurs développeurs.
  • Documentation de conformité : Rend les exigences réglementaires et les stratégies de sécurité explicites et auditables.
  • Capture des connaissances institutionnelles : préserve les leçons durement gagnées sous une forme qui guide la génération de code IA.
  • Charge cognitive réduite : Automatise l’application des stratégies organisationnelles pendant le développement.

Objectif de la constitution

Les avantages d’une constitution bien définie deviennent puissants dans la pratique grâce à l’application automatique. Si la constitution indique « Toutes les données doivent être chiffrées au repos », l’agent IA ne suggère pas de stocker des fichiers en texte clair , il incorpore automatiquement le chiffrement dans les conceptions. Lorsque vous générez une spécification pour les chargements de fichiers, le plan inclut la configuration du chiffrement stockage Azure. Lorsque vous générez le code, votre implémentation utilise des services de stockage chiffrés.

Réfléchissez à la façon dont chaque avantage se concrétise dans des scénarios de développement réels :

  • Mise en œuvre de cohérence : les projets couvrant plusieurs mois ou impliquant plusieurs développeurs peuvent dériver des décisions architecturales. Sans constitution, un développeur peut utiliser le stockage de fichiers local, tandis qu’un autre utilise Stockage Blob Azure pour des fonctionnalités similaires. La constitution empêche cette dérive par des normes d’encodage que les assistants IA référencent toujours, garantissant ainsi des choix technologiques uniformes sur toutes les fonctionnalités.

  • Documentation de conformité : les exigences réglementaires, les stratégies de sécurité et les règles de gouvernance interne doivent être respectées. La constitution rend explicite les exigences, créant un enregistrement vérifiable de la façon dont vous appliquez la conformité. Lorsqu’un auditeur demande « Comment vérifier que les données personnelles ne sont pas enregistrées ? », vous pointez sur l’exigence de constitution et indiquez que tout le code généré respecte cette contrainte.

  • Capture des connaissances institutionnelles : les architectes expérimentés et les équipes de sécurité prennent des décisions basées sur des leçons durement gagnées, comme la découverte de certains modèles d’API qui provoquent des problèmes de performances ou que des flux d’authentification spécifiques créent des vulnérabilités de sécurité. La constitution préserve cette sagesse sous une forme qui guide la génération de code IA, empêchant les nouveaux membres de l’équipe de redécouvrir à plusieurs reprises les mêmes contraintes.

  • Charge cognitive réduite : les développeurs n'ont pas besoin de mémoriser les standards de l'organisation lorsqu'ils sollicitent l'intelligence artificielle. La constitution automatise l’application de stratégies telles que « utiliser Azure Key Vault pour les secrets » ou « s’authentifier via Microsoft Entra ID ». Au lieu de vérifier manuellement chaque plan généré par rapport à une liste de vérification des exigences, l’IA les incorpore automatiquement.

Dans les environnements de développement d’entreprise, les constitutions encodent souvent :

  • Exigences de sécurité imposées par les stratégies d’entreprise.
  • Objectifs de performances et d’extensibilité pour les charges de travail d’entreprise.
  • Choix technologiques alignés sur les services Azure et les outils internes.
  • Normes de codage et modèles architecturaux issus des meilleures pratiques d’ingénierie.
  • Obligations de conformité telles que les normes d’accessibilité, la protection des données personnelles et les exigences d’audit.

Structure d’une constitution efficace

Une constitution bien structurée organise les principes en catégories que les assistants IA peuvent facilement référencer.

Les sections courantes sont les suivantes :

  • Normes technologiques.
  • Exigences de sécurité.
  • Performances et scalabilité.
  • Normes de codage.
  • Conformité et gouvernance.

Les sections suivantes illustrent comment définir efficacement chaque catégorie.

Normes technologiques

Les normes technologiques sont utilisées pour spécifier des technologies, des plateformes et des infrastructures approuvées.

Par exemple, la section suivante impose des services Azure et .NET pour le développement back-end :

## Technology Standards

- All cloud resources must be hosted on Microsoft Azure.
- Back-end services use .NET 8 or later.
- Front-end applications use React or Blazor.
- Database: Azure SQL Database or Cosmos DB (no on-premises SQL Server).
- Secret management exclusively via Azure Key Vault.

Ces contraintes empêchent l’IA de suggérer des technologies incompatibles. Si la constitution impose Azure, GitHub Copilot ne propose pas de fonctions Lambda Amazon Web Services.

Besoins de sécurité

Les exigences de sécurité peuvent être utilisées pour définir des éléments tels que l’authentification, l’autorisation, le chiffrement et les règles de protection des données.

Par exemple, la section suivante établit des principes de sécurité pour une application interne :

## Security Requirements

- Authenticate all API requests using Microsoft Entra ID tokens.
- Encrypt all data at rest using AES-256 encryption.
- Encrypt data in transit using TLS 1.2 or higher.
- Never log personally identifiable information (PII).
- Store no secrets in source code or configuration files.
- Implement role-based access control (RBAC) for all features.

Les principes de sécurité sont essentiels pour le développement d’entreprise. Les exigences explicites garantissent que le code généré incorpore la sécurité dès le début.

Performances et extensibilité

Les exigences en matière de performances et d’extensibilité sont utilisées pour définir les attentes relatives au comportement du système sous charge.

Par exemple, la section suivante définit des cibles de performances pour une API :

## Performance and Scalability

- APIs must respond within 200ms for 95th percentile requests.
- System must handle 10,000 concurrent users.
- Use asynchronous processing for operations exceeding 5 seconds.
- Implement caching for frequently accessed data.
- Design for horizontal scalability using Azure App Service or Container Apps.

Les exigences en matière de performances guident les décisions architecturales. Si la constitution exige la gestion des chargements de fichiers volumineux de manière asynchrone, le plan incorpore le traitement en arrière-plan.

Normes et directives du code

Les normes et les directives fournissent des exigences qui aident à garantir la qualité du code.

Par exemple, la section suivante décrit les conventions de codage pour un projet .NET :

## Coding Standards

- Follow Microsoft C# Coding Conventions.
- Maintain minimum 80% unit test coverage.
- All public APIs documented with XML comments.
- Use dependency injection for service dependencies.
- Implement structured logging using ILogger interface.

Les normes de codage garantissent la cohérence entre le codebase. Le code généré par l’IA s’aligne sur les conventions d’équipe lorsque la constitution les référence.

Gouvernance et conformité

Les exigences de conformité et de gouvernance sont utilisées pour documenter les exigences en matière de réglementation et de stratégie interne.

Par exemple, la section suivante capture les principes de conformité pour la gestion des données :

## Compliance and Governance

- Comply with local and international standards that protect personal information for all user data processing.
- Implement audit logging for all data modifications.
- Support accessibility standards (WCAG 2.1 Level AA).
- Enable monitoring and alerting via Azure Application Insights.
- Retain logs for minimum 90 days for compliance audits.

Les principes de conformité protègent votre organisation contre les violations réglementaires. La constitution garantit que ces principes ne sont pas oubliés pendant le développement.

Créer la constitution avec GitHub Spec Kit

La commande /speckit.constitution du GitHub Spec Kit peut être utilisée pour créer ou mettre à jour un fichier de configuration.

Projets existants

Lorsque vous travaillez sur un projet existant qui comprend déjà un fichier de constitution, vous pouvez mettre à jour la constitution à l’aide de la /speckit.constitution commande. GitHub Copilot examine la constitution existante et suggère des mises à jour basées sur votre codebase. Les mises à jour du GitHub Spec Kit lui-même peuvent également être reflétées dans les modifications suggérées.

Lorsque vous ajoutez GitHub Spec Kit à un projet existant qui n’a pas encore de constitution, vous pouvez en générer un à l’aide de la /speckit.constitution commande dans GitHub Copilot Chat. GitHub Copilot examine la base de code existante et déduit les principes et contraintes du projet pour créer un fichier initial constitution.md . Si nécessaire, vous pouvez affiner la constitution générée pour vous assurer qu’elle reflète précisément les exigences de votre projet.

Nouveaux projets

Lorsque vous démarrez un nouveau projet à l’aide de GitHub Spec Kit, vous pouvez générer une constitution à partir de zéro à l’aide de la /speckit.constitution commande dans GitHub Copilot Chat.

Pour créer la charte d’un nouveau projet :

  1. Ouvrez votre projet dans Visual Studio Code et vérifiez que GitHub Spec Kit est initialisé.

  2. Ouvrez GitHub Copilot Chat, puis exécutez la /speckit.constitution commande avec une description en langage naturel de vos principes et contraintes de projet.

    Par exemple, vous pouvez fournir l’invite suivante :

    /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.

    GitHub Copilot génère un fichier structuré constitution.md avec des sections organisées par catégorie.

Affiner la constitution générée

Après que GitHub Copilot génère la constitution initiale, examinez-la et modifiez-la pour garantir la précision.

Prenez en considération les étapes suivantes :

  • Ajouter des principes manquants : si GitHub Copilot a omis des exigences importantes, ajoutez-les manuellement. Par exemple, si votre organisation nécessite des formats de journalisation spécifiques, ajoutez cette contrainte.

  • Supprimer du contenu inutile : GitHub Copilot peut générer des principes réutilisables ou trop génériques. Supprimez tout ce qui ne fournit pas de conseils concrets.

  • Définissez des principes spécifiques et testables : remplacez les instructions vagues par des critères mesurables. Remplacez « le système doit être rapide » par « Réponses d’API terminées dans un délai de 200 ms pour 95% de requêtes ».

  • Aligner sur les normes internes : référencez les documents existants lorsque cela est possible. Par exemple : « Suivez les instructions d’excellence en ingénierie v2.3 pour la conception d’API ».

  • Vérifiez auprès des parties prenantes : partagez la constitution avec les équipes de sécurité, de conformité et d’architecture pour confirmer qu’elle capture toutes les exigences nécessaires.

La constitution est un document vivant, mais il change peu souvent. Une fois établi, il fournit des conseils stables sur le développement de fonctionnalités.

Constitution dans le workflow de développement piloté par les spécifications

Après avoir créé la constitution, GitHub Spec Kit le référence automatiquement pendant les phases de flux de travail suivantes :

  • Phase de spécification : lorsque vous exécutez /speckit.specify pour créer des spécifications de fonctionnalités, GitHub Copilot vérifie la constitution pour s’assurer que les exigences ne respectent pas les principes établis. Si la spécification propose de stocker les fichiers localement, GitHub Copilot signale ce conflit avec le mandat de Stockage Blob Azure défini dans la constitution.

  • Phase de planification : la /speckit.plan commande génère des plans techniques qui vérifient explicitement la conformité aux exigences de constitution. Le plan comprend des sections montrant comment la conception satisfait à chaque principe pertinent.

  • Phase d’analyse : l’exécution de /speckit.analyze compare vos spécifications, votre plan et vos tâches à la constitution afin d’identifier les incohérences. Par exemple, si des tâches incluent l’implémentation de l’authentification nom d’utilisateur/mot de passe, mais que la constitution requiert l’ID Microsoft Entra, l’analyse intercepte cet écart.

  • Phase d’implémentation : lorsque vous générez du code avec /speckit.implement, GitHub Copilot produit des implémentations respectant les contraintes de constitution. Le code inclut automatiquement l’authentification Microsoft Entra ID s’il est mandaté par la constitution.

Cette intégration est pourquoi la constitution est si puissante : écrire des principes une fois, et l’IA les applique automatiquement tout au long du développement.

Considérations relatives à la constitution propre à l’entreprise

Lors de la création de constitutions pour des projets internes d’entreprise, incorporez ces exigences courantes :

  • Architecture Azure first : mandatez les services Azure pour l’hébergement, le stockage, les bases de données et l’infrastructure de prise en charge. Cette exigence s’aligne sur la stratégie cloud d’entreprise et les outils disponibles.

  • Authentification d’entreprise : exiger l’ID Microsoft Entra pour l’authentification et RBAC pour l’autorisation. La plupart des applications internes d’entreprise s’intègrent aux systèmes d’identité d’entreprise.

  • Sécurité et conformité : Référencez les stratégies de sécurité d’entreprise, les principes TrustWorthy Computing et les frameworks de conformité applicables.

  • Supervision et observabilité : mandatez Azure Application Insights ou des solutions de supervision équivalentes. Les applications d’entreprise ont besoin de données de télémétrie complètes pour la prise en charge de la production.

  • Normes d’outils de développement : spécifiez des infrastructures, des bibliothèques et des pratiques de développement approuvées. Par exemple, vous devez utiliser des packages NuGet approuvés à partir de flux internes.

  • Accessibilité : incluez les exigences de conformité AA de niveau WCAG 2.1. Les outils internes d’entreprise doivent être accessibles aux employés handicapés.

Exemple d’extrait de code de constitution interne d’entreprise :

# Employee Portal Constitution

## Azure Platform Standards
- Host all services on Azure App Service or Azure Container Apps.
- Use Azure Blob Storage for document storage.
- Database: Azure SQL Database or Cosmos DB.
- Secrets stored exclusively in Azure Key Vault.
- Use Azure Front Door for global distribution.

## Identity Integration
- Authenticate via Microsoft Entra ID using OAuth 2.0 / OpenID Connect.
- Implement role-based access control using Microsoft Entra ID groups.
- Support multi-factor authentication (MFA).
- No custom authentication or local user databases.

## Corporate Compliance
- Follow enterprise Security Development Lifecycle (SDL) practices.
- Scan all dependencies for known vulnerabilities.
- Implement audit logging per enterprise retention policies.
- Support data residency requirements for EU users.
- Accessibility: WCAG 2.1 Level AA minimum.

## Development Standards
- Back end: .NET 10 following coding conventions adopted by the organization.
- Use approved packages from internal NuGet feed.
- Minimum 80% code coverage with unit tests.
- All APIs documented with OpenAPI/Swagger.
- Structured logging using ILogger interface.

En établissant ces principes au début de la constitution, vous assurez que chaque fonctionnalité créée pour le portail des employés s’aligne automatiquement sur les normes d’ingénierie d’entreprise, les exigences de sécurité et les modèles architecturaux. La constitution transforme les connaissances organisationnelles en contraintes exécutables qui guident le développement assisté par l’IA.

Résumé

Le fichier de constitution est un artefact critique dans le développement piloté par les spécifications avec GitHub Spec Kit. Il capture les principes, contraintes et normes de projet immuables qui régissent chaque phase de développement. En définissant ces exigences initialement, vous allez autoriser GitHub Copilot à appliquer automatiquement la conformité tout au long de la spécification, de la planification, de l’analyse et de l’implémentation.