Cómo escribir especificaciones efectivas para agentes de IA - Addy Osmani

• Lo que marca la mayor diferencia en la productividad de los agentes de IA → un SPEC claro y estructurado
• Un SPEC malo = ambigüedad → deriva de la IA, fallos repetidos y exceso de contexto
• Un buen SPEC = un documento vivo (SPEC.md) + actualizaciones continuas

Componentes clave de un buen SPEC

• Objetivo / visión (por qué se construye y para quién)
• Lista de funciones + prioridades
• Stack tecnológico (React 18 + TS, Node 20, etc., de forma específica)
• Comandos de ejecución (npm test, lint, build, etc.)
• Criterios de prueba (qué pruebas deben correr para considerarse exitoso)
• Estructura de código / guía de estilo
• Flujo de trabajo de Git (reglas de ramas, mensajes de commit)
• Definición de límites (✅ siempre / ⚠️ preguntar / 🚫 nunca hacerlo)

Patrón efectivo para el prompt inicial

• “Draft a detailed specification for … covering objectives, features, constraints, step-by-step plan”
• Primero Plan Mode → hacer que la IA redacte un borrador del SPEC
• Después, dividirlo en tareas pequeñas e ir dando instrucciones

Consejos prácticos (solo lo esencial)

• Mantener SPEC.md como archivo separado → incluir solo las secciones relevantes en cada tarea
• Modularizar + separar subtareas
• Después de cada tarea, ejecutar pruebas automáticas + verificar cumplimiento del SPEC
• Dejar claras las 3 capas de reglas de límites (Always / Ask / Never)