El harness de tu agente QA: el mismo arnés, otro ejecutante

En la parada 01 de esta serie dejé caer una frase y seguí de largo: “yo armé el mío: un arnés alrededor de mi agente de QA que lo convierte en un compañero de trabajo real, no en un chat que responde suelto”. Hoy cumplo esa promesa y lo abro pieza por pieza.

Esta guía es hands-on. Al terminarla vas a tener el harness mínimo de tu propio agente QA: su contexto, sus herramientas, su goal y sus reglas. Y no me refiero a “vas a entender el concepto” — me refiero a archivos concretos en tu máquina, y a un agente que analiza un ticket de tu Jira y se frena a pedirte permiso antes de escribir una sola línea hacia afuera. Ese freno lo vas a ver funcionar. Hace unos días lo vi yo con un ticket real, y te lo cuento al final porque es la mejor parte.

El mismo mapa, otro ejecutante

En la parada anterior desarmamos cualquier framework de tests en seis piezas: setup, runner, herramientas, goal, reporting y orquestación. Te mostré que son las mismas en Playwright, en k6 y en Appium — cambia el disfraz, no la función.

Ahora viene el salto que da nombre a esta parada: esas seis piezas no envuelven solo código bajo prueba. También envuelven a un agente de IA. Mira el mapa:

Fíjate en algo: no hay ninguna pieza nueva. La número 2 ya no la escribes tú (el loop viene con el agente, como el runner venía con Playwright), y la número 6 cambia de pregunta — ya no es “¿corre solo?” sino “¿corre solo sin hacer desastres?” — pero la anatomía es idéntica. Dirigir un agente usa exactamente lo que ya sabes.

Vamos pieza por pieza, construyendo. Necesitas Claude Code instalado —o un agente CLI equivalente; el modelo mental es el mismo—, acceso a Jira y permiso de tu organización para conectar el MCP de Atlassian.

Pieza 1 — El contexto: tu método, por escrito

Un test sin fixtures arranca de un estado desconocido y falla de formas creativas. Un agente sin contexto hace lo mismo: cada sesión inventa desde cero cómo se analiza un ticket, cómo se llama tu proyecto, quién eres.

El setup de tu agente son archivos. Crea una carpeta para tu harness y empieza por dos:

profile.json — quién es el QA que dirige:

{
  "name": "Tu Nombre",
  "role": "QA Senior",
  "activeCompany": "miempresa",
  "language": "es"
}

companies/miempresa.json — dónde vive tu trabajo:

{
  "company": { "name": "Mi Empresa", "key": "PROJ" },
  "tracker": {
    "type": "jira",
    "host": "miempresa.atlassian.net",
    "ticketPrefixes": ["PROJ"],
    "browseUrlPattern": "https://miempresa.atlassian.net/browse/{KEY}"
  },
  "docs": { "backend": "confluence" }
}

Y el tercero es el que más pesa: CLAUDE.md, el archivo que Claude Code lee al arrancar. Ahí no va tu biografía — va tu método. Cómo analizas un ticket, en qué orden, qué es innegociable:

## Método de análisis de tickets

1. Lee el ticket completo: título, descripción, criterios de aceptación
   y TODOS los comentarios. Si un comentario agrega una condición que no
   aparece en los criterios, incorpórala como contexto de prueba. Si contradice
   el ticket o una decisión del PO, señala el conflicto antes de generar casos:
   no elijas una versión de la verdad en silencio.
2. Aplica el gate: ¿título claro? ¿criterios medibles? ¿DoD presente?
   Un criterio tipo "debe validar los campos" NO es medible — conviértelo
   en pregunta concreta para el PO, no lo asumas.
3. Recién con el gate pasado, genera los casos: positivos, negativos,
   edge, integración y seguridad, priorizados 🔴/🟡/🟢.
4. Nada se publica sin mi confirmación. Propones, yo decido.

¿Te suena? Es tu proceso de siempre. La diferencia es que ahora está escrito donde el agente lo lee en cada sesión — igual que un fixture corre antes de cada test. Si tu método solo existe en tu cabeza, tu agente no lo tiene. Escribirlo es la mitad del trabajo, y es trabajo de QA puro: es análisis de requerimientos sobre tu propia forma de trabajar.

Pieza 3 — Las herramientas: MCP es tu WebDriver

Salto a la pieza 3 porque la 2 —el loop— ya viene resuelta: es el ciclo interno del agente, como el runner venía con tu framework. Tu trabajo no es escribir el loop; es darle al loop cosas reales que tocar.

Ahí entra MCP (Model Context Protocol). Si leíste la guía de MCP para QA, ya sabes la idea: es el conector estándar entre el agente y tus herramientas, como WebDriver fue el conector estándar entre tu test y el browser. Un archivo .mcp.json en la raíz de tu carpeta:

{
  "mcpServers": {
    "atlassian": {
      "type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp/authv2"
    },
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Sin tokens pegados en ningún lado: la primera vez, Claude Code te pide aprobar los servers y autenticas por OAuth en el navegador. Dos detalles que aprendí a golpes y te ahorro:

• Usa los endpoints oficiales vigentes (los de arriba, a julio 2026). Hay tutoriales circulando con endpoints viejos que fallan silencioso: el agente arranca, pero sin herramientas — un framework con el driver desconectado.
• Claude Code te pedirá confiar en el workspace la primera vez. Acéptalo: sin ese trust, parte de tus permisos queda desactivada, y el único aviso es una línea discreta que nadie lee.

Con esto tu agente ya puede leer un ticket real de TU Jira. Todavía no queremos que escriba nada — para eso faltan dos piezas, y son justo las que separan un juguete de una herramienta de trabajo.

Pieza 4 — El goal: ¿qué significa “terminó bien”?

Esta es la pieza que el mundo dev llama “el problema del goal verificable” y que tú conoces de toda la vida como el oráculo. En un test es el expect. En k6 es el threshold. ¿Y en un agente QA?

En un agente, el goal es el criterio — escrito, no intuido — de que la tarea quedó bien hecha. Para el flujo de análisis de tickets, mi goal tiene forma de gate con checklist:

## Goal del análisis (el agente NO termina hasta cumplir esto)

- Gate de calidad emitido: APROBADA / APROBADA CON OBSERVACIONES / RECHAZADA,
  con tabla de criterios evaluados.
- Toda ambigüedad del ticket convertida en pregunta concreta para PO/Dev.
  Cero supuestos silenciosos.
- Casos generados SOLO si el gate pasó: tabla con ID, prioridad, tipo,
  precondiciones, pasos y resultado esperado.
- Matriz de riesgos al final.
- Resumen de cierre con conteos. Si algo quedó pendiente, se dice.

¿Ves lo que pasa ahí? Es exactamente la disciplina de la parada anterior aplicada al agente: el criterio de “correcto” vive afuera del ejecutante. No le preguntas al modelo si le parece que terminó — le das la vara contra la que se mide. Igual que jamás dejarías que el código bajo prueba decida si el test pasa.

Y esto responde la objeción que seguro ya se te cruzó: “¿y si el modelo alucina?”. Puede. Por eso el goal no es “confía”, es “demuestra”: tabla de criterios, preguntas explícitas, conteos. Lo que no se puede verificar contra el goal, no vale como hecho.

Pieza 6 — Las reglas: control, no fe

La pieza que más miedo quita. Claude Code lee permisos de un archivo .claude/settings.json en tu carpeta, con tres niveles: allow (hazlo sin preguntar), ask (pregúntame antes) y deny (jamás):

{
  "permissions": {
    "allow": [
      "mcp__atlassian__getJiraIssue",
      "mcp__atlassian__searchConfluenceUsingCql"
    ],
    "ask": [
      "mcp__atlassian__addCommentToJiraIssue",
      "mcp__atlassian__createConfluencePage",
      "mcp__atlassian__updateConfluencePage"
    ],
    "deny": ["mcp__atlassian__transitionJiraIssue"]
  }
}

Léelo como QA y vas a reconocer la lógica al instante:

• Leer es gratis: consultar un ticket o buscar una página no rompe nada — allow.
• Escribir hacia afuera siempre pregunta: un comentario en Jira con tu firma, una página nueva de documentación — ask. El agente redacta el borrador completo, te lo muestra, y tú decides. Es la pieza 5 (reporting) y la 6 trabajando juntas.
• Cambiar estados de tickets, jamás: deny. Esa es una decisión de humanos en mi equipo, y en el tuyo probablemente también. Acá la confianza sobra: aunque el modelo quiera, no puede.

La prueba de fuego

Te dije al principio que el freno lo vi funcionar con un ticket real. Fue así: sesión limpia del agente con este mismo harness — método escrito, MCP autenticado, goal definido, permisos puestos. Le pedí: “Analiza [URL de un ticket real de mi Jira]”.

El agente leyó el ticket por MCP — título, descripción y el hilo completo de comentarios. Aplicó el gate: APROBADA CON OBSERVACIONES, con dos huecos detectados que eran huecos de verdad (un criterio de aceptación genérico y datos de prueba sin definir). Convirtió los huecos en preguntas para el PO en vez de asumir respuestas. Generó 19 casos priorizados con su matriz de riesgos. Y entonces llegó al momento que me importaba:

Se frenó. Solo, porque su goal y sus reglas le dicen que ahí se frena. Le dije que no — era una prueba — y no pasó nada más: ni página fantasma, ni comentario a medias. El análisis completo quedó en el chat como borrador, listo para usarse cuando yo quiera.

Y en esa misma sesión pasó otra cosa que vale la guía entera: en una de sus respuestas, el agente me tuteó mal — me soltó un “¿querés que evalúe automatización?”, en voseo, cuando todo mi contenido y mi método están escritos en tuteo. Detalle menor, ¿cierto? Pero es la demostración perfecta de la tesis: el modelo deriva. Hoy es un voseo inofensivo; mañana es un formato de comentario que tu equipo no reconoce, o un supuesto que nadie autorizó. ¿Y cómo se corrige eso? No regañando al modelo en el chat — agregando al harness la regla que faltaba. Después de esa sesión, mi método tiene una línea nueva: “tuteo siempre, jamás voseo”. La próxima deriva será otra, y le tocará su propia regla. Así se endurece un arnés con el uso: cada desvío que observas se convierte en una regla escrita, y el agente te queda un poco más firme que la semana pasada. Exactamente como una suite de regresión crece con cada bug que se te escapó a producción.

Tu checklist: las 6 piezas, versión agente

La misma radiografía de la parada anterior, apuntando ahora a tu agente. Puntúa 0 (no existe), 1 (a medias), 2 (sólida):

RADIOGRAFÍA DEL HARNESS DE TU AGENTE — 6 piezas

[ ] 1. Contexto ......... tu método está escrito donde el agente lo lee
[ ] 2. Loop ............. encadena los pasos y tiene condición de parada clara
[ ] 3. Herramientas ..... MCP conectado a TU tracker y TU espacio de docs
[ ] 4. Goal ............. "terminó bien" definido por escrito, verificable
[ ] 5. Reporting ........ todo lo que sale hacia afuera pasa por borrador
[ ] 6. Reglas ........... allow/ask/deny puestos; lo crítico en deny

                                                TOTAL: __ / 12

Un agente con 4 o menos es un chat con acceso a tu Jira — y eso da más miedo que no tener agente. Con 10+ tienes un compañero de trabajo dirigido. La distancia entre uno y otro son archivos de texto que un QA sabe escribir mejor que nadie, porque son requisitos, criterios de aceptación y quality gates. Tu oficio, aplicado a un ejecutante nuevo.

Lo que sigue

Esta guía te dio el harness mínimo hecho a mano. La versión completa de este sistema — el método entero de análisis y cierres empaquetado en skills, con instalador, validación de configuración y suite de tests propia — es el Módulo 1 del sistema QA con IA que estoy construyendo, y a mis suscriptores les va a llegar primero, como siempre.

La próxima parada le entra a la pieza que dejé señalada: hooks — los quality gates deterministas de tu agente. Los devs los usan para formatear código al guardar; nosotros vamos a usarlos para lo que realmente son: la parte del harness que NO depende del criterio del modelo. Si esta guía te dio el arnés, la que viene le pone los frenos que actúan solos — los que funcionan aunque el modelo tenga un mal día.

¿Armaste el tuyo? ¿Qué pusiste en deny? Esa lista dice mucho de cómo piensa un QA — cuéntame la tuya.