Auditoría de código con Claude Opus 5.5: verifica cada hallazgo antes del merge
Un proceso práctico para auditorías largas con Claude Opus 5.5: línea base, reproducción, clasificación del riesgo, revisión arquitectónica, parches pequeños y regresión.
Índice
Dejas a Claude Opus 5.5 revisando un repositorio durante horas y recibes decenas de hallazgos “críticos”, quizá acompañados de un parche enorme. La parte difícil empieza entonces: decidir qué defectos existen de verdad, qué cambios respetan la arquitectura y qué correcciones son seguras para integrar.
Este método trata la salida del modelo como hipótesis de auditoría, no como conclusiones. Primero congelas una línea base reproducible; después cada hallazgo debe superar las puertas de reproducción, riesgo, arquitectura, corrección y regresión.
Usa Opus 5.5 para ampliar la revisión, no para aprobar el merge
Es una opción razonable para auditorías amplias y largas, pero no es un revisor independiente. En su anuncio del 22 de septiembre de 2026, Anthropic destacó las migraciones y auditorías de repositorios completos y publicó resultados internos y de usuarios de acceso temprano. Esos datos del proveedor no garantizan el mismo resultado en tu proyecto. Consulta el anuncio de Opus 5.5.
Kent C. Dodds publicó además un prompt que abarca seguridad, rendimiento, accesibilidad, mantenibilidad, escalabilidad, arquitectura, documentación, pruebas y automatización. Dijo que Opus 5.5 encontró un problema de seguridad importante que otros modelos no vieron, pero no reveló el fallo, la reproducción ni una comparación controlada. La experiencia justifica probar el flujo, no saltarse la verificación. Consulta la publicación.
Por tanto, el objetivo no es producir el mayor número de advertencias, sino obtener hallazgos reproducibles, clasificados y revisables de forma independiente.
Convierte el criterio de éxito en comandos antes de empezar
Sin una línea base limpia no sabrás si un fallo ya existía o apareció durante el trabajo del modelo. Guarda el SHA actual, el entorno, las versiones relevantes, el comando exacto y su código de salida.
Sustituye los marcadores por los comandos reales del proyecto. Si una puerta no aplica, indícalo expresamente.
git status --short
<install-command>
<lint-command>
<type-check-command>
<unit-test-command>
<integration-test-command>
<build-command>Registra como mínimo:
- SHA del commit, runtime, gestor de paquetes y dependencias importantes;
- comando, directorio de trabajo, código de salida y resumen del error;
- fallos conocidos, pruebas inestables y excepciones temporales;
- directorios incluidos y archivos que no deben tocarse, como código generado, migraciones históricas, lockfiles o código de terceros;
- rutas críticas: autenticación, autorización, facturación, migraciones de datos y contratos de API.
Si la línea base ya falla, corrige, aísla o documenta el fallo antes de la auditoría. No permitas que un problema antiguo aparezca como un descubrimiento nuevo.
En la primera fase pide auditoría sin cambios de código
La investigación y la corrección deben estar separadas. Si el modelo edita mientras busca, ya no podrás distinguir entre un defecto original, una regresión del primer parche y un efecto cruzado de parches posteriores.
Puedes empezar con este prompt y añadir los límites concretos del repositorio:
Realiza una auditoría larga de este repositorio. En esta fase, investiga y presenta resultados; no modifiques archivos.
Alcance: <directorios, servicios, lenguajes y flujos críticos>
Exclusiones: <archivos generados, código externo, migraciones históricas y sistemas inaccesibles>
Línea base: <comandos ejecutados, códigos de salida y fallos conocidos>
Revisa:
1. seguridad y límites de autorización;
2. corrección, concurrencia, transacciones y manejo de errores;
3. rendimiento y uso de recursos;
4. accesibilidad cuando corresponda;
5. mantenibilidad y escalabilidad;
6. arquitectura y límites entre módulos;
7. carencias de documentación, pruebas y automatización.
Para cada hallazgo incluye:
- ID único y título breve;
- severidad y justificación del impacto;
- archivos, símbolos y líneas exactas;
- condición de activación, comportamiento esperado y real;
- comando reproducible o prueba mínima;
- resumen de salida y código de terminación;
- posible explicación de falso positivo;
- dirección de corrección mínima;
- verificaciones obligatorias tras corregir;
- confianza alta, media o baja.
Reglas:
- Marca como NO EJECUTADO cualquier comando que no hayas corrido.
- Si no puedes reproducirlo, marca el hallazgo como NO VERIFICADO.
- No elimines, omitas ni debilites pruebas para obtener verde.
- Detente y enumera credenciales, servicios o dependencias ausentes.
- Actualiza la tabla de estado al cerrar cada fase y espera revisión.El prompt no garantiza que el modelo cumpla. Revisa el historial de terminal, los diffs y la salida real. Su utilidad es impedir que una observación vaga pase directamente a la cola de correcciones.
Divide la tarea larga en cuatro fases controladas
Una ejecución prolongada no debe tener alcance ni permisos ilimitados. Detén el proceso al final de cada fase.
Fase 1: mapa del sistema
El modelo lee código, configuración, pruebas y documentos. Debe entregar puntos de entrada, límites de confianza, flujos de datos, dependencias externas y rutas de alto impacto, sin modificar archivos ni perseguir una cuota de bugs.
Fase 2: hallazgos candidatos
Cada candidato debe apuntar a código y a una condición concreta. Una recomendación general sin ubicación ni activador va a una lista de mejoras, no al recuento de defectos.
Fase 3: reproducción individual
Empieza por problemas de alto impacto y bajo coste de comprobación. Un experimento debe probar una sola hipótesis. Conserva la salida sin editar y los datos del entorno.
Fase 4: plan de corrección
Solo los defectos reproducidos entran en el plan. Para cada uno, exige cambio mínimo, impacto de compatibilidad, riesgo de migración, vía de rollback y puertas de prueba. Los desacuerdos arquitectónicos van antes al responsable del código.
Mantén el estado en audit-plan.md o en tickets:
| ID | Estado | Riesgo | Evidencia | Decisión de arquitectura | Rama | Aprobador |
|---|---|---|---|---|---|---|
| AUD-001 | Pendiente de reproducir | Alto | Aún no existe | Sin revisar | — | — |
El avance debe ser explícito: candidato → pendiente de reproducción → reproducido → arquitectura revisada → corregido → aceptado. La seguridad del lenguaje del modelo no cambia el estado.
Puerta de riesgo: separa severidad y confianza
La severidad mide el daño potencial; la confianza mide la calidad de la evidencia. Un posible bypass de autorización puede ser grave y tener confianza baja. Un error menor de log puede estar perfectamente reproducido y seguir siendo de impacto bajo.
| Severidad | Cuándo usarla | Evidencia mínima antes de corregir |
|---|---|---|
| Crítica | Escalada amplia de privilegios, exposición de datos sensibles, corrupción irreversible o caída del servicio central | Reproducción controlada, alcance claro y revisión inmediata del responsable |
| Alta | Afecta un flujo esencial o una entrada realista lo activa de forma estable | Reproducción mínima, prueba fallida o salida de comando y confirmación del responsable |
| Media | Impacto acotado, existe alternativa o requiere condiciones inusuales | Evidencia repetible y decisión de prioridad |
| Baja | Calidad local, documentación, mantenibilidad o rendimiento no crítico | Código concreto y beneficio superior al riesgo de regresión |
El modelo puede seguir una ruta de ejecución, pero no conoce por sí solo la sensibilidad de los datos, los compromisos con clientes o la tolerancia a interrupciones. Esa parte requiere criterio humano responsable.
Puerta de reproducción: convierte el hallazgo en una comprobación que falle
Un fragmento sospechoso no basta. Necesitas una prueba que falle antes de la corrección y pase después. Para cada hallazgo responde:
- ¿En qué commit y entorno aparece?
- ¿Cuál es la entrada mínima que lo activa?
- ¿Qué define el resultado esperado: una prueba, especificación, contrato o regla de negocio?
- ¿Cuál fue el resultado real y dónde está la salida original?
- ¿Por qué no lo detectaron las pruebas actuales?
- ¿Puede explicarlo una decisión de diseño válida o una diferencia del entorno?
La mejor evidencia es una prueba de regresión mínima. Si no puede automatizarse, documenta pasos manuales deterministas, observaciones y limpieza. Reproduce problemas de seguridad solo en sistemas propios o autorizados, preferiblemente locales, aislados o de preproducción.
Cuando el modelo afirme que ejecutó algo, exige comando completo, directorio, código de salida y salida relevante. Un resumen en prosa no es evidencia de ejecución.
Puerta de arquitectura: averigua por qué existe el diseño actual
Una solución más elegante puede romper compatibilidad, orden de despliegue o límites deliberados. Antes de aceptar una refactorización, consulta ADR, documentos de diseño, contratos, restricciones de migración e historial.
Si hay historial Git útil:
git log -- <path>
git blame -L <start>,<end> <file>
git show <commit> -- <path>Exige respuestas concretas:
- ¿Qué restricción protege el diseño actual?
- ¿Qué consumidores, formatos o pasos de despliegue dependen de él?
- ¿La propuesta corrige un defecto o cambia el producto?
- ¿Puede resolverse con un cambio local menor?
- ¿El rollback requiere restaurar código, configuración o datos?
El historial aporta pistas, no una lectura perfecta de la intención. Si no hay justificación, marca “intención arquitectónica desconocida” y pregunta a un mantenedor.
Puerta de corrección: un defecto reproducido por parche pequeño
No aceptes un megapatch con una docena de cambios sin relación. Añade primero una prueba que falle en el código anterior y luego aplica la corrección mínima.
| Puerta | Requisito | Si falla |
|---|---|---|
| Alcance | El diff solo cubre el hallazgo aprobado | Separar cambios ajenos |
| Regresión | Falla antes y pasa después | Corregir la prueba o reconsiderar el hallazgo |
| Estática | Formato, lint y tipos pasan | No ocultar errores con exclusiones globales |
| Proyecto | Unitarias, integración y build pertinentes pasan | Analizar el primer fallo nuevo antes de acumular parches |
| Arquitectura | El responsable confirma límites y compatibilidad | Reducir alcance o abrir revisión de diseño |
| Revisión humana | Se inspeccionan errores, permisos, datos y borrados | Explicar cada diferencia sospechosa |
Rechaza falsos verdes: borrar asserts, saltar pruebas, tragar excepciones, debilitar validación, ampliar reintentos para ocultar carreras o refactorizar tanto que el defecto original ya no pueda seguirse.
Puerta de regresión: ejecuta las comprobaciones propias del proyecto
La aceptación final debe usar scripts existentes o CI, no solo pruebas elegidas por el modelo. Compara la línea base completa con el resultado final y confirma que la nueva prueba falla en la revisión sin parche.
Revisa también lockfiles, migraciones, API públicas y valores predeterminados. Una mejora de rendimiento solo es válida con el mismo entorno y entrada antes y después. Si una prueba es inestable, no la repitas hasta que salga verde: registra el patrón y determina si el parche empeoró la variabilidad.
Rechaza el resultado cuando aparezca cualquiera de estas señales
- No hay ubicación exacta, activador o evidencia inspeccionable.
- Un comando no ejecutado se presenta como aprobado.
- La severidad no contiene una ruta de impacto.
- El parche rebasa el alcance o rediseña la arquitectura sin permiso.
- Se borran, omiten o debilitan pruebas, o se silencian errores.
- El cambio contradice un ADR, contrato o plan de migración sin aprobación.
- Solo existe un resumen final, sin comandos ni diff revisable.
- Una afirmación de seguridad se apoya únicamente en que otro modelo coincide.
Un segundo modelo puede buscar contraejemplos, pero el consenso entre modelos no es evidencia independiente. La validación real proviene de pruebas, salida de ejecución, historial, especificaciones y responsables humanos.
Checklist final antes del merge
- Alcance, exclusiones y commit base están congelados.
- Se conservan comandos base y códigos de salida.
- Cada hallazgo aceptado tiene ID y ubicación exacta.
- Severidad y confianza figuran por separado.
- El defecto se reproduce con una prueba o procedimiento determinista.
- Se revisaron intención arquitectónica, compatibilidad y rollback.
- Cada hallazgo corresponde a un parche pequeño y revisable.
- La prueba de regresión falla antes y pasa después.
- Las puertas completas se ejecutan mediante scripts existentes o CI.
- Un responsable revisa el diff final y lo aprueba explícitamente.
Los informes públicos convierten a Opus 5.5 en un candidato creíble para auditorías extensas y sugieren que puede sacar a la luz problemas omitidos por otros. No eliminan la necesidad de comprobar. El siguiente paso mínimo es guardar una línea base limpia y lanzar una primera fase “solo auditoría, sin modificaciones”.
