Addy Osmani publica una guía completa sobre cómo escribir especificaciones efectivas 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 recomienda comenzar con una visión de alto nivel en lugar de sobrediseñar desde el principio. 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. Luego, el agente elabora 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 ámbitos esenciales: comandos ejecutables con flags, procedimientos de prueba, estructura explícita del proyecto, ejemplos de estilo de código, flujo de trabajo de git y límites claros. Osmani propone un sistema de restricciones en tres niveles: "Always do" (acciones seguras), "Ask first" (cambios de alto impacto) y "Never do" (límites infranqueables, 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 directivas 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 trabajos que no se superponen.
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 la arquitectura. Las pruebas de conformidad en YAML sirven como contratos independientes del lenguaje. La experiencia de dominio debe incluirse explícitamente: preferencias, escollos específicos de bibliotecas, formatos esperados.
El quinto principio trata las especificaciones como documentos vivos, versionados junto con el código. El ciclo continuo prueba después de cada hito, retroalimenta los fallos al siguiente prompt y actualiza el documento cuando los supuestos resultan incompletos.
Osmani advierte contra errores comunes: 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 "vibe coding" rápido con la ingeniería de producción. Identifica una "trifecta letal": velocidad (difícil de revisar), no determinismo (resultados inconsistentes) y costo (fomenta atajos).
La metáfora central compara a los agentes de IA con "becarios competentes" que requieren instrucciones claras, contexto relevante y retroalimentación accionable. El éxito depende de equilibrar especificaciones completas con ventanas de contexto enfocadas.