erick:~$ cat bienvenido.md
Inicio chevron_right Flujos de IA chevron_right Spec-Driven Development (SDD) en Frappe: Desarrollo Seguro y Documentado con OpenSpec

Spec-Driven Development (SDD) en Frappe: Desarrollo Seguro y Documentado con OpenSpec

ERPNext Flujos de IA 4 jun 2026 • 5 min de lectura

En el desarrollo de software moderno, y especialmente al integrar Inteligencia Artificial en nuestro flujo de trabajo, existe una tentación muy grande: escribir código de inmediato. En entornos robustos y de rápido crecimiento como Frappe y ERPNext, programar sin un plano claro es una receta para el desastre técnico. Las personalizaciones terminan acopladas al núcleo, las validaciones fallan y la deuda técnica se dispara.

La solución para estructurar desarrollos limpios, predecibles y 100% documentados es el Desarrollo Guiado por Especificaciones (Spec-Driven Development o SDD).

¿Qué es Spec-Driven Development (SDD)?

SDD es una metodología de trabajo que invierte el flujo clásico de desarrollo. En lugar de saltar directamente a la implementación técnica, el programador (o el agente de IA) debe definir y aprobar una especificación detallada del comportamiento deseado antes de tocar una sola línea de código.

El Gran Beneficio: Documentación por Diseño

En el desarrollo tradicional, la documentación es algo que “se hace al final” (y que, sinceramente, casi nunca se termina haciendo). Con SDD, la especificación es el prerrequisito para programar.

[!IMPORTANT] El principal beneficio de SDD: Todo cambio en el sistema queda documentado y justificado desde su origen. La especificación técnica no es un archivo estático en un PDF olvidado; es la fuente de verdad que guía los tests, el diseño de la base de datos y la codificación. Si la especificación cambia, se actualiza el documento antes de modificar el código.

El Rol de OpenSpec

OpenSpec es un estándar abierto para definir especificaciones técnicas que tanto los desarrolladores humanos como las herramientas de IA pueden entender sin ambigüedades. Estructura el ciclo de vida de cualquier cambio en fases lógicas muy claras:

graph TD
    A[Propuesta / Proposal] --> B[Especificación / Spec]
    B --> C[Diseño Técnico / Design]
    C --> D[Tareas / Tasks]
    D --> E[Aplicación / Apply]
    E --> F[Verificación / Verify]
    F --> G[Archivo / Archive]
    style B fill:#5af0b3,stroke:#3c4a42,stroke-width:2px,color:#000
  1. Propuesta (Proposal): Se define la intención, el alcance y el problema a resolver.
  2. Especificación (Spec): El comportamiento funcional esperado y los escenarios de uso (Gherkin: Dado/Cuando/Entonces).
  3. Diseño (Design): Esquema de base de datos, hooks de Frappe, controladores y seguridad.
  4. Tareas (Tasks): Desglose atómico de las tareas de programación.
  5. Aplicación (Apply): Escritura real del código (siguiendo estrictamente las tareas).
  6. Verificación (Verify): Pruebas automatizadas y manuales contra los escenarios de la especificación.
  7. Archivo (Archive): Cierre del ciclo y consolidación de la documentación técnica.

Aplicando SDD en Frappe Framework

Frappe es un framework guiado por metadatos (Doctypes). Esto lo hace ideal para SDD, ya que un Doctype define una especificación de datos estructurada.

Ejemplo Práctico: Control de Límite de Crédito de Clientes

Supongamos que necesitamos crear una funcionalidad en Frappe para validar el límite de crédito de un cliente antes de permitir que se guarde una Orden de Venta (Sales Order). Si el límite se supera, el sistema debe bloquear el guardado y registrar la incidencia en un Doctype personalizado llamado Credit Limit Audit.

Para desarrollar esta funcionalidad con SDD, no creamos el Doctype ni escribimos el script de inmediato. Seguimos este flujo:

  1. Escribir la Spec (credit_limit.spec.md): Definimos los escenarios de negocio de forma clara. Por ejemplo:
    • Escenario 1: Cliente con crédito disponible. Al guardar un Sales Order de 1,000 USD para un cliente con límite de 5,000 USD y saldo actual de 2,000 USD, la orden se guarda correctamente.
    • Escenario 2: Cliente que supera el límite. Al intentar guardar un Sales Order de 4,000 USD para el mismo cliente, el sistema lanza una excepción de validación y bloquea la transacción.
  2. Escribir el Diseño Técnico (credit_limit.design.md): Definimos qué herramientas de Frappe usaremos:
    • Un hook en before_save para la validación (vía apps/mi_app_personalizada/mi_app_personalizada/hooks.py).
    • Un Doctype personalizado Credit Limit Audit en nuestra app externa.
    • Preservar el núcleo: ¡nunca alterar directamente apps/erpnext!

Prompt de Referencia para Trabajar con Agentes de IA en SDD

A continuación, tienes el prompt de sistema optimizado que puedes copiar y pasarle a un agente de IA de codificación (o utilizar en tu propio entorno) para asegurarte de que ejecute cualquier cambio en tus aplicaciones de Frappe siguiendo la metodología SDD de forma estricta.

Estás actuando como un Senior Architect especialista en Frappe Framework y metodologías Spec-Driven Development (SDD). Tu objetivo es guiar e implementar cambios técnicos de forma estructurada, garantizando que el núcleo de ERPNext/Frappe permanezca intacto y que toda modificación quede 100% documentada.

Para cualquier funcionalidad solicitada, debes aplicar obligatoriamente el flujo SDD antes de escribir código.

### FASE 1: RESEARCH Y ESPECIFICACIÓN (ANTES DE CODIFICAR)
1. Analiza los requerimientos del usuario y crea un documento de Propuesta y Especificación en formato Markdown.
2. Define los escenarios funcionales detallados (utilizando la estructura Dado/Cuando/Entonces).
3. Documenta el diseño de base de datos requerido (Doctypes de Frappe involucrados, campos necesarios, permisos de usuario y hooks de eventos).
4. Presenta la propuesta al usuario y detente para solicitar su aprobación. NO implementes nada hasta recibir luz verde sobre la especificación.

### FASE 2: PLAN DE EJECUCIÓN (TASKS)
1. Una vez aprobada la especificación, desglosa el trabajo en tareas atómicas y secuenciales en un checklist (por ejemplo, en un archivo `task.md` o equivalente).
2. Estructura el plan separando los cambios en:
   - Definición de Doctypes (archivos JSON de metadatos de Frappe).
   - Server Scripts / Python Controllers (siempre dentro de tu app personalizada).
   - Client Scripts / JavaScript (archivos en la carpeta pública o a nivel de vista).
   - Modificaciones de hooks (`hooks.py` de tu app).

### FASE 3: APLICACIÓN E IMPLANTACIÓN (APPLY)
1. Sigue el orden de dependencias de tu checklist.
2. Escribe código modular, autodocumentado y con manejo robusto de excepciones (utilizando `frappe.throw` con traducciones integradas en español mediante `_("Mensaje")`).
3. Asegúrate de que las traducciones personalizadas se guarden en el archivo `.csv` de traducción de tu app personalizada.

### FASE 4: VERIFICACIÓN (VERIFY)
1. Para cada escenario definido en la fase 1, describe cómo probar que funciona correctamente en un entorno local de desarrollo.
2. Genera los scripts de prueba automatizados en Python (unittest de Frappe) si el proyecto cuenta con infraestructura de tests configurada.
3. Documenta los resultados de las pruebas en un reporte final antes de finalizar.

Conclusión

El uso de SDD y herramientas como OpenSpec eleva drásticamente el estándar técnico de cualquier desarrollo. Al forzar la definición del “qué” antes de la construcción del “cómo”, no solo reducimos el tiempo de depuración, sino que garantizamos un software limpio, mantenible y libre de acoplamientos innecesarios con el core de Frappe. La documentación deja de ser una tarea pendiente para convertirse en la base del éxito del proyecto.