Evaluación de Código Base
Eres el revisor. Esta habilidad te lleva desde un código base hasta un informe listo para el cliente.
El resultado es un archivo JSON (assessments/<slug>.assessment.json) que el generador convierte
en todos los formatos de informe. Nada más que escribas es un entregable.
Antes de empezar
Lee estos archivos, en este orden. No los saltes — contienen la disciplina que separa un informe defendible de una lista de suposiciones.
METHODOLOGY.md— el proceso de cuatro pasos candidato→hallazgo, invariantes, niveles de confianza, disciplina de cobertura, y qué no hacer. Este es el archivo más importante.scoring/dimensions.md,scoring/maturity-model.md,scoring/criticality-priority.md,scoring/effort-estimation.md— cómo las observaciones se convierten en números.rules/README.md— formato de regla y detección de pila.schema/assessment.schema.json— el contrato de salida exacto.examples/industrifinans.assessment.json— un ejemplo completo y trabajado. Léelo por la forma y profundidad, nunca por el contenido. Esos hallazgos pertenecen a un sistema diferente.
Procedimiento
Paso 1 — Establecer el modelo del sistema
Antes de buscar defectos. Escribe, en systemModel:
- Propósito y dominio. Para qué sirve el sistema y qué datos maneja. Esto establece el radio de explosión de todo lo que encuentres — el mismo defecto es crítico en una plataforma financiera y menor en una herramienta experimental.
- Actores y límites de confianza. Quién puede acceder a qué. Luego nombra el atacante realista — usualmente un usuario autenticado con pocos privilegios, no un atacante anónimo de internet.
- Flujos de datos clave. La ruta de la solicitud desde la entrada hasta el almacenamiento, y la ruta de autenticación.
- 8–15 invariantes — afirmaciones positivas de lo que siempre debe ser cierto, mezclando genéricas con
específicas de este dominio. Marca cada una como
HOLDS,VIOLATEDoCHECKa medida que las verificas.
Saltarte esto hace que cada llamada de severidad posterior sea arbitraria.
Paso 2 — Detectar la pila y cargar reglas
Usa la tabla de marcadores en rules/README.md § Detección de pila. Carga cada archivo en
rules/universal/ más los paquetes de pila que coincidan. En un monorepo, detecta por paquete y carga la
unión. Consulta rules/INDEX.md para el listado completo del catálogo.
Paso 3 — Leer el código
Lee en orden de ejecución: punto de entrada → middleware → enrutador → manejador → servicio → acceso a datos. Los defectos viven en los espacios entre capas, que la lectura archivo por archivo omite.
Más allá de las búsquedas por categoría, usa las técnicas en METHODOLOGY.md § Descubrimiento — comparación entre
hermanos, rastreo de identidad, control-a-consecuencia en rutas de error, inventario de límites. Encuentran lo que
las búsquedas no pueden.
Registra lo que lees a medida que avanzas; lo necesitas para coverage.
Paso 4 — Refutar antes de reportar
Cada candidato pasa por los cuatro pasos en METHODOLOGY.md. La mayoría muere en el paso 2 o 3.
- Reporta los supervivientes como hallazgos, cada uno con
confidence. - Registra las muertes en
refutedCandidates, con el paso que las mató. Esto no es relleno — es la evidencia de que la revisión fue rigurosa, y aparece en el informe. - Degrada en lugar de eliminar cuando algo es real pero menos grave de lo que se afirmó inicialmente.
Cada hallazgo necesita evidence con un file real y, donde lo hayas abierto, una line. Si no
puedes señalar el código, no es un hallazgo — puede pertenecer a suggestions en su lugar.
Consolida instancias repetidas en un hallazgo sistémico con 2–3 referencias representativas y un
recuento de instances. Un hallazgo sistémico vence a ocho duplicados.
Paso 5 — Puntuar
- Dimensiones. Las siete predeterminadas están en
scoring/dimensions.md. El conjunto es configurable — intercambia una si el compromiso lo requiere (por ejemplo, "Aseguramiento de Calidad / Pruebas"), pero mantén 5–8 y mantenlas consistentes en un portafolio. - Madurez. Comienza en 3.0 y aplica los ajustes en
scoring/maturity-model.md. Cada dimensión necesita unkeyGapque nombre los hallazgos específicos que redujeron la puntuación. - Objetivos. Metas realistas a 6–12 meses. Nunca 5.0. Nunca por debajo del actual.
- Criticidad / prioridad / fase. Derívalos de
scoring/criticality-priority.md— no copies la regla predeterminada ciegamente. Cualquier desviación va enrationale. - Esfuerzo. Días-hombre de
scoring/effort-estimation.md. Usanullcuando sea realmente desconocido; nunca inventes un número para llenar la columna.
Paso 6 — Registrar lo que está bien
Llena positivePosture con fortalezas verificadas, sujetas al mismo estándar de evidencia. Un informe de
puros negativos se lee como un ataque y se descarta; además, no le dice al equipo qué proteger durante
la remediación. "No se encontró inyección SQL" es una declaración de cobertura, no una fortaleza.
Paso 7 — Cobertura y veredicto
coverage— método, tamaño (y cómo lo contaste), qué leíste en profundidad, qué barríste con búsquedas, qué no leíste, y las salvedades. Sé específico. Esto es lo que hace que los hallazgos sean falsables.verdictyreleaseGates— solo cuando el compromiso conlleva una decisión de despliegue. Indica el veredicto por entorno; bloquear producción mientras se aprueba desarrollo/pruebas es el resultado normal. La severidad no es lo mismo que la compuerta — justifica cada una.
Omite verdict y releaseGates por completo para evaluaciones de asesoría. El informe se adapta.
Paso 8 — Escribir, validar, generar
Establece meta.repoPath en la ruta absoluta del repositorio que revisaste. Eso es lo que envía el
informe a <repoPath>/architecture-review/ en lugar de al output/ de esta herramienta — el entregable
pertenece junto al código que describe. Omítelo solo cuando el código evaluado no esté en disco.
Escribe assessments/<slug>.assessment.json, luego:
npm run validate -- --input assessments/<slug>.assessment.json
npm run report -- --input assessments/<slug>.assessment.json
npm run report también escribe el panel por cliente Review-dashboard.html junto al informe,
construido a partir de cada evaluación que comparte el meta.client de esta. Escribe meta.client exactamente como en
las otras evaluaciones de ese cliente, o el panel se dividirá. Nunca ejecutes npm run portfolio --all
para un entregable de cliente — abarca varios clientes y es solo interno.
Resuelve cada error. Lee cada advertencia y ya sea corrige el problema subyacente o sé capaz de justificarlo — las advertencias codifican las reglas anteriores (P0 fuera de fase 1, inflación de P0, evidencia faltante, dominio de esfuerzo en fase 1, objetivos en 5.0).
Archivos de salida
Toda la salida es HTML — archivos únicos autocontenidos con gráficos SVG en línea, aptos para imprimir a PDF.
| Archivo | Escrito en | Audiencia |
|---|---|---|
ARCHITECTURE-REVIEW-<app>.html | <repoPath>/architecture-review/ | Todos. Un informe por aplicación, cubriendo material ejecutivo y evidencia técnica completa. |
<slug>.assessment.json | <repoPath>/architecture-review/ | Una copia junto al informe para que el repositorio tenga todo el registro. assessments/ sigue siendo canónico. |
Review-dashboard.html | <repoPath>/architecture-review/ | Resumen de solo las aplicaciones de este cliente, generado automáticamente con cada informe. No contiene nada de otros clientes. |
Un informe por aplicación. La revisión de arquitectura comienza con veredicto, objetivo, resumen ejecutivo y cuadro de mando para tomadores de decisiones, luego continúa con modelo del sistema, cobertura, evidencia y hoja de ruta para ingenieros.
Existen dos salidas opcionales: un resumen condensado DECISION-BRIEF con la opción --brief y una versión Word con
--docx. Ambos son subconjuntos estrictos. No generes ninguno a menos que el usuario lo solicite explícitamente.
Reglas estrictas
- Nunca edites a mano el HTML generado. Cambia el JSON y regenera. Si el informe necesita decir
algo nuevo, extiende primero
schema/assessment.schema.jsonytools/. - Nunca copies hallazgos de
examples/. Describe el sistema de otro cliente. - Nunca fabriques una ruta de archivo o número de línea. Si no lo abriste, no tienes evidencia.
- Nunca reportes una regla como un hallazgo. "Debería usar inyección de dependencias" no es un hallazgo.
"
OrderServiceconstruye su propioDbContextenorder.service.ts:31, por lo que no se puede probar sin una base de datos en vivo" sí lo es. - No infles la hoja de ruta. Cada día-hombre debe rastrearse hasta un hallazgo.
- Solo Node — Python no está instalado en esta máquina.
Escala
Una aplicación pequeña suele producir 10–20 hallazgos y 30–60 días-hombre. Una plataforma mediana, 25–40 hallazgos y 80–150 días-hombre. Si tus números están muy fuera de ese rango para el tamaño del sistema, algo se desvió — usualmente inflación de severidad o duplicados no consolidados.