Générer une spécification claire, précise et efficace

  • 14 minutes

Le fichier de spécification (spec.md) est la source unique de vérité pour ce que votre logiciel doit faire. Cette unité couvre les techniques avancées d’écriture de spécifications de niveau entreprise.

Examiner les principes fondamentaux des spécifications

Dans le développement piloté par les spécifications, la spécification définit exactement ce que le logiciel doit faire, et chaque décision d’implémentation trace à elle. Une spécification bien structurée comprend :

  • Résumé : description concise de l’application (ou nouvelle fonctionnalité) du point de vue de l’utilisateur final.
  • Récits utilisateur : brèves narrations sur la façon dont les utilisateurs interagissent avec l’application.
  • Critères d’acceptation : conditions spécifiques et testables qui doivent être vraies pour l’achèvement.
  • Exigences fonctionnelles : descriptions détaillées du comportement du système.
  • Exigences non fonctionnelles : attributs de qualité tels que les performances, la sécurité et l’extensibilité.
  • Cas limites : scénarios inhabituels, conditions d’erreur et comportements à la limite.

La spécification comme source unique de vérité

Dans le développement piloté par les spécifications, la spécification définit exactement ce que le logiciel doit faire, et chaque décision d’implémentation trace à elle. Si la fonctionnalité n’apparaît pas dans la spécification, elle n’apparaît pas dans le produit final, sauf si quelqu’un met à jour la spécification et régénère les artefacts.

Cette approche représente un changement d’état d’esprit : l’écriture de la spécification est aussi importante que l’écriture de code. La spécification n’est pas une formalité pour satisfaire la gestion de projet, c’est l’artefact qui pilote la génération de code IA. Investissez les mêmes soins dans l’élaboration de spécifications que vous le feriez dans l’implémentation manuelle des fonctionnalités.

Considérez la spécification comme documentation exécutable. Lorsque vous modifiez les exigences, vous mettez à jour la spécification et régénérez le plan et les tâches. La spécification, qui est contrôlée par la version dans Git, devient l’enregistrement faisant autorité de ce que chaque fonctionnalité doit accomplir.

Pour les développeurs d’entreprise habitués aux flux de travail agiles, la spécification sert le même objectif que les récits d’utilisateurs détaillés et les critères d’acceptation, mais avec une structure lisible par l’ordinateur que les assistants IA peuvent consommer directement.

Structure de spécification

GitHub Spec Kit organise les spécifications en sections standardisées qui couvrent le comportement fonctionnel, les exigences de qualité et les cas de périphérie.

Rubrique Résumé

Description concise de la fonctionnalité du point de vue de l’utilisateur final. Cette section doit répondre à « Que fait cette fonctionnalité ? » dans une ou deux phrases.

Par exemple:

## Summary

This feature enables employees to upload PDF and DOCX documents to their personal dashboard. Files are stored securely in Azure Blob Storage and appear in the user's document list immediately after upload.

Le résumé fournit un contexte de haut niveau. Quelqu’un qui n’est pas familiarisé avec le projet doit comprendre l’objectif de la fonctionnalité après avoir lu cette section.

Section Récits utilisateur

Brève description de la façon dont les utilisateurs interagissent avec la fonctionnalité. Les récits utilisateur capturent l’intention et la valeur plutôt que l’implémentation technique.

Par exemple:

## User Stories

As an employee, I want to upload documents to my dashboard so that I can access them from any device.

As an employee, I want to see upload progress for large files so that I know the system is processing my request.

As a system administrator, I want uploads to be logged so that we can audit file activity for compliance purposes.

Les récits utilisateur aident les assistants IA à comprendre les motivations humaines derrière les fonctionnalités, ce qui entraîne des implémentations plus intuitives.

Section Critères d’acceptation

Conditions spécifiques et testables qui doivent être vraies pour que la fonctionnalité soit considérée comme terminée. Les critères d’acceptation forment une liste de contrôle pour vérifier l’implémentation.

Par exemple:

## Acceptance Criteria

- User can select PDF or DOCX files for upload
- Maximum file size is 50MB
- Files larger than 50MB display an error message
- Unsupported file types display an error message
- Successfully uploaded files appear in the document list within 2 seconds
- Upload progress is displayed for files larger than 1MB
- Only users with 'Contributor' role can upload documents
- Uploaded files are stored in user-specific folders in Azure Blob Storage

Écrivez les critères d’acceptation en tant que faits observables. Évitez les instructions vagues telles que « le système est réactif » : spécifiez plutôt « L’API répond dans les 200 ms ».

Section Exigences fonctionnelles

Descriptions détaillées du comportement du système. Exigences fonctionnelles détaillées sur le fonctionnement de la fonctionnalité.

Par exemple:

## Functional Requirements

### Upload interface
- Dashboard displays an "Upload Document" button in the documents section
- Clicking "Upload Document" opens a file selection dialog
- User selects a file from their local filesystem
- System validates file type and size before initiating upload

### Upload process
- Files are uploaded via multipart HTTP POST to /api/documents endpoint
- Upload includes file content and metadata (filename, size, content type)
- Server validates authentication token before accepting upload
- Server checks user has 'Contributor' role before processing

### Storage
- Files are stored in Azure Blob Storage container 'employee-documents'
- Storage path follows pattern: {userId}/{fileId}/{filename}
- Server generates unique file ID to prevent naming collisions
- File metadata (original filename, upload timestamp, user ID) stored in Azure SQL Database

### User feedback
- Upload progress bar updates every 10% completion
- Success message displays upon completion: "Document uploaded successfully"
- Error messages display for: file too large, unsupported type, network error, server error

Les exigences fonctionnelles fournissent suffisamment de détails pour que l’IA génère des implémentations appropriées sans prescrire une structure de code exacte.

Section Conditions requises non fonctionnelles

Attributs de qualité tels que les performances, la sécurité, l’extensibilité et la conformité. Ces exigences font souvent référence à la constitution.

Par exemple:

## Non-Functional Requirements

### Performance
- File uploads under 5MB complete within 5 seconds on typical network
- Upload progress updates display with less than 100ms latency
- Document list refresh completes within 1 second after upload

### Security
- All uploads require valid Microsoft Entra ID authentication token
- HTTPS/TLS 1.2 enforced for all data transmission
- Files scanned for malware before storage (future enhancement)
- No sensitive data logged (filenames logged, content never logged)

### Scalability
- Support concurrent uploads (up to 5 simultaneous per user)
- Handle 1000 concurrent users uploading files

### Compliance
- Audit log records: user ID, filename, timestamp, file size, IP address
- Audit logs retained for 90 days minimum
- Support data deletion requests within the specified timeline

Les exigences non fonctionnelles garantissent que le code généré par l’IA répond aux normes de qualité de l’entreprise, et non seulement à la correction fonctionnelle.

Section Cas limites

Scénarios inhabituels, conditions d’erreur et comportements de limites. La documentation explicite des cas de périphérie empêche l’IA d’effectuer des hypothèses.

Par exemple:

## Edge Cases

### Network interruption during upload
- If connection drops, display error: "Upload failed due to network error. Please retry."
- No partial files stored in Azure Blob Storage
- User can retry upload from beginning

### Duplicate filename
- System allows duplicate filenames by generating unique file IDs
- User sees original filename in document list
- Back end uses unique IDs to prevent overwrites

### Storage capacity limits
- If Azure Blob Storage quota exceeded, display error: "Upload failed due to storage limit. Contact support."
- Log storage errors for administrator notification

### Concurrent uploads by same user
- System supports up to 5 simultaneous uploads per user
- Sixth concurrent upload queued until one completes
- Progress bars update independently for each upload

### File type detection
- System validates file type by MIME type, not just extension
- File with .pdf extension but non-PDF content rejected
- Error message: "File appears corrupted or has incorrect type"

La réflexion sur les cas de périphérie pendant la spécification empêche les bogues qui apparaissent autrement lors de l’implémentation ou du test.

Créer une spécification avec GitHub Spec Kit

L’écriture de spécifications efficaces est plus facile avec la commande de /speckit.specify GitHub Spec Kit.

GitHub Spec Kit génère des brouillons de spécifications basés sur des descriptions de langage naturel, accélérant la création de spécifications tout en conservant une structure cohérente.

Exécuter la commande spécification

Pour créer une spécification :

  1. Ouvrez votre projet dans Visual Studio Code.

  2. Ouvrez GitHub Copilot Chat, puis exécutez la /speckit.specify commande avec une invite décrivant la fonctionnalité que vous souhaitez créer.

    Par exemple:

    /speckit.specify Create a new document upload feature. The feature should allow employees to upload PDF or DOCX documents through the web dashboard. Files are stored in Azure Blob Storage under the user's account folder. After upload, the file appears in the user's document list. Only users with 'Contributor' role can upload. Maximum file size is 50MB. Show error messages for oversized files or unsupported types. Display upload progress for files larger than 1MB.

    Cette description couvre les points suivants :

    • Quoi : Téléchargez des documents PDF/DOCX
    • Où : interface de tableau de bord web
    • Comment : stocké dans le stockage Blob d'Azure
    • Qui : Utilisateurs disposant d’un rôle Contributeur
    • Contraintes : limite de 50 Mo, types de fichiers spécifiques
    • Expérience utilisateur : affichage de progression, messages d’erreur

GitHub Copilot génère un fichier structuré spec.md basé sur cette entrée, en créant des sections pour le résumé, les critères d’acceptation, les exigences et les cas de périphérie.

Passer en revue la spécification générée

Une fois que GitHub Copilot génère la spécification, ouvrez spec.md et vérifiez :

  • Complétivité : La spécification couvre-t-elle toutes les exigences que vous avez mentionnées ? Si vous avez spécifié « uniquement PDF et DOCX », confirmez les critères d’acceptation de ces types de fichiers.

  • Précision : Les détails sont-ils corrects ? Si vous avez dit une limite de 50 Mo, vérifiez que les spécifications indiquent 50 Mo, pas une valeur différente.

  • Cohérence : Les différentes sections s’alignent-ils ? Si le résumé mentionne l’affichage de la progression, les critères d’acceptation doivent l’inclure.

  • Éléments manquants : Qu’est-ce que GitHub Copilot a déduit ou omis ? Passez en revue les exigences générées pour voir si l’IA a fait des hypothèses avec lesquelles vous n’êtes pas d’accord.

La spécification initiale est un point de départ fort mais rarement parfait. Attendez-vous à l'affiner par clarifications successives.

Affinement des spécifications avec /speckit.clarify

La /speckit.clarify commande analyse votre spécification et identifie les ambiguïtés, les lacunes ou les hypothèses nécessitant une clarification.

Garantir la clarté des spécifications

Les ambiguïtés dans les spécifications entraînent des implémentations incorrectes. Utilisez /speckit.clarify pour mettre en évidence les zones peu claires.

Après avoir généré une spécification initiale :

  1. Dans GitHub Copilot Chat, exécutez :

    /speckit.clarify

  2. GitHub Copilot analyse et pose des questions sur les détails peu clairs ou manquants spec.md

    Exemples de questions de clarification :

    I've analyzed the specification and have some questions:

1. File retention: How long should uploaded documents be retained? Forever, or is there a retention policy?

2. Duplicate filenames: If a user uploads a file with the same name as an existing file, should the system:
    - Overwrite the existing file
    - Create a new version
    - Reject the upload with an error
    - Store both with unique identifiers

3. Virus scanning: Should uploaded files be scanned for malware? If so, when—before storage or asynchronously after upload?

4. Download capability: The spec describes upload but doesn't mention download. Should users be able to download their uploaded documents?

5. File sharing: Can users share documents with other employees, or are documents private to the uploader?

Ces questions vous aident à prendre des décisions sur les aspects que vous avez peut-être manqués au départ.

Répondre aux questions de clarification

Répondez à chaque question avec des décisions spécifiques :

1. File retention: Retain documents indefinitely until user deletes them. No automatic deletion.

2. Duplicate filenames: Option d - Store both with unique identifiers. Users can have multiple files with the same name. Display upload timestamp to distinguish them in the list.

3. Virus scanning: Not required for initial release. Mark as future enhancement in the spec.

4. Download capability: Yes, users should be able to download their documents. Add this to the spec.

5. File sharing: Documents are private to the uploader for this release. Sharing is a future feature.

Une fois que vous avez répondu, GitHub Copilot met à jour spec.md pour incorporer vos décisions :

  • Les critères d’acceptation gagnent : « Les utilisateurs peuvent télécharger des documents précédemment chargés ».
  • Les exigences fonctionnelles ajoutent la spécification du point de terminaison de téléchargement.
  • Les cas edge incluent : « Plusieurs fichiers avec des noms identiques distingués par l’horodatage de chargement ».
  • Remarque sur les exigences non fonctionnelles : « Analyse de virus différée à la prochaine version ».

Itérer jusqu’à la fin

Exécutez /speckit.clarify plusieurs fois si nécessaire. Chaque itération affine davantage la spécification :

  • Première passe : importantes lacunes de fonctionnalités.
  • Deuxième passage : détails des cas limites.
  • Troisième passe : Réglage précis des exigences non fonctionnelles.

Arrêtez lorsque GitHub Copilot n’a plus de questions ou ne vous pose que des questions sur les fonctionnalités que vous souhaitez différer.

Meilleures pratiques pour l’écriture de spécifications

L’écriture de spécifications claires et non ambiguës est essentielle au développement réussi piloté par les spécifications.

Être spécifique et mesurable

Remplacez les termes vagues par des valeurs précises :

  • Non : « Prendre en charge les fichiers volumineux ».

  • Au lieu de cela : « Prendre en charge les fichiers jusqu’à 50 Mo ».

  • Non : « Performances de chargement rapide ».

  • Au lieu de cela : « Les chargements de moins de 5 Mo sont terminés dans les 5 secondes sur la connexion de 10 Mbits/s . »

Les exigences spécifiques permettent à l’IA de générer des implémentations répondant à vos besoins réels.

Utiliser une terminologie cohérente

Définissez des termes une fois et réutilisez-les tout au long de la spécification. Si vous les appelez « documents » dans le résumé, ne basculez pas vers « fichiers » ou « pièces jointes » ultérieurement. La terminologie incohérente confond les humains et l’IA.

Pour les projets internes d’entreprise, utilisez les noms de produits et la terminologie officiels des normes de votre organisation.

Couvrir explicitement la gestion des erreurs

Ne supposez pas que l’IA gère les erreurs de manière appropriée. Spécifiez ce qui se passe quand les opérations échouent :

  • « Si le Stockage Blob Azure est inaccessible, affichez une erreur : « Impossible de se connecter au service de stockage. Réessayez plus tard.'"
  • « Si l’utilisateur n’a pas de rôle requis, renvoyez HTTP 403 avec le message : « Vous n’êtes pas autorisé à charger des documents. »

La gestion explicite des erreurs empêche l’IA d’implémenter des messages d’erreur génériques qui n’aident pas les utilisateurs.

Maintenir l’étendue appropriée

Si une fonctionnalité nécessite plus de 300 lignes à spécifier, envisagez de la fractionner en plusieurs spécifications :

  • Au lieu d’une spécification « Système de gestion des documents ».
  • Créez des spécifications distinctes : « Téléchargement de document », « Téléchargement de document », « Partage de documents » et « Recherche de documents ».

Les spécifications plus petites sont plus faciles à examiner, clarifier et implémenter. Ils s’alignent également sur les pratiques de livraison incrémentielles.

Détail « quoi », pas « comment »

Les spécifications définissent les exigences, et non les implémentations. Indiquez ce que le système doit faire, et non comment le coder :

  • Spécifications : « Stocker les fichiers chargés dans stockage Blob Azure ».
  • Pas dans les spécifications : « Utiliser le package NuGet Azure.Storage.Blobs avec la classe BlobContainerClient ».

Les décisions d’implémentation appartiennent à la phase du plan. Toutefois, si la constitution impose des technologies spécifiques, il convient de les référencer dans la spécification.

Vérifier la conformité avec la constitution

Avant de finaliser une spécification, vérifiez qu’elle n’est pas en conflit avec les principes du projet :

  • La Constitution exige l’authentification via Microsoft Entra ID → La spécification doit préciser l’ID Microsoft Entra, et non l’authentification personnalisée.
  • La Constitution impose une rétention d’audit de 90 jours → Spec doit inclure des exigences de journalisation d’audit.
  • La constitution limite la taille maximale du fichier à 50 Mo → La spécification ne peut pas nécessiter une prise en charge de fichier de 1 Go.

Les incohérences détectées pendant la spécification sont beaucoup moins coûteuses à corriger qu’après l’implémentation.

La spécification terminée devient votre contrat avec GitHub Copilot. Lorsque vous passez à la phase de planification, GitHub Copilot référence cette spécification pour concevoir des implémentations techniques qui correspondent précisément à vos besoins. Le temps investi dans une spécification approfondie paie les dividendes tout au long du développement.

Résumé

L’écriture de spécifications efficaces est fondamentale pour réussir le développement piloté par les spécifications. Une spécification bien structurée sert de source unique de vérité, guidant la génération de code IA et garantissant l’alignement avec les principes du projet. À l’aide des commandes /speckit.specify et /speckit.clarify de GitHub Spec Kit, vous pouvez rapidement créer et affiner des spécifications détaillées qui couvrent le comportement fonctionnel, les attributs de qualité et les cas limites. Les meilleures pratiques en matière d’écriture de spécifications améliorent la clarté, réduisent l’ambiguïté et mènent à des implémentations qui répondent aux besoins des utilisateurs et aux normes d’entreprise.