Generar una especificación clara, precisa y eficaz

  • 14 minutos

El archivo de especificación (spec.md) es la única fuente de verdad para lo que su software debe hacer. En esta unidad se tratan técnicas avanzadas para escribir especificaciones de nivel empresarial.

Revisión de los aspectos básicos de las especificaciones

En el desarrollo controlado por especificaciones, la especificación define exactamente lo que debe hacer el software y cada decisión de implementación realiza un seguimiento hacia él. Una especificación bien estructurada incluye:

  • Resumen: descripción concisa de la aplicación (o nueva característica) desde una perspectiva del usuario final.
  • Casos de usuario: breves narraciones sobre cómo interactúan los usuarios con la aplicación.
  • Criterios de aceptación: Condiciones específicas y verificables que deben cumplirse para su finalización.
  • Requisitos funcionales: descripciones detalladas del comportamiento del sistema.
  • Requisitos no funcionales: atributos de calidad como el rendimiento, la seguridad y la escalabilidad.
  • Casos extremos: Escenarios inusuales, condiciones de error y comportamientos límite.

La especificación como la única fuente de verdad

En el desarrollo controlado por especificaciones, la especificación define exactamente lo que debe hacer el software y cada decisión de implementación realiza un seguimiento hacia él. Si la funcionalidad no aparece en la especificación, no aparece en el producto final a menos que alguien actualice la especificación y vuelva a generar artefactos.

Este enfoque representa un cambio de mentalidad: escribir la especificación es tan importante como escribir código. La especificación no es una formalidad para satisfacer la administración del proyecto; es el artefacto que impulsa la generación de código de IA. Invierta la misma atención en la elaboración de especificaciones que en la implementación manual de características.

Piense en la especificación como documentación ejecutable. Al modificar los requisitos, actualice la especificación y vuelva a generar el plan y las tareas. La especificación, controlada por versiones en Git, se convierte en el registro autoritativo de lo que debe lograr cada característica.

Para los desarrolladores empresariales acostumbrados a flujos de trabajo ágiles, la especificación sirve para el mismo propósito que los casos detallados de usuario y los criterios de aceptación, pero con una estructura legible que los asistentes de IA pueden consumir directamente.

Estructura de especificación

GitHub Spec Kit organiza las especificaciones en secciones estandarizadas que abarcan el comportamiento funcional, los requisitos de calidad y los casos perimetrales.

Sección de resumen

Descripción concisa de la característica desde una perspectiva del usuario final. Esta sección debe responder a "¿Qué hace esta característica?" en una o dos oraciones.

Por ejemplo:

## 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.

El resumen proporciona contexto de alto nivel. Alguien que no esté familiarizado con el proyecto debe comprender el propósito de la característica después de leer esta sección.

Sección Casos de usuario

Breves descripciones narrativas de cómo interactúan los usuarios con la característica. Los casos de usuario capturan la intención y el valor en lugar de la implementación técnica.

Por ejemplo:

## 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.

Los casos de usuario ayudan a los asistentes a la inteligencia artificial a comprender las motivaciones humanas detrás de las características, lo que conduce a implementaciones más intuitivas.

Sección Criterios de aceptación

Condiciones específicas y verificables que deben ser verdaderas para que la característica se considere completa. Los criterios de aceptación forman una lista de comprobación para comprobar la implementación.

Por ejemplo:

## 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

Escribir criterios de aceptación como hechos observables. Evite instrucciones vagas como "el sistema responde"; en su lugar, especifique "LA API responde en un plazo de 200 ms".

Sección De requisitos funcionales

Descripciones detalladas del comportamiento del sistema. Los requisitos funcionales detallan cómo funciona la característica.

Por ejemplo:

## 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

Los requisitos funcionales proporcionan suficiente detalle para que la inteligencia artificial genere implementaciones adecuadas sin recetar la estructura exacta del código.

Sección Requisitos no funcionales

Atributos de calidad, como el rendimiento, la seguridad, la escalabilidad y el cumplimiento. Estos requisitos suelen hacer referencia a la constitución.

Por ejemplo:

## 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

Los requisitos no funcionales garantizan que el código generado por ia cumpla los estándares de calidad de la empresa, no solo la corrección funcional.

Sección Casos extremos

Escenarios inusuales, condiciones de error y comportamientos de límite. La documentación explícita de casos perimetrales impide que la inteligencia artificial realice suposiciones.

Por ejemplo:

## 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"

Pensar en casos perimetrales durante la especificación impide errores que de otro modo surgirían durante la implementación o las pruebas.

Creación de una especificación con el Kit de especificaciones de GitHub

Escribir especificaciones eficaces es más fácil con el comando del Kit de especificaciones de /speckit.specify GitHub.

GitHub Spec Kit genera borradores de especificación basados en descripciones de lenguaje natural, lo que acelera la creación de especificaciones al tiempo que mantiene una estructura coherente.

Invoque el comando especificar

Para crear una especificación:

  1. Abra su proyecto en Visual Studio Code.

  2. Abra GitHub Copilot Chat y, a continuación, inicie el comando /speckit.specify con un mensaje que describa la característica que desea crear.

    Por ejemplo:

    /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.

    En esta descripción se describe lo siguiente:

    • Qué: Cargar documentos PDF/DOCX
    • Where: Interfaz del panel web
    • Cómo: Almacenado en Azure Blob Storage
    • Quién: Usuarios con el rol de Colaborador
    • Restricciones: límite de 50 MB, tipos de archivo específicos
    • Experiencia del usuario: presentación del progreso, mensajes de error

GitHub Copilot genera un archivo estructurado spec.md basado en esta entrada, creando secciones para resumen, criterios de aceptación, requisitos y casos perimetrales.

Revisión de la especificación generada

Después de que GitHub Copilot genere la especificación, abra spec.md y compruebe lo siguiente:

  • Integridad: ¿La especificación cubre todos los requisitos que ha mencionado? Si especificó "solo PDF y DOCX", confirme que los criterios de aceptación enumeran esos tipos de archivo.

  • Precisión: ¿Son correctos los detalles? Si dijo un límite de 50 MB, compruebe que la especificación indica 50 MB, no un valor diferente.

  • Coherencia: ¿Se alinean diferentes secciones? Si el resumen menciona la presentación del progreso, los criterios de aceptación deben incluirlo.

  • Elementos que faltan: ¿Qué inferió o omitió GitHub Copilot? Revise los requisitos generados para ver si la inteligencia artificial ha realizado suposiciones con las que no está de acuerdo.

La especificación inicial es un punto de partida fuerte pero rara vez perfecto. Refínelo mediante clarificación.

Refinación de especificaciones con /speckit.clarify

El /speckit.clarify comando analiza la especificación e identifica ambigüedades, lagunas o suposiciones que requieren aclaración.

Asegurar la claridad de las especificaciones

Las ambigüedades de las especificaciones conducen a implementaciones incorrectas. Usa /speckit.clarify para destacar áreas poco claras.

Después de generar una especificación inicial:

  1. En GitHub Copilot Chat, ejecute:

    /speckit.clarify

  2. GitHub Copilot analiza spec.md y formula preguntas sobre detalles poco claros o que faltan

    Preguntas de aclaración de ejemplo:

    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?

Estas preguntas le ayudan a tomar decisiones sobre aspectos que podría haber perdido inicialmente.

Responder a preguntas de aclaración

Responda a cada pregunta con decisiones específicas:

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.

Después de que respondas, GitHub Copilot actualiza spec.md para incorporar tus decisiones:

  • Los criterios de aceptación son: "Los usuarios pueden descargar documentos subidos previamente".
  • Los requisitos funcionales incluyen la especificación del punto final de descarga.
  • Los casos límite incluyen: "Varios archivos con nombres idénticos distinguidos por la marca de tiempo de carga".
  • Nota sobre requisitos no funcionales: "El análisis de virus se ha pospuesto para una próxima versión".

Iterar hasta que se complete

Ejecute /speckit.clarify varias veces si es necesario. Cada iteración refina aún más la especificación:

  • Primer paso: brechas de funcionalidad principales.
  • Segundo paso: Detalles del caso extremo.
  • Tercer paso: Ajuste de requisitos no funcionales.

Detenga cuando GitHub Copilot no tenga más preguntas o solo pregunte sobre las características que desea aplazar.

Procedimientos recomendados para escribir especificaciones

Escribir especificaciones claras e inequívocas es clave para el desarrollo dirigido por especificaciones.

Ser específico y medible

Reemplace los términos imprecisos por valores precisos:

  • No: "Admite archivos grandes".

  • En su lugar: "Admite archivos de hasta 50 MB".

  • No: "Rendimiento rápido de carga".

  • En su lugar: "Las cargas de menos de 5 MB se completan en un plazo de 5 segundos en la conexión de 10 Mbps".

Los requisitos específicos permiten a la inteligencia artificial generar implementaciones que satisfagan sus necesidades reales.

Uso de terminología coherente

Defina los términos una vez y reutilícelas a lo largo de la especificación. Si los llama "documentos" en el resumen, no cambie a "archivos" ni "datos adjuntos" más adelante. La terminología incoherente confunde tanto a los seres humanos como a la inteligencia artificial.

En el caso de los proyectos internos de la empresa, use nombres oficiales de productos y terminología de los estándares de su organización.

Abordar el manejo de errores explícitamente

No suponga que la inteligencia artificial controla correctamente los errores. Especifique lo que ocurre cuando se produce un error en las operaciones:

  • "Si Azure Blob Storage no es accesible, se muestra un error: "No se puede conectar al servicio de almacenamiento. Inténtelo de nuevo más tarde".
  • "Si el usuario carece de rol necesario, devuelva HTTP 403 con un mensaje: "No tiene permiso para cargar documentos".

El control explícito de errores impide que la inteligencia artificial implemente mensajes de error genéricos que no ayuden a los usuarios.

Mantener el ámbito adecuado

Si una característica requiere más de 300 líneas para especificar, considere la posibilidad de dividirla en varias especificaciones:

  • En lugar de una especificación de "Sistema de administración de documentos".
  • Cree especificaciones independientes: "Carga de documentos", "Descarga de documentos", "Uso compartido de documentos" y "Búsqueda de documentos".

Las especificaciones más pequeñas son más fáciles de revisar, aclarar e implementar. También se alinean con las prácticas de entrega incremental.

Detalle "qué", no "cómo"

Las especificaciones definen requisitos, no implementaciones. Indique lo que debe hacer el sistema, no cómo codificarlo:

  • Especificación: "Almacenar archivos cargados en Azure Blob Storage".
  • No según la especificación: "Utilice el paquete NuGet Azure.Storage.Blobs con la clase BlobContainerClient".

Las decisiones de implementación pertenecen a la fase del plan. Sin embargo, si la constitución exige tecnologías específicas, hacer referencia a ellas en la especificación es adecuada.

Validar mediante marco de reglas

Antes de finalizar una especificación, compruebe que no entra en conflicto con los principios del proyecto:

  • El marco de reglas necesita la autenticación de Microsoft Entra ID → la especificación debe indicar Microsoft Entra ID, en lugar de una autenticación personalizada.
  • El marco de reglas exige una retención de auditoría de 90 días → la especificación debe incluir los requisitos de registro de la auditoría.
  • La Constitución limita el tamaño máximo del archivo a 50 MB → La especificación no puede requerir soporte para archivos de 1 GB.

Las incoherencias detectadas durante la especificación son mucho más baratas para corregir que después de la implementación.

La especificación completada se convierte en el contrato con GitHub Copilot. Al continuar con la fase de planeación, GitHub Copilot hace referencia a esta especificación para diseñar implementaciones técnicas que coincidan exactamente con sus requisitos. El tiempo invertido en especificaciones exhaustivas paga dividendos a lo largo del desarrollo.

Resumen

Escribir especificaciones eficaces es fundamental para el desarrollo impulsado por especificaciones exitoso. Una especificación bien estructurada actúa como fuente única de verdad, que guía la generación de código de IA y garantiza la alineación con los principios del proyecto. Utilizando los comandos /speckit.specify y /speckit.clarify del Kit de Especificaciones de GitHub, puede crear y refinar rápidamente especificaciones detalladas que cubren el comportamiento funcional, los atributos de calidad y los casos extremos. Los siguientes procedimientos recomendados en la escritura de especificaciones mejoran la claridad, reducen la ambigüedad y conducen a implementaciones que satisfacen las necesidades del usuario y los estándares empresariales.