Código que no se rompe

Le pides algo a Claude, te dice que ya quedó, y funciona. Dos días después se rompe algo que no tocaste. Pasa porque el mismo que escribió el código es el que dice que está bien, y a nadie le gusta encontrarse errores en lo que acaba de hacer.

Lo que ayuda es ponerle enfrente a otro que no estuvo ahí. Esta guía junta cuatro pasos en un solo proceso, del plan antes de programar hasta una prueba de tu app como si fueras un usuario. Todo corre dentro de la app de Claude Code y cada paso trae el prompt listo para pegar.

Cuando le pides algo grande a Claude sin plan, rellena los huecos con lo que a él le parece razonable, y rara vez coincide con lo que tú tenías en la cabeza. Para eso sirve el PRD: un documento corto con lo que vas a construir, para quién y qué cuenta como terminado. Lo lees tú, lo lee Claude, y los dos van para el mismo lado.

Para llegar a ese documento usamos la idea de Grill Me, una skill del repo de Matt Pocock: en vez de ponerse a construir, Claude te interroga, con una respuesta recomendada en cada pregunta, hasta que no queda ninguna decisión abierta. No hace falta instalarla. El prompt de abajo pide lo mismo y lo pegas tal cual.

1. 1

   Pega el prompt de la entrevista

   Con tu idea en una frase.

2. 2

   Contesta todo

   Y di no sé cuando no sepas.

3. 3

   Pide el PRD

   Se guarda en docs/prd.md.

4. 4

   Léelo y corrígelo

   Solo entonces dile que construya.

Déjate interrogar

Cuéntale en una frase qué quieres construir y contesta con calma. Cuando no sepas, di que no sabes: esa es justo la decisión que de otro modo habría tomado Claude solo.

Quiero construir [tu idea en una frase, por ejemplo: una página donde mis clientes agenden y paguen una llamada].
Antes de escribir una sola línea de código, interrógame hasta que no quede ninguna decisión abierta.
Reglas:
- Hazme las preguntas en rondas numeradas, de 3 a 5 a la vez.
- En cada pregunta dime la respuesta que tú recomendarías, para que yo pueda decir solo "sí, esa".
- Si algo lo puedes averiguar mirando mi proyecto, míralo tú en vez de preguntármelo.
- No asumas nada por mí. Yo no programo: usa palabras sencillas.
Cuando ya no queden dudas, dime en pocas líneas qué entendiste y espera mi respuesta.

Si después quieres la skill original, con /grill-me ya armado, está en el repo mattpocock/skills (enlace al final de la guía).

Convierte la entrevista en un PRD

Cuando la entrevista termine, no sigas con el código. Pídele a Claude que deje todo lo que contestaste en un archivo, y léelo tú antes de seguir. Si algo no suena a lo que querías, corrígelo ahí, que es barato. Corregirlo después en el código no lo es.

Con todo lo que contesté en la entrevista, escribe un PRD (el documento de lo que vamos a construir) en docs/prd.md. Usa lenguaje sencillo, sin tecnicismos.
Debe tener: qué problema resuelve y para quién, qué sí entra y qué NO entra, los pasos que sigue una persona al usarlo, qué cuenta como terminado (cosas que se puedan comprobar abriendo la app) y las preguntas que quedaron abiertas.
No escribas código todavía. Cuando termines, dime en tres líneas qué entendiste y espera mi visto bueno.

Cuando Claude dice que terminó, lo que terminó es su versión de la tarea. Antes de aceptarla, pídele que cambie de papel: que deje de ser el que construye y se ponga a buscar en qué falla. Es el mismo Claude, pero con una instrucción distinta encuentra cosas que antes dejó pasar.

Revisa el código que acabas de escribir como un crítico que quiere encontrar errores. No me digas que está bien: busca en qué puede fallar, qué casos no probaste y qué parte depende de algo que asumiste.
Después déjalo más simple: quita lo que sobra, lo que repite y lo que nadie va a usar.
Para cada cosa que encuentres, dime en una línea qué era, por qué importaba y qué cambiaste. Si no encuentras nada, dímelo y explica qué revisaste.

Si prefieres un comando, /simplify

Claude Code trae /simplify. Lanza cuatro revisores a la vez, que miran si hay código repetido, si se puede hacer más sencillo, si es lento y si el cambio está en el lugar correcto, y aplica los arreglos. Necesita la versión 2.1.154 o más reciente.

Tiene un límite que conviene saber: no caza bugs. Deja el código más limpio, pero eso no lo vuelve correcto. Para buscar errores usa el prompt de arriba o el paso 3.

Cuando buscas un error en específico

Aquí el peligro es que Claude se lance a arreglar lo primero que se le ocurra y te meta un segundo problema encima del primero. La salida es separar investigar de arreglar: que mande varios ayudantes a mirar cada uno una pista distinta, y que no toque nada hasta que te cuenten qué encontraron.

Tengo este problema: [describe qué pasa y cuándo, con tus palabras].
No arregles nada todavía. Lanza varios ayudantes (subagentes) y que cada uno investigue una causa posible distinta, por ejemplo: un cambio reciente, un dato que llega mal, algo que depende del navegador o del orden en que pasan las cosas.
Cuando todos terminen, dime qué encontró cada uno, cuál causa crees que es la real y por qué. Espera mi respuesta antes de modificar un solo archivo.

Pedirle a Claude que se critique ayuda, pero sigue siendo él mismo, con toda la conversación en la cabeza y las razones por las que tomó cada decisión. En proyectos grandes conviene un revisor nuevo: un agente con su propia ventana, que no escribió nada y solo juzga. Como no vio cómo se hizo, no tiene nada que defender.

Lo que le falta es saber qué es bien hecho en tu proyecto, y eso solo lo sabes tú. Por eso el revisor lleva una lista. No tiene que ser larga: cinco o seis reglas que de verdad te importen.

Ejemplos de una lista de bien hecho

Crea un agente revisor de este proyecto y guárdalo en .claude/agents/revisor.md.
Su trabajo es solo juzgar: nunca escribe ni modifica código. Revisa lo que cambió contra docs/prd.md y contra esta lista de lo que es bien hecho:
- Hace lo que dice el PRD y cada punto de terminado se puede comprobar.
- No se rompe con datos raros: campos vacíos, textos muy largos, doble clic.
- Se entiende: nombres claros, nada repetido y nada que sobre.
- No expone claves ni datos de otras personas.
- [agrega aquí las reglas propias de tu proyecto]
Debe devolver un veredicto claro (aprobado o no aprobado) y una lista de problemas, cada uno con qué falla, dónde y cómo se comprueba. Que no sea amable por quedar bien: si algo no cumple, que lo diga.

Para usarlo, dile a Claude: usa el revisor para revisar lo último que hicimos. Si cambias de idea sobre alguna regla, edita el archivo o pídele a Claude que lo haga.

Y dos revisores que ya vienen de fábrica

No tienes que empezar de cero. Claude Code trae dos comandos que son, en el fondo, revisores con su propia ventana. Escríbelos en el chat de la app cuando termines un cambio.

Tu revisor con lista y estos dos se complementan: los de fábrica no saben qué es bien hecho para ti, y el tuyo no sabe tanto de seguridad. Los niveles y las opciones de cada comando están en la guía Revisa tu código con Claude.

Hay dos cosas con nombres parecidos que no son lo mismo. El plugin code-review del repo de Anthropic revisa pull requests de GitHub y necesita la herramienta gh. Y claude-code-security-review es la versión de /security-review como GitHub Action, que pide una API key. Si trabajas solo y desde la app, no necesitas ninguna de las dos.

Este es el paso que más tiempo ahorra. Hasta ahora el revisor leía código. Ahora va a abrir tu app como lo haría una persona: hace clic, llena formularios y prueba todo. Si algo falla, se lo regresa al que programa, que lo arregla, y el revisor vuelve a probar. Tú entras hasta que ya funciona.

Para que el revisor maneje el navegador necesita Playwright, una herramienta que lo hace solo. Instálala una vez.

Si no quieres escribir el comando, pídele a Claude que lo corra por ti. Si después no ves las herramientas del navegador, abre una sesión nueva.

O usa el navegador que ya trae la app

La app de Claude Code tiene un panel de navegador propio, que en Mac se abre con Cmd+Shift+B. Claude puede levantar tu proyecto ahí, hacer clic, llenar formularios y tomar capturas, sin instalar nada. Usa un perfil limpio, así que no ve tus cuentas ni tus sesiones iniciadas: si tu app pide iniciar sesión, el revisor tendrá que entrar con un usuario de prueba.

Playwright sirve más cuando quieres pruebas más largas o que corran siempre igual. El panel es lo más rápido para empezar.

El prompt del ciclo

Vamos a trabajar en ciclo. Tú eres el que construye y el agente revisor es el que juzga. Quiero implementar esto: [lo que quieres cambiar o construir].
El ciclo es así:
1. Construye el cambio siguiendo docs/prd.md.
2. Llama al agente revisor. Pídele que abra la app en el navegador como lo haría una persona (con Playwright o con el panel del navegador), que haga clic y pruebe cada punto de terminado del PRD, y que intente también cosas raras: campos vacíos, doble clic, volver atrás.
3. Si el revisor reporta fallas, arréglalas y vuelve al paso 2. Arregla lo que de verdad importa; no persigas cada detalle menor.
4. Para y avísame cuando el revisor apruebe, o después de 3 vueltas aunque todavía haya fallas. En ese caso dime qué sigue sin funcionar y por qué.
Al final dame un resumen corto: qué se construyó, qué probó el revisor y qué encontró en cada vuelta.

El tope de vueltas importa. Si le pides fallas a un revisor, va a encontrar alguna, y sin un límite el ciclo se queda puliendo detalles que a nadie le importan. Tres vueltas suelen alcanzar. Si después de tres sigue fallando lo mismo, ya no es un detalle suelto y conviene volver al plan.

Cuando el ciclo termine, corre /code-review y /security-review una última vez. El revisor del ciclo prueba la app, y los comandos de fábrica leen el código, así que cada uno encuentra cosas que el otro no ve.

No hace falta hacer los cuatro cada vez. Para algo chico, basta el paso 2. Para algo grande o que toca dinero, datos o cuentas de otras personas, haz los cuatro.

1. 1

   Plan

   El prompt de la entrevista con tu idea, y luego el del PRD. Léelo antes de seguir.

2. 2

   Construcción

   Claude construye siguiendo docs/prd.md.

3. 3

   Crítica

   El prompt de crítico y simplificar. Para un bug, el de los ayudantes en paralelo.

4. 4

   Revisor aparte

   El agente revisor con tu lista de bien hecho, más /code-review y /security-review.

5. 5

   Ciclo

   Constructor y revisor con pruebas en el navegador, con tope de 3 vueltas.

6. 6

   Tu turno

   Entras tú, abres la app y la pruebas con tus manos antes de publicar.