tesal92/agent-readiness-audit

Auditoría de preparación para agentes

Audita el repositorio actual contra la lista de verificación a continuación e informa las brechas. Esta es una auditoría DE SOLO LECTURA: nunca modifiques, crees ni elimines archivos del repositorio.

Paso 1: Descubre el stack

Antes de juzgar nada, identifica:

• Lenguajes, frameworks, gestor de paquetes, estructura de monorepo
• Linter, formateador y typechecker en uso
• Test runner
• Gestor de hooks (husky, lefthook, pre-commit, simple-git-hooks, plain .git/hooks)
• Sistema de CI y su configuración
• Archivos de instrucciones para agentes (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions, etc.)
• Directorios que contengan skills, runbooks, prompts o documentos de flujo de trabajo

Evalúa usando las herramientas que este repositorio realmente usa. No recomiendes cambiar de herramientas a menos que las actuales no puedan hacer el trabajo.

Presupuesto

• Comienza con listados de directorios, archivos de configuración y archivos de instrucciones. Usa grep, conteos y listados de archivos en lugar de leer archivos fuente completos.
• Muestrea como máximo 3 archivos representativos por paquete principal.
• Si el repositorio es demasiado grande para cubrirlo, indica qué partes no se examinaron.

Paso 2: Evalúa cada elemento de la lista de verificación

Asigna un estado por elemento:

• PASS: claramente presente y funcionando
• PARTIAL: existe pero está incompleto, desactualizado, no se aplica o es inconsistente
• MISSING: lo verificaste y no está presente
• N/A: no aplica a este stack (explica por qué)
• UNCLEAR: no pudiste verificarlo (indica qué te bloqueó, ej. CI externo o partes del repo no examinadas)

Respaldar cada estado con evidencia: rutas de archivos, claves de configuración o fragmentos citados cortos (menos de 15 palabras cada uno). Nunca adivines: si verificaste y no encontraste nada, marca MISSING; si no pudiste verificar, marca UNCLEAR.

Lista de verificación

1. Instrucciones compartidas para agentes

   • Archivo de instrucciones único a nivel raíz leído por todos los agentes y nuevos ingenieros
   • Cubre reglas de estilo de código (estilo de exportación, estructura de importaciones, organización de archivos, antipatrones)
   • Exige validar datos externos en los límites de confianza
   • Indica qué pruebas vale la pena escribir
   • Define una puerta de finalización: lint, typecheck y pruebas relevantes deben pasar antes del commit
   • Es actual y específico. Verifica 3 a 5 reglas contra el código real e informa si el código las sigue.

2. Skills de flujo de trabajo en el repositorio

   • Flujos de trabajo recurrentes documentados como skills paso a paso o runbooks junto al código
   • Cobertura: commits, apertura/apilamiento de PRs, revisión de código, pasar un PR por CI, cambios de dependencias, localización
   • Flujos de trabajo específicos del stack cubiertos (capa de datos, enrutador, sistema de diseño, codegen, etc.)
   • Cada skill tiene un desencadenante, pasos ordenados y una definición de finalización
   • Los skills son la única fuente de verdad, no duplicados ni contradictorios

3. Convenciones aplicadas como reglas de lint

   • Las convenciones documentadas tienen reglas de lint correspondientes
   • Reglas de lint personalizadas o plugins cubren usos específicos del proyecto (obtención de datos, estilos, pruebas, traducciones)
   • Existen reglas antipatrón para errores comunes de agentes: aserciones de tipo encadenadas o innecesarias, parámetros débilmente tipados (unknown/any), spreads condicionales de objetos vacíos, más cualquier patrón de baja calidad recurrente encontrado en este código
   • Las reglas son errores, no advertencias, sin desactivaciones generales

4. Gateways automatizados

   • El hook pre-commit formatea, aplica lint y typecheck al código modificado
   • El hook pre-push aplica lint o pruebas a los paquetes afectados, incluyendo dependientes
   • El CI vuelve a ejecutar las mismas comprobaciones para que los hooks no se puedan saltar
   • Los hooks son razonablemente rápidos
   • Los hooks están configurados: la configuración del hook está commiteada, existe un paso de instalación (script prepare, documento de configuración o core.hooksPath), y los comandos que llama existen. Verifica leyendo archivos; nunca ejecutes hooks.

5. Supervisión y estructura

   • Decisiones de arquitectura documentadas
   • Se requiere revisión de PR antes de fusionar (verifica protección de rama o CODEOWNERS si es visible)
   • Los límites de paquetes y módulos son claros y se aplican

Paso 3: Encuentra convenciones no documentadas

Muestrea el código en busca de patrones aplicados consistentemente pero no escritos en ningún lado, y de patrones que los agentes suelen equivocarse (tipado débil, datos externos no validados, exportaciones inconsistentes, lógica duplicada). Enumera los 5 principales candidatos para agregar al archivo de instrucciones o convertir en reglas de lint.

Paso 4: Informe

Produce:

1. Una tabla resumen: elemento, estado, evidencia en una línea
2. Una sección de "brechas": cada elemento PARTIAL, MISSING o UNCLEAR, qué está mal y por qué es importante para la fiabilidad del agente
3. Una lista de recomendaciones priorizadas (de mayor apalancamiento primero), cada una con un paso concreto siguiente y esfuerzo aproximado (pequeño/mediano/grande), expresadas en términos de las herramientas existentes de este repositorio
4. Las 5 principales convenciones candidatas del Paso 3

Sé directo. No adornes con elogios. Si algo está bien, di PASS y continúa.

Después del informe, ofrece andamiar las piezas faltantes (archivo de instrucciones inicial, plantillas de skills, esbozos de reglas de lint), pero no crees nada hasta que te lo pidan.