Checklist de producción para agentes de IA

Audita cómo este proyecto gestiona la ventana de contexto del agente. ¿Existe alguna medición de cuánto contexto está ocupado durante una sesión, y algún mecanismo que compacte o resuma el historial antes de llegar a un umbral (~40 %)? ¿O simplemente se deja crecer hasta que el proveedor corta? Lista dónde se acumula contexto sin control y propón un punto concreto donde medir la ocupación y disparar la compactación.

Audita dónde vive el estado de larga duración de este agente. ¿Los datos que no caben en contexto (historial extenso, ficheros del proyecto, resultados previos) están en disco o base de datos y el agente los consulta cuando los necesita? ¿O se intenta mantener todo en el prompt? Lista qué información se arrastra en contexto pudiendo estar fuera, y propón cómo externalizarla y recuperarla bajo demanda.

Audita cómo se lanzan los subagentes en este proyecto. Cuando el orquestador delega una tarea, ¿el subagente recibe solo el contexto mínimo que necesita para esa tarea concreta, o hereda todo el historial del orquestador? Lista los puntos donde se delega trabajo y, para cada uno, indica qué contexto se está pasando de más y propón el subconjunto mínimo que debería recibir.

Audita qué pasa con las respuestas largas de las herramientas en este agente. Cuando una herramienta devuelve un output extenso (un dump de logs, una respuesta de API, el contenido de un fichero), ¿ese texto se resume o se descarta del historial una vez usado, o permanece entero para siempre? Lista las herramientas que devuelven respuestas grandes y propón, para cada una, cómo resumir o purgar su output tras su uso.

Audita si este proyecto tiene una estrategia explícita para sesiones largas del agente. ¿Hay compaction, notas externas, checkpoints o algún plan deliberado para tareas que duran horas, o se asume que "la ventana es lo bastante grande"? Describe qué pasaría en una sesión de varias horas con el diseño actual y propón una estrategia concreta de gestión de contexto para esos casos.

Audita la calidad del contexto que recibe este agente. ¿El prompt de sistema y los datos que se le pasan están curados —lo justo, de alta señal y relevante—, o se vuelca documentación, ficheros y ejemplos "por si acaso"? Lista qué partes del contexto aportan poco o nada a la tarea típica del agente y propón qué recortar para subir la relación señal/ruido.

Audita las definiciones de herramientas de este agente. Para cada herramienta, ¿el nombre y la descripción dejan claro sin ambigüedad qué hace, cuándo usarla y qué espera de parámetros? Lista las herramientas con nombres genéricos, descripciones vagas o solapamiento de propósito que un modelo podría confundir, y propón un nombre y una descripción mejores para cada una.

Audita el inventario de herramientas de este agente. ¿Hay herramientas que se solapan en propósito o que casi nunca se usan? Revisa, si es posible, qué herramientas se invocan en la práctica y cuáles no. Lista las candidatas a eliminar o fusionar y, para cada una, explica por qué sobra y qué herramienta cubriría su función.

Audita los mensajes de error que devuelven las herramientas de este agente. Cuando una herramienta falla, ¿el error explica qué pasó y qué hacer para arreglarlo, o devuelve un traceback crudo o un código sin contexto? Lista las herramientas cuyos errores no son accionables y, para cada una, propón un mensaje de error que un LLM pueda leer y usar para corregirse.

Audita las herramientas peligrosas de este agente: las que escriben, borran, envían o gastan dinero. ¿Están detrás de un mecanismo de confirmación, un sistema de permisos o un dry-run, o el agente las ejecuta directamente? Lista todas las herramientas con efectos irreversibles y, para cada una, indica si tiene freno y propón uno si no lo tiene.

Audita si en este proyecto se ha medido el efecto del número de herramientas sobre el rendimiento del agente. ¿Se ha probado quitar herramientas y comparar resultados, o se asume que más herramientas es mejor? Identifica herramientas candidatas a retirar y propón un experimento concreto: qué quitar, qué métrica observar y cómo comparar antes y después.

Audita si este agente puede ejecutar código para resolver tareas que no estaban previstas con herramientas a medida. ¿Tiene acceso a un entorno de ejecución (un sandbox, un intérprete) y ese entorno está aislado del sistema real? Indica si la capacidad existe, si el aislamiento es seguro, y propón cómo añadir o reforzar la ejecución de código en un entorno seguro.

Audita este proyecto. Cuando el agente de IA completa una tarea, ¿existe un mecanismo que verifique de forma objetiva que el trabajo está bien —tests que se ejecutan de verdad, comprobación del build, validación del output—, o el agente simplemente declara que ha terminado? Lista las áreas que se dan por completadas sin verificación automática y, para cada una, propón una comprobación concreta y dónde añadirla.

Audita los sensores deterministas de este proyecto. ¿Existen linters, type-checks y tests que corren de forma rápida y automática antes de integrar un cambio? ¿Están conectados al flujo del agente? Lista qué controles deterministas faltan o no se ejecutan antes de integrar y propón cuáles añadir y en qué punto del flujo dispararlos.

Audita los mensajes que producen los sensores de este proyecto (linters, type-checks, tests). Cuando fallan, ¿el mensaje está redactado para que un LLM lo entienda y se autocorrija —dice qué regla se incumple y cómo arreglarlo—, o es críptico? Lista los sensores cuyo output no es apto para que un agente lo consuma y propón cómo mejorar sus mensajes.

Audita dónde viven las guías del agente en este proyecto: CLAUDE.md, convenciones de código, documentación de arquitectura, reglas del proyecto. ¿Están versionadas en el repositorio y actualizadas, o viven en la cabeza de alguien, en un chat o desactualizadas? Lista qué conocimiento que el agente debería tener no está en el repo y propón qué documentar y dónde.

Audita dónde hay revisión —humana o de otro agente— en este proyecto. Identifica los puntos donde un fallo silencioso del agente saldría caro (cambios en producción, migraciones, comunicación con clientes, gasto). Para cada uno, indica si existe una revisión antes de que el efecto sea irreversible y, si no, propón qué tipo de revisión añadir.

Audita cómo se reparten los controles de calidad en el tiempo en este proyecto. ¿Se distingue entre controles baratos y rápidos (linters, type-checks, unit tests) que corren antes de integrar y controles caros y lentos (e2e, integración, evals) que corren después en el pipeline? Lista controles mal ubicados —caros corriendo demasiado pronto o baratos demasiado tarde— y propón dónde debería ir cada uno.

Audita este agente buscando la "lethal trifecta": acceso a datos privados, exposición a contenido no confiable (web, emails, documentos de terceros) y capacidad de comunicar al exterior. ¿Coinciden las tres en algún flujo? Para cada flujo donde se junten, explica el riesgo de exfiltración y propón cuál de los tres elementos romper para cerrar la combinación.

Audita con qué identidad y permisos actúa este agente. ¿Opera con la identidad del usuario concreto que hizo la petición y solo con sus permisos, o usa una cuenta de servicio con acceso total a todos los datos? Lista los puntos donde el agente accede a recursos con más privilegios de los que el usuario tendría y propón cómo restringirlo a la identidad correcta.

Audita cómo trata este agente el contenido no confiable: páginas web, emails, documentos de terceros, entradas de usuario. ¿Ese contenido se trata como datos a procesar, o puede acabar interpretado como instrucciones de confianza por el modelo? Lista los puntos donde contenido externo entra en el prompt sin separación clara y propón cómo delimitarlo y marcarlo como no confiable.

Audita dónde se ejecuta el código que este agente genera o lanza. ¿Corre en un sandbox aislado —contenedor efímero, microVM— sin acceso al sistema real, o se ejecuta en el mismo entorno que el servicio? Indica qué tendría acceso un script malicioso generado por el agente en el diseño actual y propón cómo aislar la ejecución.

Audita las credenciales que usa este agente para acceder a recursos externos (bases de datos, APIs, servicios). Para cada una, ¿tiene solo los permisos que el agente realmente necesita —read-only donde solo lee—, o son credenciales amplias por comodidad? Lista las credenciales con más privilegios de los necesarios y propón el conjunto mínimo de permisos para cada caso.

Audita el código generado por IA en este proyecto en busca de fallos de seguridad típicos: secretos o credenciales hardcodeados, endpoints o rutas sin autenticación, queries a base de datos sin límite ni paginación, e inyección por concatenación de input. Lista cada hallazgo con su fichero y línea, explica el riesgo y propón el arreglo concreto.

Audita qué registra este agente de cada ejecución. ¿Se guardan las trazas de razonamiento, las llamadas a herramientas con sus argumentos y resultados, y las decisiones intermedias —o solo el resultado final? Lista qué partes del recorrido del agente no quedan registradas y propón qué loguear y en qué formato para poder depurar una ejecución después.

Audita cómo se mide el éxito de este agente. ¿La observabilidad distingue "ejecutó sin error" de "tomó la decisión correcta", o solo se vigilan excepciones y caídas? Indica si hay alguna forma de saber si el agente acierta cuando técnicamente "funciona" y propón cómo medir la corrección de las decisiones, no solo su ausencia de error.

Audita si en este proyecto se puede reconstruir, días después, qué hizo el agente en una ejecución concreta. ¿Se conservan las trazas, el input, el output y las versiones de prompt y modelo de cada ejecución, con retención suficiente? Indica qué falta para poder investigar un incidente reportado una semana después y propón cómo cerrar esos huecos.

Audita la visibilidad de coste de este proyecto. ¿Se puede saber cuánto cuesta cada acción, cada tarea o cada agente —en tokens y dinero—, o solo se ve la factura total del proveedor a fin de mes? Indica qué granularidad de coste falta y propón cómo instrumentar el coste por ejecución para poder atribuir el gasto.

Audita si este proyecto puede detectar la degradación gradual de calidad del agente —no las caídas duras, sino la deriva lenta. ¿Hay alguna métrica de calidad que se siga en el tiempo y permita ver una tendencia a peor? Indica qué se vigila hoy y qué no, y propón qué métricas seguir y cómo detectar la deriva antes de que sea grave.

Audita el sistema de alertas de este proyecto. ¿Hay alertas automáticas que avisan cuando el coste o la tasa de error se salen de lo normal, o las métricas solo se miran cuando alguien decide entrar al panel? Indica qué condiciones deberían disparar una alerta, si existen hoy, y propón qué alertas añadir y con qué umbrales.

Audita si este proyecto tiene un conjunto de evals propio que decida si el agente está listo para desplegar. ¿Existe un set de casos representativos con criterios de éxito, ejecutable de forma repetida? Indica si la decisión de desplegar hoy se basa en datos o en intuición, y propón cómo construir un eval set inicial a partir de las tareas reales del agente.

Audita si en este proyecto se hace error analysis: mirar trazas reales del agente una a una, etiquetar los fallos y agruparlos para encontrar los modos de fallo sistemáticos. Indica si ese proceso existe o solo se miran métricas agregadas, y propón cómo arrancar un error analysis: qué muestra de trazas revisar y cómo categorizar los fallos.

Audita cómo se evalúa este agente. ¿La evaluación mira solo si la respuesta final es correcta, o también la trayectoria —la secuencia de decisiones, llamadas a herramientas y pasos intermedios? Indica si un agente que acierta por mal camino pasaría hoy la evaluación y propón cómo evaluar también la calidad del proceso, no solo del resultado.

Audita cómo se gestionan en este proyecto los cambios de prompt, modelo o herramientas. ¿Se ejecuta el eval set antes y después de cada cambio para comparar el impacto, o los cambios se hacen y despliegan a ojo? Indica qué cambios recientes se hicieron sin medición y propón un proceso para evaluar antes y después de tocar prompt, modelo o herramienta.

Audita la resiliencia de las tareas largas de este agente. ¿Puede reanudar desde un checkpoint si se cae a mitad de una tarea, en vez de empezar de cero? ¿Tiene condiciones de parada explícitas —límite de pasos, de tiempo, de coste— para no quedarse en bucle? Indica qué falta de las dos cosas y propón cómo añadir checkpointing y límites de parada.

Audita la capacidad de rollback de este proyecto. Si una versión nueva del prompt o del modelo empeora el comportamiento del agente, ¿se puede volver a la versión anterior de forma rápida y controlada? Indica si los prompts y la versión de modelo están versionados y desplegables de forma independiente, y propón cómo habilitar un rollback rápido.