Files

4.5 KiB

name, description
name description
sdd Flujo de desarrollo guiado por especificaciones (Spec-Driven Development) basado en los principios de ingeniería de software con IA y sintaxis EARS.

Skill: Spec-Driven Development (SDD)

Esta skill define el arnés metodológico innegociable para implementar, refactorizar o validar funcionalidades en admin-edu-space.

Principio Fundamental

La especificación manda: Ninguna línea de código de negocio se escribe si no está precedida por una especificación aprobada (spec.md), un plan técnico (plan.md) y una lista de tareas atómicas (tasks.md).


Flujo de Trabajo (7 Pasos)

1. Constitución (docs/constitution.md)
   ↓
2. Especificación (specs/NNN-nombre/spec.md)
   ↓
3. Clarificación (Revisión QA - detección de ambigüedades)
   ↓
4. Planificación (specs/NNN-nombre/plan.md)
   ↓
5. Desglose de Tareas (specs/NNN-nombre/tasks.md)
   ↓
6. Implementación (Tarea por tarea, Test-First)
   ↓
7. Validación (RF por RF + Criterios de Finalización)

Sintaxis EARS (Easy Approach to Requirements Syntax)

Todo Requisito Funcional (RF) debe redactarse usando exclusivamente una de las 5 estructuras EARS en español:

  1. Ubicuo (Comportamiento permanente):

    EL SISTEMA <comportamiento permanente>. Ejemplo: EL SISTEMA registrará en AuditLog toda modificación de asignación de aula.

  2. Basado en Eventos (Disparado por una acción):

    CUANDO <evento>, EL SISTEMA <respuesta>. Ejemplo: CUANDO el usuario confirme una reserva con conflicto físico, EL SISTEMA bloqueará la operación y retornará un error HTTP 409 con el detalle de la superposición.

  3. Basado en Estados (Activo mientras se cumpla una condición):

    MIENTRAS <estado>, EL SISTEMA <respuesta>. Ejemplo: MIENTRAS una comisión posea co-docencia activa registrada, EL SISTEMA permitirá la superposición horaria del docente auxiliar.

  4. No Deseado / Excepciones (Manejo de errores y límites):

    SI <condición no deseada>, ENTONCES EL SISTEMA <respuesta>. Ejemplo: SI la matrícula de la comisión supera el aforo máximo del aula, ENTONCES EL SISTEMA impedirá el guardado y alertará al operador de Bedelía.

  5. Opcional (Funcionalidad dependiente de configuración o rol):

    DONDE <característica opcional>, EL SISTEMA <respuesta>. Ejemplo: DONDE el usuario posea rol Bedelia o Admin, EL SISTEMA habilitará el botón de reasignación directa de aulas libres.


Reglas de Ejecución para Agentes

  1. No inventar: Si falta información o un caso de uso no está cubierto, detenerse y marcar [NECESITA ACLARACIÓN].
  2. Tareas pequeñas: Cada tarea en tasks.md debe tener una duración estimada de 20-30 minutos y contar con su criterio "Hecho cuando:".
  3. Test-First: En la lógica de backend, escribir primero el test en rojo antes de tocar el código de la solución.
  4. Validación RF por RF: Al finalizar, verificar cada RF de la especificación contra los tests y la interfaz gráfica.
  5. Tolerancia Cero a Errores de Código (@[current_problems]) (Principio 10 de la Constitución): Es estrictamente inadmisible declarar una tarea o spec como completada si persisten errores en la terminal o problemas de diagnóstico. Todos los errores de importación, narrowing de tipos, NoneType y linter deben ser resueltos antes de dar el veredicto de aprobación.
  6. Diseño Modular y Contratos Fuertes (Principio 11 de la Constitución): Toda nueva API o endpoint debe dividirse en 4 capas desacopladas (main.py, routers/, schemas/, storage.py), usar Pydantic (BaseModel + Field) para validar bodies y query params con tipado estricto, levantar HTTPException controladas (404/422/400) sin retornar null ante fallos, y documentarse automáticamente en Swagger UI (/docs). Las integraciones con modelos de lenguaje (LLMs) deben implementarse con clientes asíncronos httpx, timeouts generosos (600s), formato estándar de roles e integrarse con la pestaña de IA en Configuración Global.
  7. Memoria: Al completar cada fase o entrega, actualizar MEMORY.md.
  8. Bump de Versión, Git Push y Despliegue en Producción (Skill deploy): Conforme al Principio 9 de la Constitución, incrementar versión semántica (package.json, app.js, __init__.py, CHANGELOG.md), ejecutar git push origin dev al repositorio remoto y desplegar en producción al servidor institucional LXC (10.0.0.217) utilizando las credenciales de .credenciales.