Santiago.

🔒 Un candado para el vibe coding: un revisor de PRs con Claude

3 de octubre de 2026 · 7 min de lectura

Estoy trabajando en un proyecto y me pasó algo que me gustó mucho: Claude, corriendo dentro de GitHub Actions, revisó y corrigió mis pull requests (PR). Me pareció muy bacano y muy eficiente, tanto que quise entender cómo funciona para contártelo aquí. Para mí es como un candado 🔒 para el vibe coding: te deja avanzar rápido, pero asegura que no se te escape nada.

🧠 El problema: el agente pierde contexto

Cuando programas con IA, lo que ya se conoce como vibe coding (decirle a la IA lo que quieres y dejar que escriba el código, muchas veces aceptándolo sin leerlo a fondo), el agente con el que estás programando a veces se pierde en cositas. Por más que uno trate de darle siempre contexto, a medida que la sesión se alarga lo va perdiendo, y algunas cosas se le pasan: una regla de negocio, un caso borde, un archivo que también dependía de lo que cambió.

El revisor funciona distinto. Arranca cada vez con la cabeza limpia, con una sola misión: revisar ese pull request. No arrastra una conversación de horas, y por eso, en mi experiencia, es mucho más eficiente encontrando lo que el agente de programación dejó pasar.

🤖 ¿Qué es?

Claude Code GitHub Actions es una Action de GitHub (anthropics/claude-code-action) que ejecuta Claude Code dentro de los workflows de tu repositorio. Funciona de dos maneras:

  • Interactivo: lo mencionas con @claude en un comentario de un PR o de un issue y responde ahí mismo.
  • Automático: le das un prompt y se ejecuta solo cuando pasa algo en el repositorio, por ejemplo cada vez que se abre un pull request.

Para un revisor nos interesa el segundo.

Ojo con una diferencia: el revisor que montamos más abajo comenta, no modifica código. Si además quieres que Claude haga la corrección, lo mencionas con @claude, y para que pueda subir cambios el workflow necesita permisos de escritura (contents: write y pull-requests: write).

⚙️ Cómo implementarlo

⚡ El camino rápido. Abre claude dentro de tu repositorio y ejecuta /install-github-app. Instala la app de GitHub, guarda el secreto de autenticación y te deja listo un pull request con los workflows. Necesitas ser administrador del repositorio, tener el GitHub CLI autenticado (gh auth login) y que el repositorio esté en github.com.

🛠️ El camino manual. Son tres pasos:

  1. Instalar la app de Claude en tu repositorio.
  2. Guardar un secreto: ANTHROPIC_API_KEY (clave de API) o CLAUDE_CODE_OAUTH_TOKEN (si usas una suscripción).
  3. Crear un workflow en .github/workflows/.

Este workflow revisa cada pull request cuando se abre o se actualiza, usando el plugin de revisión oficial:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Lo importante de cada parte:

  • on: pull_request: se dispara al abrir, actualizar, reabrir o marcar como listo un PR.
  • plugins y prompt: instalan el plugin code-review y ejecutan su revisión sobre ese PR.
  • --comment: Claude publica la revisión en el propio PR, con un comentario en línea por cada problema, o con uno de resumen si no encuentra nada. Sin esta opción, solo verías el resultado en el log de la ejecución.
  • claude_args: conserva esta línea, porque es la que habilita los comentarios en línea.
  • Claude se salta los PRs en borrador, los cerrados, los triviales y los que ya tienen un comentario suyo.

🎯 Lo que más importa: el prompt del revisor

Aquí está la diferencia entre un revisor que solo hace ruido y uno que de verdad te ayuda. La calidad del revisor depende en gran parte del prompt que le programes. El plugin oficial ya trae el suyo, pero si quieres un revisor que conozca tu negocio y tu arquitectura, escribes el tuyo (o un skill). Estas son las cosas que, desde mi experiencia, hay que darle:

  • 💼 Contexto del negocio. Qué hace el producto y para quién, cuáles son los flujos críticos y las reglas que no se pueden romper: cómo se calculan los montos, quién puede ver o modificar qué, qué estados son válidos. Sin esto, el revisor solo ve código; con esto, ve si el código hace lo que el negocio necesita.
  • 🏗️ Contexto de la arquitectura. Las capas y sus responsabilidades, las convenciones, los patrones que hay que respetar y lo que está prohibido, por ejemplo meter lógica de negocio en los controladores. Si tienes documentos de arquitectura o decisiones registradas, indícale dónde están.
  • 📋 Qué revisar y en qué orden. Primero lo que más cuesta: errores de lógica y casos borde, seguridad, integridad de los datos, riesgo de romper otras partes y pruebas que faltan.
  • 🚫 Qué ignorar. El formato y el estilo que ya valida el linter, y las preferencias personales. Si no, te llena el PR de ruido.
  • 🔍 Que mire más allá del diff. Pídele que revise quién usa lo que cambió, no solo las líneas modificadas. Muchos errores están en lo que el diff no muestra.
  • 💬 Cómo debe responder. Que clasifique cada hallazgo (bloqueante, importante o sugerencia), que indique archivo y línea, el impacto y la corrección propuesta. Que diga cuando tiene una duda en lugar de inventar, y que, si todo está bien, lo diga en una sola frase.

Una plantilla para empezar:

Eres el revisor senior de este repositorio. Revisa el pull request actual.

Contexto del negocio:
- Qué hace el producto y para quién.
- Reglas críticas: cómo se calculan los montos, quién puede ver o
  modificar qué, estados válidos de cada proceso.

Contexto de la arquitectura:
- Capas y responsabilidades (API, servicios, acceso a datos).
- Convenciones y patrones que se deben respetar.
- Lo que está prohibido (por ejemplo, lógica de negocio en controladores).

Qué revisar, en este orden:
1. Errores de lógica y casos borde.
2. Seguridad y manejo de datos sensibles.
3. Integridad de los datos y transacciones.
4. Riesgo de romper otras partes: revisa quién usa lo que cambió,
   no solo el diff.
5. Pruebas que faltan.

Qué ignorar: formato y estilo que ya valida el linter, y preferencias
personales.

Cómo responder:
- Clasifica cada hallazgo como bloqueante, importante o sugerencia.
- Indica archivo y línea, explica el impacto y propone la corrección.
- Si no estás seguro, dilo como duda; no inventes.
- Si todo está bien, dilo en una sola frase.

Dónde ponerlo, según cómo trabajes:

  • En el prompt del workflow. Con un texto propio, Claude no tiene acceso a la terminal ni a la API de GitHub hasta que le des las herramientas que necesita con --allowedTools en claude_args. Indícale también cuál PR revisar: el número viene en ${{ github.event.pull_request.number }}.
  • En un skill del repositorio. Lo guardas en .claude/skills/, haces el checkout antes y pasas /nombre-del-skill como prompt. Así el prompt queda versionado y se revisa como cualquier otro código.
  • En el CLAUDE.md. Es el lugar para el estilo de código, los criterios de revisión y las reglas del proyecto. Claude lo lee en cada ejecución. Mantenlo corto, porque se lee cada vez.

Y no esperes que quede perfecto a la primera. Mira qué falsos positivos te da, qué cosas se le escapan, y ajusta el prompt. Es un trabajo iterativo, como afinar cualquier otra herramienta.

🛡️ Cuidados que no debes olvidar

  • 🔑 Secretos: nunca subas claves al repositorio; guárdalas como secrets de GitHub.
  • 🔐 Permisos mínimos: dale al workflow solo lo que necesita. En el ejemplo, solo lectura de código, PRs e issues, más id-token: write, que la Action necesita para autenticarse. Si quieres que Claude suba correcciones, necesitará escritura: dásela solo al workflow que lo requiera.
  • 💰 Costos: cada ejecución gasta minutos de GitHub Actions y tokens de la API (o de tu suscripción, si autenticas con un token OAuth). --max-turns, los timeouts y el control de concurrencia ayudan a limitarlo.
  • 🌐 Repositorios públicos: GitHub no entrega los secretos a las ejecuciones de PRs que vienen de forks.
  • 🧑‍💻 Tú decides: el revisor no reemplaza el criterio humano. Revisa sus comentarios y los cambios de Claude antes de hacer merge.

Si no quieres mantener un workflow, existe también Code Review, el producto de Claude que revisa cada pull request automáticamente sin que escribas ninguno.

💡 Mi conclusión

🔒 El vibe coding es poderoso, pero necesita su candado. Para mí, la IA no quita responsabilidad: la reparte mejor. Yo escribo con ayuda de la IA, un revisor con la cabeza limpia y buen contexto revisa, y yo decido. Esa combinación es la que me da tranquilidad para avanzar rápido.

✍️ Por Santiago Perea Restrepo

← Volver