Cómo escribir buenas especificaciones para agentes de IA

 (addyosmani.com)
110 puntos por GN⁺ 2026-01-19 | 3 comentarios | Compartir por WhatsApp
  • Si le lanzas una especificación enorme de una sola vez a un agente de código con IA, no va a funcionar bien; la clave está en escribir especificaciones inteligentes
  • Se recomienda presentar primero una visión de alto nivel y dejar que la IA amplíe el plan detallado; luego revisar ese plan en Plan Mode en modo de solo lectura y después pasar a la etapa de escritura de código
  • Según el análisis de más de 2,500 archivos de configuración de agentes en GitHub, una especificación efectiva incluye 6 áreas clave: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
  • En tareas grandes, para evitar una caída de calidad, es mejor dividir el trabajo en tareas pequeñas y modulares en vez de usar un prompt gigante, y proporcionar solo el contexto necesario para cada tarea
  • La clave de un flujo de desarrollo basado en especificaciones es incorporar en la spec límites de 3 niveles (Always/Ask first/Never), autoverificación y pruebas de adecuación, además de probar, iterar y hacerla evolucionar continuamente

TL;DR

  • Escribe una especificación clara que incluya el nivel adecuado de detalle (estructura, estilo, pruebas, límites, etc.)
  • Para tareas grandes, se recomienda dividir en unidades pequeñas en lugar de usar un solo prompt monolítico
  • El plan debe definirse primero en modo de solo lectura, y luego ejecutarse y mejorarse continuamente

Principio clave: escribir especificaciones inteligentes

  • El enfoque de simplemente arrojar una spec enorme a un agente de IA fracasa porque choca con las limitaciones de la ventana de contexto y con el presupuesto de atención (attention budget) del modelo
  • Una “smart spec” es un documento que guía al agente con claridad, se mantiene dentro de un tamaño de contexto práctico y evoluciona junto con el proyecto
  • Aquí se organiza en forma de framework un conjunto de principios extraídos de la experiencia usando agentes de código como Claude Code y Gemini CLI

Principio 1: da primero la visión general y deja que la IA redacte los detalles

  • En vez de intentar diseñarlo todo en exceso desde el principio, conviene empezar definiendo con claridad solo una declaración de objetivos y algunos requisitos clave
  • La idea es tratar esta spec inicial como un “product brief” y dejar que el agente, a partir de ella, amplíe y redacte una spec detallada
  • Los agentes basados en LLM suelen completar bien los detalles cuando las instrucciones de alto nivel son claras, pero si la misión es ambigua, tienden a desviarse con facilidad
  • Por eso, lo importante es dejar fijada desde el inicio una misión clara para que el agente no divague

  • Uso de Plan Mode

    • Plan Mode de Claude Code es un modo que mantiene al agente en solo lectura y lo limita a analizar el codebase y elaborar un plan detallado
    • Al entrar a Plan Mode con Shift+Tab y explicar “qué quieres construir”, el agente revisa el código existente y redacta un borrador de la spec
    • En ese momento también puedes pedirle que revise el plan en términos de arquitectura, buenas prácticas, riesgos de seguridad y estrategia de pruebas
    • Debes mantener Plan Mode hasta que el plan esté lo suficientemente depurado y sin margen de interpretación, y solo entonces salir de Plan Mode para pasar a la ejecución

  • Usar la spec como contexto

    • La spec confirmada se guarda en un archivo como SPEC.md, y al trabajar se vuelven a pasar al agente solo las secciones necesarias
    • Como el archivo de spec permanece entre sesiones, también sirve para mantener anclada a la IA al mismo punto de referencia cuando se retoma el proyecto
    • Esto ayuda a reducir el olvido que aparece cuando el historial de conversación se alarga o cuando se reinicia el agente
    • Igual que un equipo usa un PRD (documento de requisitos del producto) como referencia compartida, aquí cumple el rol de “documento fuente único” que consultan tanto humanos como IA

  • Mantener el enfoque en los objetivos

    • Una spec de alto nivel funciona mejor si, en lugar de describir desde el inicio cómo se implementará todo, se concentra en el what/why y deja el how concreto para después
    • Puede estructurarse como historias de usuario y criterios de aceptación: “¿Quién es el usuario? / ¿Qué necesita? / ¿Cómo se ve el éxito?”
    • En GitHub Spec Kit también se enfatiza este flujo: “dar una explicación de alto nivel sobre qué se está construyendo y por qué, y permitir que el agente de código genere especificaciones detalladas centradas en la experiencia de usuario y los criterios de éxito”

Principio 2: estructurar la especificación como un PRD profesional (o SRS)

  • Es importante tratar una especificación de IA no como una simple colección de notas, sino como un documento estructurado con secciones claras
  • Un formato integral y ordenado, como un PRD o un documento de diseño de sistemas, encaja especialmente bien con una IA que interpreta el contenido de forma literal
  • Según un análisis de más de 2,500 archivos de configuración de agentes en GitHub, las especificaciones efectivas incluyen en común 6 áreas clave

    • 1. Commands

      • Colocar los comandos ejecutables al principio del documento
      • No solo indicar el nombre de la herramienta, sino especificar el comando completo con flags incluidos: npm test, pytest -v, npm run build

    • 2. Testing

      • Indicar de forma específica cómo ejecutar las pruebas, qué framework se usa, dónde están los archivos de prueba y cuál es el nivel de cobertura esperado

    • 3. Project Structure

      • Diferenciar claramente la ubicación del código fuente, las pruebas y la documentación
      • Ejemplo: "src/ es para el código de la aplicación, tests/ para las pruebas unitarias y docs/ para la documentación"

    • 4. Code Style

      • En lugar de describir el estilo largamente, un solo snippet de código real es mucho más efectivo
      • Presentar también las reglas de naming, los criterios de formato y ejemplos del resultado deseado

    • 5. Git Workflow

      • Si se especifican las reglas de naming de ramas, el formato de los mensajes de commit y los requisitos de PR, el agente también seguirá ese flujo

    • 6. Boundaries

      • Definir con claridad las áreas que el agente no debe tocar bajo ninguna circunstancia
      • Secretos, directorios vendor, configuraciones de producción, carpetas específicas, etc.
      • En la investigación de GitHub, "nunca hacer commit de secretos" resultó ser la restricción útil más mencionada

  • Especificar la stack de forma concreta

    • En lugar de generalizar con algo como “proyecto React”, es importante escribir algo específico como “React 18 + TypeScript + Vite + Tailwind CSS”
    • También se deben incluir las versiones y las dependencias principales; una especificación ambigua termina produciendo código ambiguo

  • Usar un formato consistente

  • Integrar la especificación en la toolchain

    • Tratar la especificación no como un simple documento, sino como un “artefacto ejecutable” conectado al control de versiones y a CI/CD
    • GitHub Spec Kit usa un workflow de compuertas de 4 etapas que pone la especificación en el centro del proceso de ingeniería
      • Specify: proporcionar una descripción de alto nivel de qué se va a construir y por qué, y dejar que el agente de codificación genere la especificación detallada
      • Plan: establecer un plan técnico que incluya la stack deseada, la arquitectura y las restricciones
      • Tasks: dividir la especificación y el plan en unidades reales de trabajo, y descomponer cada una en tamaños comprobables
      • Implement: el agente de codificación procesa las tareas una por una o en paralelo

  • Personas especializadas mediante agents.md

    • En herramientas como GitHub Copilot, se pueden definir personas de agente especializadas
    • Es posible separar roles como @docs-agent (documentación técnica), @test-agent (QA) y @security-agent (revisión de código)
    • Cada archivo agents.md funciona como una especificación focalizada que contiene la forma de actuar, los comandos y los límites de esa persona

  • Diseño de Agent Experience (AX)

    • Así como una API se diseña pensando en la experiencia del desarrollador (DX), una especificación también debe diseñarse considerando la experiencia del agente (AX)
    • Es importante un formato limpio y fácil de parsear
      • El esquema OpenAPI de la API que usará el agente
      • Resúmenes de documentación para consumo de LLM (llms.txt)
      • Definiciones de tipos explícitas
    • Cuanto más siga una especificación estándares como MCP (Model Context Protocol), más estable será la comprensión y ejecución por parte del agente

  • Mantenerla como un documento vivo

    • La especificación no es un documento que se escribe una vez y se termina, sino que se actualiza continuamente cada vez que se toman decisiones con la IA o surgen nuevos hechos
    • En un workflow basado en especificaciones, la especificación guía la implementación, las pruebas y la descomposición de tareas, y no se pasa a la siguiente etapa hasta que la especificación quede validada
    • Esta especificación no es un documento solo para la IA, sino una herramienta clave para que los desarrolladores supervisen todo el flujo y verifiquen que los resultados de la IA realmente cumplan los requisitos

Principio 3: dividir las tareas en prompts y contexto modularizados

  • En lugar de meter todo en un solo prompt gigantesco, proporciona el contexto para que se concentre en una sola tarea a la vez
  • Si metes en un único prompt los requisitos, el código y las instrucciones de todo el proyecto, es más fácil que aumente la confusión
  • No solo existe el riesgo de chocar con el límite de tokens, sino que además la "maldición de las instrucciones" (curse of instructions) puede hacer que la capacidad de concentración del modelo caiga drásticamente

  • La maldición de las instrucciones

    • Según los resultados de investigación, mientras más instrucciones o datos se acumulan en el prompt, el desempeño para seguir cada instrucción con precisión disminuye de forma notable
    • Incluso modelos potentes como GPT-4 o Claude tienen dificultades cuando se les pide cumplir muchos requisitos al mismo tiempo
    • Por ejemplo, si se les dan 10 reglas detalladas en viñetas, tienden a cumplir solo las primeras y a ignorar cada vez más las que vienen después
    • Una mejor estrategia es la concentración iterativa: enfocarlo en un solo subproblema a la vez y, cuando termine, pasar al siguiente

  • Dividir la especificación en etapas o componentes

    • Si el documento de especificación es largo o abarca mucho, conviene considerar dividirlo en varias partes
    • Ejemplo: separar “Backend API Spec” y “Frontend UI Spec” en secciones distintas
    • Cuando se trabaja en el backend, no siempre hace falta incluir también la especificación del frontend
    • En un entorno multiagente, también se pueden asignar agentes separados o subprocesos por cada área
    • La guía de IA de DigitalOcean también advierte que “no mezcles una tarea de autenticación con cambios al esquema de base de datos en una sola vez”

  • TOC/resumen expandido para especificaciones grandes

    • Un método es hacer que el agente redacte primero un índice expandido (TOC) que resuma toda la especificación
    • Cada sección se comprime en algunos puntos clave o palabras clave, junto con referencias a dónde está el detalle
    • Ejemplo: “Security: usar HTTPS, proteger API keys, implementar validación de entradas (ver especificación completa §4.2)”
    • Si se crea este resumen jerárquico de antemano, el prompt puede conservar solo la visión general y entregar los detalles únicamente cuando hagan falta
    • El TOC expandido funciona como una especie de índice, permitiendo que el agente reconozca “ah, hay una sección de seguridad” y solicite esa parte
    • Este enfoque de resumen jerárquico ayuda a que el LLM mantenga una estructura de alto nivel

  • Uso de subagentes o “skills”

    • Como los subagentes (o “skills”) que menciona Anthropic, es posible usar múltiples agentes con roles separados
    • Cada subagente se configura para un área de especialidad específica y recibe solo la parte de la especificación correspondiente a esa área
    • Ejemplo: el subagente Database Designer solo conoce la sección del modelo de datos, y el subagente API Coder solo la especificación de endpoints de la API
    • Esto permite que cada agente tenga un contexto más pequeño y un rol más claro, lo que posibilita mejor precisión y trabajo en paralelo
    • Claude Code admite definir subagentes con su propio system prompt y herramientas

  • Agentes en paralelo para aumentar el throughput

    • Ejecutar varios agentes al mismo tiempo está emergiendo como la siguiente etapa de la productividad de los desarrolladores
    • En vez de esperar a que termine un agente, se asignan agentes en paralelo a tareas que no se superponen
    • Simon Willison describe esto como “aceptar a los agentes de codificación en paralelo”, y menciona que es sorprendentemente efectivo, aunque mentalmente bastante agotador
    • La clave es dividir con claridad el alcance de las tareas para que los agentes no interfieran entre sí
    • Frameworks de orquestación como LangGraph u OpenAI Swarm ayudan con esta coordinación, y
    • si se usa una base de datos vectorial como Chroma como memoria compartida, se puede acceder al contexto común sin repetir prompts

  • Agente único vs. multiagente: cuándo usar cada uno

    Aspecto Agente único Paralelo/multiagente
    Ventajas Configuración simple, bajo overhead y facilidad para depurar y seguir el flujo Mayor throughput, mejor manejo de interdependencias complejas y especialización por dominio
    Desventajas Sobrecarga de contexto en proyectos grandes, menor velocidad de iteración, punto único de falla Mayor costo de coordinación, posibilidad de conflictos, necesidad de memoria compartida
    Cuándo conviene Módulos aislados, proyectos pequeños o medianos, prototipado inicial Codebases grandes, separación entre codificación, testing y review, desarrollo de funcionalidades independientes
    Tip Usar resúmenes de especificación, actualizar el contexto por tarea, resetear sesiones con frecuencia Al inicio, limitarse a 2 o 3 agentes, compartir herramientas con MCP, aclarar bien los límites

  • Enfocar cada prompt en una sola tarea o sección

    • Incluso sin un entorno multiagente complejo, se puede forzar suficiente modularidad de forma manual
    • Ejemplo: después de escribir la especificación, en la etapa “Step 1: implementar el esquema de base de datos” se entrega solo la sección Database de la especificación
    • Cada vez que cambie la tarea principal, recompón el contexto para reducir distracciones causadas por información vieja o irrelevante
    • Algunas guías recomiendan iniciar una nueva sesión cuando se cambia de funcionalidad principal, para limpiar el contexto

  • Uso de instrucciones inline y TODO en el código

    • Un enfoque consiste en dejar en el código comentarios // TODO con lo que hay que hacer, y hacer que el agente los vaya completando uno por uno
    • Cada TODO funciona como una mini especificación para una tarea pequeña
    • Como resultado, la IA termina concentrándose en un alcance muy reducido, del tipo “implementa solo esta función según este fragmento de especificación”

Principio 4: incorporar autoevaluación, restricciones y experiencia humana

  • Trata la especificación no solo como una lista de tareas para el agente, sino como una guía para controlar la calidad, incorporando activamente tu propia experiencia
  • Una buena especificación anticipa dónde puede equivocarse la IA y coloca guardrails en esos puntos
  • Incluye conocimiento del dominio, casos límite y diversas “precauciones” para evitar que la IA opere en un vacío sin contexto
  • Es útil pensar en la especificación como el coach y árbitro de la IA: guía el enfoque correcto y frena de inmediato las acciones incorrectas
  • Según el análisis de GitHub de más de 2,500 archivos de agentes, las especificaciones más efectivas no usan solo una lista de prohibiciones, sino un sistema de límites de 3 niveles
    • Le indica claramente al agente cuándo puede seguir adelante tal cual, cuándo debe detenerse para preguntar y cuándo debe parar por completo

    • ✅ Always do (hacer siempre)

      • Tareas que debe ejecutar sin preguntar
      • Ej.: “ejecutar pruebas siempre antes de hacer commit”, “cumplir siempre con la convención de nombres de la guía de estilo”, “registrar siempre los errores en el servicio de monitoreo”

    • ⚠️ Ask first (preguntar primero)

      • Tareas que requieren aprobación humana
      • Ej.: “preguntar antes de modificar el esquema de la base de datos”, “preguntar antes de agregar una nueva dependencia”, “preguntar antes de cambiar la configuración de CI/CD”
      • Aunque técnicamente puedan ser posibles, aquí se filtran los cambios que requieren juicio humano por su amplio impacto

    • 🚫 Never do (nunca hacer)

      • Áreas con una detención total y explícita
      • Ej.: “nunca hacer commit de secretos ni API keys”, “nunca editar node_modules/ ni vendor/”, “no eliminar pruebas que fallen sin aprobación explícita”
      • La investigación también confirmó que “nunca hacer commit de secretos” fue una de las restricciones útiles más frecuentes

  • Fomentar la autoverificación

    • Guía al agente para que revise por sí mismo los resultados contra la especificación
    • Si las herramientas lo permiten, incluye en el flujo de trabajo la ejecución directa de pruebas unitarias o linting después de generar código
    • También se pueden dar instrucciones de reconfirmación a nivel de prompt
      • Ej.: “después de implementar, compara el resultado con la especificación, verifica que cumpla todos los requisitos y, si hay puntos no cumplidos, enuméralos”
    • Esto hace que el LLM contraste su propia salida con la especificación y reduce omisiones

  • LLM-as-a-Judge para verificaciones subjetivas

    • Para criterios difíciles de automatizar, como estilo de código, legibilidad o cumplimiento de patrones de arquitectura, usa el enfoque LLM-as-a-Judge
    • Un segundo agente (o un prompt separado) revisa la salida del primer agente según los criterios de calidad de la especificación
    • Ej.: “revisa si este código cumple nuestra guía de estilo y marca las infracciones”
    • El agente que hace de árbitro devuelve retroalimentación, que luego puede incorporarse o usarse como base para corregir

  • Pruebas de conformidad

    • Willison recomienda construir una suite de conformidad (conformance suite)
    • Funciona como un contrato independiente del lenguaje, a menudo basado en YAML, que toda implementación debe pasar obligatoriamente
    • Si estás creando una API, la suite de conformidad define entradas y salidas esperadas, y el código creado por el agente debe satisfacerlas todas
    • En la sección Success de la especificación, indica criterios como “debe pasar todos los casos de conformance/api-tests.yaml”

  • Usar pruebas en la especificación

    • Si es posible, incluye directamente un plan de pruebas o pruebas reales en la especificación y en el flujo del prompt
    • Como en TDD, los casos de prueba aclaran los requisitos
      • Ej.: en Success Criteria, “esta entrada de ejemplo debe generar obligatoriamente esta salida”
    • Willison describe una suite de pruebas robusta como algo que le da al agente prácticamente un superpoder
    • Porque permite validar de inmediato e iterar cuando una prueba falla
    • En una configuración con subagentes, incluso puede haber un agente de pruebas dedicado que reciba los criterios de la especificación y valide continuamente la salida del código

  • Reflejar conocimiento del dominio

    • La especificación debe incluir insights realistas que solo conocen desarrolladores con experiencia o personas que entienden el contexto
    • Ej.: al crear un agente para e-commerce, deja explícito que “products” y “categories” tienen una relación muchos a muchos
      • No esperes que la IA lo infiera por sí sola
    • Si una biblioteca específica es problemática, también conviene indicar las trampas o precauciones más comunes
    • Es una forma de plasmar tu mentoría dentro de la especificación
      • Ej.: “al usar la biblioteca X, la versión Y tiene problemas de fuga de memoria, así que aplica la solución alternativa Z”

  • Minimalismo para tareas simples

    • Aunque una especificación minuciosa es importante, parte de la experiencia consiste en saber cuándo conviene simplificar
    • En tareas relativamente simples y aisladas, una especificación excesiva puede generar más confusión
    • Ej.: para una tarea como “centrar un div en la página”
      • algo como “mantén la solución concisa y no agregues markup ni estilos innecesarios” puede ser suficiente
    • En cambio, una tarea compleja como “implementar un flujo OAuth con renovación de tokens y manejo de errores” sí requiere una especificación detallada
    • Una regla práctica es ajustar la densidad de la especificación al nivel de complejidad de la tarea

  • Mantener al humano como filtro final de calidad

    • La especificación delega autoridad al agente, pero la responsabilidad final por la calidad sigue siendo del desarrollador
    • Aunque el agente cumpla técnicamente la especificación, si el resultado no se siente correcto o no encaja con el contexto, confía en tu propio criterio
    • Si hace falta, también es natural volver a refinar la especificación o retocar directamente el resultado
    • Willison compara trabajar con agentes de IA con “una forma muy extraña de gestión” y dice que “se parece de manera incómodamente cercana a gestionar a un becario humano”
    • En última instancia, sigue siendo tarea del humano proporcionar instrucciones claras (la especificación), suficiente contexto y retroalimentación accionable

Principio 5: probar, iterar y hacer evolucionar la especificación (usar las herramientas correctas)

  • Considera la redacción de especificaciones y la construcción de agentes no como una tarea de una sola vez, sino como un bucle iterativo
    • Un flujo de probar rápido, recopilar retroalimentación, refinar la especificación y automatizar verificaciones con herramientas
  • La especificación inicial no es la versión final, sino el punto de partida del ciclo

  • Pruebas continuas

    • No esperes a que termine toda la implementación; realiza pruebas o revisiones manuales simples por hitos importantes o por función
    • Si detectas una falla, no sigas adelante tal cual; primero corrige la especificación o el prompt
    • Las pruebas automatizadas son especialmente efectivas y, si existen, puedes hacer que el agente ejecute directamente comandos como npm test
    • Usa el resultado fallido de la prueba tal cual como entrada del siguiente prompt
      • Ejemplo: “La salida no cumple la especificación en X, Y y Z, así que corrígela”
    • El bucle agéntico de código → prueba → corrección → repetición es una forma muy poderosa de trabajar

  • Iteración de la propia especificación

    • Si el agente malinterpretó algo o se hizo evidente que faltaban requisitos, no tapes el problema: primero corrige el documento de especificación
    • Vuelve a sincronizar explícitamente la especificación corregida con el agente
      • Ejemplo: “Actualicé la especificación de la siguiente manera. Ajusta el plan o refactoriza el código para reflejar este cambio”
    • Mantén siempre la especificación como fuente única de verdad
    • Si es posible, deja historial de versiones con mensajes de commit o notas para poder rastrear qué cambió y por qué

  • Gestión de contexto y uso de herramientas de memoria

    • El ecosistema de herramientas para ayudar con el contexto y la gestión del conocimiento de agentes de IA está creciendo rápidamente
    • Si aprovechas el patrón RAG (generación aumentada por recuperación), el agente puede traer al instante solo la información necesaria desde una base de conocimiento como una base de datos vectorial
    • Si la especificación es muy grande, puedes incrustar sus secciones y hacer que el agente recupere solo las partes más relevantes en vez de recibirla completa
    • Los frameworks basados en MCP (Model Context Protocol) proporcionan automáticamente el contexto adecuado para la tarea actual
    • Herramientas como Context7(context7.com) cargan automáticamente fragmentos relevantes desde la documentación según en qué estés trabajando

  • Paralelización con cuidado

    • Algunos desarrolladores aceleran el trabajo ejecutando varias instancias de agentes en paralelo sobre tareas distintas
    • Ejemplo: un agente genera código y otro escribe pruebas al mismo tiempo
    • Si eliges este enfoque, las tareas deben ser realmente independientes o estar claramente separadas para evitar conflictos
    • Ejemplo: limita que dos agentes modifiquen el mismo archivo al mismo tiempo
    • Para reducir la carga de gestión, al inicio es realista empezar con un máximo de 2 o 3 agentes

  • Control de versiones y bloqueo de la especificación

    • Haz un seguimiento cuidadoso del trabajo del agente con herramientas de control de versiones como Git
    • Cuanto más uses IA, más importante se vuelve tener buenos hábitos de control de versiones
    • Haz commit también del propio archivo de especificación en el repositorio para conservar el historial de cambios
    • El agente también puede leer git diff o blame y entender el contexto de los cambios
      • De hecho, los LLM son bastante buenos interpretando diff
    • Si la especificación está en el repo, tanto desarrolladores como IA pueden seguir juntos la evolución del proyecto
    • Willison dice que los modelos son “ferozmente competentes con Git”

  • Consideraciones de costo y velocidad

    • Las tareas que usan modelos grandes y contextos extensos pueden ser lentas y costosas
    • Separa estratégicamente la elección del modelo
      • Usa modelos rápidos y baratos para borradores iniciales o tareas repetitivas
      • Usa el modelo más capaz (y más caro) para la salida final o el razonamiento complejo
    • Ejemplo: deja GPT-4 o Claude para la planificación y las etapas clave, y delega expansiones simples o refactorizaciones a modelos locales o modelos API pequeños
    • Para un agente que ejecuta pruebas o un agente linter, un modelo relativamente pequeño suele ser suficiente
    • El tamaño del contexto también debe gestionarse

  • Monitorea y registra todo

    • En flujos de trabajo complejos con agentes, los logs de comportamiento y salida del agente son esenciales
    • Los logs permiten verificar si el agente se desvió de la intención o si ocurrió un error
    • Muchos frameworks ofrecen logs de trazas o permiten imprimir el proceso de razonamiento paso a paso
    • Al revisar los logs, se vuelve visible dónde se interpretó mal la especificación o la instrucción

  • Aprendizaje y mejora

    • Toma cada proyecto como una oportunidad de aprendizaje para pulir tu capacidad de escribir especificaciones
    • Puedes observar si ciertas expresiones confunden repetidamente a la IA o qué estructura de especificación se respeta mejor
    • Incorpora activamente esas lecciones en la siguiente especificación
    • El campo de los agentes de IA está evolucionando con rapidez, y siguen apareciendo nuevas herramientas y mejores prácticas

Evitar errores comunes

  • Tras analizar más de 2,500 archivos de agentes en GitHub, la principal causa de fracaso fue que las especificaciones y las instrucciones eran demasiado ambiguas

  • Prompts ambiguos

    • Solicitudes como “haz algo genial” o “haz que funcione mejor” dejan al agente sin criterios de evaluación
    • Debes especificar con la mayor claridad posible las entradas, salidas y restricciones
    • Asignaciones de rol generales como “eres un asistente de programación útil” casi no tienen efecto
    • En cambio, algo como “eres un ingeniero de pruebas que escribe tests para componentes React, sigues este ejemplo y nunca modificas el código fuente” funciona mucho mejor porque define rol, alcance y restricciones a la vez

  • Demasiado contexto sin resumen

    • Volcar un documento de 50 páginas completo en el prompt y esperar que el modelo lo entienda por sí solo casi siempre falla
    • Hace falta usar resumen jerárquico o RAG para exponer solo el contenido directamente relacionado con la tarea actual
    • Aumentar la longitud del contexto no compensa la falta de calidad del contexto

  • Saltarse la revisión humana

    • La regla personal de Willison: “No hago commit de código que no pueda explicarle a otra persona”
    • Que el agente haya producido algo que pasa las pruebas no significa automáticamente que ese código sea correcto, seguro y mantenible
    • En especial, los caminos críticos del código siempre deben revisarse manualmente
    • La metáfora de una “casa de naipes” encaja bien con el código generado por IA: puede verse sólido por fuera, pero colapsar en casos límite no probados

  • Confundir vibe coding con ingeniería de producción

    • El prototipado rápido con IA, el llamado “vibe coding”, es adecuado para etapas exploratorias o proyectos de una sola vez
    • Si despliegas ese resultado directamente a producción sin especificaciones estrictas, pruebas ni revisión, es muy probable que surjan problemas
    • Debes distinguir claramente entre “vibe coding” e “ingeniería asistida por IA”; esta última requiere la disciplina y los procesos descritos en esta guía
    • Es importante tener claro en qué modo estás trabajando en cada momento

  • Ignorar la “triple amenaza”

    • Las tres propiedades que, según advierte Willison, vuelven peligrosos a los agentes de IA
      • Velocidad: generan resultados más rápido de lo que una persona puede revisarlos
      • No determinismo: con la misma entrada, pueden producir salidas distintas en cada ejecución
      • Costo: empuja a usar atajos en vez de validar lo suficiente
    • La especificación y el proceso de revisión deben diseñarse teniendo en cuenta esas tres cosas
    • En particular, hace falta control consciente para que la velocidad no supere la capacidad de validación

  • Omitir las 6 áreas clave

    • Si la especificación no cubre Commands, Testing, Project Structure, Code Style, Git Workflow y Boundaries, es fácil que el agente pase por alto información importante para realizar la tarea
    • Antes de entregársela al agente, lo más seguro es revisarla una vez más con una lista de verificación de 6 áreas

Conclusión

  • Redactar especificaciones efectivas para agentes de codificación con IA requiere combinar principios sólidos de ingeniería de software con un enfoque ajustado a las características de los LLM
  • Todo comienza por definir con claridad el objetivo, y a partir de ahí repartir los roles para que la IA amplíe el plan y los detalles
  • La especificación no debe tratarse como una nota, sino como un documento de diseño serio, e incluir 6 áreas clave y manejarse como un artefacto ejecutable conectado con la toolchain
  • En lugar de entregar todo de una vez, conviene dividirlo por unidades de trabajo para mantener la concentración del agente
    (Un TOC resumido, subagentes y la orquestación en paralelo son medios prácticos para manejar especificaciones grandes)
  • Mediante límites de 3 niveles (Always / Ask first / Never), autoverificación y pruebas de adecuación, se pueden bloquear de antemano las trampas en las que la IA suele caer
  • La clave es tratar la especificación y la implementación no como resultados fijos, sino como un proceso iterativo, y seguir puliendo tanto la especificación como el código mediante pruebas y retroalimentación
  • Si se siguen estas pautas, se puede reducir notablemente la probabilidad de que un agente de IA pierda el rumbo en contextos extensos o derive en respuestas sin sentido

Lecturas relacionadas

3 comentarios

 
gomjellie 2026-01-22

Aunque es una traducción hecha por IA, hay una versión traducida al coreano, así que comparto el enlace.

https://rosetta.page/post/…
 
qor0923 2026-01-20

Gracias.
 
googol 2026-01-19

Personalmente, cuando desarrollé un proyecto con SDD (Specs Driven Development), al principio sentí una mejora clara en la productividad, pero como todavía no todo el código puede escribirse con base en especificaciones y cada vez que se necesita hacer una corrección manual hay que actualizar tanto el código como las especificaciones, terminé teniendo la experiencia de que la productividad más bien disminuía.