Addy Osmani publica una guía exhaustiva sobre cómo redactar especificaciones eficaces para agentes de codificación de IA, abordando el problema central de que las especificaciones masivas provocan sobrecarga de contexto y degradan el rendimiento del modelo.
El primer principio aboga por partir de una visión de alto nivel en lugar de sobreingeniería desde el inicio. El uso de Plan Mode (Shift+Tab en Claude Code) permite una exploración de solo lectura antes de la generación de código. El agente elabora después los detalles en un archivo SPEC.md persistente para mantener la coherencia entre sesiones.
El segundo principio estructura las especificaciones como PRD profesionales que cubren seis áreas esenciales: comandos ejecutables con flags, procedimientos de prueba, estructura explícita del proyecto, ejemplos de estilo de código, flujo de trabajo git y límites claros. Osmani propone un sistema de restricciones de tres niveles: "Always do" (acciones seguras), "Ask first" (cambios de alto impacto), "Never do" (bloqueos absolutos, como confirmar secretos en un commit).
El tercer principio divide el trabajo en tareas modulares. La investigación revela una "maldición de las instrucciones" en la que demasiadas instrucciones simultáneas reducen significativamente la adherencia del modelo. Las soluciones incluyen archivos de especificación separados (SPEC_backend.md, SPEC_frontend.md), subagentes especializados y agentes en paralelo para trabajo sin solapamiento.
El cuarto principio integra la autoverificación. El patrón "LLM-as-a-Judge" utiliza un segundo agente para verificar la adherencia al estilo y a la arquitectura. Las pruebas de conformidad YAML sirven como contratos independientes del lenguaje. La experiencia de dominio debe incluirse explícitamente: preferencias, trampas específicas de bibliotecas, formatos esperados.
El quinto principio trata las especificaciones como documentos vivos versionados junto con el código. El ciclo continuo prueba tras cada hito, retroalimenta los fallos en el siguiente prompt y actualiza el documento cuando los supuestos resultan incompletos.
Osmani advierte sobre errores frecuentes: especificaciones demasiado vagas (el modo de fallo dominante según el estudio de GitHub), omitir la revisión humana porque las pruebas pasan, y confundir el rápido "vibe coding" con la ingeniería de producción. Identifica una "trifecta letal": velocidad (difícil de revisar), no determinismo (resultados inconsistentes) y coste (fomenta atajos).
La metáfora central compara a los agentes de IA con "pasantes competentes" que requieren instrucciones claras, contexto relevante y retroalimentación accionable. El éxito depende de equilibrar especificaciones completas con ventanas de contexto enfocadas.