Documentar código y revisar pull requests son dos tareas que casi todo equipo sabe que debería hacer mejor y casi ninguno hace con la constancia deseada. La documentación se queda obsoleta porque nadie tiene tiempo de actualizarla; las revisiones de código se vuelven superficiales cuando hay prisa o cuando el cambio es enorme. Además, aquí la IA puede ser una ayuda real: redacta borradores de comentarios y de documentación a partir del código, resume el contenido de un cambio, señala posibles problemas y prepara una lista de puntos que el revisor humano debería mirar con atención. Pero tiene un límite claro: no conoce los acuerdos de tu equipo, la historia del proyecto ni las razones de negocio detrás de cada decisión, y puede resultar convincente cuando se equivoca.

Esta guía propone un método para usar asistentes de IA en documentación y revisión de código sin perder el criterio del equipo. Además, incluye prompts listos para copiar, un ejemplo práctico, buenas prácticas de integración en el flujo de trabajo y los errores más comunes. Las herramientas concretas (asistentes de chat, extensiones de editor, bots de revisión integrados en plataformas de código) cambian constantemente; consulta siempre sus webs oficiales para conocer funciones, límites y precios.
Qué necesitas antes de revisar pull requests
- Acuerdos de equipo escritos. Guía de estilo, convenciones de nombres, criterios de revisión, definición de «terminado». La IA los puede aplicar si los conoce; si no existen, aplicará los suyos.
- Un flujo de pull requests establecido. Ramas, plantillas de descripción, integración continua con tests y linter. La IA complementa, no sustituye, las comprobaciones automáticas.
- Política de uso de IA y de datos. Qué código puede compartirse con servicios externos, qué herramientas están autorizadas y cómo se gestionan secretos. Es especialmente importante en proyectos de clientes.
- Un lugar donde viva la documentación. README, carpeta docs, wiki o generadores de documentación. Sin un hogar claro, la documentación generada se perderá.
- Una persona responsable de cada cambio. Quien abre el pull request sigue siendo responsable de su contenido, aunque lo haya redactado un asistente, y quien lo revisa sigue siendo responsable de aprobarlo.
Parte 1: documentar código con IA
Qué tipos de documentación conviene generar
- Comentarios y docstrings. Explican qué hace una función, sus parámetros, su valor de retorno y sus excepciones.
- README del proyecto. Qué es, cómo se instala, cómo se ejecuta, cómo se prueba y cómo se contribuye.
- Documentación de arquitectura. Visión general de módulos y relaciones, decisiones importantes y su motivo.
- Guías de uso y ejemplos. Cómo usar una API o librería interna con casos reales.
- Registro de cambios (changelog). Resumen de cambios entre versiones, legible para personas.
Principio clave: documenta el porqué
Un asistente puede describir muy bien qué hace una línea («incrementa el contador»), pero ese comentario no aporta nada que el código no diga. Lo valioso es el porqué: por qué se eligió esta estrategia, qué restricción existe, qué ocurre si se cambia. Asimismo, eso no está en el código y la IA solo lo conocerá si se lo cuentas. Pide siempre que marque los puntos donde necesita contexto en lugar de inventarlo.
Prompt 1: docstrings y comentarios
Actúa como desarrollador senior con experiencia en [lenguaje]. Añade docstrings al siguiente código siguiendo el estilo [Google / NumPy / JSDoc / Javadoc]. Para cada función incluye: propósito en una frase, parámetros con tipo, valor de retorno, excepciones y un ejemplo breve de uso. Reglas: - Describe el comportamiento real del código; no inventes funcionalidades. - No añadas comentarios que repitan lo que ya dice el código. - Si no puedes deducir el motivo de una decisión, escribe [PREGUNTAR] en lugar de suponerlo. - No modifiques la lógica ni el formato del código. Código: [pega aquí el código]
README de un proyecto (prompt 2)
Escribe un README en español para este proyecto a partir de la información que te doy. Secciones: descripción, requisitos, instalación, uso con ejemplos, cómo ejecutar los tests, estructura del proyecto, cómo contribuir y licencia. Información: [descripción, comandos reales, estructura de carpetas, versiones] No inventes comandos, rutas ni opciones; si falta algo, deja un marcador [COMPLETAR] y lista al final lo que debo confirmar.
Documentación de arquitectura (prompt 3)
Este es el listado de módulos principales del proyecto y un resumen de sus responsabilidades: [pega la información] Redacta un documento de arquitectura con: visión general, descripción de cada módulo, flujos principales entre módulos, decisiones de diseño conocidas y riesgos o deuda técnica detectados. Incluye un diagrama en formato Mermaid. Marca como [VERIFICAR] cualquier relación que hayas deducido y que yo no haya confirmado.
Parte 2: revisar pull requests con IA
Qué puede aportar un asistente en una revisión
- Resumen del cambio. Qué archivos se tocan, cuál es la intención y qué partes son más delicadas. Muy útil en pull requests grandes.
- Detección de problemas evidentes. Errores de lógica, falta de validación, casos límite sin cubrir, recursos sin cerrar, posibles problemas de seguridad.
- Comprobación de consistencia. Nombres, estilo, duplicaciones, funciones demasiado largas.
- Sugerencias de tests. Casos que faltan para el comportamiento nuevo.
- Lista de comprobación para el revisor humano. Qué puntos merecen más atención.
Qué no debe hacer
- Aprobar el cambio. La aprobación es humana.
- Decidir sobre arquitectura o prioridades. Dependen del contexto del equipo.
- Sustituir al linter y a los tests. Son más fiables para lo que cubren.
- Revisar sin contexto. Un diff aislado no muestra cómo encaja el cambio en el resto del sistema.
Resumen y puntos de atención de un pull request (prompt 4)
Eres un revisor de código experimentado en [lenguaje/framework]. Contexto del proyecto: [breve descripción y convenciones relevantes]. Objetivo del cambio según el autor: [descripción del pull request]. Diff: [pega aquí el diff] Entrega: 1. Resumen del cambio en un máximo de 6 líneas. 2. Posibles errores de lógica, casos límite sin considerar o riesgos de seguridad, indicando archivo y línea aproximada. 3. Problemas de legibilidad o mantenibilidad con una sugerencia concreta. 4. Tests que faltan. 5. Preguntas que haría al autor. Distingue entre "problema probable" y "posible mejora". Si no estás seguro de algo porque falta contexto, indícalo en lugar de afirmarlo.
Redactar la descripción del pull request (prompt 5)
A partir de este diff y de los mensajes de commit, redacta la descripción de un pull request en español con: qué cambia y por qué, cómo probarlo, impacto (migraciones, compatibilidad, rendimiento) y puntos en los que quiero una revisión especialmente cuidadosa. Sé concreto y no inventes pruebas que no se hayan hecho. [pega diff y commits]
Paso a paso para revisar pull requests con IA
- Empieza con la descripción del pull request. Es el uso de menor riesgo y mayor retorno: un resumen claro ayuda a todo el equipo.
- Añade un paso previo de autorrevisión. Antes de pedir revisión humana, pasa tu propio diff por el asistente y corrige lo evidente.
- Define cómo se usarán los comentarios generados. Por ejemplo, como sugerencias que el autor evalúa, nunca como requisitos obligatorios.
- Mantén los cambios pequeños. Los pull requests más pequeños se revisan mejor por humanos y por IA.
- Revisa la calidad de la documentación generada. Una persona del equipo debe validar que describe la realidad.
- Automatiza con criterio. Si usas un bot de revisión integrado, ajusta su nivel de detalle y descarta el ruido para no generar fatiga de comentarios.
- Mide y ajusta. Observa cuántas sugerencias son útiles, cuánto tiempo ahorras y qué tipo de errores se siguen colando.
Ejemplo práctico: revisar pull requests con IA
Una desarrolladora abre un pull request que modifica la validación de un endpoint de registro: pasa de comprobar manualmente los campos a usar un esquema de validación. Asimismo, el diff toca cuatro archivos y añade doce tests.
Antes de pedir revisión, usa el prompt 5 y obtiene una descripción clara con el motivo del cambio, cómo probarlo y un aviso sobre un comportamiento que cambia: los espacios al inicio y final de los correos ahora se eliminan. Después ejecuta el prompt 4 sobre su propio diff. Por otro lado, el asistente señala dos cosas: un caso en el que un campo opcional vacío ya no devuelve el mismo código de error que antes y la ausencia de un test para correos con mayúsculas. Ella revisa ambos puntos: el primero era un cambio accidental y lo corrige; el segundo lo añade como test.
El revisor del equipo recibe un pull request bien descrito, con menos errores evidentes, y puede dedicar su atención a lo que el asistente no puede juzgar: si el cambio respeta la política de compatibilidad con clientes antiguos y si el nuevo esquema encaja con la dirección que el equipo quiere para la validación. Detecta además que el asistente había sugerido una refactorización que contradecía un acuerdo del equipo, y la descarta con una nota en el comentario. Además, el resultado combina velocidad y criterio.
Para la documentación, después del cambio usa el prompt 1 en las funciones nuevas y actualiza el README con los nuevos comportamientos, revisando cada afirmación contra el código.
Buenas prácticas de seguridad y privacidad
- No compartas secretos. Claves, tokens, contraseñas y variables de entorno deben quedar fuera de lo que pegas o de lo que la herramienta puede leer.
- Revisa qué datos retiene el servicio. Condiciones de uso, almacenamiento y entrenamiento. Prefiere configuraciones empresariales cuando trabajes con código de terceros.
- Atención al código de clientes. Consulta contratos y políticas antes de usar herramientas externas.
- Cuidado con datos personales en fixtures y logs. Si pegas trazas o datos de ejemplo, anonimízalos.
- Licencias. Si el asistente sugiere código que parece copiado de otra fuente, verifica su origen y licencia antes de incluirlo.
Cómo evitar la fatiga al revisar pull requests
Los bots de revisión pueden generar decenas de observaciones menores que ahogan lo importante. Por otro lado, algunas medidas útiles: indica en el prompt que solo señale problemas con impacto probable, limita el número de comentarios, separa seguridad, corrección y estilo en categorías y deja el estilo al linter. Si el equipo empieza a ignorar los comentarios del asistente, el sistema ha perdido valor. Asimismo, mejor menos comentarios y más acertados.
Errores frecuentes al revisar pull requests con IA
- Aceptar documentación sin comprobarla. La documentación incorrecta es peor que la inexistente porque induce a error con apariencia de autoridad.
- Generar comentarios que repiten el código. Ruido que se desactualiza sin aportar valor.
- Revisar solo con IA. Un asistente puede pasar por alto problemas de diseño o contexto que un compañero detectaría al instante.
- Pegar el pull request entero sin contexto. Sin descripción de objetivo ni convenciones, la revisión será genérica.
- Pull requests gigantes. Ni humanos ni IA los revisan bien. Divide el trabajo.
- No ajustar el asistente a las convenciones del equipo. Obtendrás sugerencias que contradicen acuerdos existentes.
- Tomar los comentarios como órdenes. El autor debe evaluar cada sugerencia con criterio.
- Olvidar la actualización. Documentación generada una vez y nunca revisada acaba obsoleta. Intégrala en la definición de «terminado».
- Exponer secretos o código confidencial. Revisa siempre qué se comparte y con qué servicio.
Preguntas frecuentes sobre revisar pull requests
¿La IA puede sustituir a la revisión de código humana?
No. Puede detectar problemas y ahorrar tiempo, pero la decisión de aprobar un cambio depende de contexto, de acuerdos del equipo y de responsabilidad que corresponde a personas.
¿Es mejor usar un chat o un bot integrado en la plataforma?
Depende del flujo. Además, el chat da flexibilidad y control de contexto; el bot integrado automatiza y comenta directamente en el pull request. Por otro lado, prueba ambos en un proyecto piloto y consulta las funciones actuales en la web oficial de cada herramienta.
¿Cómo evito que la documentación generada esté desactualizada?
Intégrala en el proceso: que cada pull request actualice la documentación afectada y que la revisión compruebe que lo hace. Puedes pedir al asistente que compare el diff con la documentación existente y señale discrepancias.
¿Qué hago con las sugerencias que no estoy seguro de que sean correctas?
Compruébalas con el código, los tests y la documentación oficial. Asimismo, si dudas, pregunta a un compañero. Además, nunca apliques sin entender.
¿Se puede usar con proyectos privados?
Sí, siempre que cumplas las políticas de tu organización y las condiciones del servicio sobre privacidad y retención de datos. Revisa las opciones empresariales.
¿Por dónde empiezo?
Por la descripción del pull request y los docstrings de funciones nuevas. Además, son tareas de bajo riesgo y alto valor, y te permiten ajustar los prompts antes de pasar a la revisión de problemas.
Más recursos sobre revisar pull requests
Además, conviene contrastar siempre la información con fuentes fiables, como la documentación oficial de GitHub sobre pull requests. Por otro lado, si quieres profundizar, puedes leer nuestra comparativa de GitHub Copilot, Cursor y Claude Code.
¿Hay IA gratis para revisar código?
Algunos asistentes y bots ofrecen planes gratuitos para proyectos públicos o con límites de uso. Asimismo, comprueba las condiciones y no subas código privado a servicios sin garantías.
Fuentes oficiales para profundizar
Para profundizar en revisar pull requests, conviene contrastar con fuentes oficiales y no fiarse solo de lo que genera una IA.
- Claude Code: Página oficial de esta herramienta de programación.
- Cursor: Sitio oficial del editor con IA integrada.
- documentación de GitHub Copilot: Cómo funciona y se configura este asistente de código.
Guías relacionadas
- Prompts para depurar código y escribir tests unitarios
- ¿Puede la IA sustituir a un programador? Análisis para España
- Cómo usar la IA para programar más rápido: guía para desarrolladores junior
- Qué dice el Reglamento europeo de IA para los profesionales
Conclusión sobre cómo revisar pull requests
Documentar y revisar código con IA funciona cuando el asistente se usa como ayudante que prepara, resume y señala, y las personas mantienen el criterio, el contexto y la responsabilidad. Empieza por tareas de bajo riesgo, adapta los prompts a las convenciones de tu equipo, protege los secretos y los datos y mide si de verdad ahorras tiempo y mejoras la calidad. Además, así la documentación deja de ser una deuda permanente y las revisiones ganan profundidad en lugar de perderla.





