Mejores Prácticas

Escribiendo Buenas Especificaciones

1. Sé Específico, No Ambiguo

Malo:

El usuario puede crear tareas fácilmente.

Bueno:

El usuario puede crear tareas mediante POST /todos
con título (requerido, 1-100 chars) y descripción
(opcional, max 500 chars).

2. Define Criterios de Aceptación Claros

Usa checkboxes verificables:

## Criterios de Aceptación
- [ ] Título vacío retorna 400
- [ ] Título > 100 chars retorna 400
- [ ] Creación exitosa retorna 201 + Todo
- [ ] Todo incluye id generado UUID

3. Documenta Casos Edge

## Casos Edge
- Título con solo espacios: Trim y validar vacío
- Descripción null vs undefined: Tratados igual
- ID inexistente: 404 con mensaje claro

4. Mantén Especificaciones Atómicas

Una spec por feature. Evita specs monolíticas.

Constitution Efectiva

Principios sobre Tecnologías

Malo:

Usar React 18.2.0

Bueno:

UI declarativa con estado predecible.
Framework: React (versión estable actual).

Restricciones Explícitas

Las restricciones previenen errores:

## Restricciones
- NO mutación directa de estado
- NO any en TypeScript
- NO console.log en producción
- NO dependencias sin tipos

Errores Comunes

1. Saltarse la Constitution

Problema: Sin constitution, cada spec puede contradecir a otras.

Solución: Siempre crear constitution primero.

2. Specs Demasiado Técnicas

Problema: Mezclar “qué” con “cómo”.

Malo:

Usar bcrypt con cost 12 para hashear.

Bueno en Spec:

Passwords almacenados de forma segura e irreversible.

Bueno en Plan:

Implementar con bcrypt, cost 12.

3. Tasks No Atómicas

Problema: Tasks que toman días o son ambiguas.

Malo:

- [ ] Implementar autenticación

Bueno:

- [ ] Crear User entity
- [ ] Crear AuthService interface
- [ ] Implementar RegisterUseCase
- [ ] Tests RegisterUseCase

4. Ignorar Refinamiento

Problema: Implementar specs incompletas.

Solución: Iterar specs hasta que estén claras.

specify → revisar → ajustar → specify → ...

Patrones de Integración

Con Git

# Branch por spec
git checkout -b spec/user-auth

# Commit constitution
git add .spec/constitution.md
git commit -m "spec: add project constitution"

# Commit spec
git add .spec/specs/
git commit -m "spec: user authentication requirements"

# Commit implementation
git add src/
git commit -m "feat: implement user authentication"

Con CI/CD

# .github/workflows/specs.yml
name: Validate Specs

on: [push]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check spec completeness
        run: |
          # Verificar que cada spec tiene plan
          # Verificar que cada plan tiene tasks

Con Code Review

1. PR de Spec: Revisar requisitos antes de codificar
2. PR de Plan: Revisar arquitectura antes de implementar
3. PR de Code: Verificar que código cumple spec

Checklist de Calidad

Antes de Implementar

• Constitution documenta stack completo
• Spec tiene criterios de aceptación
• Spec cubre casos de error
• Plan define interfaces claras
• Tasks son atómicas y verificables

Después de Implementar

• Código sigue constitution
• Todos los criterios de aceptación pasan
• Tests cubren casos documentados
• Specs actualizadas si hubo cambios

Recursos Adicionales

• Repositorio Spec-Kit
• Ejemplos de Specs

Conclusión

Spec-Kit transforma el desarrollo haciendo que las especificaciones sean ciudadanos de primera clase. Con práctica, el flujo spec→plan→tasks→implement se vuelve natural y produce código de mayor calidad.

← Volver al índice