Mejora la calidad de tus Pull Requests con Claude Code
Usa Claude Code con plantillas de PR, CI, pruebas y handoff para reducir PRs ruidosos generados con IA.
Un Pull Request es el lugar donde un equipo propone, revisa y fusiona cambios. La documentación oficial de GitHub lo presenta como una pieza central de colaboración, y esa idea se vuelve más importante cuando Claude Code acelera la implementación. El cuello de botella deja de ser escribir código y pasa a ser explicar el cambio: descripciones vagas, diffs enormes, pruebas poco claras, riesgos de seguridad sin revisar y comentarios de review que vuelven una y otra vez.
En esta guía usaremos Claude Code como asistente de calidad de PR, no como generador de texto bonito. Un diff es el conjunto de líneas cambiadas, CI es la puerta automática de tests y builds, un diff-size budget es el límite de tamaño del PR, y handoff es la nota breve que permite que otro reviewer continúe sin releer todo. Para ampliar el flujo, consulta también la guía de code review con Claude Code y las estrategias de testing.
flowchart LR
A["Implementar con Claude Code"] --> B["Completar plantilla de PR"]
B --> C["Limitar diff en CI"]
C --> D["Añadir evidencia de pruebas"]
D --> E["Preparar handoff"]
E --> F["Borrador de release notes"]
Las fuentes oficiales usadas aquí son GitHub Pull Requests, plantillas de Pull Request, sintaxis de workflows de GitHub Actions, protected branches, secrets en GitHub Actions, Claude Code docs y, si usas categorías de commits, Conventional Commits.
Fija el estándar en una plantilla de PR
Si cada vez pides a Claude Code “redacta una buena descripción de PR”, el resultado dependerá del contexto del momento. Es mejor guardar el contrato de review en .github/pull_request_template.md. GitHub puede insertar esa plantilla automáticamente en el cuerpo del PR, de modo que la definición de “listo para revisar” queda dentro del repositorio.
## Qué cambió
<!-- Separa implementación, configuración, documentación y archivos generados. -->
## Por qué se necesita
<!-- Enlaza issue, incidente, petición de usuario o decisión de diseño. -->
## Foco de review
- [ ] Lógica de negocio
- [ ] UI/UX
- [ ] Contrato de API o base de datos
- [ ] Seguridad y privacidad
## Evidencia de pruebas
- [ ] Tests automáticos:
- [ ] Comprobación manual:
- [ ] Capturas o grabación:
## Tamaño del diff
- Archivos modificados:
- Líneas añadidas/eliminadas:
- Por qué no se dividió:
## Seguridad y operación
- [ ] No contiene secrets, tokens ni datos personales
- [ ] Los logs no exponen credenciales ni datos personales
- [ ] Permisos, variables de entorno y feature flags revisados
- [ ] Plan de rollback escrito
## Handoff para reviewers
<!-- Archivos a leer primero, decisiones abiertas, riesgos y PRs posteriores. -->
Los campos más útiles suelen ser “por qué no se dividió” y “plan de rollback”. Cuando están vacíos, el PR suele ser demasiado amplio o no explica cómo se operará en producción. Claude Code puede completar la plantilla, pero la plantilla define la calidad mínima.
Genera el cuerpo del PR con hechos
Después de crear la plantilla, pide a Claude Code que la rellene desde el diff. La regla más importante es no inventar hechos. Si no hay evidencia de pruebas, debe decir “no ejecutado”. Si el impacto no aparece en el diff, debe marcarlo como pendiente de confirmar.
git diff origin/main...HEAD | claude -p "
Lee este diff y redacta el cuerpo del Pull Request usando .github/pull_request_template.md.
Reglas:
- No inventes hechos que no sean visibles en el diff
- Si falta evidencia de pruebas, escribe 'no ejecutado'
- Explica los términos técnicos la primera vez que aparezcan
- Limita el foco de review a los 3 archivos o áreas más importantes
- Revisa secrets, tokens, datos personales y logs riesgosos
- Termina con una lista de puntos que una persona debe confirmar
"
Así el PR deja de ser un resumen genérico y se convierte en un mapa para revisar. El reviewer puede empezar por la función de autorización, la pantalla modificada o la migración, en lugar de leer todo el branch desde cero.
Pon un presupuesto de tamaño en CI
Los PRs grandes reducen la profundidad de la revisión. Claude Code puede formatear, renombrar, refactorizar, escribir tests y documentar en la misma sesión. Eso es cómodo, pero mezcla objetivos. Un diff-size budget convierte “esto se siente grande” en una regla concreta.
En un proyecto Node, añade scripts/check-pr-size.mjs. El script ignora lockfiles y salidas generadas, y cuenta lo que realmente debe revisar una persona.
#!/usr/bin/env node
import { execFileSync } from "node:child_process";
const [range = "origin/main...HEAD", maxLinesRaw = "700", maxFilesRaw = "35"] =
process.argv.slice(2);
const maxLines = Number(maxLinesRaw);
const maxFiles = Number(maxFilesRaw);
const ignored = [
/^package-lock\.json$/,
/^pnpm-lock\.yaml$/,
/^yarn\.lock$/,
/^dist\//,
/^coverage\//,
];
function numeric(value) {
const parsed = Number(value);
return Number.isFinite(parsed) ? parsed : 0;
}
const output = execFileSync("git", ["diff", "--numstat", range], {
encoding: "utf8",
}).trim();
let files = 0;
let lines = 0;
for (const row of output.split(/\r?\n/).filter(Boolean)) {
const [added, deleted, file] = row.split("\t");
if (ignored.some((pattern) => pattern.test(file))) continue;
files += 1;
lines += numeric(added) + numeric(deleted);
}
if (files > maxFiles || lines > maxLines) {
console.error(
`PR is too large: ${files} files / ${lines} changed lines. ` +
`Budget is ${maxFiles} files / ${maxLines} lines.`,
);
console.error("Split formatting, generated files, and behavior changes into separate PRs.");
process.exit(1);
}
console.log(`PR size OK: ${files} files / ${lines} changed lines.`);
Conéctalo a GitHub Actions. Los workflows viven en .github/workflows, y después puedes convertir este job en required status check dentro de una rama protegida.
name: PR quality
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: read
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Install dependencies
run: npm ci
- name: Run project checks
run: |
npm run lint --if-present
npm test --if-present
- name: Enforce PR size budget
run: node scripts/check-pr-size.mjs "origin/${{ github.base_ref }}...HEAD" 700 35
No hace falta discutir si 700 líneas es una ley universal. Es un punto de partida. Si el PR es una migración o un refactor mecánico, puede tener una excepción, pero esa excepción debe explicarse en el cuerpo del PR.
Deja evidencia de pruebas reproducible
“Tests pasados” es una frase débil. El PR debe mostrar comandos, resultados, comprobaciones manuales, capturas si hay UI, y una lista de lo que no se verificó. Claude Code puede formatear esa sección, pero no debe afirmar que algo se ejecutó si no ocurrió.
claude -p "
Prepara la sección de evidencia de pruebas para el Pull Request de este branch.
Formato:
## Tests automáticos
- Comando:
- Resultado:
- Motivo de fallo, si aplica:
## Comprobación manual
- Pantalla, API o job revisado:
- Datos de entrada:
- Resultado esperado:
- Resultado real:
## No verificado
- Elementos pendientes:
- Quién debe verificarlos antes del merge:
Usa solo hechos. No marques como aprobado un comando que no se ejecutó.
"
Hay tres casos típicos. Un cambio de UI necesita capturas, anchos de pantalla y notas de accesibilidad. Un cambio de API necesita compatibilidad, respuestas de error y comportamiento de logs. Una migración o batch necesita dry run, rollback y tiempo estimado. Separar esos casos ayuda a que cada reviewer empiece por lo que domina.
Revisa seguridad y privacidad por PR
El código generado con IA puede tocar más archivos de los previstos. Un secret puede aparecer en ejemplos, logs, fixtures o capturas. Los secrets de GitHub Actions sirven para valores sensibles en workflows, pero no autorizan imprimirlos en logs ni pegarlos en el PR.
Revisa este diff desde seguridad y privacidad.
Checklist:
1. Secrets, tokens, API keys, cookies y session IDs
2. Datos personales en logs, fixtures, capturas o errores
3. Permisos aplicados en servidor, no solo ocultos en UI
4. Permissions de GitHub Actions demasiado amplios
5. Errores que expongan rutas internas o credenciales
6. Feature flags o variables de entorno que cambien el rollout
Devuelve severidad High/Medium/Low e incluye nombres de archivos.
Añade también áreas sospechosas que no puedas confirmar.
La última línea evita una falsa sensación de seguridad. En una revisión de seguridad, las zonas inciertas suelen ser más útiles que un “no encontré nada” demasiado rápido.
Prepara handoff y respuestas de review
Un handoff permite que otro reviewer continúe sin reconstruir todo el contexto. Es clave en equipos distribuidos, PRs largos y rotaciones de guardia. Pasa a Claude Code la conversación y el resumen del diff.
PR_NUMBER=123
{
gh pr view "$PR_NUMBER" --comments
gh pr diff "$PR_NUMBER" --stat
} | claude -p "
Escribe una nota de handoff para reviewers de este Pull Request.
Incluye:
- Propósito en dos frases o menos
- Hasta 3 archivos para leer primero
- Comentarios de review ya atendidos
- Comentarios pendientes de decisión
- Riesgos de CI, pruebas manuales y release
Debe poder leerse en menos de cinco minutos.
"
También sirve para responder comentarios. “Arreglado” casi nunca basta. Una buena respuesta dice qué cambió, en qué archivo, qué prueba lo cubre y por qué no se aplicó una sugerencia si fue el caso. Claude Code puede redactar el borrador; tú recortas lo defensivo, especulativo o demasiado largo.
Convierte PRs en release notes
La calidad del PR se nota en el release. Si el cuerpo del PR no se puede convertir en una nota para usuarios, probablemente no explicaba bien el impacto. Conventional Commits ayuda a agrupar, pero las release notes deben sonar a lenguaje humano.
gh pr list --state merged --base main --limit 20 \
--json number,title,body,mergedAt \
| claude -p "
Redacta un borrador de release notes a partir de estos Pull Requests fusionados.
Secciones:
## Nuevas funciones
## Correcciones
## Rendimiento
## Documentación
## Cambios para desarrolladores
Reglas:
- Conserva los números de PR
- Resume los cambios internos
- Destaca breaking changes, migraciones y feature flags
- No inventes impacto que no esté respaldado por el cuerpo del PR
"
Este cierre mejora el principio: si sabes que el PR alimentará el release, escribes mejor la motivación, el riesgo y la evidencia desde el inicio.
Evita PRs de IA con demasiado ruido
El fallo más común no es que Claude Code escriba poco, sino que escriba demasiado. Formateo no solicitado, renombres masivos, refactors especulativos, comentarios duplicados, explicaciones con tono de marketing y pruebas no verificadas hacen más lenta la revisión.
Reglas simples funcionan bien: separa cambios de formato, mantén el diff mínimo, escribe solo hechos, explica por qué aceptaste una sugerencia de Claude Code y divide cambios mecánicos, cambios de comportamiento y tests cuando sea posible.
| PR ruidoso | PR revisable |
|---|---|
| “Claude mejoró el módulo” | “Movimos autorización a server/auth.ts” |
| Formato y lógica mezclados | PR de formato separado del PR funcional |
| “Todo bien” sin evidencia | Comandos, resultados y huecos listados |
| Sin foco de review | Archivos y riesgos nombrados al inicio |
Encaje monetizable para ClaudeCodeLab
Este flujo conecta bien con plantillas, formación y consultoría. Un equipo no necesita solo un prompt; necesita plantilla de PR, reglas en CLAUDE.md, puertas de CI y hábitos de review. Enlaza este artículo con plantillas CLAUDE.md, reglas de handoff de equipo y formación o consultoría para que el lector pase de aprender a implantarlo.
Despliega por semanas. Semana 1: plantilla de PR. Semana 2: presupuesto de diff. Semana 3: nota de handoff. Semana 4: release notes desde PRs fusionados. Si impones todo de golpe, el equipo discutirá el proceso antes de mejorar la calidad.
Resultado probado
Probé este flujo en un proyecto Node pequeño. La combinación de plantilla y límite de tamaño fue lo más eficaz. Claude Code solo producía descripciones largas pero irregulares; la plantilla sacó a la luz pruebas no ejecutadas, revisión de seguridad, archivos prioritarios y rollback. El presupuesto de 700 líneas y 35 archivos también ayudó a separar formato de cambios de comportamiento antes de pedir review.
Resumen
Claude Code mejora la calidad de los Pull Requests cuando le das carriles: plantilla estricta, límite de diff en CI, evidencia de pruebas reproducible, checklist de seguridad y privacidad, handoff de review y release notes. El objetivo no es que el PR suene mejor. El objetivo es que los cambios asistidos por IA sean fáciles de revisar, verificar y publicar.
PDF gratis: cheatsheet de Claude Code
Introduce tu email y descarga una hoja con comandos, hábitos de revisión y flujos seguros.
Cuidamos tus datos y no enviamos spam.
Sobre el autor
Masa
Ingeniero enfocado en workflows prácticos con Claude Code.
Artículos relacionados
Escalera de permisos de Claude Code para ampliar acceso sin perder control
Pasa de read-only a ediciones limitadas, comandos de prueba y checks de deploy con menos riesgo.
Claude Code Small PR Proof Pack: cambios pequeños que sí se pueden revisar
Un paquete de prueba para PRs de Claude Code: diff, checks, URL pública, CTA y rollback.
Gate de revisión antes del commit con Claude Code
Cómo revisar con Claude Code antes del commit: diff, build, URL pública, Gumroad, consultoría, tests y archivos ajenos.