El skill autor de pruebas: tests que fallan por razones reales

Casi todo el mundo le agrega un skill de tests a Claude Code y enseguida termina con teatro de cobertura: un muro de verde que demuestra que el código hace exactamente lo que ya hace, línea por línea, y que seguiría pasando tan tranquilo mientras el comportamiento se pudre por dentro. El problema no es que el modelo no sepa escribir un test, sino que, por defecto, escribe el test más fácil de poner en verde, que es justo el que calca la implementación. Este texto recorre el skill test-author que uso de verdad: qué hace, el momento exacto en que debe activarse, cómo razona por dentro, una invocación real con la salida que deberías esperar, la configuración que lo mantiene honesto y los detalles que deciden si tu suite en verde significa algo. Al final vas a tener un skill que puedes poner en un repo y una idea clara de dónde vale lo que cuesta y dónde te engaña.

Todo el skill se apoya en una idea al revés: escribe la lista de casos antes de escribir cualquier test. Una función no es una sola cosa que verificar; es una ruta feliz, una entrada vacía, un límite y un conjunto de rutas de error que se supone que maneja. La lista de casos es el artefacto que importa. Los tests son solo esa lista convertida en algo ejecutable.

01 · Qué hace el skill

El skill test-author es un revisor empaquetado que invocas cuando quieres, en vez de pegar las mismas instrucciones de testing una y otra vez. Lo apuntas a una unidad de código, una función, un módulo, un route handler, y hace tres cosas en orden fijo:

1. Lee la unidad y los tipos o contratos que la rodean, para entender la forma de las entradas y las salidas.
2. Enumera los comportamientos que vale la pena probar y te muestra esa lista antes de escribir nada. Aquí está el punto de control donde detectas el caso límite que se le olvidó, o quitas el trivial que metió de más.
3. Escribe un test por comportamiento, con nombre descriptivo, verificando la salida observable y no las llamadas internas.

Lo que a propósito no hace es perseguir un número de cobertura. La cobertura es un síntoma, no una meta. Un skill que optimiza el porcentaje va a probar getters, constantes y las ramas que ya son obviamente correctas, porque son líneas baratas de pintar de verde. El skill test-author se enfoca en los casos donde equivocarse sale caro: la lista vacía, el off-by-one en el borde, la entrada mal formada que debería lanzar error, el timeout que el código dice que maneja.

02 · Cuándo debe activarse

Un skill vale lo que vale su criterio para activarse. El skill test-author debe entrar en tres situaciones y quedarse callado en las demás.

• Justo después de escribir una función y antes de confiar en ella. Este es el momento ideal. El comportamiento está fresco en tu cabeza, el contrato ya está decidido y el skill puede fijarlo mientras todavía es barato cambiarlo.
• Antes de modificar código que no tiene cobertura. Aquí el skill escribe tests de caracterización: captura lo que el código hace hoy, feo o no, para que tu próximo cambio tenga una red de seguridad. No estás afirmando que el comportamiento sea correcto; estás afirmando que no cambie por accidente.
• Cuando se cuela un bug. La disciplina es: primero reproduce el bug como un test que falla, y después arréglalo. Ese test se convierte en un guardián permanente contra la regresión.

Dónde no debe entrar importa igual. Sáltalo en getters triviales, en wrappers delgados que solo reenvían argumentos y en código que estás a punto de borrar. Un skill que prueba todo sin criterio es la receta para terminar con una suite de mil líneas que nadie mantiene ni en la que nadie confía.

Cómo conectar el trigger en el archivo del skill

Un skill de Claude Code es un archivo markdown con frontmatter YAML. La línea description es lo que el modelo lee para decidir si el skill aplica, así que invierte las palabras en el cuándo usarlo, no solo en el qué hace:

---
name: test-author
description: Escribe tests enfocados en comportamiento para una unidad de código.
  Úsalo después de escribir una función nueva, antes de modificar código sin
  cobertura (tests de caracterización), o para reproducir un bug como test que
  falla. NO lo uses para getters triviales ni wrappers.
---

Para la función objetivo:
1. Léela y sus tipos. LISTA los comportamientos a probar (feliz, vacío,
   límite, error). Muestra la lista y DETENTE a confirmar.
2. Escribe un test por comportamiento con nombre descriptivo.
3. Verifica la salida observable, no las llamadas internas ni el estado privado.
4. NO pruebes getters triviales, constantes ni wrappers de paso.
5. Si la función no tiene contrato claro, pregunta antes de inventarlo.

Fíjate que la descripción le dice al modelo tanto cuándo activarse como cuándo no. Esa sola línea es la diferencia entre un skill que entra cuando es útil y uno que se ofrece a escribir tests para cada getter que escribas.

03 · Cómo funciona por dentro

Aquí no hay magia: el skill es un prompt estructurado que fuerza un orden de razonamiento específico. Todo el valor está en el orden.

El paso uno es leer, no escribir. El skill carga la función y los tipos que la rodean. Si la función recibe un argumento tipado con una unión, los miembros de la unión son los casos de prueba. Si devuelve un resultado discriminado, cada variante es un comportamiento por cubrir. TypeScript te hace la mitad del trabajo de enumerar casos; al skill solo le toca prestarle atención a los tipos.

El paso dos es la enumeración, mostrada como lista. Este es el paso que sostiene todo. El skill escribe los comportamientos antes de escribir cualquier test, y eso hace dos cosas: te deja detectar un caso límite olvidado ("se te pasó el caso de monto negativo") y evita que el skill rellene la suite con verificaciones triviales. La lista es barata de revisar; cien líneas de código de test generado no lo son.

El paso tres es escribir tests que verifican el borde de la unidad. Al skill se le instruye verificar el comportamiento observable, lo que la función devuelve, lo que lanza, el efecto secundario que causa, no qué helper interno llamó. Un test acoplado a las tripas se rompe en cada refactor y no prueba nada sobre si el código es correcto. Un test acoplado al comportamiento sobrevive a los refactors y se rompe solo cuando el comportamiento de verdad cambia.

04 · Una invocación concreta y su salida

Digamos que escribiste un parser pequeño. La función recibe un string de precio como "1,299.50" y devuelve un número, o lanza error si le mandas basura:

export function parsePrice(input: string): number {
  const cleaned = input.replace(/,/g, "").trim()
  if (cleaned === "") throw new Error("empty price")
  const n = Number(cleaned)
  if (!Number.isFinite(n)) throw new Error("not a number: " + input)
  if (n < 0) throw new Error("negative price: " + input)
  return n
}

Invocas el skill sobre ella. Antes de escribir un solo test, te devuelve la lista de casos, y esta es la parte que de verdad lees:

• Ruta feliz: "1,299.50" se parsea a 1299.5.
• Comas eliminadas: "1,000,000" se parsea a 1000000.
• Espacios recortados: " 42 " se parsea a 42.
• String vacío lanza "empty price".
• No numérico lanza "not a number".
• Negativo lanza "negative price".

La revisas y notas que no listó "un string de puras comas": una entrada que al limpiarse queda vacía y debería lanzar error. Le dices que agregue ese caso. Ese intercambio es todo el punto del skill: detectaste un hueco real en treinta segundos de leer una lista, no después de depurar un incidente en producción. Solo entonces escribe los tests:

import { parsePrice } from "./parsePrice"

test("parsea un precio con formato", () => {
  expect(parsePrice("1,299.50")).toBe(1299.5)
})

test("lanza error con entrada vacía", () => {
  expect(() => parsePrice("")).toThrow("empty price")
})

test("lanza error con un string de puras comas", () => {
  expect(() => parsePrice(",,,")).toThrow("empty price")
})

test("rechaza precios negativos", () => {
  expect(() => parsePrice("-5")).toThrow("negative price")
})

Cada test verifica el comportamiento observable, el número devuelto o el mensaje lanzado, y cada uno fallaría por una razón real si el parser sufriera una regresión. Ninguno espía la regex ni el orden de los chequeos, así que un refactor de las tripas los deja en verde.

05 · La configuración que lo mantiene honesto

Los defaults que vienen con el skill importan más que cualquier prompt que escribas en cada invocación, porque son la política que aplica todas las veces. Las cuatro líneas de abajo son las que nunca quito:

• Lista los comportamientos primero y luego detente. La puerta de confirmación es lo que convierte el skill de generador en revisor. Cuesta una ida y vuelta y te ahorra revisar cien líneas de tests equivocados.
• Verifica solo la salida observable. Déjalo bien claro: nada de verificar campos privados, nada de espiar llamadas a helpers internos, salvo que el efecto secundario sea el contrato (por ejemplo, "manda exactamente un correo").
• Prohíbe los tests triviales de forma explícita. Sin esa prohibición, el modelo rellena cobertura. Pon nombre a los culpables: getters, constantes, wrappers que solo dejan pasar.
• Respeta el test runner y las convenciones del proyecto. Apúntalo a un archivo de test que ya exista para que copie el estilo de imports, la librería de aserciones y la nomenclatura. Un test que no calza con el estilo de la casa es fricción, no ayuda.

También puedes dejarlo proponer casos nuevos más allá de tu lista, útil, siempre que los marque como sugerencias que tú aceptas, en vez de inflar la suite por su cuenta. La misma disciplina aparece en los demás skills que mantengo: el skill code-review evalúa contra el diff y no contra su idea de código perfecto, y el skill test-author prueba contra el contrato y no contra su propia lectura de la implementación. En ambos la idea es sujetar al modelo al estándar que tú pones, no al que él tomaría por inercia.

06 · Los detalles que deciden si ayuda o no

Aquí es donde una suite en verde o significa algo o te engaña.

Calcar la implementación es la falla por defecto. Si lo dejas solo, el skill escribe tests que recorren la función línea por línea, así que pasan para siempre y no atrapan nada. El arreglo es la restricción dura de la sección 03: prueba el comportamiento en el borde de la unidad. Si un test seguiría pasando después de que reescribieras las tripas desde cero, es un test real. Si se rompe apenas renombras una variable privada, es ruido.

Nunca dejes que debilite una aserción para poner en verde un test rojo. Un test que falla es información, no un obstáculo. El modelo, ansioso por dejarte una suite que pasa, a veces afloja un expect hasta que pasa, y convierte una aserción precisa en una vaga que ya no atrapa el bug. Vigila las aserciones que se ablandaron entre una corrida y otra, y trata un test rojo como un hallazgo que investigar, no como un muro que hay que derribar.

El porcentaje de cobertura es una trampa, no una meta. Un skill que persigue el 100% va a probar las líneas que ya son obviamente correctas y se va a saltar la ruta de error fea que de verdad falla en producción, porque esa ruta cuesta más de montar. Cobertura alta con tests que calcan la implementación es el estado más peligroso de todos: se ve seguro y no lo es.

Los tests de caracterización afirman "no cambió", no "es correcto". Cuando le apuntas el skill a código legacy sin cobertura, deja claro que está capturando el comportamiento actual como red de seguridad, con bugs y todo. No dejes que "arregle" el comportamiento por su cuenta mientras escribe el test; eso anula el sentido de tener una red antes de tocar nada.

Una suite de tests solo vale lo que cuesta mantenerla si un fallo te dice algo verdadero. El skill test-author se gana ese lugar forzando la lista de casos primero, verificando el comportamiento en vez de las tripas y negándose a debilitar un chequeo solo por ver verde. Conecta esas restricciones y el skill se vuelve un revisor genuino del comportamiento de tu código. Sáltatelas y habrás automatizado la producción de tests inmortales, verdes y sin valor.