Quise borrar una carpeta con rm -rf y mi propio quality gate me frenó a mí.
Estaba preparando la publicación del repositorio, apurada, y el hook que yo misma había escrito se negó a ejecutar el comando. Me quedé un segundo mirando la pantalla, entre el fastidio de tener que hacerlo a mano y la satisfacción de comprobar que funcionaba.
Un control que solo frena a los demás no es un control. Es una recomendación bien redactada.
Eso que me frenó es lo que publico hoy: QA Harness Pro, el andamiaje con el que dirijo agentes de IA para que trabajen como trabajo yo. Es gratuito, es open source con licencia MIT y vive en github.com/adrianagit87/qa-harness-pro.
Este artículo no es el manual de instalación. Es el porqué: qué es un harness, por qué esa palabra es nuestra antes que de la industria de la IA, y qué decisiones hay que tomar antes de dejar a un agente tocar el Jira de tu equipo.
Este es el artículo del concepto. Si lo que quieres es instalarlo y llegar a tu primer análisis, esa es la guía paso a paso, que termina con las dos verificaciones que casi nadie hace.
Un pack de prompts no es un harness
Es lo primero que se asume cuando digo que tengo “mi setup de IA para QA”, así que lo aclaro de entrada.
Un pack de prompts es texto que pegas en un chat. Funciona mientras tú estés mirando, y se degrada en cuanto te distraes, porque nada obliga al modelo a cumplirlo. Si un día el modelo decide saltarse la regla tres, no pasa nada. No hay error, no hay aviso, no hay registro.
Un harness es otra cosa. Es lo que rodea a lo que se ejecuta y lo hace rendir dentro de un límite.
Y no es una palabra que inventó la industria de la IA. La inventamos nosotros, hace décadas.
Tres palabras que ya eran tuyas
Harness. En testing, el arnés es el ambiente, los datos, la configuración y las reglas del juego alrededor de lo que se prueba. Aplicado a un agente: tus herramientas, tu método y tus límites, envolviendo al modelo. El modelo no trabaja en el aire, trabaja adentro de algo que tú definiste.
Goal. El criterio verificable de que algo terminó y terminó bien. Nosotros lo llamamos oráculo desde siempre: cómo sabes que el resultado es el correcto, y no solamente que el programa no explotó. Aplicado a un agente: que sepa cuándo un análisis está completo y cuándo un ciclo está de verdad cerrado, en vez de frenar cuando se le acaba la conversación.
Loop. Percibir, razonar, actuar, observar, repetir. Es arrange, act, assert con otro nombre y con una persona mirando.
La industria de la IA no te está enseñando un vocabulario nuevo. Te está devolviendo el tuyo, con otro acento.
La tesis del proyecto entero cabe en una línea: tú diriges, la IA ejecuta dentro del harness. No al revés, y no sin arnés.
La decisión de diseño que lo vuelve portable
Cuando empecé a armarlo me choqué con el problema de siempre: mi forma de trabajar y los datos de la empresa donde la aplico vivían mezclados en el mismo archivo. Cada cambio de contexto era reescribir todo otra vez.
Así que lo partí en tres capas.
- Método. Cómo trabajas como QA: cómo analizas un ticket, qué miras antes de aceptarlo, cómo cierras un ciclo. Es lo portable. No cambia cuando cambias de empleo.
- Configuración. Los datos de tu empresa: proyectos, ambientes, dónde se documenta. Un archivo.
- Perfil. Quién eres tú: tu nombre, tu tono, qué priorizas. Es el que firma los cierres.
La consecuencia práctica es la que hace que valga la pena: el día que cambias de empresa, cambias un archivo y no tocas ni una skill. Tu método, que es lo que tardaste quince años en construir, se muda contigo.
Ese mismo corte trajo un beneficio que no había previsto. Como el método quedó separado de todo lo demás, el harness funciona con Claude Code, Cursor, Antigravity y Codex desde un solo instalador, sin duplicar una línea. Y en la v2 las reglas de los gates viven en un único núcleo: cada herramienta es apenas un traductor.
Los gates, que es donde se pone serio
Las cinco skills son las cinco cosas que hago todas las semanas: generar casos de prueba, analizar un ticket con su matriz de riesgos, decidir si vale la pena automatizar antes de escribir una línea de código, cerrar un ciclo y cerrar el ambiente final. La v2.2.0 suma una sexta, opcional y apagada por defecto, que se merece su propio artículo.
Eso es el método. Pero el método es texto, y un modelo puede saltárselo.
Los gates no son texto. Son programas que se ejecutan solos antes de cada acción, y pueden frenarla:
- Comandos destructivos.
rm -rf,git reset --hard,git cleanforzado sobre directorios ygit pushforzado en sus tres variantes. - Después de cada edición, se valida el archivo modificado: sintaxis y tests para Python, sintaxis para shell, formato para JSON. También cuando el agente escribe el archivo por la terminal y no con su herramienta de edición.
- Antes de publicar en Jira, Confluence o Notion, se revisa el contenido: se rechaza lo vacío, lo demasiado corto y lo que todavía tiene un marcador sin completar.
Y hay una cuarta regla que no es un gate, es una frontera: el harness documenta, no mueve estados. Transicionar un ticket sigue siendo una decisión humana. Está denegado en tres lugares distintos, a propósito.
Esa no es una limitación técnica pendiente de resolver. Un agente que mueve tickets convierte un error de lectura suyo en un estado equivocado en el tablero de todo el equipo, y el equipo se entera tarde.
Cinco cosas que aprendí construyéndolo
Esta es la parte que no suele contarse, y es la única que me parece que vale la pena leer si nunca vas a instalar el proyecto.
Un gate que solo frena a los demás no es un gate. Es la historia que abre este artículo. Y es la prueba más barata que le puedes hacer a tu propio control: intenta romperlo tú.
Los tests encontraron un bug que rompía al usuario. Escribiendo pruebas para uno de los instaladores apareció que, al instalar, borraba en silencio los hooks propios de quien lo usaba: la fusión de configuración reemplazaba la lista entera en vez de combinarla. Nadie se habría quejado nunca. Nadie reclama lo que no sabe que perdió.
Un gate que se rompe no protege. Tres hooks se caían con un error interno cuando recibían un JSON válido con una forma inesperada. Hoy fallan cerrado: ante la duda, bloquean. Un control que se rompe y deja pasar es peor que no tener ninguno, porque además te deja tranquila.
Un gate desconectado no avisa que lo está. Deja pasar todo, y tú sigues creyendo que estás protegida. Por eso el harness trae verificaciones para comprobar que el gate muerde, en vez de confiar en que está ahí porque lo instalaste una vez.
Y el quinto me pasó revisando la versión que iba a publicar, tres días antes de la fecha. Una de las herramientas tenía su archivo de reglas en el repo, documentado en el README y mencionado en la tabla de equivalencias. El instalador no lo copiaba a ningún lado. Nunca.
Quien lo usaba instalaba, validaba, le daba verde, corría su primer análisis y el análisis salía bien. Bien, pero sin mi método adentro.
Las tres primeras lecciones son sobre controles que fallan de manera ruidosa, y esas son las fáciles. Las dos últimas son el mismo problema: el resultado se ve correcto. No hay error, no hay rojo, no hay nada que revisar. Es la falla que un QA reconoce de inmediato, porque es la misma que tenemos en nuestras suites cuando un test pasa sin verificar nada.
Las cinco preguntas antes de soltar un agente en tu equipo
Esta parte no es sobre mi proyecto. Es lo que me gustaría que se preguntara cualquier equipo que hoy está por darle acceso a una IA a su Jira, use lo que use.
Son cinco, y están ordenadas: si no puedes responder la primera, las otras cuatro no importan.
- ¿Qué puede ejecutar sin preguntarme? No “qué debería”. Qué puede, hoy, si nadie mira.
- ¿Qué está explícitamente prohibido, y dónde está escrito eso? Si la única respuesta es “está en el prompt”, entonces no está prohibido: está sugerido.
- ¿Cómo me entero de que un control dejó de funcionar? Un gate desconectado no protesta. Si no tienes una forma de comprobarlo, tu respuesta es “no me entero”.
- ¿Quién puede apagarlo? Casi siempre hay alguien fuera del equipo que puede cambiar una política y dejarte sin cobertura sin avisarte.
- ¿Qué queda escrito de lo que hizo? Si el agente trabaja y no deja rastro revisable, no tienes un colaborador: tienes un rumor.
Si alguien de tu equipo te pasó este artículo, este bloque es el que te interesa. Las cinco preguntas no piden presupuesto ni una herramienta nueva: piden que las respuestas existan antes del próximo release, no después del primer incidente.
Ese es el orden en que están resueltas dentro del harness, por si quieres ver una implementación concreta: permisos declarados, prohibiciones en tres capas, verificaciones para comprobar que el gate muerde, límites documentados por herramienta, y todo lo que hace queda como documentación revisable antes de publicarse.
Lo que no te voy a prometer
Las cuatro herramientas no se comportan igual, y está documentado dónde difieren. En Claude Code y en Codex, el chequeo posterior a una edición le devuelve el error al agente en el momento. En Cursor y en Antigravity no puede hacerlo: deja una marca que salta en la llamada siguiente. Es una limitación real de esas herramientas, no algo que se arregle escribiendo mejor el hook.
Lo mismo pasa con lo que el agente escribe por la terminal, con una redirección o un sed -i. En Claude Code y en Codex pasa por el mismo chequeo. En Cursor está enganchado según su documentación, pero todavía no lo vi morder en una sesión real. En Antigravity no está cubierto, y lo dice el README.
Tampoco es un producto terminado. Es la v2 de algo que uso todos los días.
Qué hay adentro del repo, para quien quiera mirarlo antes de instalarlo
Cinco skills con el método y una sexta opcional, tres gates con sus hooks, un instalador único para las cuatro herramientas, un validador que comprueba que lo instalado sigue apuntando a tu copia del repo, y 276 tests unitarios más 431 comprobaciones de humo corriendo en cada cambio. Las comprobaciones de humo instalan el harness entero en carpetas temporales, una vez por herramienta, y verifican archivo por archivo que quedó donde tenía que quedar.
Los datos de tu empresa nunca entran al historial de git: están en el
.gitignore por diseño, no por olvido.
Por qué lo publico
El método que hay adentro no lo inventé sola. Lo aprendí en quince años de equipos, de gobierno a fintech, mirando cómo se rompen las cosas cuando nadie definió quién decide qué.
Y porque un arnés que no se puede revisar no es un arnés. Si el código está cerrado, lo único que te queda es creerme.
Clónalo, adáptalo, rómpelo. Si algo no funciona, abre un issue. Si tienes una forma mejor de resolver alguna de las tres capas, los PRs están abiertos: la licencia es MIT justamente para eso.
Y si lo que necesitas no es instalar un harness sino saber qué está protegiendo hoy la suite de tu equipo, eso es lo que hago cuando entro a un proyecto. La llamada de diagnóstico es gratis.