aryashreep/ctx-audit

Auditoria de Contexto

Repositórios que adotam esta convenção mantêm um pequeno conjunto de arquivos persistentes para que agentes não precisem redescobrir as mesmas coisas a cada sessão: quais são as convenções do projeto (AGENTS.md), o que já foi decidido e por quê (memory.md) e, aproximadamente, como a base de código está organizada (.agent/graph.md). Esta skill verifica se esses arquivos existem e estão atualizados antes de você confiar neles ou antes de recorrer à varredura manual do repositório.

Frases de gatilho

Início de sessão / verificação de confiança

• "me atualize sobre este repositório"
• "o que você sabe sobre este projeto"
• "devo confiar em AGENTS.md / memory.md"
• "os arquivos de contexto estão atualizados"
• "verificar contexto" / "auditoria de contexto"

Desatualização

• "AGENTS.md está desatualizado" / "memory.md está desatualizado"
• "quantos commits desde a última sincronização"
• "meus arquivos de agente estão atualizados"
• "verificar se o contexto está desatualizado"

Custo de tokens

• "quanto os arquivos de contexto economizam"
• "economia de tokens" / "custo de contexto"
• "benchmark de economia de tokens"
• "tokens de linha de base vs. tokens curados"

Configuração / integração

• "criar estrutura AGENTS.md" / "inicializar contexto"
• "instalar ctx-audit" / "configurar o hook de contexto"
• "configurar contexto de IA" / "este projeto está pronto para IA"

CI / automação

• "adicionar ctx-audit ao CI"
• "adicionar um hook pre-push"
• "impor atualização do contexto no CI"

Arquitetura

• "eu tenho um mapa de arquitetura"
• "gerar graph.md" / "executar graphify"

Como executar

A maneira recomendada de executar o ctx-audit:

npx ctx-audit

Alternativamente, se instalado como skill:

node <caminho-para-pasta-da-skill>/../scripts/audit.mjs

Flags:

• --json — saída legível por máquina (use se for agir no resultado programaticamente).
• --strict — código de saída 1 se algo estiver faltando ou desatualizado.
• --ci — apelido para --strict --json.
• --help — exibe uso e sai.

Subcomandos

# Criar estrutura AGENTS.md + memory.md (interativo — escreve arquivos diretamente na raiz do repositório)
npx ctx-audit init

# Instalação em um comando: copia skill para ~/.claude/skills/, registra em CLAUDE.md
npx ctx-audit install

# Hook Git: executa auditoria --strict a cada push
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall

# CLAUDE.md do projeto: adiciona um bloco de instruções para agentes
npx ctx-audit claude install
npx ctx-audit claude uninstall

# Relatório de economia de tokens (formato focado e compartilhável)
npx ctx-audit benchmark

Tabela de decisão do agente

Status	Significado	Ação
FRESCO	Menos da metade do limite de desatualização em commits desde a última sincronização	Confie no arquivo — leia-o em vez de escanear o código-fonte bruto
DESATUALIZADO?	Aproximando-se do limite (possivelmente desatualizado)	Cautela leve — verifique rapidamente alegações críticas antes de confiar
DESATUALIZADO!	Acima do limite, conta como falha	Trate as alegações como não verificadas; verifique rapidamente contra o código real; atualize após a sessão
DESATUALIZADO	Significativamente atrasado, conta como falha	Mesmo que DESATUALIZADO!, mas mais urgente; atualize imediatamente após a sessão
AUSENTE (obrigatório)	Arquivo não existe	Execute npx ctx-audit init; não prossiga como se a convenção estivesse em vigor
ausente (opcional)	Arquivo opcional não presente	Aceitável; considere executar /graphify para gerar graph.md
acima do orçamento	Contagem de tokens excede maxTokens	Arquivo está inchado — corte-o; lê-lo pode custar mais do que economiza
referência morta	Caminho com crase ou dir/arquivo.ext mencionado no arquivo não existe no disco	Atualize a referência; o arquivo documenta estrutura desatualizada
SHA alterado	last_synced_commit atualizado, mas corpo inalterado	Verifique se o arquivo realmente reflete mudanças recentes; pode ser uma atualização mecânica

Interpretando resultados

• AUSENTE (arquivo obrigatório): não prossiga como se a convenção estivesse em vigor. Ofereça-se para criar um arquivo inicial (execute npx ctx-audit init) em vez de trabalhar sem ele ou silenciosamente adotar a abordagem antiga de "explorar tudo manualmente".
• FRESCO: o arquivo está atualizado. Leia-o em vez de escanear o código-fonte bruto.
• DESATUALIZADO? (possivelmente desatualizado): aproximando-se do limite. Verifique rapidamente alegações críticas.
• DESATUALIZADO! (provavelmente desatualizado): trate suas alegações como não verificadas. Verifique rapidamente qualquer coisa importante contra o código real e, após sua sessão, atualize o arquivo e seu last_synced_commit.
• DESATUALIZADO: significativamente atrasado. Mesmo tratamento que DESATUALIZADO!, mas mais urgente.
• As contagens de tokens são uma heurística de ~3,5 caracteres/token — direcionalmente útil, não exata. Se um arquivo for sinalizado como "acima do orçamento", é porque ficou inchado o suficiente para que lê-lo comece a custar o que deveria economizar; sugira cortá-lo.
• Avisos de referência morta: caminhos mencionados em arquivos de contexto que não existem mais no disco. Indica que o arquivo referencia uma estrutura desatualizada.

Exemplos práticos

Auditoria básica no início da sessão:

npx ctx-audit

Portão de CI (falhar build se o contexto estiver desatualizado):

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

Saída JSON para uso programático:

npx ctx-audit --json | jq '.checks[] | {file, stalenessLevel, stale}'

Integração em um comando:

npx ctx-audit install        # copia skill, registra em CLAUDE.md
npx ctx-audit hook install   # adiciona guarda pre-push
npx ctx-audit claude install # adiciona nota ao CLAUDE.md do projeto
npx ctx-audit init           # cria estrutura AGENTS.md + memory.md

Verificar desatualização de subsistema específico (via frontmatter):

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

Apenas commits que tocam em src/auth/ ou src/api/ contam para desatualização deste arquivo.

Benchmark de economia de tokens:

npx ctx-audit benchmark

Configuração

Coloque .ctx-audit.json na raiz do repositório para personalizar o comportamento:

{
  "files": [{ "id": "...", "file": "...", "label": "...", "maxTokens": N, "required": true }],
  "sourceDirs": ["src", "packages/core"],
  "staleThreshold": 10,
  "baselineFileCap": 300
}

Frontmatter

Cada arquivo de contexto deve começar com frontmatter:

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

O campo watches (opcional) restringe as verificações de desatualização apenas a commits que tocam naqueles caminhos, em vez de todos os diretórios de código-fonte.

Se arquivos obrigatórios estiverem faltando — crie a estrutura

Execute npx ctx-audit init para gerar modelos. Em um TTY, ele escreve os arquivos diretamente na raiz do repositório; quando redirecionado, imprime na saída padrão para redirecionamento. A flag legada --init ainda é suportada como um apelido compatível com versões anteriores.

AGENTS.md — convenções estáveis do projeto: comandos de build/teste/lint, regras de organização de arquivos, coisas que o agente nunca deve fazer. Deve mudar raramente.

memory.md — um registro contínuo de decisões, não uma reafirmação do código atual. Cada entrada: o que foi tentado, o que foi decidido, por quê, e o que reconsiderar se as circunstâncias mudarem. Anexe, não reescreva o histórico.

.agent/graph.md (opcional, mas recomendado quando o repositório crescer) — um parágrafo por módulo principal descrevendo sua responsabilidade e com o que ele se comunica. Não é o conteúdo dos arquivos, não é uma árvore exaustiva — apenas o suficiente para que um agente possa navegar sem reler tudo. Dica: execute /graphify para gerar isso automaticamente a partir da base de código, em vez de escrever manualmente.

Após criar ou atualizar qualquer um destes, atualize seu last_synced_commit para o HEAD atual, para que a próxima auditoria não o sinalize imediatamente como desatualizado.