sdd-kit

O problema

Agentes de IA escrevem código rápido, mas sem processo: esquecem o projeto a cada sessão, abrem pull requests gigantes, decidem coisas que eram do dono e, quando o CI fica vermelho, às vezes resolvem desligando o teste.

As ferramentas de SDD da comunidade cuidam bem da especificação. O trecho que fica para a pessoa é a entrega: transformar a spec em tickets revisáveis, manter o CI verde e fechar a versão.

A solução

O kit leva para qualquer repositório o jeito de entregar de um time profissional:

• Uma skill que ensina o agente o processo inteiro: análise com evidências, specs com critérios de aceite, épico por fase, um ticket por branch e por pull request, revisão, CHANGELOG e tag.
• Um script de adoção, em sh e em PowerShell, que copia o template sem sobrescrever nada: CLAUDE.md, modelos de issue e PR, specs e CI pronto para Go, Node/TypeScript, Java, Python, Rust e C#/.NET, com cobertura mínima de testes.
• Um motor de eventos no GitHub Actions, que faz os passos mecânicos sem IA: atualiza o checkpoint a cada merge, resume o CI vermelho, traz a main para os PRs, abre o PR de fechamento e dispara a release.
• Checkpoints de retomada: a sessão pode acabar a qualquer momento, e a próxima continua de onde a anterior parou.
• O axyn, uma CLI em Go que leva o mesmo processo para modelos gratuitos ou locais, só avançando quando os portões de qualidade passam.

Como a qualidade é garantida

O kit é desenvolvido com o próprio processo, e cada pull request passa por 12 verificações:

• Lint de Markdown e de shell, testes dos scripts e verificação dos workflows (actionlint).
• A adoção testada no Linux, no macOS e no Windows.
• Cada template de linguagem adotado num projeto mínimo, com o make ci gerado rodando de verdade.
• Rastreabilidade: cada critério de aceite citado num teste; uma regra falha o CI se algum ficar sem.
• A versão de cada release é calculada pelos commits, com o Go Release Manager.

Decisões técnicas

• Pontos de parada explícitos: decisões, revisão, merge e tag são do dono, salvo delegação.
• Os testes são soberanos: CI vermelho se resolve pela causa raiz, nunca afrouxando ou pulando um teste.
• Scripts em sh POSIX e em PowerShell, para rodar igual no Linux, no macOS e no Windows.
• A adoção nunca sobrescreve arquivos do projeto, e uma sincronização semanal mantém os repositórios adotados atualizados.

Resultado

O kit nasceu do cv-craft, que saiu de protótipo para a v1.x com esse processo: 10 specs e 71 critérios de aceite, todos com teste automatizado. Hoje ele conduz o Go Release Manager e o sdd-kit-demo, um projeto criado do zero com épico, tickets, pull requests e release, além do próprio kit. O mesmo método, com specs e testes soberanos, guia este site.

Limites

O kit depende do GitHub e de um agente (o Claude Code, ou o opencode por meio do axyn). Até agora é usado nos meus projetos; falta a validação de outros times. O processo não dispensa a pessoa: as decisões e a revisão continuam sendo do dono.