Tu primer agente de QA: de cero a uno que corre

En la Parte 1 te dije que no necesitas un agente más inteligente: necesitas dirigir un equipo de agentes que piensen distinto.

La pregunta que más me repitieron después fue siempre la misma: “OK Adriana, me convenciste. ¿Pero cómo armo UNO?”. Y tienen razón: antes de dirigir un equipo hay que saber construir un solo agente y verlo correr. Eso es esta guía.

Sin abstracción: vas a salir de acá con un agente hecho por ti, guardado en tu compu, que corre cuando lo llamas. Lo voy a responder todo — qué es, cómo se arma, dónde vive en tu máquina y cómo lo invocas — porque si copias algo y no funciona, no aprendiste nada.

La idea que lo desbloquea todo

Antes de tocar nada, quiero que entiendas esto:

Un agente bien armado tiene cinco cajas. Y ya las llenas todos los días cuando diseñas una prueba:

Ese músculo ya lo tienes entrenado. No vamos a aprender a programar agentes. Vamos a traducir algo que ya sabes hacer.

Qué vamos a construir: el Analista

Nada de un agente de juguete que dice “hola mundo”. Vamos a armar uno que usarías el lunes: el Analista.

Le das una historia de usuario con sus criterios de aceptación, y te devuelve lo que un buen QA detecta antes de que la historia llegue a desarrollo: las ambigüedades, los riesgos y las preguntas que llevarías al refinamiento.

Si leíste El costo de no invitar a QA al refinamiento, sabes por qué elegí justo este: el momento más barato para encontrar un problema es antes de escribir una línea. El Analista te da un primer barrido en segundos, para que entres a la reunión con las preguntas ya en la mano.

Antes del archivo: qué es un agente, de verdad

Un párrafo de concepto, porque si no entiendes esto, lo demás es copiar y rezar.

Un agente (o subagente) en Claude Code es un asistente con un solo trabajo y un contexto propio. Cuando lo llamas, arranca limpio: no ve tu conversación, no arrastra lo que venías hablando. Recibe la tarea, hace su trabajo enfocado en su rol, y te devuelve un resultado. Después desaparece sin ensuciar tu hilo principal.

¿Y dónde se define ese rol? En un archivo. Vamos a él.

Dónde vive en tu compu

Esta es la duda número uno, y la que casi nadie explica bien. Tu agente es un archivo de texto que vive en una carpeta específica. Hay dos lugares posibles, y la diferencia importa:

Para el Analista te recomiendo la global (~/.claude/agents/): analizar historias lo vas a hacer en cualquier proyecto, no en uno solo.

Desde tu terminal, esta línea crea la carpeta global (el -p no se queja si ya existe):

mkdir -p ~/.claude/agents

Listo. Ahí es donde va a vivir tu agente. Si en algún momento dos agentes se llaman igual —uno en el proyecto y uno global— gana el del proyecto. Bueno saberlo, no urgente hoy.

La anatomía del archivo

El archivo es Markdown (.md) y tiene dos partes: un encabezado entre --- (los datos del agente) y debajo, el cuerpo (sus instrucciones, lo que llamamos el prompt de sistema).

---
name: nombre-del-agente
description: Cuándo se usa este agente
tools: Read
model: sonnet
---

Acá van las instrucciones permanentes del agente.
Esto es lo que el agente "es" cada vez que lo llamas.

El encabezado tiene cuatro campos, y solo dos son obligatorios. Acá es donde vuelven tus cinco cajas:

Y el cuerpo —las instrucciones de abajo— es donde viven las otras tres cajas: el contexto que recibe, los límites de lo que NO debe hacer, y el formato del resultado.

Construyamos el Analista, caja por caja

Ahora lo armamos de verdad. Voy campo por campo para que entiendas cada decisión, no para que copies a ciegas.

Caja 1 y 2 — Objetivo y nombre (el encabezado):

name: qa-analista
description: Analista de QA. Lee una historia de usuario con sus criterios de aceptación y devuelve ambigüedades, riesgos y preguntas para llevar al refinamiento. Úsalo antes de estimar o escribir casos, cuando una historia parece clara pero no tanto.

Fíjate en la description: dice qué hace (analiza), sobre qué (una historia con criterios) y cuándo (antes de estimar o escribir casos). Esas tres cosas son las que hacen que Claude lo elija en el momento correcto.

Caja 3 — Herramientas (el alcance):

tools: Read

El Analista solo necesita leer. No escribe archivos, no corre comandos, no toca nada. Limitarlo a Read es exactamente lo que harías con el alcance de una prueba: ni un permiso de más. Un agente con menos poder es uno en el que confías más.

Cajas 4 y 5 — Contexto, límites y validación (el cuerpo):

Acá está el archivo completo. Guárdalo como ~/.claude/agents/qa-analista.md:

---
name: qa-analista
description: Analista de QA. Lee una historia de usuario con sus criterios de aceptación y devuelve ambigüedades, riesgos y preguntas para llevar al refinamiento. Úsalo antes de estimar o escribir casos, cuando una historia parece clara pero no tanto.
tools: Read
model: sonnet
---

Eres un analista de QA con años de experiencia en refinamiento. Tu trabajo NO es
escribir casos de prueba ni aprobar la historia. Tu trabajo es leer una historia
de usuario con sus criterios de aceptación y encontrar lo que falta ANTES de que
llegue a desarrollo.

Recibes una historia de usuario. Devuelves tres cosas:

1. AMBIGÜEDADES: dónde la historia se puede interpretar de más de una forma. Por
   cada una, di la duda concreta — no un comentario genérico.
2. RIESGOS: qué se puede romper o qué daño aparece si esto sale mal — datos,
   seguridad, casos límite que el criterio no menciona.
3. PREGUNTAS PARA EL REFINAMIENTO: las preguntas exactas que llevarías a la
   reunión, redactadas para hacerlas tal cual.

## Reglas

- No inventes requisitos: marca lo que falta, no lo que te gustaría que dijera.
- No escribas casos de prueba todavía: esto es el paso anterior.
- Si un criterio ya está bien definido, no lo cuestiones por cuestionar.
- Concreto y específico a ESTA historia, no un checklist genérico.

## Formato de salida (obligatorio)

Tres secciones con esos títulos exactos. Listas con viñetas. Español, tuteo.

Léelo despacio y vas a reconocer tu propio oficio: le digo qué recibe (contexto), le digo qué NO hacer —no escribir casos, no inventar— (límites), y le exijo un formato fijo de salida (resultado esperado). Las cinco cajas, en un archivo de texto.

Dos formas de crearlo (y un detalle que confunde a todos)

Tienes dos caminos para que el archivo exista. La diferencia entre ellos es la causa número uno del “lo armé y no funciona”:

/agents

Cómo lo llamas

Ya existe. Ahora, cómo lo pones a correr. Hay tres formas, de menos a más control:

1. Que Claude lo elija solo. Si tu description es buena, basta con pedir la tarea en lenguaje natural y Claude delega al Analista cuando encaja:

Analiza esta historia de usuario antes de que la estimemos: [pegas la historia]

2. Nombrarlo en la frase. Le dices cuál quieres, sin ceremonia:

Usa el agente qa-analista para revisar esta historia: [pegas la historia]

3. Invocarlo con @ (control total). Escribes @ y aparece una lista; eliges tu agente. Esto garantiza que corre ese y no otro:

@agent-qa-analista revisa esta historia: [pegas la historia]

Córrelo: la prueba de que no es humo

Le pasé al Analista una historia chiquita y común, de esas que en la reunión todos asienten como si estuviera clarísima:

Historia: Como usuario registrado, quiero recuperar mi contraseña ingresando mi email, para volver a entrar si la olvidé.

Criterios de aceptación:

• El usuario ingresa su email y recibe un enlace de recuperación.
• El enlace expira a las 24 horas.
• Con el enlace, define una contraseña nueva.

Tres líneas. “Está clara”, diría cualquiera. Esto devolvió el Analista:

De tres líneas que “estaban claras”, salieron nueve cosas para definir. Eso es exactamente lo que quieres tener antes de entrar al refinamiento, no descubrirlo en producción.

Dónde NO confiar a ciegas

El Analista no aprueba la historia. La prepara. Lo que te entrega es un borrador inteligente que te ahorra el primer barrido — el tedioso, el que a veces saltas por las prisas. Pero la decisión de qué entra, qué se descarta y qué pregunta vale la pena pelear en la reunión, sigue siendo tuya.

Por eso este agente te suma incluso siendo senior: no reemplaza tu ojo, te despeja la pista para usarlo donde rinde.

Lo que te llevas

Armaste un agente desde cero. Sabes dónde vive (~/.claude/agents/), de qué está hecho (un .md con cinco cajas que ya conocías), cómo se crea (con /agents o a mano, reiniciando) y cómo se invoca (con @). Eso es todo el misterio.

Y acá está lo importante: no copies mi Analista y pares ahí. Copia el método. Las cinco cajas sirven para el agente que TÚ necesitas — uno que arme datos de prueba, otro que revise tus reportes de bug, otro que traduzca un requisito técnico. El que te duela en tu día a día.

El primer agente es el que cuesta. Ya lo cruzaste. El resto es repetir el patrón.