evolveguard

evolveguard

O que faz • Início rápido • Referência da CLI • Uso nativo para agentes • Servidor MCP • Comparação • Perguntas frequentes

Detecte desvios comportamentais quando uma Skill de Agente Claude ou um arquivo MEMORY.md do Claude Code se edita, antes que a edição seja enviada.

# 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 os pacotes estão ativos e nomeados de forma consistente: evolveguard-cli no PyPI e evolveguard-cli no npm (renomeado em 2026-07-19 do antigo evolveguard simples, que agora está obsoleto em ambos os registros). npm install -g evolveguard-cli e pip install evolveguard-cli funcionam hoje; os GIFs de demonstração abaixo foram gravados contra os pacotes publicados, não uma compilação local.

O que faz

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

EvolveGuard v0.2.0 -- 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)

Essa é a saída real do próprio caso de teste fixtures/labeled-non-breaking-edits/case-03-add-write-capability/ deste repositório, conectado a filesystem: read-only tornando-se read-write no frontmatter da skill. Reproduza você mesmo: evolveguard record o before/SKILL.md nessa pasta contra seu fixtures.json, depois evolveguard check o after/SKILL.md.

Recursos

Análise estática, não uma execução de agente ao vivo. record analisa o frontmatter YAML de um arquivo de skill (declarado tools, network, filesystem, scope e qualquer hooks incluído), verifica o texto do corpo da skill e os scripts de hook em busca de evidências de chamadas de rede ou gravações no sistema de arquivos, e combina ambos em uma superfície de capacidades. check re-analisa o arquivo editado com a mesma lógica e compara os resultados. Nenhum comando executa eval, chama um subprocesso ou executa os scripts de hook de uma skill, tanto na distribuição TypeScript quanto na Python.

Comparação em dois níveis captura desvios que um único fixture pode perder. O expectedToolCalls de cada fixture filtra a superfície de capacidades registrada para o que esse fixture importa, mas check também compara a superfície de capacidades completa da skill separadamente. Uma nova capacidade que nenhum expectedToolCalls de fixture cobre ainda aparece como uma entrada surfaceChanges em vez de passar silenciosamente. Confirmado contra o próprio fixture case-04-scope-widened deste repositório, onde um escopo fs.write se amplia de ./workspace/** para ./**.

0% de falsos positivos em um corpus rotulado, de forma reproduzível. npx vitest run src/evolveguard/benchmark.test.ts executa o pipeline de registro/verificação/comparação contra fixtures/labeled-non-breaking-edits/: 2 casos rotulados manualmente como não críticos (um ajuste de redação, uma correção de erro de digitação) e 3 rotulados como críticos (uma nova capacidade de gravação, um escopo ampliado, um script de hook ganhando uma chamada de rede). A partir deste commit, ambos os casos não críticos permanecem limpos: 0 de 2 sinalizados como desvio. O corpus é pequeno e cresce conforme mais edições reais de skills são relatadas.

Uma proteção contra path traversal em scripts de hook. Os caminhos de hook declarados de uma skill são resolvidos e validados contra o próprio diretório da skill antes de serem lidos, incluindo uma reverificação de escape de symlink que é executada após a verificação de contenção lexical passar (src/evolveguard/paths.ts e python/src/evolveguard/paths.py).

Todo subcomando suporta --json. record, check e report aceitam uma flag --json e retornam uma estrutura estável marcada com schemaVersion, para que um agente de codificação possa chamar qualquer um deles como subprocesso e analisar o resultado diretamente.

Duas distribuições mantidas independentemente, compatíveis em formato. O pacote npm (TypeScript, raiz do repositório) e o pacote PyPI (Python, python/) analisam o mesmo esquema de frontmatter e produzem JSON de baseline e relatório byte-compatível. Um baseline registrado com uma CLI pode ser verificado com a outra; veja docs/concepts.md para os detalhes do formato de arquivo.

evolveguard detecta mudanças no que uma skill é declarada ou mostrada ser capaz de fazer. Ele não executa um agente LLM ao vivo nem reproduz uma transcrição real de conversa, então não pode dizer se um agente realmente se comportaria de forma diferente em um determinado prompt. Esse é um limite de escopo intencional, e também é por isso que não precisa de nada hospedado e roda totalmente offline em um hook de pré-commit ou job de CI.

Início 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

Um arquivo de fixtures é um array JSON de prompts rotulados e as formas de chamada de ferramenta que cada um deve tocar:

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

expectedToolCalls é opcional; omita-o e o fixture será tratado como exercitando a superfície de capacidades inteira da skill. scopeMatches (um glob) restringe uma ferramenta a um escopo específico do sistema de arquivos, por exemplo, { "tool": "fs.write", "scopeMatches": "./workspace/**" }.

Referência de comandos da CLI

Gerado a partir da saída real de --help da CLI instalada (verificado contra ambas as compilações npm e PyPI; flags e padrões são idênticos entre as distribuições).

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 saída: 0 todos os fixtures PASSAM e nenhum desvio de superfície, 1 pelo menos um DRIFT foi encontrado (passe --allow-drift para ainda sair com 0 enquanto ainda o relata), 2 um erro de uso ou um arquivo que falhou ao analisar.

[!WARNING] O evolveguard --version da compilação npm atualmente imprime 0.1.0 mesmo que o pacote publicado esteja em uma versão package.json mais recente; a compilação PyPI lê sua versão dos metadados do pacote instalado e a relata corretamente. Use os selos acima, não --version, se precisar do número de versão exato atualmente publicado do pacote npm.

Uso nativo para agentes

Todo subcomando suporta --json para saída estruturada que um agente pode analisar diretamente:

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] A distribuição Python inclui um servidor MCP real (veja Servidor MCP abaixo). O subcomando evolveguard mcp da distribuição npm/TypeScript ainda é um stub "em breve"; até que seja lançado, chame record/check/report --json diretamente como um subprocesso do seu agente de codificação, ou use o servidor MCP Python mesmo que o resto da sua ferramenta esteja no pacote npm.

Servidor MCP

A distribuição Python (evolveguard-cli no PyPI) inclui um servidor Model Context Protocol, para que um agente compatível com MCP (Claude Desktop, Claude Code, etc.) possa chamar evolveguard diretamente em vez de chamar um subprocesso e analisar texto. A distribuição npm/TypeScript ainda não inclui um — seu subcomando evolveguard mcp permanece um stub.

pip install "evolveguard-cli[mcp]"

Adicione-o à configuração do seu cliente MCP, por exemplo, o claude_desktop_config.json do Claude Desktop:

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

Ele expõe uma única ferramenta, run(args: list[str]), que chama a CLI evolveguard instalada com os argv exatos que você digitaria em um terminal e retorna {returncode, stdout, stderr, json?} (ou {error: ...} se o comando falhar, expirar ou sair com código não zero) — então uma ferramenta cobre record, check e report sem uma ferramenta MCP personalizada por subcomando. Exemplo de chamada de um agente:

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

que retorna o mesmo relatório estruturado que evolveguard check ./SKILL.md --json imprimiria, mais o returncode/stdout/stderr bruto.

API de biblioteca

evolveguard também exporta uma API programática para o mesmo pipeline, para equipes que desejam integrá-lo em suas próprias ferramentas em vez de chamar a CLI. Ambas as distribuições expõem as mesmas funções e o mesmo formato de arquivo compatível com JSON; um baseline registrado com uma CLI pode ser verificado com a outra (veja 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);

Veja src/evolveguard/index.ts para a superfície exportada completa: parseSkillFile, deriveCapabilitySurface, loadSkill, buildFixtureSnapshots, loadFixtures, recordBaseline, replaySkill, diffFixture, diffAll, diffSurface, writeBaseline, readBaseline, writeReport, readReport, mais as interfaces types.ts compartilhadas.

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)

Veja python/README.md para o passo a passo específico do Python e a mesma superfície exportada sob evolveguard/__init__.py.

Comparação

Braintrust é uma plataforma geral de avaliação e observabilidade de LLM. É uma escolha forte se você já está registrando traces de um agente ao vivo e deseja pontuação estatística de avaliação entre execuções, mas precisa de integração de SDK e uma etapa de definição de avaliação por aplicativo. evolveguard não precisa de nenhum dos dois: aponte-o para um arquivo SKILL.md e um JSON de fixtures, e ele funciona.

agent-eval (o outro repositório deste mesmo autor) responde a uma pergunta diferente: se o comportamento de um agente mudou entre duas versões que você define, para qualquer agente, independente de framework, executando ambas as versões você mesmo e calculando um valor-p na diferença. evolveguard é acionado diretamente por um diff de arquivo em SKILL.md/MEMORY.md e responde se esta edição específica mudou a superfície de capacidades que um baseline registrou. Ele analisa o artefato da skill em si e nunca pede que você defina ou execute nada ao vivo.

O que é evolveguard e por que ele existe

evolveguard é uma ferramenta de linha de comando e biblioteca TypeScript que detecta desvios de capacidades em arquivos de Skill de Agente Claude (SKILL.md) e arquivos de auto-memória do Claude Code (MEMORY.md) após serem editados, por um humano ou por um agente. Ele funciona analisando o escopo declarado no frontmatter de uma skill e qualquer evidência estática de comportamento de rede ou gravação no sistema de arquivos em seu texto do corpo e scripts de hook incluídos, capturando isso como um baseline e re-derivando a mesma captura após uma edição para comparar com ele. Ele existe porque o ecossistema de Agent Skills do Claude Code permite que skills e arquivos de memória mudem o comportamento de um agente sem que um humano necessariamente revise cada edição para regressões, e nenhuma ferramenta existente verifica essa forma específica de artefato sem exigir integração de SDK ou uma execução de agente ao vivo.

Status

Esta é uma versão v0.1: uma adição pequena e focada ao ecossistema existente de Claude Agent Skills. Ela é totalmente licenciada sob MIT, sem camada proprietária, e é distribuída como dois pacotes independentes e igualmente de primeira classe:

• PyPI (evolveguard-cli, Python), disponível em pypi.org/project/evolveguard-cli. Um port independente genuíno, não um wrapper em torno do binário Node (veja python/README.md). pip install evolveguard-cli o instala diretamente. O pacote foi originalmente publicado sob o nome evolveguard; esse projeto PyPI mais antigo foi descontinuado e não recebe mais atualizações; instale evolveguard-cli em vez dele.
• npm (evolveguard-cli, TypeScript), disponível em npmjs.com/package/evolveguard-cli. npm install -g evolveguard-cli o instala diretamente. Renomeado em 2026-07-19 do antigo evolveguard simples, que agora está obsoleto, para corresponder à convenção de nomenclatura do pacote PyPI.

FAQ

O que é evolveguard, exatamente? Uma ferramenta de linha de comando e biblioteca que detecta desvio de capacidade em arquivos de Claude Agent Skill (SKILL.md) e arquivos de memória automática do Claude Code (MEMORY.md) após serem editados. Não é um framework de agentes auto-evolutivos e não constrói, executa ou hospeda agentes por conta própria. É um portão de CI para testes de regressão que reage a um diff de arquivo em um artefato de skill que já mudou, por um humano ou um agente. Veja "O que é evolveguard e por que ele existe" acima para a definição completa.

O evolveguard chama um LLM? Não. Tanto record quanto check são totalmente estáticos e determinísticos; veja "Recursos" acima para exatamente o que cada comando analisa e escaneia.

Qual é o diferencial principal em relação a uma ferramenta geral de teste ou avaliação? Ele não precisa de nada hospedado e nada para integrar: aponte-o para um arquivo SKILL.md e um JSON de fixtures, e record/check funcionam imediatamente, com zero integração de SDK e nenhuma execução de agente ao vivo. Esse é o trade-off que a tabela "Como ele se compara" acima documenta: escopo mais restrito do que uma plataforma geral de avaliação, em troca de zero configuração.

Como o evolveguard se compara ao Braintrust? O Braintrust é uma plataforma geral de avaliação e observabilidade de LLM que exige integração de SDK e uma etapa de definição de avaliação, e pontua rastros reais de uma execução de agente ao vivo. O evolveguard não exige nada disso; ele analisa o próprio arquivo de skill e nunca chama um LLM. Use o Braintrust se você já registra rastros e deseja pontuação estatística de avaliação entre execuções. Use o evolveguard se você quiser uma verificação de pré-commit ou CI de que uma edição de SKILL.md/MEMORY.md não ampliou silenciosamente o que a skill pode fazer. Veja a tabela de comparação em "Como ele se compara" acima para o detalhamento completo, incluindo como ele se compara ao agent-eval do mesmo autor.

Funciona com arquivos MEMORY.md, que não têm frontmatter? Sim. Um arquivo sem frontmatter é analisado com um escopo declarado vazio, então sua superfície de capacidade vem inteiramente de evidências estáticas encontradas no corpo do texto.

Em quais plataformas ele roda e como eu o instalo? O pacote npm requer Node.js >=20.12 (qualquer SO que o Node suporte) e instala com npm install -g evolveguard-cli. O pacote PyPI requer Python >=3.9 e instala com pip install evolveguard-cli. Ambas as distribuições são pacotes puros de biblioteca/CLI, sem bindings nativos, então não há etapa de build específica do SO em nenhum dos lados.

Qual é uma limitação real a se conhecer antes de confiar nisso? Ele só vê capacidade declarada ou mostrada, não comportamento em tempo de execução. Uma skill pode passar em check e ainda se comportar de maneira diferente em um determinado prompt, de formas que não tocam sua superfície de capacidade. O benchmark de falsos positivos (veja "Recursos" acima) também é atualmente um corpus pequeno e rotulado manualmente de 5 pares antes/depois, não um grande conjunto de dados, então trate o valor de 0% como uma medição inicial, não uma garantia estatística. A distribuição Python inclui um servidor MCP real (veja "Servidor MCP" acima); o subcomando mcp do npm/TypeScript ainda é um stub "em breve", e a saída de evolveguard --version do build npm atualmente fica atrás da versão publicada real do pacote (veja "Referência de comandos da CLI" acima).

Isso é um framework geral de evolução de agentes? Não. Veja "Como ele se compara" acima. O evolveguard deliberadamente não constrói nem hospeda um framework de agentes auto-evolutivos; ele apenas testa edições de skills/memórias que já aconteceram.

O evolveguard é gratuito para uso, inclusive comercial? Sim. Ele é licenciado sob MIT, sem camada proprietária ou versão paga; veja LICENSE. Você pode usar, modificar e redistribuí-lo, inclusive em projetos comerciais, sob os termos padrão do MIT.

Contribuindo

Veja CONTRIBUTING.md. Cada mudança chega com testes em ambas as distribuições; uma mudança no esquema de frontmatter, na derivação da superfície de capacidade ou na lógica de veredito de diff deve ser feita tanto em src/evolveguard/ (TypeScript) quanto em python/src/evolveguard/ (Python), com cobertura equivalente adicionada a ambas as suítes.

Segurança

Veja SECURITY.md. O evolveguard lê arquivos locais que você aponta para ele e nunca executa nenhum deles; ele não faz chamadas de rede e não executa um agente ao vivo.

Licença

MIT. Veja LICENSE.