Workflow
O ciclo tem quatro comandos e uma propriedade que os amarra: cada um produz um artefato que o próximo consome, e todos ficam no seu repositório. Antes deles há um passo zero opcional — o estudo, para quando ainda não se sabe o que propor. Não é um chat com memória boa — é uma cadeia de documentos versionados que sobrevive à conversa, à pessoa e ao agente.
Um quinto comando, /pipeline, roda a cadeia inteira de ponta a ponta — é retomável do ponto exato onde parou, e avisa quando vale rodar o estudo do passo zero antes.
O ciclo
O passo 00 é opcional — o estudo que se faz quando ainda não se sabe o que propor. Os quatro seguintes têm portão: não se implementa sem especificação, não se fecha fase sem revisão. Os portões são código, não recomendação.
Nem todo trabalho começa com a solução na mão. O estudo diverge antes de convergir — mapeia o território, enumera opções, compara trade-offs ou persegue a causa raiz — e sai com as perguntas em aberto numeradas, cada uma com dono, além do mesmo bloco de contrato que o resto da cadeia lê. Encerrar sem decisão é resultado válido; o que não vale é decidir sem ter olhado. A proposta seguinte herda o estudo em vez de reexplorar do zero.
/analysis
Você descreve o que quer. Sai uma proposta com o problema, os cenários, os princípios de desenho, os riscos e os critérios de aceitação. Junto dela, embutido no mesmo arquivo, sai um bloco de contrato legível por máquina: as unidades em que o trabalho se decompõe, os critérios que o verificam e as âncoras que ligam cada cenário ao critério que o fecha.
/proposal
A proposta não é executada direto. Cada unidade do contrato vira uma especificação própria, com regras de negócio numeradas e testáveis, invariantes, e os testes determinísticos que provarão cada uma. É aqui que "o agente entendeu" deixa de ser aposta: o que ele vai fazer está escrito antes, e o que conta como feito também.
/ai-spec
O agente implementa lendo a especificação da fase, não a conversa. Nada é escrito sem a sua aprovação, e ao final a suíte de testes e o build são executados — não declarados. Uma fase que não produziu os arquivos que a spec prometeu não fecha.
/implement
A revisão roda com contexto isolado do que implementou e devolve um veredito: aprovado, aprovado com observações, ou mudanças necessárias. Mudanças necessárias devolvem a fase para implementação — e o gatilho é o veredito, não a contagem de achados críticos, porque uma regra sem teste reprova sem ser crítica.
/review
Como o SDD se materializa
Desenvolvimento guiado por especificação costuma morrer no mesmo ponto: a spec é um documento que ninguém consegue executar, então ela envelhece à margem do código. Aqui ela tem uma metade que a máquina lê, e é essa metade que dirige a execução.
Além da prosa que humanos revisam, cada artefato carrega um bloco estruturado com as unidades, os critérios e as âncoras. É esse bloco — não o texto — que o orquestrador consome para decidir em quantas fases o trabalho se divide e em que ordem elas dependem umas das outras.
Quando o contrato existe e é válido, as fases são derivadas dele e assinadas por checksum. Se a proposta mudar, a assinatura deixa de bater e as fases são recalculadas — e o trabalho já registrado é reencontrado pela identidade da unidade, nunca pela posição numa lista.
Proposta antiga, sem o bloco? O orquestrador cai para a tabela de fases em prosa, e depois para perguntar a você — anunciando em qual degrau caiu e por quê. Nenhuma execução é interrompida por falta de contrato; o que não acontece é a degradação silenciosa.
Uma proposta formal e uma user story emitem o mesmo contrato. É por isso que trocar a metodologia do time não reescreve o pipeline: o que vem depois lê o contrato e não sabe de qual origem ele veio.
A consequência prática: a spec não pode envelhecer em silêncio. Se ela mudar, a assinatura do contrato deixa de bater, e o orquestrador diz que deixou — em vez de seguir executando um plano que ninguém aprovou.
Execução
Cada passo concluído é gravado no estado da execução assim que termina — nunca em lote. O arquivo diz qual fase está em qual etapa, qual artefato saiu de cada uma, e quem iniciou a run, com identidade vinda do git.
Fechou o terminal, caiu a conexão, acabou o dia? A execução seguinte lê o estado, pula o que está pronto e continua do primeiro passo pendente. Você também pode rodar um intervalo de fases de propósito, para revisar em lotes.
Antes de começar, o passo é marcado como em andamento, com hora e tentativa. Uma execução que morreu no meio é distinguível de uma que está trabalhando — e quem retomar sabe em qual tentativa está, em vez de adivinhar.
Passo que falha grava o erro e para, em vez de seguir sobre uma base quebrada. A execução seguinte encontra o registro do que aconteceu, não um estado ambíguo que parece progresso.
Customização
O comportamento de cada comando resolve em três camadas. A do meio é versionada e revisada como código; a de cima fica na sua máquina e não vai para o repositório.
| Camada | Quem edita | Onde vive | Versionada |
|---|---|---|---|
| Base | Quem escreve a skill | viaja com o produto | Sim |
| Time | O time, por code review | .claude/skill-config/ | Sim |
| Pessoal | Cada desenvolvedor, por máquina | .local.json (fora do git) | Não |
O comportamento padrão de cada comando. Você não edita — recebe, e ele se atualiza junto com o produto.
A convenção do time: contexto que todo comando deve carregar, passos que rodam antes ou depois de uma skill, nível de rigor. Vive em git e é revisada como qualquer arquivo — mudar a convenção é um pull request, não um acordo verbal.
A sua preferência, na sua máquina, que não vai para o repositório e não incomoda ninguém. Discordar do padrão do time em algo que só afeta você não exige convencer o time.
Como as camadas se combinam
Fatos que todo comando deve conhecer e passos de preparação são concatenados na ordem base → time → pessoal, preservando a ordem de cada camada. Sua preferência pessoal acrescenta à convenção do time em vez de substituí-la — que é o comportamento certo para o tipo de coisa que essas chaves carregam.
Já o que roda ao terminar um comando não soma — a camada mais próxima de você substitui o valor inteiro, sem mesclar. E declarar explicitamente "nenhum" conta como declaração: é assim que um time desliga um gancho herdado, em vez de conviver com ele.
Os comandos que escrevem por cima de trabalho existente — rotacionar histórico, reorganizar módulos, preparar ambiente, criar branch, remover código obsoleto — não aceitam ganchos de fluxo. Neles, "personalizar" significaria remover a verificação que impede perda. A recusa é executada pelo motor, não confiada à disciplina.
Além do comportamento das skills, a execução tem perfis: qual modelo roda cada etapa, se as etapas correm isoladas em subagentes ou na mesma sessão, o que fazer com as pendências no fim. Você escolhe o perfil ativo da sua máquina sem alterar o padrão do repositório.
Adaptação ao time
O ciclo acima é o mesmo em qualquer time. O que muda é o vocabulário, o comando com que você especifica, o que é agrupado por quê e a tela em que o cockpit abre — tudo configuração, nenhuma linha do produto.
Num time ágil você especifica com /story e vê o trabalho em kanban com velocidade; num time enterprise, o mesmo trabalho aparece como matriz de rastreabilidade. A etapa de especificar muda de front-end; as de implementar e revisar não sabem da diferença, porque leem o contrato e não o documento.
Metodologia e rigor são eixos independentes: um time ágil pode subir para o nível estrito numa feature de pagamento sem deixar de falar em story e sprint. Quem escolhe um não fica preso ao outro.
Depois do desenvolvimento
Terminar de implementar não é o fim da cadeia. A pergunta que sobra — este requisito está mesmo coberto por código e por teste? — é respondida contra o repositório real.
As âncoras que a especificação declarou — cenário leva a caso de uso, que leva a critério — são resolvidas contra o repositório real. Cada elo recebe status resolvido, parcial ou não resolvido, com arquivo e linha como evidência. O que ficou sem cobertura aparece por nome, em vez de ser descoberto em produção.
/traceability
Uma matriz legível — cenário, caso de uso, critério, código, teste, status — para quem revisa. E o mesmo conteúdo estruturado, determinístico e versionável, para quem automatiza. As duas saem da mesma resolução, então não podem divergir.
No nível mais leve o gate é pulado; no padrão ele avisa; no estrito ele bloqueia quando existe elo não resolvido. É a mesma dosagem por risco que vale no resto do fluxo — quem decide quando a trava fecha é o projeto, não a ferramenta.
Rastreabilidade, resultados dos scans de segurança e as revisões são reunidos num único pacote de evidência. Auditoria deixa de ser uma escavação por pastas e vira um artefato que se entrega.
A trilha que fica
Cada sessão de trabalho grava início e fim, com escopo e resultado, e a autoria vem do git — não de um campo preenchido. É o registro cronológico do que aconteceu, na ordem em que aconteceu.
Escolhas estruturantes viram registros datados com contexto, alternativas descartadas e consequências. Uma decisão superada ganha um aviso no topo e mantém o corpo intacto — o histórico da decisão vale tanto quanto a decisão.
Achado adiado, critério não verificado, limitação de ambiente: tudo entra num registro central com severidade, dono e estado, ligado à feature que o originou. O débito para de depender de alguém lembrar.
Descontinuar algo é um registro com ciclo próprio — anunciado, depreciado, em janela de remoção, removido — em vez de um comentário que ninguém encontra. Some quando foi decidido que sumiria, não quando alguém tropeça nele.
Tudo isso versiona junto com o código e é legível por humano e por máquina — inclusive se você parar de usar o Spaccy. Peça acesso antecipado e rode o primeiro ciclo.
