Prompt de revisión de código: seis reglas y una plantilla

Por qué la mayoría de los prompts de revisión generan ruido

La mayoría de los prompts de revisión de código son una lista de temas: «Revisa este código; fíjate en los errores, las vulnerabilidades de seguridad, el rendimiento y la legibilidad». El modelo se toma la lista al pie de la letra y escribe algo debajo de cada apartado. El resultado es un comentario largo, amable y en gran parte inútil. El autor del pull request o lo lee entero y descarta casi todo, o no lee nada.

Lo que de verdad cambia la respuesta es exigir pruebas: el modelo escribe lo que puede demostrar y calla lo que no. En diffox, cuando repartimos un pull request entre 17 agentes especializados, las instrucciones de cada agente empiezan con esa misma exigencia (cómo funciona, en otro artículo). Las seis reglas de abajo salen de esa experiencia y de la documentación de las propias herramientas.

Las seis reglas

1. Pide pruebas. Que cada hallazgo llegue con una entrada o un estado concretos que produzcan el resultado erróneo: «Con la lista vacía, el promedio divide entre cero». Si el modelo no puede construir un escenario así, debe callar. Esta sola frase elimina la mayoría de los comentarios del tipo «también convendría revisar esto».
2. Pide una cita literal, no un número de línea. Los modelos no son fiables contando líneas; una cita, en cambio, se puede buscar en el archivo y encontrar. La documentación de Anthropic recomienda la misma técnica: si el modelo no encuentra una cita que respalde lo que afirma, debe retirar la afirmación (fuente).
3. Limita el alcance a este cambio. La revisión es para los problemas que causan las líneas que el pull request añade o modifica. Cargarle al autor de hoy cada defecto del código antiguo hace que nadie lea el comentario.
4. Deja fuera las cuestiones de gusto y lo que ya revisan tus herramientas. El formato, una preferencia al poner nombres o un comentario que falta no son hallazgos de revisión; no le pidas al modelo que repita lo que ya señalan el linter y el comprobador de tipos. La documentación de Codex dice lo mismo: las comprobaciones de formato y de lint se dejan a la CI.
5. Define la gravedad. Qué es «bloqueante» y qué es «menor» lo escribes tú: un resultado erróneo, una pérdida de datos o una vulnerabilidad de seguridad son bloqueantes; lo que solo aparece en un caso poco frecuente o se reduce a un nombre engañoso es menor. Sin definición, todo hallazgo sale «importante».
6. Fija el formato de la respuesta. Que cada hallazgo llegue con los mismos campos: archivo, cita, escenario, resultado erróneo, gravedad y una corrección de una línea. Si no hay hallazgos, que el modelo lo diga en una línea y se detenga; que no rellene una revisión vacía.

Lo que tienen en común las seis reglas es que describen una comprobación que el modelo puede hacer. «Ten cuidado» no se puede comprobar; «¿está la cita en el archivo?» sí.

Copia esta plantilla y adáptala a tu repositorio

El prompt de abajo reúne las seis reglas en un solo texto. Está escrito en inglés, porque las cuatro herramientas siguen sin problema instrucciones en inglés; el idioma de los comentarios lo fija la última línea. Hay dos partes que cambiar: la definición de gravedad y la lista «Do not report».

You are reviewing a pull request. Report only defects that this
change introduces or exposes.

A finding is valid only if you can state all three:
1. the code, quoted word for word from the changed lines;
2. a concrete input or state that reaches that code;
3. the wrong result that follows, and what the right one would be.
If you cannot state all three, do not report it.

Do not report: style, formatting, naming taste, missing comments,
anything a linter or a type checker already reports, or code this
change did not touch.

Severity:
- blocking: wrong result, data loss, security hole, or a crash on
  an ordinary path
- minor: wrong only on a rare path, or a name, comment or test that
  says something the code does not do

For each finding give: file, the quoted code, the scenario, the
wrong result, severity, and a one-line fix.
If you find nothing, write "No findings" and stop.
Write the findings in Spanish.

La plantilla es corta a propósito. La documentación de Claude Code advierte que la longitud tiene un coste: un archivo de instrucciones largo diluye las reglas que más importan. Cuando añadas reglas propias, comprueba si cada línea nueva cambia algún hallazgo.

¿Qué archivo lee cada herramienta?

Dónde escribir el prompt depende de la herramienta. La tabla de abajo sale de la documentación de cada una de las cuatro, leída el 15 de octubre de 2026.

Fuente: la documentación de cada herramienta, 15 de octubre de 2026.

Hay dos detalles que suelen pasarse por alto. En Claude Code, REVIEW.md solo lo lee el Code Review de GitHub; el /code-review del terminal no lo lee. Copilot, por su parte, lee las instrucciones de la rama head del pull request: un pull request que cambia el archivo de instrucciones cambia también las reglas de su propia revisión.

Para convertir tu propio prompt en un comando de Claude Code, escribe una skill (habilidad): pon la plantilla en .claude/skills/revisar/SKILL.md y añade al principio la línea !`git diff main...HEAD`. Esa línea ejecuta el comando y mete su salida en el prompt; cuando escribes /revisar, el modelo ya tiene el diff delante (documentación de skills).

Cómo escribir las reglas de tu repositorio

La plantilla cubre lo general; el valor de verdad está en las reglas propias de tu repositorio. Son lo que repites en cada revisión: qué dato no puede cruzar qué capa, qué efecto secundario es peligroso, qué contrato no se puede romper.

Una buena regla tiene tres partes, y la documentación de Codex enumera las tres: el comportamiento que hay que señalar, por qué importa y el camino seguro o la excepción. La tercera es la que más se olvida: si no le dices al modelo cuál es el camino correcto, también señalará como error el comportamiento esperado.

• Débil: «Ten cuidado con las consultas a la base de datos».
• Fuerte: «Cada consulta debe limitarse al tenant de quien la llama. Camino seguro: la función auxiliar scoped(). Excepción: los informes de administración».

También puedes exigir pruebas a nivel de repositorio. El ejemplo de la documentación de Claude Code: una afirmación sobre el comportamiento debe señalar un archivo y una línea del código fuente, no deducirse de los nombres. Esta sola regla reduce las falsas alarmas que le cuestan al autor una ronda de trabajo en vano.

Cuando un prompt no basta

Si a un solo prompt le preguntas a la vez por seguridad, concurrencia, pruebas y cumplimiento de las reglas, el modelo reparte su atención y encuentra un poco de cada cosa. En los cambios grandes funciona dividir el trabajo: cada prompt busca una sola cosa y debe demostrar lo que encuentra.

El segundo paso es comprobar lo que dice el modelo. El modelo puede escribir algo convincente pero falso: citar una línea que no está en el archivo u objetar código que el cambio no tocó. Como pides una cita, eso lo puede comprobar un programa: ¿la cita está de verdad en ese archivo y pertenece a las líneas cambiadas? La documentación del Code Review de Claude Code describe el mismo esquema: cada agente busca una clase distinta de problema y después un paso de verificación descarta las falsas alarmas.

En diffox, estos dos pasos los hace el propio producto: cada uno de los 17 agentes especializados del equipo busca una sola cosa y muestra lo que encuentra con una cita literal del código; la cita no la comprueba el modelo, sino el código. Las frases que expresan una obligación en el archivo de reglas de la raíz de tu repositorio (AGENTS.md o CLAUDE.md) también llegan a los agentes como reglas de revisión.

Prueba la regla en un pull request real

Si un prompt es bueno no se sabe leyéndolo. El consejo de la documentación de Codex es el más práctico: abre un pull request representativo, pide una revisión, corrige las reglas según los hallazgos que lleguen y acota o quita la instrucción que genera ruido.

• Pruébala en un cambio con una infracción que la regla debería detectar: ¿la detecta?
• Pruébala en un cambio que usa el camino seguro: ¿se calla?
• Pruébala en un cambio que no tiene nada que ver: ¿sigue callada?

Si pides dos veces la revisión del mismo pull request, puedes obtener dos resultados distintos; un solo intento no es un resultado. Compara los resultados antes y después de añadir una regla, siempre sobre los mismos pocos pull requests.