Tip 025: Añade un PITFALLS.md junto a cada SKILL.md

Cuando se trabaja con asistentes de inteligencia artificial en entornos profesionales, uno de los problemas más recurrentes es que el modelo repite errores que ya habían sido corregidos en sesiones anteriores. Esto ocurre porque las correcciones puntuales no quedan registradas de forma estructurada. La solución no está en sobrecargar el archivo de instrucciones principales, sino en crear un documento complementario que actúe como memoria de fallos. Este enfoque, que llamaremos archivo de lecciones aprendidas, permite que los agentes IA evolucionen con cada interacción sin perder el contexto de los errores pasados.

La idea es sencilla pero poderosa: junto a cada guía de habilidades o SKILL.md, se crea un archivo PITFALLS.md que recoge de forma concisa los errores típicos, sus desencadenantes y la conducta correcta. Este registro es acumulativo: nunca se eliminan entradas, solo se añaden nuevas. De esta forma, el sistema comienza cada sesión conociendo tanto el camino deseado como las trampas que debe evitar. Es una práctica que trasciende el ámbito de la inteligencia artificial y se asemeja a la documentación técnica de proyectos de software a medida, donde los casos de error se documentan por separado del flujo principal.

En el contexto empresarial, aplicar esta metodología tiene implicaciones directas en la eficiencia operativa. Por ejemplo, en desarrollos de aplicaciones a medida, los equipos que integran IA generativa pueden reducir drásticamente el tiempo dedicado a reexplicar correcciones. Cada vez que un agente comete un error, se registra el patrón en el archivo de fallos, y la próxima vez que se ejecute la tarea, el modelo ya contará con esa experiencia implícita. Esto es especialmente valioso cuando se trabaja con servicios cloud AWS y Azure, donde los entornos cambian con frecuencia y es fácil incurrir en configuraciones incorrectas si no hay un registro histórico de incidentes.

La separación entre el flujo ideal y los casos excepcionales no es solo una buena práctica de prompt engineering, sino un principio que también se aplica en ciberseguridad y en servicios inteligencia de negocio. Cuando se implementan paneles de power bi, por ejemplo, es habitual encontrarse con errores de transformación de datos que se repiten en cada actualización si no se documentan. Un archivo de fallos dedicado permite que el asistente de inteligencia artificial recuerde esas reglas sin ensuciar las instrucciones principales.

Desde una perspectiva técnica, este enfoque encaja perfectamente con la filosofía de separación de responsabilidades: la guía principal dice qué hacer, el archivo de fallos dice qué no hacer. Es como tener un blueprint y un registro de incidentes al lado. Para equipos que desarrollan ia para empresas, esta práctica acelera la iteración sobre los modelos y evita que el conocimiento tácito de los expertos se pierda cuando cambian los contextos de trabajo. Además, al mantener las instrucciones principales breves y centradas en el camino feliz, se facilita la revisión y el mantenimiento del sistema.

En Q2BSTUDIO aplicamos esta filosofía en nuestros proyectos de automatización de procesos y desarrollo de agentes IA. Sabemos que la inteligencia artificial solo es útil si aprende de sus errores de manera sistemática. Por eso, recomendamos a nuestros clientes que adopten este patrón documental no solo para prompts, sino para cualquier interacción repetitiva con sistemas de IA. La combinación de un SKILL.md enfocado y un PITFALLS.md vivo genera un ciclo de mejora continua que convierte cada fallo en una lección permanente.