🤖 Prototipado y agentes de IA
Los comandos de la familia 09: reducir la idea al mínimo comprobable, especificar antes de construir, diseñar el agente completo —prompt, herramientas, memoria— y evaluar antes de escalar.
🧪 /prototype + /MVP — lo mínimo comprobable
/prototype reduce la idea a artefacto mínimo capaz de validar la hipótesis crítica. /MVP elige el conjunto mínimo de capacidades que aporta valor real y genera aprendizaje. Ambos parten de la misma pregunta: ¿cuál es la hipótesis que, si resulta ser falsa, lo derrumba todo?
✓ Prototipo que valida
- ✓Hipótesis: «los consultores pagarían por una propuesta automática». Prototipo: generas 5 propuestas a mano y cobras R$ 50 por cada una, en 3 días.
- ✓MVP: generador con 1 plantilla, pago por link, soporte por WhatsApp. Nada más.
✗ Prototipo decorativo
- ✗Landing page bonita con "próximamente": prueba el diseño, no la disposición a pagar.
- ✗MVP con inicio de sesión, dashboard, 4 planes e integración con 3 herramientas, antes del primer cliente.
¿Nuevo por aquí? Hipótesis crítica es la suposición que, si es falsa, vuelve irrelevante todo lo demás. Por lo general, se refiere al comportamiento humano ("van a pagar", "van a volver"), no a la tecnología ("se puede construir"). Pruébala primero con el artefacto más rudimentario que funcione.
🎯 Copia y ejecuta
/prototype /MVP para <ideia>; declare a hipótese crítica, o menor artefato que a testa em até 1 semana, o que conta como validação (número), e depois o MVP com no máximo 3 capacidades e o que fica explicitamente fora
Cómo verificar: el prototipo cabe en una semana y la validación es un número («5 clientes de pago»). La lista de lo que «queda fuera» es más larga que la de lo que «entra».
📄 /spec — especifica requisitos y límites
Define requisitos, interfaces, comportamiento, límites, excepciones y criterios de aceptación. Es el contrato entre quien pide y quien construye — y, cuando quien construye es un agente de IA, es literalmente el prompt de construcción.
📐 Las seis partes de una spec
- •Requisitos: qué hace el sistema, en frases con «debe».
- •Interfaces: qué entra, qué sale, en qué formato.
- •Comportamiento: qué pasa en el camino feliz — paso a paso.
- •Límites y excepciones: qué pasa con una entrada no válida, un timeout o un dato ausente.
- •Criterios de aceptación: pruebas que, si se superan, cierran la discusión sobre «¿ya está listo?».
- •Fuera de alcance: qué NO hace este ciclo — por escrito, para que nadie «aproveche para incluirlo».
🎯 Copia y ejecuta
/spec para <funcionalidade ou sistema>; requisitos com "deve", interfaces de entrada/saída, comportamento no caminho feliz, 5 exceções com resposta esperada, critérios de aceitação testáveis e lista de fora-de-escopo
Cómo verificar: cada criterio de aceptación puede convertirse en una prueba automática o una verificación de 30 segundos; ninguno empieza con «debe ser intuitivo».
💡 Consejo práctico
Escribe los criterios de aceptación ANTES del comportamiento. Quien sabe cómo lo va a verificar describe mejor lo que quiere y descubre requisitos que faltaban.
🤖 /agent — diseña el agente completo
Define objetivo, herramientas, memoria, reglas, entradas, salidas, límites y evaluación. Ocho decisiones que, tomadas en conjunto, hacen que un agente sea confiable — y que, tomadas una a la vez a medida que aparecen los bugs, hacen que sea impredecible.
Ilustrativo: el núcleo es objetivo + prompt; los cuatro módulos alrededor son comandos propios; la base es /eval.
¿Nuevo por aquí? Agente es un sistema de IA que recibe un objetivo, decide qué herramientas usar, ejecuta acciones en secuencia y verifica el resultado, en vez de solo responder con texto. La diferencia con un chatbot es su capacidad para actuar e iterar sin instrucciones humanas en cada paso.
🎯 Copia y ejecuta
/agent para <tarefa que o agente vai cumprir>; objetivo em uma frase, entradas e saídas, ferramentas com quando usar cada uma, o que memoriza e o que esquece, regras invioláveis, limites de ação e como será avaliado
Cómo verificar: el objetivo cabe en una frase sin «y». Un agente con dos objetivos son dos agentes — o uno que hace mal ambas cosas.
⚠️ El agente que lo hace todo
La tentación es darle al agente acceso a todas las herramientas y «dejar que decida». El resultado es un sistema que nadie puede evaluar porque no hay un comportamiento esperado. Primero, un alcance acotado; amplíalo cuando pase el /eval.
📝 /prompt + /tools — prompt sólido y herramientas
/prompt especifica rol, objetivo, contexto, reglas, herramientas, formato y criterios de calidad. /tools asigna cada tarea a una herramienta y —la parte que todos se saltan— define cuándo no usar y cuándo escalar a una persona.
| Bloque del prompt | Qué evita | Ejemplo |
|---|---|---|
| Rol | Tono y profundidad aleatorios | "Eres el asistente de propuestas de |
| Reglas | Comportamiento inventado ante las excepciones | "Nunca informes el precio sin confirmar el plan del cliente" |
| Formato | Salida que nadie puede procesar | "Responde en JSON con los campos: titulo, items[], total" |
| Criterio de calidad | Agente satisfecho con una respuesta deficiente | "La propuesta está lista cuando todos los elementos tienen precio y plazo" |
Ejemplo didáctico: cada bloque existe para cerrar una puerta que el agente abriría por su cuenta.
🎯 Copia y ejecuta
/prompt /tools para <agente>; prompt completo com papel, objetivo, contexto, regras invioláveis, formato de saída e critério de qualidade; tabela de ferramentas com tarefa, quando usar, quando NÃO usar e quando escalar
Cómo verificar: la columna "cuándo NO usar" tiene contenido en cada fila. Una herramienta sin restricciones es una herramienta que se usará mal.
💡 Consejo práctico
Prueba el prompt con la peor entrada que se te ocurra antes de probarlo con la mejor. Si el agente se comporta bien con «haz cualquier cosa», se comportará bien con una solicitud clara.
🧠 /memory — memoria del sistema
Separa memoria de sesión, perfil, hechos persistentes, historial y política de actualización. La pregunta no es «¿el agente recuerda?», sino «¿qué recuerda, por cuánto tiempo y quién tiene poder para cambiarlo?».
Sesión: lo que desaparece al cerrar
Contexto de la conversación actual. Barato, descartable, nunca debe contener una decisión que deba perdurar.
Perfil y hechos persistentes: lo que perdura entre sesiones
Preferencias del usuario, datos confirmados, decisiones tomadas. Cada elemento con origen y fecha.
Política de actualización: quién escribe, quién borra
¿El agente puede agregar un hecho por su cuenta? ¿Necesita confirmación? ¿Los hechos prevalecen? Sin una política, la memoria acumula errores que parecen verdad.
¿Nuevo por aquí? Política de actualización es la regla que indica cuándo un hecho entra en la memoria, cuándo se reemplaza y cuándo vence. "El usuario dijo X una vez" y "el usuario confirmó X tres veces" merecen tratamientos distintos; la política es donde queda escrito.
🎯 Copia y ejecuta
/memory para <agente>; classifique o que ele precisa lembrar em sessão / perfil / fatos / histórico, defina formato e origem de cada item, política de atualização (quem escreve, quando expira) e o que NUNCA deve ser memorizado
Cómo verificar: la lista "nunca memorizar" existe e incluye al menos datos sensibles e inferencias no confirmadas.
🧫 /eval — evalúa antes de escalar
Define casos de prueba, criterios, métricas, fallas críticas y umbral de aprobación. Es la base del diseño de arriba: nada escala sin pasar por aquí — y «pasó» es un número, no una sensación.
✓ Eval que decide
- ✓30 casos reales (incluidos 8 que ya fallaron en producción), criterio para cada caso, umbral: 90% de aciertos y CERO fallas críticas.
- ✓Se ejecuta con cada cambio del prompt; el resultado se compara con la ejecución anterior.
✗ Eval de demostración
- ✗"Lo probé con unos 5 ejemplos y quedó bien."
- ✗Solo casos fáciles; ningún caso excepcional; ninguna falla clasificada como crítica, porque nadie pensó en qué podría serlo.
¿Nuevo por aquí? Falla crítica es el error que, aunque ocurra una vez entre cien, vuelve inviable el sistema: filtrar datos de otro cliente, ejecutar una acción irreversible sin autorización, inventar un precio. Los fallos críticos no entran en el promedio: anulan la aprobación.
🎯 Copia y ejecuta
/eval para <agente>; 20-40 casos de teste incluindo exceções e casos que já falharam, critério de acerto por caso, métricas agregadas, lista de falhas críticas (tolerância zero) e limiar de aprovação para escalar
Cómo verificar: existe una lista de fallas críticas separada de la métrica general, y el umbral de aprobación es un número que se decide antes de ejecutar.
📊 Por qué el 90% no es el número
El umbral depende del costo del error. Un agente que sugiere títulos para publicaciones puede equivocarse un 20% sin problema. Uno que envía propuestas con precios, no. Define el umbral según el costo del peor fallo común, no según un número redondo.
🛡️ /guardrails — límites, fallback, escalamiento
Crea reglas de seguridad, autorización, validación, fallback y escalamiento. El agente confiable no es el que nunca se equivoca: es el que, cuando no sabe, se detiene y pregunta en vez de improvisar.
🚧 Cinco capas de guardrail
- •Autorización: ¿qué acciones requieren confirmación humana (pagar, borrar, enviar al exterior)?
- •Validación de entrada: ¿qué hacer con una solicitud fuera del alcance o mal formada?
- •Validación de salida: ¿La respuesta pasa por una verificación antes de salir (formato, rango de valores, datos sensibles)?
- •Alternativa: cuando la herramienta falla o la confianza es baja, ¿cuál es el comportamiento predeterminado?
- •Escalamiento: ¿en qué condición el agente entrega el trabajo a una persona y a quién?
🎯 Copia y ejecuta
/guardrails para <agente>; ações que exigem autorização humana, validações de entrada e saída, comportamento de fallback por tipo de falha, condições de escalonamento com destinatário e o que registrar em log
Cómo verificar: toda acción irreversible está en la lista de autorización, y todo fallback tiene un comportamiento definido — nunca «vuelve a intentarlo hasta que funcione».
⚠️ Un guardrail en el prompt no es un guardrail
Una regla escrita solo en el prompt es una petición, no un límite — el modelo puede ignorarla. Un guardrail de verdad vive fuera del modelo: validación de código, permisos de herramientas, confirmación humana. El prompt avisa; la infraestructura lo impide.
🔌 /integrate — integraciones y sincronización
Mapea sistemas, APIs, autenticación, datos, eventos, errores y sincronización. Es el comando que transforma al agente que funciona en la demo en el agente que funciona el lunes, con el CRM real y la hoja de cálculo que alguien renombró.
| Dimensión | Pregunta | Error clásico |
|---|---|---|
| Autenticación | ¿Cómo demuestra el agente quién es ante cada sistema? | Token personal del desarrollador en producción |
| Datos | ¿Qué formato entra, cuál sale y quién es la fuente de la verdad? | Dos sistemas con el mismo campo y valores diferentes |
| Eventos | ¿Qué activa al agente: polling, webhook, agenda? | Consulta cada 10 segundos a una API con un límite de 100 llamadas/hora |
| Errores | ¿Qué pasa cuando la API responde 500 o tarda? | Reintento infinito que duplica solicitudes |
| Sincronización | ¿Quién gana cuando ambos lados cambiaron? | "El último que guardó" — borrando el trabajo de alguien |
Ejemplo didáctico: cada línea de la tabla ya fue un incidente en algún proyecto real.
🎯 Copia y ejecuta
/integrate para <agente> com <sistemas envolvidos>; para cada sistema: autenticação, dados de entrada/saída com fonte da verdade, gatilho (evento/polling/agenda), tratamento de erro com limite de retry e regra de sincronização em conflito
Cómo verificar: toda integración tiene una regla de conflicto y un límite de retry por escrito — y ninguna usa credenciales personales.
💡 Receta compuesta
Arquitectura de agente completa, directamente del documento: /agent /tools /memory /guardrails /eval /integrate. Observa el orden: eval antes de integrate — se evalúa en un entorno controlado antes de conectarlo con el mundo.
Autoverificación rápida (opcional): ¿por qué /eval va antes de /integrate en la receta de arquitectura de agentes?
🎓 Resumen del módulo
Próxima Ruta:
6.1 - Comunicación y aprendizaje — construyes y evalúas; ahora aprende a explicar, enseñar y adaptar el mensaje para quienes toman decisiones.