evolveguard

Traducción al español del markdown

evolveguard

Qué hace • Inicio rápido • Referencia de la CLI • Uso nativo para agentes • Servidor MCP • Comparación • Preguntas frecuentes

Detecta la deriva de comportamiento cuando una habilidad de agente de Claude o un archivo MEMORY.md de Claude Code se modifica a sí mismo, antes de que el cambio se publique.

# PyPI -- Python CLI + library (genuine port, not a Node wrapper)
pip install evolveguard-cli

# npm -- JavaScript/TypeScript CLI + library
npm install -g evolveguard-cli

[!NOTE] Ambos paquetes están publicados y tienen nombres coherentes: evolveguard-cli en PyPI y evolveguard-cli en npm (renombrado el 2026-07-19 desde el antiguo evolveguard, que ahora está obsoleto en ambos registros). npm install -g evolveguard-cli y pip install evolveguard-cli funcionan ambos hoy; los GIF de demostración a continuación se grabaron con los paquetes publicados, no con una compilación local.

Qué hace

evolveguard record ./SKILL.md --fixtures ./fixtures.json
# ... skill gets edited, by a human or an agent ...
evolveguard check ./SKILL.md

EvolveGuard v0.1.4 -- Regression Check
skill: monorepo-scanner  baseline: 2026-07-15  fixtures: 1

[DRIFT] fixture: "scan a monorepo"  new tool call: fs.write (baseline had none)
         -> new tool call: fs.write (baseline had none) -- this edit introduces a
            capability the baseline never used

0 PASS, 1 DRIFT, 0 FAIL
exit code 1 (DRIFT blocks merge by default; override with --allow-drift)

Esa es la salida real del caso de prueba fixtures/labeled-non-breaking-edits/case-03-add-write-capability/ del propio repositorio, conectado a filesystem: read-only que se convierte en read-write en el frontmatter de la habilidad. Reprodúcelo tú mismo: evolveguard record el before/SKILL.md en esa carpeta contra su fixtures.json, y luego evolveguard check el after/SKILL.md.

Características

Análisis estático, no una ejecución de agente en vivo. record analiza el frontmatter YAML de un archivo de habilidad (declarados tools, network, filesystem, scope y cualquier hooks incluido), escanea el cuerpo del texto de la habilidad y los scripts de hooks en busca de evidencia de llamadas de red o escrituras en el sistema de archivos, y combina ambos en una superficie de capacidades. check vuelve a analizar el archivo editado con la misma lógica y compara los resultados. Ninguno de los dos comandos ejecuta eval, lanza un subproceso ni ejecuta los scripts de hooks de una habilidad, ni en la distribución de TypeScript ni en la de Python.

Comparación de dos niveles detecta deriva que un solo fixture podría pasar por alto. El expectedToolCalls de cada fixture filtra la superficie de capacidades registrada para quedarse con lo que ese fixture considera relevante, pero check también compara por separado la superficie de capacidades completa de la habilidad. Una nueva capacidad que ningún expectedToolCalls de fixture cubra por casualidad aparece como una entrada surfaceChanges en lugar de pasar en silencio. Confirmado con el fixture case-04-scope-widened del propio repositorio, donde un alcance fs.write se amplía de ./workspace/** a ./**.

0 % de falsos positivos en un corpus etiquetado, de forma reproducible. npx vitest run src/evolveguard/benchmark.test.ts ejecuta el pipeline de registro/comprobación/diff contra fixtures/labeled-non-breaking-edits/: 2 casos etiquetados como no ruptura (un ajuste de redacción, una corrección de errata) y 3 etiquetados como ruptura (una nueva capacidad de escritura, un alcance ampliado, un script de hook que gana una llamada de red). A fecha de este commit, ambos casos no ruptura se mantienen limpios: 0 de 2 marcados como deriva. El corpus es pequeño y crece a medida que se reportan más ediciones reales de habilidades.

Una protección contra path traversal en los scripts de hooks. Las rutas de hooks declaradas de una habilidad se resuelven y se validan contra el propio directorio de esa habilidad antes de leerse, incluida una verificación de escape de symlink que se ejecuta después de que pase la comprobación léxica de contención (src/evolveguard/paths.ts y python/src/evolveguard/paths.py).

Todos los subcomandos admiten --json. record, check y report aceptan todos una bandera --json y devuelven una estructura estable etiquetada con schemaVersion, de modo que un agente de codificación puede invocar cualquiera de ellos como subproceso y analizar el resultado directamente.

Dos distribuciones mantenidas de forma independiente y compatibles en formato. El paquete npm (TypeScript, raíz del repositorio) y el paquete PyPI (Python, python/) analizan el mismo esquema de frontmatter y producen JSON de baseline y de informe byte-compatibles. Una línea base registrada con una CLI se puede comprobar con la otra; consulta docs/concepts.md para los detalles del formato de archivo.

evolveguard detecta cambios en lo que una habilidad está declarada o mostrada como capaz de hacer. No ejecuta un agente LLM en vivo ni reproduce una transcripción real de conversación, por lo que no puede decirte si un agente se comportaría de manera diferente ante un prompt dado. Ese es un límite de alcance intencional, y también la razón por la que no necesita nada alojado y funciona completamente sin conexión en un hook de pre-commit o en un trabajo de CI.

Inicio rápido

# 1. Record a baseline against a skill and its labeled fixtures
evolveguard record ./skills/my-skill/SKILL.md --fixtures ./fixtures/my-skill.json
# writes ./skills/my-skill/.evolveguard-baseline.json

# 2. Edit the skill (by hand, or let an agent edit it)

# 3. Check for drift
evolveguard check ./skills/my-skill/SKILL.md
# writes ./evolveguard-report.json, exits 1 if drift was found

Un archivo de fixtures es un arreglo JSON de prompts etiquetados y las formas de llamada de herramientas que se espera que cada uno toque:

[
  {
    "id": "scan-a-monorepo",
    "prompt": "scan a monorepo",
    "expectedToolCalls": [{ "tool": "fs.read" }, { "tool": "fs.write" }]
  }
]

expectedToolCalls es opcional; omítelo y el fixture se tratará como si ejercitara la superficie de capacidades completa de la habilidad. scopeMatches (un glob) reduce una herramienta a un alcance específico del sistema de archivos, p. ej. { "tool": "fs.write", "scopeMatches": "./workspace/**" }.

Referencia de comandos de la CLI

Generada a partir de la salida real de --help de la CLI instalada (verificada tanto con las compilaciones de npm como de PyPI; las banderas y los valores predeterminados son idénticos en ambas distribuciones).

Usage: evolveguard [options] [command]

Regression-testing CLI for self-edited Claude Agent Skills (SKILL.md,
MEMORY.md) -- golden-transcript record/replay against a skill's own declared
and inferred capability surface, zero hosted infrastructure.

Options:
  -V, --version                  output the version number
  -h, --help                     display help for command

Commands:
  record [options] <skillPath>   Record a golden-transcript baseline for a
                                 skill against a set of labeled fixtures
  check [options] <skillPath>    Replay the fixtures from a baseline against
                                 the current (possibly edited) skill and report
                                 drift
  report [options] [reportPath]  Print a previously generated
                                 evolveguard-report.json
  mcp                            [coming soon] Expose record/check/report as
                                 MCP tools for a coding agent to call
                                 mid-session
  help [command]                 display help for command

Usage: evolveguard record [options] <skillPath>

Record a golden-transcript baseline for a skill against a set of labeled
fixtures

Arguments:
  skillPath          path to the SKILL.md or MEMORY.md file to baseline

Options:
  --fixtures <path>  path to a fixtures JSON file (array of {id, prompt,
                     expectedToolCalls?})
  --baseline <path>  path to write the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --json             output structured JSON instead of human-readable text
                     (default: false)
  -h, --help         display help for command

Usage: evolveguard check [options] <skillPath>

Replay the fixtures from a baseline against the current (possibly edited) skill
and report drift

Arguments:
  skillPath          path to the SKILL.md or MEMORY.md file to check

Options:
  --baseline <path>  path to the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --report <path>    path to write the report file (default:
                     "./evolveguard-report.json")
  --allow-drift      exit 0 even if drift is detected (drift is still reported)
                     (default: false)
  --json             output structured JSON instead of human-readable text
                     (default: false)
  -h, --help         display help for command

Usage: evolveguard report [options] [reportPath]

Print a previously generated evolveguard-report.json

Arguments:
  reportPath  path to the report file (default: "./evolveguard-report.json")

Options:
  --json      output structured JSON instead of human-readable text (default:
              false)
  -h, --help  display help for command

Códigos de salida: 0 todos los fixtures PASAN y no hay deriva a nivel de superficie, 1 se encontró al menos una DERIVA (pasa --allow-drift para salir igualmente con 0 mientras se sigue reportando), 2 un error de uso o un archivo que no se pudo analizar.

[!WARNING] El evolveguard --version de la compilación npm imprime actualmente 0.1.0 aunque el paquete publicado está en una versión package.json más reciente; la compilación PyPI lee su versión de los metadatos del paquete instalado y la reporta correctamente. Usa las insignias de arriba, no --version, si necesitas el número de versión publicado exacto del paquete npm.

Uso nativo para agentes

Cada subcomando admite --json para una salida estructurada que un agente pueda analizar directamente:

evolveguard check ./SKILL.md --json

{
  "schemaVersion": 1,
  "skillName": "monorepo-scanner",
  "results": [
    {
      "id": "scan-a-monorepo",
      "verdict": "DRIFT",
      "changes": [
        /* ... */
      ]
    }
  ],
  "surfaceChanges": [],
  "summary": { "pass": 0, "drift": 1, "total": 1 },
  "exitCode": 1
}

[!NOTE] La distribución de Python incluye un servidor MCP real (consulta Servidor MCP a continuación). La distribución npm/TypeScript sigue teniendo el subcomando evolveguard mcp como un "próximamente" pendiente; hasta que se publique, invoca record/check/report --json directamente como subproceso desde tu agente de codificación, o usa el servidor MCP de Python incluso si el resto de tu cadena de herramientas está en el paquete npm.

Servidor MCP

La distribución de Python (evolveguard-cli en PyPI) incluye un servidor del Protocolo de Contexto de Modelos (MCP), de modo que un agente compatible con MCP (Claude Desktop, Claude Code, etc.) pueda invocar evolveguard directamente en lugar de usar un subproceso y analizar texto. La distribución npm/TypeScript todavía no incluye uno: su subcomando evolveguard mcp sigue siendo un stub.

pip install "evolveguard-cli[mcp]"

Agrégalo a la configuración de tu cliente MCP, por ejemplo el claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "evolveguard": {
      "command": "evolveguard-mcp"
    }
  }
}

Expone una única herramienta, run(args: list[str]), que invoca la CLI de evolveguard instalada con los mismos argv que escribirías en una terminal y devuelve {returncode, stdout, stderr, json?} (o {error: ...} si el comando falla, se agota el tiempo, o sale con un código distinto de cero), de modo que una sola herramienta cubre record, check y report sin necesidad de una herramienta MCP personalizada por subcomando. Ejemplo de llamada desde un agente:

{ "tool": "run", "arguments": { "args": ["check", "./SKILL.md", "--json"] } }

que devuelve el mismo informe estructurado que evolveguard check ./SKILL.md --json imprimiría, más el returncode/stdout/stderr sin procesar.

API de librería

evolveguard también exporta una API programática para el mismo pipeline, para equipos que quieran integrarlo en sus propias herramientas en lugar de invocar la CLI como subproceso. Ambas distribuciones exponen las mismas funciones y el mismo formato de archivo compatible con JSON; una línea base registrada con una CLI se puede comprobar con la otra (consulta docs/concepts.md).

TypeScript:

import {
  recordBaseline,
  replaySkill,
  diffAll,
  writeBaseline,
  readBaseline,
} from 'evolveguard';

const baseline = recordBaseline('./SKILL.md', './fixtures.json');
writeBaseline('./.evolveguard-baseline.json', baseline);

// ... skill gets edited ...

const saved = readBaseline('./.evolveguard-baseline.json');
const replay = replaySkill('./SKILL.md', saved);
const report = diffAll(saved, replay);

Consulta src/evolveguard/index.ts para ver la superficie exportada completa: parseSkillFile, deriveCapabilitySurface, loadSkill, buildFixtureSnapshots, loadFixtures, recordBaseline, replaySkill, diffFixture, diffAll, diffSurface, writeBaseline, readBaseline, writeReport, readReport, más las interfaces compartidas types.ts.

Python (pip install evolveguard-cli):

from evolveguard import record_baseline, replay_skill, diff_all, write_baseline, read_baseline

baseline = record_baseline("./SKILL.md", "./fixtures.json")
write_baseline("./.evolveguard-baseline.json", baseline)

# ... skill gets edited ...

saved = read_baseline("./.evolveguard-baseline.json")
replay = replay_skill("./SKILL.md", saved)
report = diff_all(saved, replay)

Consulta python/README.md para el recorrido específico de Python y la misma superficie exportada bajo evolveguard/__init__.py.

Comparación

Braintrust es una plataforma general de evaluación y observabilidad de LLM. Es una opción sólida si ya estás registrando trazas de un agente en vivo y quieres puntuación de evaluación estadística entre ejecuciones, pero requiere integración con SDK y un paso de definición de evaluación por aplicación. evolveguard no necesita nada de eso: apúntalo a un archivo SKILL.md y a un JSON de fixtures, y funciona.

agent-eval (el otro repositorio del mismo autor) responde a una pregunta distinta: si el comportamiento de un agente cambió entre dos versiones que tú defines, para cualquier agente, sin importar el framework, ejecutando ambas versiones tú mismo y calculando un valor p sobre la diferencia. evolveguard se activa directamente por un diff de archivo en SKILL.md/MEMORY.md y responde si esta edición específica cambió la superficie de capacidades que registró una línea base. Analiza el artefacto de la habilidad en sí y nunca te pide que definas ni ejecutes nada en vivo.

Qué es evolveguard y por qué existe

evolveguard es una herramienta de línea de comandos y una librería de TypeScript que detecta deriva de capacidades en archivos de habilidades de agente de Claude (SKILL.md) y archivos de auto-memoria de Claude Code (MEMORY.md) después de que se editan, por un humano o por un agente. Funciona analizando el alcance declarado del frontmatter de una habilidad y cualquier evidencia estática de comportamiento de red o de escritura en el sistema de archivos en su cuerpo de texto y scripts de hooks incluidos, guardando una instantánea de eso como línea base y volviendo a derivar la misma instantánea después de una edición para compararla con ella. Existe porque el ecosistema de habilidades de agente de Claude Code permite que las habilidades y los archivos de memoria cambien el comportamiento de un agente sin que un humano necesariamente revise cada edición en busca de regresiones, y ninguna herramienta existente comprueba esa forma específica de artefacto sin requerir integración con SDK o una ejecución de agente en vivo.

Estado

Esta es una versión v0.1: una adición pequeña y enfocada al ecosistema existente de Claude Agent Skills. Se distribuye completamente bajo licencia MIT, sin nivel propietario, como dos paquetes independientes e igualmente de primera clase:

• PyPI (evolveguard-cli, Python), disponible en pypi.org/project/evolveguard-cli. Un port independiente genuino, no un envoltorio alrededor del binario de Node (ver python/README.md). pip install evolveguard-cli lo instala directamente. El paquete se publicó originalmente bajo el nombre evolveguard; ese proyecto anterior de PyPI está retirado y ya no recibe actualizaciones; instala evolveguard-cli en su lugar.
• npm (evolveguard-cli, TypeScript), disponible en npmjs.com/package/evolveguard-cli. npm install -g evolveguard-cli lo instala directamente. Renombrado el 2026-07-19 desde el antiguo evolveguard simple, que ahora está obsoleto, para coincidir con la convención de nombres del paquete de PyPI.

Preguntas frecuentes

¿Qué es evolveguard, exactamente? Una herramienta de línea de comandos y una biblioteca que detecta desviaciones de capacidad en archivos de Claude Agent Skill (SKILL.md) y archivos de auto-memoria de Claude Code (MEMORY.md) después de que se editan. No es un framework de agentes auto-evolutivos y no construye, ejecuta ni aloja agentes por sí mismo. Es una compuerta de CI de pruebas de regresión que reacciona a un diff de archivo en un artefacto de skill que ya cambió, por un humano o un agente. Consulta "Qué es evolveguard y por qué existe" arriba para la definición completa.

¿Evolveguard llama a un LLM? No. Tanto record como check son completamente estáticos y deterministas; consulta "Características" arriba para ver exactamente qué analiza y escanea cada comando.

¿Cuál es el diferenciador principal frente a una herramienta de pruebas o evaluación general? No necesita nada alojado ni nada que integrar: apúntalo a un archivo SKILL.md y a un JSON de fixtures, y record/check funcionan de inmediato, con integración de SDK cero y sin ejecución de agente en vivo. Ese es el equilibrio que documenta la tabla "Cómo se compara" arriba: un alcance más limitado que una plataforma de evaluación general, a cambio de configuración cero.

¿Cómo se compara evolveguard con Braintrust? Braintrust es una plataforma general de evaluación y observabilidad de LLMs que requiere integración de SDK y un paso de definición de evaluación, y puntúa trazas reales de una ejecución de agente en vivo. evolveguard no requiere nada de eso; analiza el propio archivo de skill y nunca llama a un LLM. Usa Braintrust si ya estás registrando trazas y quieres puntuación estadística de evaluación entre ejecuciones. Usa evolveguard si quieres una verificación de pre-commit o de CI de que una edición de SKILL.md/MEMORY.md no amplió silenciosamente lo que la skill puede hacer. Consulta la tabla de comparación en "Cómo se compara" arriba para el desglose completo, incluida la comparación con agent-eval del mismo autor.

¿Funciona con archivos MEMORY.md, que no tienen frontmatter? Sí. Un archivo sin frontmatter se analiza con un ámbito declarado vacío, por lo que su superficie de capacidad proviene enteramente de la evidencia estática que se encuentra en el texto del cuerpo.

¿En qué plataformas se ejecuta y cómo lo instalo? El paquete de npm requiere Node.js >=20.12 (cualquier sistema operativo que Node soporte) y se instala con npm install -g evolveguard-cli. El paquete de PyPI requiere Python >=3.9 y se instala con pip install evolveguard-cli. Ambas distribuciones son paquetes de biblioteca/CLI puros, sin enlaces nativos, por lo que no hay un paso de compilación específico del sistema operativo en ninguno de los dos lados.

¿Cuál es una limitación real a conocer antes de confiar en esto? Solo ve la capacidad declarada o mostrada, no el comportamiento en tiempo de ejecución. Una skill podría pasar check y aun así comportarse de manera diferente ante un prompt dado, de formas que no tocan su superficie de capacidad. El benchmark de falsos positivos (ver "Características" arriba) también es actualmente un corpus pequeño etiquetado a mano de 5 pares de antes/después, no un conjunto de datos grande, así que trata la cifra del 0% como una medición inicial, no como una garantía estadística. La distribución de Python incluye un servidor MCP real (ver "Servidor MCP" arriba); el subcomando mcp de npm/TypeScript sigue siendo un stub de "próximamente", y la salida de evolveguard --version de la compilación de npm actualmente va por detrás de la versión real publicada del paquete (ver "Referencia de comandos CLI" arriba).

¿Es un framework general de evolución de agentes? No. Consulta "Cómo se compara" arriba. evolveguard deliberadamente no construye ni aloja un framework de agentes auto-evolutivos; solo prueba ediciones de skill/memoria que ya ocurrieron.

¿Evolveguard es gratuito para usar, incluso comercialmente? Sí. Está bajo licencia MIT sin nivel propietario ni versión de pago; consulta LICENSE. Puedes usarlo, modificarlo y redistribuirlo, incluso en proyectos comerciales, bajo los términos estándar de MIT.

Contribuciones

Consulta CONTRIBUTING.md. Cada cambio llega con pruebas en ambas distribuciones; un cambio en el esquema del frontmatter, en la derivación de la superficie de capacidad o en la lógica del veredicto de diff debe realizarse tanto en src/evolveguard/ (TypeScript) como en python/src/evolveguard/ (Python), con una cobertura equivalente añadida a ambas suites.

Seguridad

Consulta SECURITY.md. evolveguard lee archivos locales a los que le apuntas y nunca ejecuta ninguno de ellos; no hace llamadas de red y no ejecuta un agente en vivo.

Licencia

MIT. Consulta LICENSE.