Agentes de IA: contexto y skills para evitar código genérico

Gerente Comercial de ACL powered by DataArt

Cuando una empresa incorpora agentes de IA al desarrollo, espera que sus equipos puedan avanzar con menos trabajo repetitivo. Pero esa expectativa se pone a prueba cuando hay que revisar lo que producen: ¿la propuesta utiliza los componentes existentes?, ¿respeta las reglas del negocio?, ¿se puede integrar sin rehacer buena parte del trabajo?

Un agente puede generar código que compile y supere una prueba aislada, pero que duplique una funcionalidad, utilice una integración obsoleta o interprete mal un permiso. Para una organización, ese resultado todavía representa trabajo pendiente.

El contexto entrega información sobre el proyecto. Las Skills organizan instrucciones y recursos reutilizables para realizar tareas concretas. Su utilidad está en orientar al agente con conocimiento pertinente y establecer qué debe comprobar antes de entregar una propuesta.

Desde una mirada de negocio, conviene evaluar ese recorrido completo. El tiempo de generación es solo una parte: también cuentan la revisión, las correcciones y el esfuerzo necesario para incorporar el resultado al sistema.

Por qué un agente sin contexto genera respuestas genéricas

Conocer un lenguaje de programación no equivale a conocer una aplicación. Un modelo puede manejar patrones habituales de desarrollo y desconocer las decisiones del equipo, las restricciones de una integración o los componentes que ya resuelven parte del problema.

Pensemos en un ejemplo ilustrativo: una empresa necesita añadir una consulta de solicitudes a su portal de clientes. Sin información del proyecto, el agente podría proponer un nuevo endpoint, un mecanismo de autenticación y una consulta directa a la base de datos.

Sin embargo, esa empresa podría disponer de un servicio que concentra la información, un componente de autorización obligatorio y un contrato de API utilizado por otros sistemas.

La propuesta debe evaluarse frente a esas condiciones. Una solución razonable en otro entorno puede requerir cambios importantes para funcionar en este.

Antes de atribuir el problema exclusivamente al modelo, conviene revisar qué información recibió, qué fuentes consultó y qué instrucciones debía seguir. También importa saber cómo comprobó su propuesta: una explicación convincente no demuestra que el cambio sea compatible con el proyecto.

Qué información necesita conocer

El contexto necesario depende de la tarea. Para modificar una validación puede bastar con revisar una regla, su implementación y sus pruebas. Para cambiar una integración harán falta contratos, dependencias y condiciones de operación.

Podemos organizar ese conocimiento en cuatro grupos:

Negocio: qué necesidad se atiende, quién utilizará la funcionalidad y qué reglas deben respetarse.
Sistema: dónde se implementará el cambio, qué componentes existen y qué dependencias podrían verse afectadas.
Forma de trabajo: qué estándares, convenciones y procedimientos utiliza el equipo.
Validación: qué condiciones debe cumplir el resultado y cómo se comprobarán.

La selección es importante. Dar acceso a más documentos no resuelve por sí solo las contradicciones entre ellos. Cada fuente debería tener un responsable y una referencia de versión o vigencia.

Si una regla sigue abierta, debe mantenerse como pregunta pendiente. Este trabajo comienza desde la definición de la necesidad, como explicamos en nuestra guía sobre cómo usar IA para definir requisitos de software.

Repositorios y arquitectura

El repositorio permite revisar cómo está implementado el sistema: módulos, dependencias, convenciones, pruebas y componentes compartidos.

Antes de proponer un cambio, conviene pedir al agente que identifique qué puede reutilizar. En el ejemplo del portal, eso significa localizar el servicio de solicitudes, el mecanismo de autorización y las pruebas existentes.

La documentación de arquitectura agrega información que el código puede no explicar por sí solo: límites entre servicios, decisiones de integración y restricciones de operación. Los registros de decisiones arquitectónicas ayudan a entender por qué se eligió una alternativa y qué condiciones justificaron esa elección.

También hay una precaución relevante: el código existente no siempre representa el estándar que la organización quiere mantener. Puede contener excepciones, deuda técnica o componentes que están siendo reemplazados.

Por eso, el contexto debe distinguir los patrones recomendados de las soluciones que requieren revisión. De lo contrario, el agente podría reproducir una práctica que el equipo busca abandonar.

Persona utilizando un celular junto a un computador portátil, con ilustraciones de un asistente virtual y conexión a la nube

Documentación de negocio

Expresiones como “cliente activo”, “solicitud cerrada” o “usuario autorizado” parecen claras hasta que distintas áreas las interpretan de manera diferente.

En el portal del ejemplo, “mis solicitudes” podría significar las creadas por una persona o todas las asociadas a su empresa. Esa diferencia afecta los permisos, las consultas y las pruebas.

La documentación de negocio debería ayudar a responder:

¿Quién puede realizar la operación?
¿Qué condiciones habilitan o impiden una acción?
¿Qué excepciones existen?
¿Cuál es el sistema de referencia para consultar la información?
¿Quién puede resolver una duda sobre la regla?

Si las fuentes no permiten responder, el agente debe señalar la incertidumbre. Completar el vacío con una suposición puede convertir una decisión pendiente en una funcionalidad que nadie pidió.

Para el equipo, mantener visible esa duda permite resolverla antes de que llegue al código y a las pruebas.

Estándares técnicos

Los estándares son más útiles cuando se expresan como instrucciones que pueden aplicarse y comprobarse.

“Escribir código mantenible” plantea una intención. Para orientar una tarea, hay que precisar cuestiones como la estructura de los módulos, el manejo de errores, las dependencias permitidas y las pruebas requeridas.

En lugar de indicar únicamente “seguir las convenciones del proyecto”, conviene entregar referencias concretas:

El componente que sirve como ejemplo.
La guía vigente.
Los comandos de validación.
Las situaciones que requieren una excepción.
El rol que puede aprobarla.

Cuando sea posible, estas instrucciones deben acompañarse de controles ejecutables: pruebas, análisis estático o validaciones del pipeline.

Esto permite revisar algo más que la explicación del agente. El equipo puede comprobar si el resultado satisface las condiciones acordadas y decidir qué necesita corregirse.

Qué es una Skill

Una Skill es un conjunto reutilizable de instrucciones y recursos que orienta a un agente para realizar una tarea específica.

En el formato abierto Agent Skills, se organiza en una carpeta con un archivo SKILL.md, que contiene metadatos e instrucciones. Puede incluir scripts, referencias y plantillas. Los agentes compatibles pueden cargar esos recursos cuando la tarea los requiere.

Con SPIREX®, las Skills incorporan criterios, estándares y contexto de negocio al trabajo del modelo. Entre los ejemplos que presentamos están criterios INVEST para historias de usuario, patrones de arquitectura y glosarios del negocio.

Una aplicación posible sería una Skill para modificar APIs. Podría indicar que el agente debe revisar el contrato vigente, identificar consumidores, reutilizar el mecanismo de autorización y ejecutar las pruebas correspondientes.

Este es un ejemplo ilustrativo. Para convertirlo en un recurso útil para un proyecto, habría que incorporar las referencias reales, definir cuándo se aplica y revisar sus comprobaciones.

Skills vs. prompts

Un prompt expresa una solicitud o instrucción. Una Skill permite organizar un procedimiento y sus recursos para reutilizarlos cuando sean pertinentes.

Ambos pueden trabajar juntos. Por ejemplo:

Añade la consulta de solicitudes del cliente y aplica el procedimiento de modificación de APIs del proyecto.

La solicitud define el cambio. La Skill aporta el procedimiento que debe seguirse.

Un prompt también puede guardarse, compartirse y versionarse. La diferencia práctica está en cómo se organiza el conocimiento: si cada persona debe reconstruir las instrucciones en una conversación o si el equipo dispone de un recurso compartido, identificable y revisable.

La Skill tampoco reemplaza el contexto de la tarea. Un procedimiento para modificar APIs todavía necesita conocer el servicio afectado, la versión del contrato y las reglas de negocio correspondientes.

Mano robótica bajo engranajes conectados, acompañada de iconos de verificación y control de procesos

Caso DataArt: una Skill compartida para Girls Who Code

Girls Who Code trabajó con DataArt para incorporar Claude Code a su proceso de desarrollo. Como parte de esa implementación, construyeron una Skill compartida con las reglas de ingeniería y las directrices del proyecto, acompañada de documentación de configuración para facilitar su uso consistente.

El programa incluyó una línea base, adopción por etapas y revisión humana antes de integrar código o ejecutar los casos de prueba generados por IA.

Según el caso publicado por DataArt, el tiempo promedio que un ticket permanecía en desarrollo activo pasó de aproximadamente siete días a tres días y medio, dentro de un programa de adopción de tres meses.

El resultado corresponde al conjunto de la implementación; no permite atribuir la mejora exclusivamente a la Skill. El caso muestra cómo las reglas del equipo pueden convertirse en un recurso compartido que acompaña el trabajo con IA. Es una experiencia de DataArt con Claude Code, independiente de SPIREX®.

Versionado y revisión del conocimiento

Una instrucción utilizada por varios agentes puede influir en múltiples entregas. Por eso, sus cambios necesitan revisión.

En la propuesta pública de SPIREX®, las Skills se versionan en Git, se revisan por pares y permiten fijar versiones por proyecto mediante skills.lock. Esto ayuda a identificar qué instrucciones se utilizan. Mantener una versión no implica que todas las respuestas del modelo vayan a ser idénticas.

Para gestionar ese conocimiento, conviene registrar:

El propósito de la Skill y cuándo debe utilizarse.
El responsable de mantenerla.
Las fuentes de referencia.
La versión y los cambios realizados.
Las pruebas utilizadas para revisarla.
La aprobación antes de incorporarla al flujo.

El alcance de la revisión debe corresponder al cambio. Corregir una errata y actualizar una regla de autorización requieren comprobaciones diferentes.

En el segundo caso, por ejemplo, habría que revisar escenarios de acceso permitido y denegado. También sería necesario identificar qué proyectos utilizan esa instrucción y cómo recibirán la actualización.

Esta gestión forma parte de la gobernanza de agentes de IA en el SDLC: las instrucciones que orientan al agente también necesitan responsables, versiones y evidencia de revisión.

Riesgos de contexto desactualizado

Una Skill puede estar bien redactada y apuntar a un servicio que ya fue reemplazado. El agente seguiría el procedimiento indicado, pero partiría de una referencia incorrecta.

También pueden aparecer conflictos entre un documento de negocio actualizado y una plantilla antigua, o entre una guía general y una excepción aprobada para un proyecto.

Para gestionar estas situaciones, conviene definir una fuente de referencia, un responsable que resuelva contradicciones y los cambios que obligan a revisar las instrucciones. Una migración, una modificación de permisos o la sustitución de una API deberían activar esa revisión cuando afecten a la Skill.

Las versiones antiguas también necesitan un tratamiento claro: cuáles siguen siendo válidas, para qué proyectos y cuándo deben retirarse.

Además, hay que distinguir entre consultar información y aceptar instrucciones. Un documento recuperado como contexto no debería poder modificar por sí solo los permisos del agente.

Las Skills aportan orientación; los controles de acceso y ejecución deben aplicarse en las herramientas y la plataforma.

Cómo medir si el conocimiento mejora el resultado

Para evaluar el aporte del contexto y las Skills, proponemos comparar tareas equivalentes bajo tres condiciones:

Contexto básico: la solicitud y los antecedentes mínimos.
Contexto específico del proyecto: fuentes, reglas y componentes pertinentes.
Contexto específico más una Skill revisada: el mismo conocimiento acompañado del procedimiento reutilizable.

Esta comparación ayuda a distinguir qué mejora al aportar información y qué cambia al organizar además la forma de trabajar.

Conviene mantener el mismo modelo, herramientas y criterios de evaluación, registrar las versiones y repetir las pruebas en varias tareas. Una sola respuesta favorable no basta para concluir que el procedimiento funciona de manera consistente.

Los indicadores pueden centrarse en:

Aprobación en primera revisión: proporción de entregas aceptadas sin correcciones sustanciales.
Esfuerzo de revisión: tiempo humano dedicado a comprobar y corregir cada propuesta.
Cumplimiento de reglas: resultados que satisfacen las comprobaciones aplicables.
Reutilización adecuada: uso de componentes existentes cuando corresponde.
Retrabajo posterior: correcciones por errores de contexto, reglas o integración.

También deben registrarse el tiempo total y el consumo de herramientas. La evaluación debe incluir el esfuerzo de preparar y mantener el conocimiento.

Para empezar, se puede elegir una tarea repetida y un problema concreto: propuestas que duplican componentes, historias que omiten reglas o pruebas que no siguen las convenciones del proyecto. Con ese alcance, el equipo puede definir qué espera mejorar y revisar tanto los aciertos como los fallos.

En el desarrollo de software con IA, esa evidencia ayuda a decidir qué conocimiento merece convertirse en una Skill compartida y qué instrucciones todavía necesitan ajustes.

¿Tu equipo debe adaptar una y otra vez las propuestas de sus agentes? Conversemos sobre SPIREX® y cómo evaluar el contexto y las Skills en un flujo concreto de desarrollo, con criterios de calidad y revisión definidos.

Preguntas frecuentes

¿Una Skill entrena al modelo con información de la empresa?

En el enfoque descrito, la Skill aporta instrucciones y recursos durante la ejecución. Incorporarla no equivale, por sí solo, a modificar los parámetros del modelo mediante entrenamiento.

¿Basta con dar acceso al repositorio?

El repositorio aporta contexto técnico, pero puede no explicar reglas de negocio, decisiones arquitectónicas o excepciones vigentes. El agente necesita las fuentes pertinentes para la tarea y una forma de resolver contradicciones.

¿Una Skill puede utilizarse en varios proyectos?

Puede reutilizarse cuando sus instrucciones son aplicables. Las referencias, herramientas y reglas específicas deben revisarse para cada proyecto; compartir el archivo no garantiza compatibilidad.

¿Quién debería revisar las Skills?

El responsable del conocimiento que contienen. Una Skill de arquitectura requiere revisión técnica; una de requisitos puede necesitar participación de negocio y QA. Si incluye scripts, también debe revisarse qué ejecutan y con qué permisos.

¿Las Skills evitan todos los errores del agente?

No. Pueden orientar el trabajo, pero sus instrucciones pueden estar incompletas, desactualizadas o aplicarse incorrectamente. Las pruebas, los controles de ejecución y la revisión humana siguen siendo necesarios.

¿Te ha interesado este contenido? No te pierdas nuestros otros artículos

Contrata a los mejores desarrolladores de software en Latinoamérica

Accede a talento top y soluciones de TI eficientes con nuestros servicios Nearshore.

Contáctanos