Método SDLC — Fábrica de software com agentes
Meu jeito de construir sistema com o Claude Code, todo dia. Cada estágio grava um artefato que o próximo lê. Eu só entro nos pontos de julgamento; o time de agents faz o resto sozinho.
▶ Arranque rápido — o que eu faço todo dia
Projeto já adotado (fiz /sdlc:adopt nele uma vez). Isto é o começo de toda demanda nova:
Depois, na aba do planner, escrevo a demanda em português como falaria com um colega. A partir daí só respondo os 3 gates (intent, plano, merge). Detalhe completo em Fluxo da demanda.
/sdlc:setup vai acusar FALTA.1 Configurar a máquina uma vez por PC
Pré-requisitos que o Claude Code não instala sozinho: Git (no Windows vem com o Git Bash), jq, GitHub CLI já logado (gh auth login) e Claude Code ≥ 2.1.234.
| O que faz | Checa git, jq, gh e a versão do Claude Code; instala claude-agent-kit (o time) e mattpocock-skills; garante o code-craftsman (gate de qualidade); grava a persona global em ~/.claude/CLAUDE.md (com backup do meu). Imprime uma tabela ok/FALTA. |
|---|---|
| Quando | Uma vez por máquina. Pode rodar de novo a qualquer hora só pra conferir — é idempotente. |
| Depois | Feche e reabra o claude: plugins e CLAUDE.md global só carregam no início da sessão. |
2 Cadastrar modelos 1x por modelo que não é Claude
Opcional. Serve para rodar o dev num modelo barato e deixar planner/reviewer no Claude — corta muito custo de um time rodando horas. Se eu só uso Claude, pulo isto.
| O que faz | Pergunta o provedor (deepseek kimi-k3 glm qwen minimax), o modelo de cada slot e a chave. Grava ~/.claude-kit/profiles.json e ~/.claude-kit/secrets.env. A chave nunca aparece no chat. |
|---|---|
| Quando | Antes do primeiro /sdlc:adopt que use aquele modelo. Uma vez por provedor. |
~/.claude-kit/secrets.env é o único lugar das chaves. Nenhum comando recria sem eu digitar tudo de novo. Faça backup desse arquivo.3 Adotar o método no projeto 1x por repositório
| O que faz | Copia os artefatos do método (REVIEW.md, intent/, specs/, evals/, docs/bugs.json, .claude/sdlc/) sem sobrescrever nada; detecta a branch base; pergunta o modelo de cada papel e grava .claude/sdlc/team.json; funde CLAUDE.md e .claude/settings.json existentes mostrando o diff antes. |
|---|---|
| Por quê | Os agents leem contrato de arquivo, não conversa: CLAUDE.md diz como buildar e testar, REVIEW.md diz o que o reviewer cobra, team.json diz quem roda em qual modelo e para onde vai a PR (pr_base). |
| Depois | Se o diff do CLAUDE.md mostrou <placeholder>, preencho (comandos de build/test/lint com a saída saudável). Commito os arquivos novos numa branch chore/sdlc. |
main é produção? O adopt oferece pr_base: dev pra PR não bater contra produção. Trocar papel depois sem editar arquivo: /sdlc:adopt --reviewer claude.◆ Fluxo da demanda — o coração do método
Depois do /sdlc:up, na aba do planner, descrevo a demanda. A sequência é sempre a mesma:
| Passo | Quem | O que acontece | Eu |
|---|---|---|---|
| Intent | planner /sdlc:intent | Me entrevista e grava intent/<slug>.md | aprovo ✔ ou corrijo |
| Plano | planner planf3 + code-craftsman | Escreve specs/<slug>.html e escolhe o tipo: hotfix, feature ou review-only | aprovo ✔ (libera push da branch + PR) |
| Pipeline | planner /sdlc:team | Inicia pipeline.json, manda o kickoff ao dev e dorme | saio |
| Build→review→e2e→PR→doc | dev reviewer tester-e2e document | Cada um fecha seu estágio com /sdlc:next e passa o bastão. Achado dentro da spec volta ao dev sozinho (até 3x) | nada |
| Done | planner /entrega | Rubrica com evidência de cada gate; PR aberta | leio, decido o merge |
blocked, exhausted ou thrash — o planner explica em 1 linha.6 Os 6 estágios
| # | Estágio | Artefato | Quem | Gate meu |
|---|---|---|---|---|
| 1 | Plan | intent/<slug>.md (entrevista) | originador + planner | aprovo intent |
| 2 | Design + plano | specs/<slug>.html (planf3) + gate code-craftsman | planner | aprovo plano |
| 3 | Build | diff em worktree, TDD, rubrica com evidência | dev | — |
| 4 | Test | veredito do reviewer + achados do tester-e2e | reviewer, tester-e2e | só bug fora do escopo |
| 5 | Deploy | PR + rubrica /entrega | dev, reviewer, document, planner | merge |
| 6 | Maintain | /sdlc:ops vigia CI e PRs, escreve intents novos | ops (opcional) | trio a fila |
Estado vive em specs/<slug>/pipeline.json. Skill é conselho; hook é lei: test-lock, protected-paths, prod-gate.
★ Quem é quem
Planeja e orquestra, nunca implementa. Entrevista → intent → plano (planf3) → dispara o time → conduz até o fim. É quem fala comigo. Claude.
Implementa exatamente a spec via TDD (RED→GREEN→REFACTOR), num worktree isolado. Não re-planeja nem inventa requisito. Modelo barato.
Confere conformidade com a spec (não testa): quebra o plano em requisitos e julga cada um contra o código com arquivo:linha. Barra o dev. Claude.
Valida no app rodando de verdade (Chrome DevTools/Playwright): golden path + edge cases. Reporta bug, não conserta. Barato.
Escreve o que foi entregue a partir da evidência (diff, rubrica, testes). Atualiza docs. Não toca no código. Barato.
Skill always-on de qualidade. Gate do plano (scope creep + cobertura TDD) e enforcement por hooks: bloqueia vibe coding, over-engineering, código sem teste. Ver Regras inegociáveis.
✋ Onde EU decido (gates humanos)
Fora destes pontos, o planner conduz sozinho. Eu aprovo artefato em fronteira de estágio, não cada saída.
| Gate | Quando | O que eu faço |
|---|---|---|
| G1 | intent.md escrito | Confirmo que o problema está certo antes de planejar |
| G2 | plano planf3 escrito e interrogado | Aprovo o plano — isso autoriza push da branch e PR |
| G3 | PR aberto com rubrica | Leio a rubrica e decido o merge |
| G-bug | bug fora do escopo achado em review/e2e | Aprovo (ou não) o fix antes do dev implementar |
↻ Próxima demanda no mesmo projeto
O time fica aberto entre demandas; só o dev muda (nasce num worktree por slug).
/clear apaga a conversa, não a sessão. Nunca dê /clear no dev ou reviewer no meio de um estágio — o trabalho deles só existe na conversa. Plugin atualizado exige fechar e reabrir a aba (/clear não carrega versão nova).⌘ Referência rápida de comandos
| Comando | Quem roda | Para quê |
|---|---|---|
/sdlc:setup | eu, 1x por máquina | instalar e conferir o ambiente |
/sdlc:models | eu, 1x por modelo | cadastrar provedor e chave |
/sdlc:adopt | eu, 1x por repo | preparar o projeto e o team.json |
/sdlc:up | eu, por demanda | abrir o time |
/sdlc:intent | planner | entrevista → intent/<slug>.md |
/sdlc:team | planner | iniciar o pipeline com o time |
/sdlc:next | cada agent | fechar o estágio e passar o bastão |
/entrega | planner | rubrica final com evidência |
/sdlc:painel | eu, quando quiser | ver quem está rodando, pipelines, tokens e custo |
/sdlc:ops | sessão ops (opcional) | vigiar CI e PRs, escrever intents novos |
/code-craftsman:on|off|pause|status | eu | ligar/desligar o gate de qualidade na sessão |
claude plugin update sdlc && claude plugin update claude-agent-kit (só baixa quando a versão sobe). O code-craftsman atualiza com git -C ~/.claude/skills/code-craftsman pull.◈ Qual modelo em qual papel
Regra que funciona: planner e reviewer em Claude, dev no modelo barato.
| Papel | Recomendado | Por quê |
|---|---|---|
| planner | Claude | entrevista, plano, supervisão: é julgamento, e é quem fala comigo |
| reviewer | Claude | é quem barra o dev; modelo fraco aqui aprova código fraco |
| dev | DeepSeek, GLM, Qwen, Kimi… | volume de código; o reviewer pega o que ele errar |
| tester-e2e | barato | executa fluxos e reporta; pouca decisão |
| document | barato | escreve a partir do diff; pouca decisão |
🔨 Regras inegociáveis (code-craftsman)
O que a skill de qualidade força em toda interação. É o "porquê" da disciplina.
RED → GREEN → REFACTOR. Teste falhando primeiro. Sem teste antes do código → bloqueado por hook. Cobertura ≥80% no que mudou; mutação ≥70%.
Mínimo que resolve. Nada especulativo. Sem abstração de uso único, sem IRepository com 1 implementação, sem UseCase pra CRUD. Flat first.
Toco só no que preciso. Não "melhoro" código adjacente. Cada linha alterada rastreia até o pedido.
Sem "exemplo genérico, adapte", sem pseudocódigo, sem TODO, sem catch(e){throw e}. Resposta compila + passa lint + tem teste na 1ª tentativa.
Proibido Manager/Processor/Handler/Util/Helper sem domínio, prefixo I em interface. Classe = substantivo, método = verbo.
Função ≤20 linhas, ≤2 params, ≤2 níveis de indentação. Arquivo ≤500 linhas. Commit subject ≤50 chars.
docs/adr/.⚠ Se travar
| Sintoma | Causa | Saída |
|---|---|---|
| Aba em "Is this a project you trust?" | pasta nova sem confiança | /sdlc:up já pré-aprova; à mão, escolha "Yes" uma vez |
401 Authentication Failed na aba do dev | chave errada/trocada | corrija com /sdlc:models <id>, feche a aba, relance o papel (abaixo) |
SendMessage pede [ref] | duas sessões com o mesmo nome | um nome por papel; feche as antigas |
| hooks não disparam | falta jq ou Git Bash | jq --version |
| update diz "última versão" mas falta arquivo | versão não subiu | claude plugin uninstall sdlc@sdlc && claude plugin install sdlc@sdlc |
Relançar só um agente que caiu (o pipeline não perde nada — estado está no pipeline.json + worktree):
✅ Checklist — antes de começar a codar
Bato o olho aqui toda vez. (As marcações ficam salvas neste navegador.)