robertodiasduarte/sdd-starter

sdd-auditoria-harness

Audita read-only o harness SDD de um repositório para FAXINA E DERIVA: inventaria comandos, agentes, skills, hooks, settings e scripts de QUALQUER motor (Claude Code, Codex, Kimi CLI: le CLAUDE.md e AGENTS.md, .claude/, .agents/ e .codex/), mede referências…

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/robertodiasduarte/sdd-starter --skill sdd-auditoria-harness

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

  1. Defina REPO_ROOT como a raiz do repositório auditado.
  2. Execute primeiro o Safety Gate desta Skill.
  3. Leia as fontes de verdade do SDD: os arquivos de instrução do projeto (CLAUDE.md e/ou AGENTS.md), índice/readme do SDD e as configurações do motor (.claude/settings.json / .claude/settings.local.json, .codex/config.toml).
  4. Opcionalmente, gere evidência estruturada somente em stdout:

python scripts/collect_evidence.py "$REPO_ROOT".

  1. Faça a análise seguindo references/AUDIT_PROTOCOL.md.
  2. Crie somente o novo relatório AUDITORIA_SDD_<AAAA-MM-DD>.md, usando references/REPORT_TEMPLATE.md.
  3. 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çaClaude CodeCodex / Kimi CLI
Instruções do projetoCLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.mdAGENTS.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, rm ou mv;
  • 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 formato AAAA-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:

  1. Confirme que a ação é somente leitura.
  2. Recuse qualquer comando que possa escrever, apagar, mover, renomear, instalar, sincronizar ou alterar Git/estado do projeto.
  3. Prefira comandos de inspeção como git log, git status, git diff, git ls-files, git grep, rg, grep, find sem ações destrutivas, cat, sed sem -i, awk, head, tail, wc e leitura via ferramentas nativas.
  4. Não use find -delete, find -exec com comandos mutantes, sed -i, redirecionamentos >/>>, tee, touch, mkdir, cp, rsync ou scripts que escrevam durante a auditoria.
  5. A única escrita permitida é a criação do relatório final novo, no caminho calculado.
  6. Se REPORT_PATH já 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:

  1. o arquivo de instruções do projeto na raiz — CLAUDE.md ou AGENTS.md, o que existir (podem coexistir);
  2. o mesmo, em subdiretórios relevantes ao harness;
  3. índice/readme do diretório SDD, como sdd/_index.md, .claude/sdd/_index.md ou equivalente;
  4. a configuração do motor: .claude/settings.json e .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:

  1. Referências cruzadas: referências de entrada no restante do harness.
  2. Recência: git log -1 --format=%cs -- <arquivo>.
  3. Sinal de execução: menções em relatórios/logs do SDD, quando existirem.
  4. Duplicação: sobreposição objetiva de propósito/saída com outro item.
  5. 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:

  • MANTER
  • APOSENTAR — com tombstone/ponteiro; nunca recomendar delete seco;
  • FUNDIR com <item>
  • ESCLARECER
  • ARQUIVAR
  • REDUZIR

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:

  1. pasta de relatórios do SDD, se existir e for claramente a casa de relatórios;
  2. 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:

  1. confirme que nenhum arquivo existente foi alterado;
  2. confirme que somente o relatório final novo foi criado;
  3. confirme que cada achado contém evidência;
  4. confirme que rótulos e ações usam apenas os valores permitidos;
  5. confirme que dúvidas não comprovadas ficaram fora da tabela de achados;
  6. mostre no chat o sumário executivo e o caminho do relatório;
  7. 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ÍGUO somente 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

ItemRótulo(s)EvidênciaRecomendação
.claude/commands/old-release.mdOBSOLETO, CONFLITANTELinha 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

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
robertodiasduarte
커뮤니티

sdd-new-session

Abre uma frente de trabalho isolada neste repositório: cria uma git worktree fora da pasta do projeto, com uma branch nova nascida da branch de produção ATUALIZADA do remoto, prepara a pasta (dependências, arquivos locais) e abre no editor. Na primeira vez, investiga o repositório e grava o que descobriu em sdd/ambiente.md. Use quando o usuário disser 'abrir uma frente', 'nova sessão', 'nova tarefa isolada', 'criar worktree para X' ou quiser começar uma feature/correção sem misturar com outra em

1시간 설치 수
1
GitHub Stars
0
업데이트
10월 4일
robertodiasduarte
커뮤니티

sdd-brainstorm

Conduz o brainstorm da Fase 0 de um fluxo SDD/AgentSpec por interação com o usuário: explora contexto, faz perguntas de descoberta uma por vez, coleta amostras, compara 2–3 abordagens, aplica YAGNI, valida incrementalmente e gera um BRAINSTORM pronto para a fase /define. Use para ideias vagas de software, automações, agentes, produtos ou features que ainda precisam de exploração antes de formalizar requisitos; também quando o usuário pedir para transformar uma conversa, problema ou notas iniciai

1시간 설치 수
2
GitHub Stars
0
업데이트
10월 1일
robertodiasduarte
커뮤니티

sdd-build

Executar a fase Build de um fluxo SDD/AgentSpec a partir dos arquivos Markdown de Brainstorm, Define e Design e de interações com o usuário. Usar quando o usuário quiser implementar uma feature já especificada: ler os três artefatos, extrair e ordenar o File Manifest, recomendar e confirmar o modo de execução, alterar somente o código previsto, verificar incrementalmente, tratar drift e prompts LLM, executar o Verify Gate bloqueante do Define e gerar BUILDREPORT{FEATURE}.md com evidências. Reque

1시간 설치 수
2
GitHub Stars
0
업데이트
10월 1일
robertodiasduarte
커뮤니티

sdd-checar-ambiente

Diagnostica, sem alterar nada, se este computador e este repositório estão prontos para trabalhar com SDD: repositório git, agente de código, identidade do git, worktrees órfãs, dependências e editor. Responde em uma linha quando está tudo certo e, quando não está, lista o que impede primeiro, cada item com o comando exato que resolve. Use quando o usuário pedir para checar o ambiente, antes de abrir a primeira frente de trabalho num projeto, ou quando algo estranho acontecer (commit que falha,

1시간 설치 수
2
GitHub Stars
0
업데이트
10월 1일