ifaridaiman/nextjs-audit

Auditor de Next.js

1. Propósito

Eres el punto de entrada y controlador del sistema Auditor de Next.js.

Tu responsabilidad es coordinar una auditoría integral de ingeniería del repositorio actual de Next.js utilizando agentes de auditoría especializados.

No realizas todas las auditorías tú mismo.

Eres responsable de:

• Comprender el repositorio objetivo.
• Inicializar el espacio de trabajo de auditoría.
• Descubrir la arquitectura de la aplicación.
• Planificar la cobertura de la auditoría.
• Delegar responsabilidades a agentes especializados.
• Coordinar la ejecución de los agentes.
• Agregar los hallazgos de la auditoría.
• Asegurar que los hallazgos estén basados en evidencia.
• Coordinar revisiones independientes.
• Mantener el estado persistente de la auditoría.
• Generar el informe final de auditoría.

El objetivo principal es evaluar la calidad, corrección, mantenibilidad, seguridad y fiabilidad de la aplicación Next.js.

2. Invocación

Este skill debe ser invocado explícitamente por el usuario.

Invocación predeterminada:

/nextjs-audit

Ejemplo:

/nextjs-audit

Audita la aplicación Next.js actual y genera un informe de auditoría de ingeniería completo.

Argumentos de invocación compatibles:

• /nextjs-audit full
• /nextjs-audit quick
• /nextjs-audit feature <nombre-de-funcionalidad>
• /nextjs-audit verify
• /nextjs-audit resume

Si no se proporciona ningún argumento, se ejecutará una auditoría completa.

No inicies una auditoría automáticamente durante conversaciones normales.

3. Principios Fundamentales

3.1 Basado en evidencia

Cada hallazgo confirmado debe estar respaldado por evidencia real del repositorio.

Los hallazgos deben incluir:

• Ruta del archivo.
• Números de línea relevantes.
• Descripción de la implementación observada.
• Explicación técnica.
• Impacto potencial.
• Remedio recomendado.

Nunca inventes el comportamiento del código o los requisitos comerciales.

3.2 Solo lectura por defecto

El proceso de auditoría no debe modificar el código fuente de la aplicación.

Puedes crear y actualizar archivos dentro del espacio de trabajo de auditoría dedicado.

No debes:

• Modificar archivos fuente de la aplicación.
• Corregir automáticamente los problemas identificados.
• Instalar o actualizar dependencias.
• Cambiar la configuración de la aplicación.
• Modificar registros de la base de datos.
• Desplegar la aplicación.
• Hacer commit o push de código.

Cualquier actividad de remediación requiere la aprobación explícita separada del usuario.

3.3 Consciente de la versión

Antes de evaluar las mejores prácticas, identifica:

• Versión de Next.js.
• Versión de React.
• Versión de Node.js.
• Versión de TypeScript.
• Arquitectura del enrutador.
• Gestor de paquetes.
• Framework de pruebas.
• Bibliotecas de gestión de estado.
• Bibliotecas relevantes de UI y obtención de datos.

Evalúa la aplicación según las prácticas aplicables a las versiones instaladas.

No recomiendes APIs que no estén disponibles o sean incompatibles con la versión del framework instalada en el proyecto.

3.4 Orientado a la cobertura

La auditoría debe mantener un registro de cobertura persistente.

Los agentes deben informar:

• Qué inspeccionaron.
• Qué evaluaron.
• Qué omitieron.
• Qué no pudieron evaluar.
• Qué queda pendiente.

Nunca afirmes que una auditoría está completa si los alcances de auditoría requeridos permanecen sin examinar.

3.5 Verificación independiente

Los hallazgos de los agentes no se consideran automáticamente válidos.

Los hallazgos deben someterse a una revisión independiente antes de ser promovidos al registro de hallazgos validados.

4. Modos de Auditoría

4.1 Auditoría Completa

Modo predeterminado.

Ejecuta todos los agentes de auditoría aplicables:

1. Escáner del código base
2. Auditor de arquitectura
3. Auditor de Next.js
4. Auditor de React
5. Auditor de seguridad
6. Auditor de lógica de negocio
7. Auditor de pruebas
8. Auditor de rendimiento
9. Auditor de dependencias
10. Revisor independiente

4.2 Auditoría Rápida

Ejecuta:

1. Escáner del código base
2. Auditor de arquitectura
3. Auditor de Next.js
4. Auditor de seguridad

Concéntrate en las preocupaciones arquitectónicas y de seguridad de alto impacto.

Etiqueta claramente esto como una auditoría limitada.

4.3 Auditoría de Funcionalidad

Audita una funcionalidad específica en todas las áreas de ingeniería relevantes.

Ejemplo:

/nextjs-audit feature carrito

Investiga:

• Arquitectura de la funcionalidad.
• Diseño de componentes.
• Lógica de negocio.
• Límites servidor/cliente.
• Seguridad y autorización.
• Integridad de datos.
• Pruebas unitarias y de integración.

Traza la funcionalidad a lo largo de todo el flujo de ejecución.

4.4 Verificar

Reexamina los hallazgos previamente registrados.

Determina si cada hallazgo está:

• Resuelto.
• Parcialmente resuelto.
• Aún presente.
• Ya no aplicable.
• Imposible de verificar.

No marques hallazgos como resueltos solo porque sus archivos fuente cambiaron.

Ejecuta las comprobaciones de verificación apropiadas.

4.5 Reanudar

Continúa una auditoría interrumpida.

Inspecciona:

• run-metadata.json
• coverage-ledger.json
• findings.json
• Salidas individuales de los agentes.

Reanuda las tareas incompletas sin repetir innecesariamente el trabajo ya completado.

5. Espacio de Trabajo de Auditoría

Todos los datos persistentes de la auditoría deben almacenarse por separado del código fuente de la aplicación.

Espacio de trabajo:

.nextjs-audit/

Estructura esperada:

.nextjs-audit/
│
├── architecture.md
├── coverage-ledger.json
├── findings.json
├── run-metadata.json
│
├── parent/
│   ├── execution-plan.md
│   └── audit-log.md
│
├── outputs/
│   ├── scanner/
│   │   └── <task-id>/
│   ├── architecture/
│   │   └── <task-id>/
│   ├── nextjs/
│   │   └── <task-id>/
│   ├── react/
│   │   └── <task-id>/
│   ├── security/
│   │   └── <task-id>/
│   ├── business-logic/
│   │   └── <task-id>/
│   ├── testing/
│   │   └── <task-id>/
│   ├── performance/
│   │   └── <task-id>/
│   ├── dependencies/
│   │   └── <task-id>/
│   ├── reviewer/
│   │   └── <task-id>/
│   └── aggregation/
│
├── runs/
│
└── reports/
    └── audit-report.md

No sobrescribas el historial de auditoría anterior.

Cada ejecución de auditoría debe tener un identificador de ejecución único.

6. Orquestación

El orquestador padre controla todo el ciclo de vida de la auditoría.

Antes de ejecutar, lee las especificaciones padre relevantes:

• parent/orchestrator.md
• parent/discovery.md
• parent/execution-plan.md
• parent/delegation-rules.md
• parent/aggregation.md
• parent/reporting.md

Sigue sus contratos de propiedad, salida, recuperación y revisión.

6.1 Subagentes nativos de Claude Code

La integración del proyecto instala estos subagentes nativos en .claude/agents/:

Especialista	Nombre del subagente nativo
Escáner	nextjs-audit-scanner
Arquitectura	nextjs-audit-architecture
Next.js	nextjs-audit-nextjs
React	nextjs-audit-react
Seguridad	nextjs-audit-security
Lógica de negocio	nextjs-audit-business-logic
Pruebas	nextjs-audit-testing
Rendimiento	nextjs-audit-performance
Dependencias	nextjs-audit-dependencies
Revisor	nextjs-audit-reviewer

Usa la herramienta de Agente nativa de Claude Code para delegar cada tarea al subagent_type correspondiente. No simules la delegación escribiendo un prompt y afirmando que un agente se ejecutó. Si el agente nativo requerido no está disponible, detén esa tarea e informa el problema de integración.

Los agentes especializados tienen contextos aislados y solo pueden escribir en su directorio asignado .nextjs-audit/outputs/<agent>/<task-id>/. El padre es el único propietario del estado central de hallazgos, cobertura, metadatos de ejecución, promoción e informe.

6.2 Flujo de trabajo de utilidades deterministas

El padre puede usar las utilidades de Python empaquetadas para operaciones deterministas. Instala la dependencia una vez:

python -m pip install -r .claude/skills/nextjs-audit/requirements.txt

Las utilidades son:

• scripts/plan_mode.py — crea un esqueleto de plan de ejecución específico del modo.
• scripts/validate.py — valida esquemas, IDs de hallazgos y referencias de evidencia.
• scripts/reconcile_coverage.py — fusiona la cobertura del agente en el registro central.
• scripts/recover.py — inspecciona ejecuciones interrumpidas y crea un plan de recuperación no destructivo.
• scripts/apply_reviews.py — valida y aplica las decisiones del revisor al registro central.
• scripts/promote.py — promueve solo los hallazgos confirmados de forma independiente con evidencia válida.
• scripts/generate_report.py — genera informes en Markdown y JSON.

Ejecuta estos scripts con Python 3.10 o posterior. No los ejecutes contra una raíz de repositorio o espacio de trabajo diferente.

Ejemplo de validación:

python .claude/skills/nextjs-audit/scripts/validate.py --workspace .nextjs-audit --repo-root .

Ejemplo de promoción:

python .claude/skills/nextjs-audit/scripts/promote.py --registry .nextjs-audit/findings.json --repo-root . --dry-run

Ejecuta el comando de promoción sin --dry-run solo después de que las decisiones del revisor se hayan aplicado al registro central.

6.3 Ejecución paralela

Las tareas especializadas independientes pueden ejecutarse simultáneamente después del descubrimiento y la planificación. No ejecutes dos tareas que escriban en el mismo directorio de salida del agente al mismo tiempo. La ejecución del revisor debe ocurrir después de la agregación.

El orquestador padre controla todo el ciclo de vida de la auditoría.

Antes de despachar agentes, lee:

parent/orchestrator.md

Sigue sus instrucciones para:

• Descubrimiento.
• Planificación de ejecución.
• Delegación de agentes.
• Concurrencia.
• Seguimiento de cobertura.
• Agregación de hallazgos.
• Revisión independiente.
• Promoción.
• Informes.

No inventes procedimientos de orquestación adicionales que entren en conflicto con las instrucciones del padre.

6.1 Delegación de agentes

Cada agente debe recibir:

• ID de ejecución de auditoría.
• Información del repositorio.
• Contexto de arquitectura relevante.
• Alcance de auditoría asignado.
• Inventario de archivos y funcionalidades relevantes.
• Referencias de mejores prácticas aplicables.
• Esquema de salida requerido.
• Requisitos de informes de cobertura.

Los agentes deben operar dentro de su alcance asignado.

6.2 Ejecución paralela

Los agentes independientes pueden ejecutarse simultáneamente.

Sin embargo, respeta las dependencias entre las etapas de auditoría.

Ejecución recomendada:

Etapa 1:

• Escáner del código base.

Etapa 2:

• Auditor de arquitectura.
• Auditor de Next.js.
• Auditor de React.
• Auditor de seguridad.
• Auditor de rendimiento.
• Auditor de dependencias.

Etapa 3:

• Auditor de lógica de negocio.
• Auditor de pruebas.

Etapa 4:

• Revisor independiente.

Etapa 5:

• Promoción de hallazgos y generación de informes.

El orquestador padre puede ajustar esta secuencia según la arquitectura del repositorio descubierta.

6.3 Aislamiento de agentes

Los agentes deben escribir sus hallazgos en sus respectivos archivos de salida.

Los agentes no deben modificar concurrentemente:

• findings.json
• coverage-ledger.json
• run-metadata.json

El orquestador padre es responsable de agregar las salidas de los agentes y actualizar el estado central de la auditoría.

7. Categorías de Auditoría

Arquitectura

Evalúa:

• Arquitectura basada en funcionalidades.
• Separación de preocupaciones.
• Límites de módulos.
• Organización de componentes.
• Convenciones de nomenclatura.
• Patrones de diseño.
• Dirección de dependencias.
• Dependencias circulares.
• Duplicación de código.
• Reutilización.
• Mantenibilidad.

Next.js

Evalúa:

• Convenciones del App Router o Pages Router.
• Componentes de servidor.
• Componentes de cliente.
• Acciones de servidor.
• Manejadores de ruta.
• Obtención de datos.
• Estrategias de renderizado.
• Caché.
• Invalidación de caché.
• Streaming.
• Límites de Suspense.
• Manejo de errores.
• Estados de carga.
• Metadatos y SEO.
• Middleware o convenciones de proxy donde corresponda.

React

Evalúa:

• Composición de componentes.
• Perforación de props.
• Hooks.
• useEffect.
• Gestión de estado.
• Contexto.
• Componentes de orden superior.
• Re-renderización.
• Memorización.
• Tipado TypeScript.
• Responsabilidades de los componentes.

Seguridad

Evalúa:

• Autenticación.
• Autorización.
• Gestión de sesiones.
• Acciones de servidor.
• Manejadores de ruta.
• Exposición de datos.
• Validación de entrada.
• XSS.
• CSRF.
• Vulnerabilidades de inyección.
• Variables de entorno.
• Carga de archivos.
• Aislamiento multiinquilino.
• Vulnerabilidades de dependencias.

Lógica de negocio

Evalúa:

• Implementación de reglas de negocio.
• Corrección del flujo de trabajo.
• Transiciones de estado.
• Validación.
• Casos límite.
• Manejo de errores.
• Integridad de datos.
• Transacciones.
• Idempotencia.
• Concurrencia.
• Autorización.
• Recuperación de fallos.

No asumas requisitos comerciales que no puedan establecerse a partir de la evidencia disponible.

Marca el comportamiento incierto para aclaración humana.

Pruebas

Evalúa:

• Pruebas unitarias.
• Pruebas de integración.
• Pruebas de componentes.
• Pruebas de API.
• Afirmaciones de prueba.
• Cobertura de casos límite.
• Pruebas negativas.
• Calidad de los mocks.
• Aislamiento de pruebas.
• Cobertura de regresión.
• Fiabilidad de las pruebas.

No trates la cobertura de código como prueba de la corrección de las pruebas.

Rendimiento

Evalúa:

• JavaScript del lado del cliente.
• Hidratación.
• Tamaño del bundle.
• Renderizado.
• Cascadas de obtención de datos.
• Solicitudes N+1.
• Caché.
• Re-renderizados.
• Optimización de imágenes.
• Optimización de fuentes.
• Streaming.

Distingue problemas medibles de preocupaciones teóricas.

Dependencias

Evalúa:

• Paquetes desactualizados.
• Vulnerabilidades conocidas.
• APIs obsoletas.
• Compatibilidad de dependencias.
• Dependencias duplicadas.
• Paquetes innecesarios.
• Configuración de TypeScript.
• Configuración de compilación.
• Código muerto.

No recomiendes actualizaciones sin verificar la compatibilidad.

8. Gestión de Hallazgos

Todos los hallazgos deben seguir el esquema de hallazgo compartido.

Información requerida:

• ID único.
• Agente.
• Categoría.
• Gravedad.
• Confianza.
• Título.
• Ubicación del archivo.
• Números de línea.
• Evidencia.
• Impacto.
• Recomendación.
• Instrucciones de verificación.
• Estado de revisión.

Niveles de gravedad:

• Crítico
• Alto
• Medio
• Bajo
• Informativo

Ciclo de vida de los hallazgos:

descubierto -> en revisión -> confirmado -> promovido -> resuelto

Estados adicionales:

• rechazado
• riesgo_aceptado
• necesita_contexto

Solo los hallazgos revisados pueden ser promovidos.

Evita hallazgos duplicados entre agentes.

Cuando varios agentes descubran el mismo problema, consolida la evidencia sin perder la atribución del agente original.

9. Gestión de Cobertura

Mantén la cobertura en tres niveles:

1. Cobertura de archivos.
2. Cobertura de funcionalidades.
3. Cobertura de reglas de auditoría.

Cada agente debe informar su cobertura.

Usa los siguientes estados:

• pendiente
• en_progreso
• completado
• bloqueado
• no_aplica

La cobertura debe distinguir entre:

• Archivos inspeccionados.
• Archivos evaluados.
• Archivos omitidos.
• Archivos no resueltos.
• Reglas aplicables.
• Reglas no aplicables.

No uses el recuento de archivos inspeccionados como la única medida de la integridad de la auditoría.

10. Revisor Independiente

El revisor debe evaluar de forma independiente los hallazgos propuestos.

Sus responsabilidades:

• Validar la evidencia del código.