Personalizar Code Review

Ajusta lo que Code Review señala en tus pull requests con REVIEW.md y CLAUDE.md: recalibra la severidad, omite rutas, agrega comprobaciones y consulta qué copia se aplica.

Puedes cambiar lo que Code Review señala en tu repositorio confirmando instrucciones en él. Así es como reduces el volumen de nits, detienes los comentarios sobre archivos generados o agregas una regla que le importa a tu equipo. Colócalas en uno de estos dos archivos:

• CLAUDE.md: instrucciones del proyecto que Claude Code lee en cada tarea, incluidas las revisiones. Code Review las lee como contexto del proyecto y señala los cambios que las infringen.
• REVIEW.md: instrucciones exclusivas para las revisiones. Úsalo para indicar qué quiere tu equipo que se señale, con qué severidad y qué omitir.

Agrega REVIEW.md en la raíz de tu repositorio y fusiónalo. Luego protege tu rama predeterminada.

[!NOTE]

Para cambiar qué tan exhaustivas son las revisiones o cuándo se ejecutan, pídele a un Owner que cambie el nivel de revisión o el ajuste Review runs.

Usa CLAUDE.md para reglas de todo el proyecto

Code Review lee los archivos CLAUDE.md de tu repositorio como contexto del proyecto. Un cambio que infringe una de sus reglas se convierte en un hallazgo con el nivel de severidad que corresponda al problema.

Una revisión lee el CLAUDE.md de la raíz de tu repositorio y los archivos CLAUDE.md de los directorios padre de cada archivo modificado. El CLAUDE.md de un subdirectorio se lee cuando el pull request modifica un archivo bajo esa ruta.

Usa REVIEW.md para reglas exclusivas de revisión

REVIEW.md es un archivo en la raíz de tu repositorio que adapta Code Review a tu repositorio. En una rama protegida, también puedes agregar un REVIEW.md en la mayoría de los subdirectorios para añadir comprobaciones a los cambios bajo ese subdirectorio, además del archivo raíz.

Los agentes que encuentran problemas y los agentes que los verifican reciben su contenido como las instrucciones de revisión de tu repositorio, junto con las pautas de revisión predeterminadas de Code Review. El paso que redacta la revisión final lo consulta antes de definir la severidad y escribir el resumen.

Este diseño de ejemplo tiene un archivo raíz y un archivo en un subdirectorio:

your-repo/
├── REVIEW.md            # Root file
├── services/
│   └── billing/
│       └── REVIEW.md    # Adds checks for changes under services/billing/
└── src/

Antes de depender de un archivo en un subdirectorio, protege tu rama predeterminada y consulta qué lee una revisión según la configuración de tus ramas.

[!NOTE]

El servicio Code Review y el comando local /code-review son dos herramientas distintas y leen archivos diferentes. El servicio lee tanto CLAUDE.md como REVIEW.md. El comando /code-review, que ejecutas dentro de una sesión de Claude Code en tu propia máquina, lee tus archivos CLAUDE.md pero no REVIEW.md. Coloca en CLAUDE.md las pautas que quieras aplicar en ambos lugares y reserva REVIEW.md para reglas específicas de la revisión de pull requests.

Cuándo no se aplica un REVIEW.md de subdirectorio

Code Review no aplica un REVIEW.md que esté en un subdirectorio con uno de estos nombres, o por debajo de él, sin importar lo que contenga el subdirectorio. El nombre de un subdirectorio coincide solo si es completo, con cualquier combinación de mayúsculas y minúsculas y a cualquier profundidad, así que Tests coincide y integration-tests no:

• Pruebas: test, tests, __tests__, testdata, fixtures, __fixtures__, golden, corpus, snapshots, __snapshots__
• Ejemplos: example, examples, sample, samples, demo, demos
• Código generado: generated
• Código de terceros: vendor, third_party, third-party, thirdparty, node_modules, bower_components, external, extern, deps, godeps, pods, carthage, site-packages, contrib

Coloca las comprobaciones para esos subdirectorios en el REVIEW.md raíz, o en el REVIEW.md de un subdirectorio padre cuando ni ese padre ni nada por encima de él esté en la lista.

Los archivos REVIEW.md de subdirectorio restantes en las rutas que cambia un pull request comparten un límite de 150,000 bytes, sin contar el archivo raíz. Si la ejecución de comprobación reporta que algunos de ellos no cupieron, acorta los archivos para que se ajusten a ese límite.

Ejemplo de REVIEW.md

Este REVIEW.md recalibra la severidad para un servicio de backend, limita los nits, omite los archivos generados y agrega comprobaciones específicas del repositorio.

# Review instructions

## What Important means here

Reserve Important for findings that would break behavior, leak data,
or block a rollback: incorrect logic, unscoped database queries, PII
in logs or error messages, and migrations that aren't backward
compatible. Style, naming, and refactoring suggestions are Nit at
most.

## Cap the nits

Report at most five Nits per review.

## Do not report

- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rules

## Always check

- New API routes have an integration test
- Log lines don't include email addresses, user IDs, or request bodies
- Database queries are scoped to the caller's tenant

Elige qué escribir en REVIEW.md

REVIEW.md es markdown de formato libre que cambia lo que una revisión encuentra y reporta. No cambia el formato de la revisión. Busca el problema que estás viendo y luego agrega una instrucción como la que se muestra. El ejemplo usa las cuatro primeras.

• Se marcan como Important las cosas equivocadas: redefine qué significa 🔴 Important para tu repositorio. La calibración predeterminada apunta a código de producción, y un repositorio de documentación, un repositorio de configuración o un prototipo podrían necesitar una definición mucho más estrecha. Indica qué clases de hallazgos son Important y cuáles son, como mucho, Nit. También puedes escalar, por ejemplo, tratando cualquier infracción de CLAUDE.md como Important.
• Demasiados nits: limita cuántos comentarios 🟡 Nit publica una sola revisión. Un límite como "reporta como máximo cinco nits" mantiene las revisiones accionables.
• Comentarios sobre archivos generados o sobre lo que CI ya comprueba: enumera las rutas y categorías de hallazgos en las que Claude debe omitir hallazgos. Los candidatos habituales son el código generado, los lockfiles y las dependencias incluidas en el repositorio (vendored), junto con cualquier cosa que tu CI ya aplique, como el linting o la revisión ortográfica. Para rutas que merecen algo de revisión pero no un escrutinio completo, establece un umbral más alto: "en scripts/, reporta solo si es casi seguro y grave".
• No se comprueba una regla del equipo: agrega las reglas que quieras que se señalen en cada pull request, como "las nuevas rutas de API deben tener una prueba de integración".
• Hallazgos que resultan ser incorrectos: exige evidencia antes de que se publique una clase de hallazgo. Por ejemplo, "las afirmaciones sobre el comportamiento necesitan una cita file:line en el código fuente, no una inferencia a partir de los nombres" reduce los falsos positivos que, de lo contrario, le costarían al autor una ida y vuelta.

Algunas de estas instrucciones necesitan el archivo raíz en una rama predeterminada protegida.

Limita REVIEW.md a instrucciones que cambien el comportamiento de la revisión y deja el contexto general del proyecto en CLAUDE.md.

Incluye otros archivos en REVIEW.md

Puedes dividir las instrucciones de revisión en varios archivos e incorporarlos en tu REVIEW.md raíz. Usa esto cuando REVIEW.md se vuelva largo o cuando ya mantengas reglas de revisión en otro archivo.

Para incluir un archivo, agrega una línea al REVIEW.md raíz que contenga solo @ y el nombre del archivo. Code Review coloca el contenido del archivo en lugar de esa línea, de modo que se aplica como parte de REVIEW.md. En este ejemplo, el archivo raíz da una instrucción propia y luego incluye dos archivos de reglas:

# Review instructions

Report at most five Nits per review.

@review-security.md
@review-api.md

Guarda los archivos incluidos en la raíz del repositorio, junto a REVIEW.md:

your-repo/
├── REVIEW.md
├── review-security.md
└── review-api.md

Code Review incluye los archivos cuando lee REVIEW.md desde una rama protegida, así que consulta qué rama lee una revisión para tu repositorio:

• Rama protegida: Code Review coloca el archivo incluido en lugar de su línea @
• Rama predeterminada sin protección: la línea @ permanece en REVIEW.md como texto sin formato. Si el pull request cambia el archivo que nombra la línea, la línea se omite.

Cuando una revisión no aplica un archivo incluido, comprueba cada uno de estos puntos:

• Ubicación: mueve el archivo a la raíz del repositorio. Salvo en el caso de un archivo de skill, una ruta hacia un subdirectorio, como @docs/review-rules.md, no se incluye.
• Nombre: haz coincidir el nombre del archivo exactamente, incluidas mayúsculas y minúsculas, y usa un nombre sin espacios. Una línea cuyo nombre no coincide con ningún archivo junto a REVIEW.md permanece en REVIEW.md como texto sin formato, y la ejecución de comprobación no la reporta como una inclusión omitida.
• Un solo nivel: enumera todos los archivos en el REVIEW.md raíz. Una línea @ en un archivo incluido o en un REVIEW.md de subdirectorio permanece como texto sin formato (los archivos de skill son distintos), y un enlace de markdown a otro archivo no es una inclusión.
• Límites: incluye como máximo ocho archivos distintos y mantén REVIEW.md y los archivos que incluye por debajo de 150,000 bytes en conjunto. Un archivo que alcanzaría el límite de bytes se omite por completo, no se recorta. La ejecución de comprobación reporta cuántas líneas de inclusión omitió por cualquiera de los dos límites.
• Enlaces: mantén 64 enlaces de markdown o menos entre REVIEW.md y los archivos que incluye. Los enlaces a direcciones http, https o mailto y a anclas # no cuentan, ni tampoco los enlaces de un archivo de skill. Si se supera ese límite, la revisión omite todo tu REVIEW.md raíz, no solo los archivos incluidos. La ejecución de comprobación entonces indica que las instrucciones no se aplicaron.
• Copia fusionada: fusiona el archivo incluido en la rama desde la que se lee REVIEW.md. La revisión lee ambos desde el mismo commit, nunca desde los propios cambios del pull request.

Incluye un archivo de skill

Para que las revisiones sigan las pautas que mantienes en un skill, incluye el SKILL.md del skill en tu REVIEW.md raíz. Code Review no ejecuta skills.

Agrega @ y la ruta a SKILL.md, con la forma .claude/skills/<folder>/SKILL.md, en una línea propia:

# Review instructions

Report at most five Nits per review.

@.claude/skills/api-review/SKILL.md

Treat any change under `migrations/` as Important.

Protege la rama desde la que se lee REVIEW.md, porque Code Review incluye un archivo de skill solo cuando lee REVIEW.md desde una rama protegida. El archivo de skill cuenta para los límites de ocho archivos y 150,000 bytes, y tiene su propio límite de 30,000 bytes.

Escribe una línea de skill que Code Review incluya

Usa un nombre de carpeta sin espacios. Una línea con un espacio en su ruta permanece en REVIEW.md como texto sin formato, y la ejecución de comprobación no la reporta como una inclusión omitida.

Si la línea @ de un skill incumple alguna de las reglas siguientes, Code Review no incluye el skill desde esa línea:

• Ruta: escribe la ruta como .claude/skills/<folder>/SKILL.md desde la raíz del repositorio, con la carpeta del skill directamente bajo skills/. A diferencia de un nombre de archivo en la raíz, una ruta de esta forma que no coincide con ningún archivo se omite y se cuenta.
• Origen: copia las pautas de cualquier otro archivo bajo .claude/, o de un skill integrado, personal o de plugin, en un archivo junto a REVIEW.md. No puedes incluirlos directamente.
• Archivo: haz commit de SKILL.md como un archivo de texto normal. Code Review no sigue enlaces simbólicos, ya sea que el enlace sea el archivo o una carpeta de su ruta.
• Tamaño: mantén SKILL.md en 30,000 bytes o menos, incluido el frontmatter
• Cantidad: escribe como máximo ocho líneas de skill. Una línea repetida vuelve a contar para las ocho.
• Bloques en REVIEW.md: mantén la línea @ fuera de los bloques de código delimitados. Cierra cada comentario HTML y cada bloque <pre>, <script>, <style> o <textarea> que esté por encima de ella.

Cuando Code Review omite una línea de skill por incumplir la regla de Archivo, Tamaño, Cantidad o Bloques, el mensaje sobre líneas de inclusión omitidas de la ejecución de comprobación la cuenta. El mensaje aparece solo cuando la revisión aplica REVIEW.md desde una rama protegida.

Comprueba qué obtiene una revisión de un skill

Cuando el skill se incluye, una revisión obtiene el cuerpo de SKILL.md y nada más del skill, así que revisa el skill con la lista siguiente.

• Frontmatter: repite en el cuerpo todo lo que una revisión necesite del frontmatter, por ejemplo, las condiciones que description indica para usar el skill
• Comandos inyectados: escribe explícitamente lo que proporcionaría un comando !. Code Review no ejecuta el comando y reemplaza toda la línea o el bloque que lo contiene con un marcador de posición.
• Sustituciones: reemplaza $ARGUMENTS y otras sustituciones con texto fijo, porque una revisión no pasa argumentos y las deja tal como están escritas
• Archivos de apoyo: copia en SKILL.md lo que una revisión necesite, porque Code Review no carga scripts, archivos enlazados ni referencias @file
• Exclusiones y límites de Nit: escribe las instrucciones que excluyen hallazgos o limitan los Nits en REVIEW.md o en un archivo junto a él, no en el skill. Code Review no acepta el texto de un skill como motivo para ninguna de las dos cosas.
• Enlaces a archivos del repositorio: indica con palabras a qué apunta un enlace o una referencia @file. La revisión ve la ruta como texto sin formato o como un marcador de posición.

Si editas los comandos !, $ARGUMENTS o los enlaces del skill, también cambias cómo funciona en Claude Code. Si tu equipo depende de ellos, copia las pautas en un archivo junto a REVIEW.md e incluye ese archivo en lugar del skill.

Caracteres que Code Review cambia en el texto de un skill

Code Review cambia algunos caracteres del texto del skill, por lo que tus ejemplos de código llegan a una revisión con la forma siguiente.

In SKILL.md:       Use `items[0]`, never `List<String>`.
The review reads:  Use ˋitems(0)ˋ, never ˋList< String>ˋ.

In SKILL.md:       Run `ps | grep api` and ask @alice.
The review reads:  Run ˋps ¦ grep apiˋ and ask @ alice.

Cuando una regla dependa de uno de esos caracteres, indícala también con palabras.

Desde qué rama se lee REVIEW.md

Code Review lee REVIEW.md desde la rama base del pull request o desde la rama predeterminada, nunca desde los propios cambios del pull request. Para cambiar el comportamiento de la revisión, fusiona primero el cambio en REVIEW.md.

Mantén REVIEW.md en tu rama predeterminada y protege esa rama. Cuando una revisión lee la copia de una rama predeterminada protegida, la primera fila de la tabla siguiente, respeta estas instrucciones del archivo raíz:

• Reducir la severidad de un hallazgo
• Excluir rutas, archivos o clases de problemas
• Limitar los comentarios de tipo nit

Escribe las exclusiones y los límites de Nit en REVIEW.md o en un archivo junto a él, no en un skill incluido.

Qué cuenta como protección de rama

Code Review considera protección los siguientes ajustes:

• Rama predeterminada: una regla clásica de protección de rama o un ruleset
• Cualquier otra rama: solo un ruleset

Un ruleset cuenta cuando restringe las actualizaciones o exige pull requests con al menos una aprobación. Si exige pull requests, también debe descartar esa aprobación ante un nuevo push o exigir que la aprobación llegue después del último push.

Qué lee una revisión según la configuración de ramas

Busca la situación de tu repositorio en la primera columna de la tabla siguiente.

Si la ejecución de comprobación menciona REVIEW.md, consulta The check run mentions REVIEW.md.

Recursos relacionados

• Code Review: qué es el servicio y cómo se ejecuta una revisión
• Leer y solicitar revisiones en un pull request: qué significa cada nivel de severidad y cómo aparecen los hallazgos
• Configurar Code Review: el nivel de revisión y cuándo se ejecutan las revisiones, que establece un Owner
• Revisar localmente con /code-review: el comando /code-review, sus argumentos y los niveles de esfuerzo
• Memoria: cómo funcionan los archivos CLAUDE.md en Claude Code