aryashreep/ctx-audit

Auditoría de contexto

Los repositorios que adoptan esta convención mantienen un pequeño conjunto de archivos persistentes para que los agentes no tengan que derivar lo mismo en cada sesión: cuáles son las convenciones del proyecto (AGENTS.md), qué se ha decidido y por qué (memory.md), y aproximadamente cómo está organizado el código base (.agent/graph.md). Este skill comprueba si esos archivos existen y están actualizados antes de que confíes en ellos o antes de que recurras a escanear el repositorio manualmente.

Frases de activación

Inicio de sesión / comprobación de confianza

• "ponme al día en este repositorio"
• "¿qué sabes sobre este proyecto?"
• "¿debería confiar en AGENTS.md / memory.md?"
• "¿los archivos de contexto están actualizados?"
• "verificar contexto" / "auditoría de contexto"

Desactualización

• "¿AGENTS.md está obsoleto?" / "¿memory.md está obsoleto?"
• "¿cuántos commits desde la última sincronización?"
• "¿mis archivos de agente están actualizados?"
• "comprobar si el contexto está obsoleto"

Costo de tokens

• "¿cuánto ahorran los archivos de contexto?"
• "ahorro de tokens" / "costo de contexto"
• "medir ahorro de tokens"
• "tokens de línea base vs tokens seleccionados"

Configuración / incorporación

• "inicializar AGENTS.md" / "inicializar contexto"
• "instalar ctx-audit" / "conectar el hook de contexto"
• "configurar contexto de IA" / "¿este proyecto está listo para IA?"

CI / automatización

• "añadir ctx-audit a CI"
• "añadir un hook pre-push"
• "forzar frescura del contexto en CI"

Arquitectura

• "¿tengo un mapa de arquitectura?"
• "generar graph.md" / "ejecutar graphify"

Cómo ejecutar

La forma recomendada de ejecutar ctx-audit:

npx ctx-audit

Alternativamente, si está instalado como skill:

node <ruta-a-esta-carpeta-del-skill>/../scripts/audit.mjs

Banderas:

• --json — salida legible por máquina (úsala si vas a actuar sobre el resultado mediante programación).
• --strict — código de salida 1 si falta algo o está obsoleto.
• --ci — alias de --strict --json.
• --help — muestra el uso y sale.

Subcomandos

# Inicializar AGENTS.md + memory.md (interactivo — escribe archivos directamente en la raíz del repositorio)
npx ctx-audit init

# Instalación en un solo comando: copia el skill a ~/.claude/skills/, lo registra en CLAUDE.md
npx ctx-audit install

# Hook de git: ejecuta auditoría --strict en cada push
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall

# CLAUDE.md del proyecto: añade un bloque de instrucciones para agentes
npx ctx-audit claude install
npx ctx-audit claude uninstall

# Informe de ahorro de tokens (formato centrado y compartible)
npx ctx-audit benchmark

Tabla de decisión del agente

Estado	Significado	Acción
FRESCO	Menos de la mitad del umbral de obsolescencia en commits desde la última sincronización	Confía en el archivo — léelo en lugar de escanear las fuentes sin procesar
¿OBSOLETO?	Acercándose al umbral (posiblemente obsoleto)	Precaución leve — verifica afirmaciones críticas antes de confiar
¡OBSOLETO!	Superó el umbral, se considera fallo	Trata las afirmaciones como no verificadas; verifica contra el código real; actualiza después de la sesión
OBSOLETO	Significativamente atrasado, se considera fallo	Igual que ¡OBSOLETO! pero más urgente; actualiza inmediatamente después de la sesión
FALTA (requerido)	El archivo no existe	Ejecuta npx ctx-audit init; no continúes como si la convención estuviera en vigor
ausente (opcional)	El archivo opcional no está presente	Aceptable; considera ejecutar /graphify para generar graph.md
sobre presupuesto	El recuento de tokens supera maxTokens	El archivo está inflado — recórtalo; leerlo puede costar más de lo que ahorra
referencia muerta	Una ruta con backticks o dir/archivo.ext mencionada en el archivo no existe en disco	Actualiza la referencia; el archivo documenta una estructura desactualizada
SHA cambiado	last_synced_commit actualizado pero el cuerpo sin cambios	Verifica si el archivo realmente refleja cambios recientes; puede ser una actualización mecánica

Interpretación de resultados

• FALTA (archivo requerido): no continúes como si la convención estuviera en vigor. Ofrece inicializar un archivo de inicio (ejecuta npx ctx-audit init) en lugar de trabajar sin uno o de volver silenciosamente al enfoque de "explorar todo manualmente".
• FRESCO: el archivo está actualizado. Léelo en lugar de escanear las fuentes sin procesar.
• ¿OBSOLETO? (posiblemente obsoleto): acercándose al umbral. Verifica afirmaciones críticas.
• ¡OBSOLETO! (probablemente obsoleto): trata sus afirmaciones como no verificadas. Verifica cualquier afirmación importante contra el código real, y después de tu sesión, actualiza el archivo y su last_synced_commit.
• OBSOLETO: significativamente atrasado. Mismo tratamiento que ¡OBSOLETO! pero más urgente.
• Los recuentos de tokens son una heurística de ~3.5 caracteres/token — útiles como orientación, no exactos. Si un archivo se marca como "sobre presupuesto", es que se ha vuelto tan inflado que leerlo empieza a costar lo que se suponía que debía ahorrar; sugiere recortarlo.
• Advertencias de referencia muerta: rutas mencionadas en archivos de contexto que ya no existen en disco. Indican que el archivo referencia una estructura desactualizada.

Ejemplos prácticos

Auditoría básica al inicio de sesión:

npx ctx-audit

Puerta de CI (fallar compilación si el contexto está obsoleto):

# .github/workflows/ctx-audit.yml
- name: Auditar frescura del contexto
  run: npx ctx-audit --strict

Salida JSON para uso programático:

npx ctx-audit --json | jq '.checks[] | {archivo, nivelDeObsolescencia, obsoleto}'

Incorporación en un solo comando:

npx ctx-audit install        # copia el skill, lo registra en CLAUDE.md
npx ctx-audit hook install   # añade guardia pre-push
npx ctx-audit claude install # añade nota al CLAUDE.md del proyecto
npx ctx-audit init           # inicializa AGENTS.md + memory.md

Verificar obsolescencia solo de un subsistema específico (mediante frontmatter):

---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---

Solo los commits que tocan src/auth/ o src/api/ cuentan para la obsolescencia de este archivo.

Medir ahorro de tokens:

npx ctx-audit benchmark

Configuración

Coloca .ctx-audit.json en la raíz del repositorio para personalizar el comportamiento:

{
  "archivos": [{ "id": "...", "archivo": "...", "etiqueta": "...", "maxTokens": N, "requerido": true }],
  "directoriosFuente": ["src", "packages/core"],
  "umbralObsolescencia": 10,
  "topeArchivoBase": 300
}

Frontmatter

Cada archivo de contexto debe comenzar con frontmatter:

---
last_synced_commit: <sha de git>
watches: src/auth/**, src/api/**
---

El campo watches (opcional) limita las comprobaciones de obsolescencia solo a commits que tocan esas rutas, en lugar de a todos los directorios fuente.

Si faltan archivos requeridos — inicialízalos

Ejecuta npx ctx-audit init para generar plantillas. En una TTY escribe archivos directamente en la raíz del repositorio; cuando se redirige, imprime en stdout para redireccionamiento. La bandera --init heredada sigue siendo compatible como alias hacia atrás.

AGENTS.md — convenciones estables del proyecto: comandos de compilación/prueba/linting, reglas de diseño de archivos, cosas que el agente nunca debe hacer. Debe cambiar raramente.

memory.md — un registro de decisiones en curso, no una repetición del código actual. Cada entrada: qué se probó, qué se decidió, por qué, y qué reconsiderar si las circunstancias cambian. Añade, no reescribas la historia.

.agent/graph.md (opcional pero recomendado una vez que el repositorio crezca) — un párrafo por módulo principal describiendo su responsabilidad y con qué se comunica. No contenido de archivos, no un árbol exhaustivo — solo lo suficiente para que un agente pueda navegar sin tener que releer todo. Consejo: ejecuta /graphify para generar esto automáticamente a partir del código base en lugar de escribirlo a mano.

Después de inicializar o actualizar cualquiera de estos archivos, actualiza su last_synced_commit al HEAD actual para que la próxima auditoría no lo marque inmediatamente como obsoleto.