How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/robertodiasduarte/sdd-starter --skill sdd-auditoria-harnessBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Auditoria Read-Only do Harness SDD
Na primeira resposta desta skill, comece com esta linha, uma vez só: sdd-auditoria-harness v1.0.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest
Quick start
- Defina
REPO_ROOTcomo a raiz do repositório auditado. - Execute primeiro o Safety Gate desta Skill.
- Leia as fontes de verdade do SDD: os arquivos de instrução do projeto (
CLAUDE.mde/ouAGENTS.md), índice/readme do SDD e as configurações do motor (.claude/settings.json/.claude/settings.local.json,.codex/config.toml). - Opcionalmente, gere evidência estruturada somente em stdout:
python scripts/collect_evidence.py "$REPO_ROOT".
- Faça a análise seguindo references/AUDIT_PROTOCOL.md.
- Crie somente o novo relatório
AUDITORIA_SDD_<AAAA-MM-DD>.md, usando references/REPORT_TEMPLATE.md. - Termine no chat com o sumário executivo, o caminho do relatório e a frase:
nenhuma alteração foi feita — a faxina em si é decisão humana.
Quando usar / Quando não usar
Quando usar
Use esta Skill para auditar o harness SDD de um repositório, seja qual for o motor. As superfícies mudam de caminho conforme a ferramenta; audite as que existirem:
| Peça | Claude Code | Codex / Kimi CLI |
|---|---|---|
| Instruções do projeto | CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md | AGENTS.md (padrão aberto; o Claude Code também o lê por fallback desde a 2.1.277) |
| Skills | .claude/skills/*/SKILL.md | .agents/skills/*/SKILL.md, .codex/skills/*/SKILL.md |
| Comandos | .claude/commands/**/*.md | .codex/prompts/**/*.md |
| Agentes/subagentes | .claude/agents/**/*.md | .agents/agents/**/*.md |
| Configuração | .claude/settings.json, .claude/settings.local.json | .codex/config.toml |
| Scripts do harness | .claude/scripts/** | .agents/scripts/**, .codex/scripts/** |
Audite ainda:
- hooks, permissões e scripts referenciados pelo harness;
- docs de processo, playbooks, notas de memória e diretórios de specs;
- divergências entre o fluxo SDD oficial e itens legados, duplicados ou sem evidência de uso.
Quando não usar
Não use esta Skill para:
- apagar, editar, renomear, mover, formatar ou reorganizar arquivos existentes;
- corrigir automaticamente achados;
- fazer
git add,commit,push,pull,fetch,checkout,restore,reset,clean,rmoumv; - instalar dependências, executar deploys ou comandos com efeito colateral;
- auditar fora da raiz informada do repositório;
- concluir que algo é “NÃO UTILIZADO” apenas porque parece antigo ou raro.
Dados necessários
Obrigatórios
REPO_ROOT: raiz do repositório que contém o harness a auditar.- Acesso de leitura ao repositório e, quando disponível, ao histórico Git.
Derivados automaticamente
REPORT_DATE: data local da execução, no formatoAAAA-MM-DD.REPORT_DIR: pasta de relatórios do SDD, se houver uma claramente estabelecida; caso contrário, a raiz do repo.REPORT_PATH:REPORT_DIR/AUDITORIA_SDD_<REPORT_DATE>.md.
Se REPO_ROOT não estiver claro, pergunte apenas: Qual é a raiz do repositório SDD que devo auditar?
Procedimento passo a passo
0. Safety Gate bloqueante
Antes de executar qualquer comando:
- Confirme que a ação é somente leitura.
- Recuse qualquer comando que possa escrever, apagar, mover, renomear, instalar, sincronizar ou alterar Git/estado do projeto.
- Prefira comandos de inspeção como
git log,git status,git diff,git ls-files,git grep,rg,grep,findsem ações destrutivas,cat,sedsem-i,awk,head,tail,wce leitura via ferramentas nativas. - Não use
find -delete,find -execcom comandos mutantes,sed -i, redirecionamentos>/>>,tee,touch,mkdir,cp,rsyncou scripts que escrevam durante a auditoria. - A única escrita permitida é a criação do relatório final novo, no caminho calculado.
- Se
REPORT_PATHjá existir, não sobrescreva. Pare a escrita, entregue o sumário no chat e peça um novo nome explicitamente autorizado.
1. Estabelecer o SDD principal
Leia, nesta ordem:
- o arquivo de instruções do projeto na raiz —
CLAUDE.mdouAGENTS.md, o que existir (podem coexistir); - o mesmo, em subdiretórios relevantes ao harness;
- índice/readme do diretório SDD, como
sdd/_index.md,.claude/sdd/_index.mdou equivalente; - a configuração do motor:
.claude/settings.jsone.claude/settings.local.json, e/ou.codex/config.toml, incluindo hooks e permissões.
⚠️ Se o repositório tem `AGENTS.md` e nenhum `CLAUDE.md`, isso não é lacuna: desde o Claude Code 2.1.277 o AGENTS.md é lido por fallback, e Codex/Cursor/Gemini CLI já o liam nativamente. Não classifique a ausência de CLAUDE.md como achado.
⚠️ Se os dois existem, registre a precedência real: por padrão o Claude Code lê só os arquivos CLAUDE.md e ignora o AGENTS.md — a menos que o CLAUDE.md o importe com @AGENTS.md ou que Project instructions esteja em claude-md-and-agents-md. Instrução que o aluno acha que vale e não é lida é CONFLITANTE, e é dos achados mais úteis desta auditoria.
Produza um resumo de 5–10 linhas contendo:
- fases oficiais;
- comandos que invocam cada fase;
- caminho dos artefatos produzidos;
- regras de precedência/fonte de verdade, se declaradas.
Esse resumo é a régua para classificar AMBÍGUO e CONFLITANTE.
2. Inventário completo do harness
Inclua um item por linha para:
- comandos/slash commands;
- agentes;
- skills;
- hooks e permissões;
- scripts de apoio;
- docs de processo e diretórios de specs;
- scripts externos à pasta do motor (
.claude/,.agents/,.codex/) que sejam referenciados pelo harness.
Para cada item registre: caminho | tipo | propósito declarado | idioma/origem aparente.
Não marque “copiado de template” sem indício concreto. Se a origem não puder ser provada, use indeterminada.
3. Medir uso e vitalidade
Para cada item, colete:
- Referências cruzadas: referências de entrada no restante do harness.
- Recência:
git log -1 --format=%cs -- <arquivo>. - Sinal de execução: menções em relatórios/logs do SDD, quando existirem.
- Duplicação: sobreposição objetiva de propósito/saída com outro item.
- Deriva: referências a arquivos, fases, modelos, comandos ou paths inexistentes.
O helper scripts/collect_evidence.py pode acelerar os itens 1–3 e apontar candidatos do item 5. Ele só lê arquivos e escreve JSON em stdout.
Zero referências de entrada e nenhum sinal de execução é apenas a condição mínima para considerar NÃO UTILIZADO. Se o item puder ser raro por design, classifique como dúvida e não como certeza.
4. Classificar achados
Use somente estes rótulos, exatamente:
- EXCESSO
- OBSOLETO
- SUPÉRFLUO
- NÃO UTILIZADO
- AMBÍGUO
- CONFLITANTE
Um item pode receber mais de um rótulo.
Todo achado precisa conter:
- arquivo;
- linha, quando a evidência estiver em conteúdo textual;
- evidência concreta;
- recomendação.
Achado sem evidência verificável não entra na tabela de achados; vai para “Dúvidas para o dono do repo”.
Critérios detalhados e cautelas estão em references/AUDIT_PROTOCOL.md.
5. Recomendar, sem executar
Para cada achado, escolha exatamente uma ação sugerida:
MANTERAPOSENTAR— com tombstone/ponteiro; nunca recomendar delete seco;FUNDIR com <item>ESCLARECERARQUIVARREDUZIR
A recomendação descreve o que o dono poderia fazer depois; não faça a alteração.
6. Criar o relatório final
Use references/REPORT_TEMPLATE.md.
Local:
- pasta de relatórios do SDD, se existir e for claramente a casa de relatórios;
- senão, raiz do repositório.
Nome: AUDITORIA_SDD_<AAAA-MM-DD>.md
Crie esse arquivo somente depois de toda a análise estar pronta e somente se ele ainda não existir.
7. Verificação final
Antes de concluir:
- confirme que nenhum arquivo existente foi alterado;
- confirme que somente o relatório final novo foi criado;
- confirme que cada achado contém evidência;
- confirme que rótulos e ações usam apenas os valores permitidos;
- confirme que dúvidas não comprovadas ficaram fora da tabela de achados;
- mostre no chat o sumário executivo e o caminho do relatório;
- repita:
nenhuma alteração foi feita — a faxina em si é decisão humana.
Validações e checklist de qualidade
- [ ] O SDD principal foi resumido antes dos achados.
- [ ] Todos os itens do harness entraram no inventário.
- [ ] Cada item tem caminho, tipo, propósito e idioma/origem aparente.
- [ ] Referências cruzadas foram medidas por evidência objetiva.
- [ ] A última mudança Git foi coletada quando o histórico está disponível.
- [ ] Paths citados foram verificados antes de acusar deriva.
- [ ] Itens raros por design foram tratados como dúvida quando necessário.
- [ ] Cada achado usa somente rótulos permitidos.
- [ ] Cada achado cita evidência concreta e, quando útil, linha.
- [ ] Cada recomendação usa somente ações permitidas.
- [ ] O relatório tem as seis seções obrigatórias.
- [ ] O sumário executivo tem no máximo 10 linhas.
- [ ] Nenhum arquivo existente foi alterado.
- [ ] O relatório final não sobrescreveu arquivo pré-existente.
- [ ] A mensagem final afirma explicitamente que a faxina depende de decisão humana.
Tratamento de exceções
- Sem Git disponível → marque recência como
não verificável; não invente data. - Sem diretório de relatórios/logs → não trate ausência de sinal como prova isolada de desuso.
- Item sem referências, mas aparentemente sazonal/release-only → mover para “Dúvidas”.
- Dois documentos parecem duplicados, mas não há evidência suficiente de precedência →
AMBÍGUOsomente se disputarem objetivamente o mesmo papel; caso contrário, “Dúvidas”. - Path citado contém variável/glob → resolva somente se houver contexto inequívoco; caso contrário, “Dúvidas”.
- Arquivo muito grande/binário → inventarie, mas registre limitação de leitura.
- Repositório com milhares de artefatos de processo → o cruzamento de referências do
collect_evidence.py é quadrático: cada item é procurado no corpo de todos os outros. Medido: ~0,5 s para 27 itens; acima de ~5.000 arquivos em pastas como sdd/ ou reports/ ele deixa de terminar em tempo útil. Nesse caso não espere o script: rode-o apontando para um subdiretório por vez (por exemplo só .claude/commands e .claude/agents), ou faça o inventário com git ls-files e meça referências com git grep -c. O script é um acelerador opcional — a auditoria não depende dele.
- `REPORT_PATH` já existe → não sobrescreva e não escolha silenciosamente outro nome.
- Comando necessário teria efeito colateral → não execute; registre a limitação em “Dúvidas”.
Examples
Exemplo de achado válido
| Item | Rótulo(s) | Evidência | Recomendação |
|---|---|---|---|
.claude/commands/old-release.md | OBSOLETO, CONFLITANTE | Linha 18 grava specs em docs/specs/, enquanto o SDD principal define .claude/sdd/specs/; o path antigo não existe; último commit: 2025-11-03. | APOSENTAR |
Exemplo que deve virar dúvida
Um agente tem zero referências de entrada e nenhuma menção recente em logs, mas sua descrição diz que só é usado no release anual. Não classifique como NÃO UTILIZADO com certeza; registre em “Dúvidas para o dono do repo”.
Parte do SDD Open by RDD — https://github.com/robertodiasduarte/sdd-open

