fabiodrneles/sdd-kit

English
**Spec Driven Development do primeiro commit até a release**, conduzido pelo Claude Code e entregue do jeito que um time profissional entrega: specs com critérios de aceite, épico por fase, um ticket por tarefa, uma branch e um PR por ticket, CI verde, revisão, CHANGELOG e tag.
> **O dono decide, o agente executa.** Você responde às decisões e revisa os PRs; o agente analisa, especifica, abre os tickets, escreve código e testes e mantém o CI verde.
*A adoção num repositório vazio e o primeiro make ci, com a saída real (como foi gerado).*
O kit nasceu do cv-craft, que saiu de protótipo para v1.x com esse processo (estudo de caso), e o próprio sdd-kit é desenvolvido com ele (specs, épico #1). Para ver o processo num projeto criado do zero, com épico, tickets, PRs e release, abra o sdd-kit-demo.
Sumário
- O que vem no kit
- Como funciona
- Começar num repositório novo
- Adotar num repositório existente
- Onde está o ganho
- Por que o sdd-kit
- Comandos e verificações
- Motor orientado a eventos
- Atualização automática
- axyn
- Passo a passo para iniciantes
- Problemas comuns e como resolver
- Como o axyn funciona por dentro
- Atualizar o axyn
- Instalar a skill
- Script de adoção
- Perguntas frequentes
- Contribuir
O que vem no kit
| Parte | Para quê | Spec |
|---|---|---|
| Skill sdd-delivery | Ensina o agente o processo inteiro: análise com evidências, specs, épicos, PRs, CI vermelho tratado pela causa raiz, revisão, fechamento de fase e release. Escrita em inglês, escreve specs, issues e PRs no idioma do dono | 002 |
| template/ | CLAUDE.md, hook de sessão, templates de issue e PR, CONTRIBUTING.md, CHANGELOG.md, esqueleto de specs/ e CI pronto para **Go, Node/TS, Java, Python, Rust e C#/.NET** | 003 |
| Script de adoção | Copia o template para um repositório novo ou existente **sem sobrescrever nada**; sh e PowerShell | 004 |
Como funciona
| Etapa | Quem | O que fica no repositório |
|---|---|---|
| Descoberta | Agente | specs/ANALYSIS.md: o que foi verificado (comando → resultado), achados por severidade com evidência, decisões em aberto D1..Dn com recomendação |
| Decisões | **Dono** | Respostas registradas nas specs; nada é implementado antes |
| Specs | Agente | specs/constitution.md (princípios verificáveis), uma spec por área com FR-*, NFR-* e AC-* (Dado/Quando/Então), ROADMAP.md por fases (a versão vem do go-release-manager no fechamento) |
| Planejamento | Agente | Um épico por fase e um ticket por tarefa, como sub-issues nativas do GitHub |
| Implementação | Agente | Uma branch e um PR por ticket; cada AC-* vira teste; make ci verde antes de todo push |
| Revisão e merge | **Dono** | Revisão na ordem do épico; o agente responde e corrige |
| Fechamento | Agente → **Dono** | PR de fechamento (status das specs, ROADMAP, CHANGELOG); o dono cria a tag e o workflow publica a release |
O **estado do trabalho vive no GitHub**, não na conversa: o épico guarda um comentário "Estado da fase" com PRs, CI, decisões e próximo passo. Uma sessão nova lê esse comentário e continua de onde parou.
Começar num repositório novo
Em uns 5 minutos o kit está instalado e o agente trabalhando no seu projeto.
**Você precisa de:** git, um repositório no GitHub e o Claude Code instalado. Para o CI passar na sua máquina, também a linguagem do projeto.
1. Crie o repositório no GitHub e clone.
2. Na pasta do projeto, instale o kit, trocando go pela linguagem do projeto (node, java, python, rust ou dotnet):
O comando copia para o repositório:
- as instruções para o agente (CLAUDE.md e AGENTS.md);
- a pasta specs/, onde ficam o planejamento e as decisões, e o CHANGELOG.md;
- o CI pronto para a linguagem (lint, testes com cobertura mínima e build) e o Makefile com o make ci;
- os modelos de issue e de PR e o hook que prepara as sessões do Claude Code na web.
**Ele nunca sobrescreve um arquivo que você já tem** e mostra no final o que criou e o que deixou de lado. Para só ver o que ele faria, sem gravar nada, acrescente --dry-run:
Num repositório vazio, --skeleton cria também um projeto mínimo com um teste, para o primeiro CI já nascer verde.
3. Faça o commit do que foi criado e abra o Claude Code na pasta do projeto.
4. Peça: *"use a skill sdd-delivery: crie a constituição, as specs e o ROADMAP para a minha ideia: …"*. O agente propõe as decisões em aberto e **para** até você responder.
5. Depois das respostas: *"crie o épico da Fase 1 com os tickets e siga ticket a ticket"*. Cada tarefa vira um PR pequeno, com CI verde, para você revisar.
Adotar num repositório existente