GUIA DO VIAJANTE

Da máquina nova à primeira feature

Tudo roda dentro de uma sessão do Claude Code: instalar, escolher modelo, adotar num projeto e abrir o time do dia. Quatro momentos, cada um com um comando.

Os quatro momentos

1

Máquina nova

uma vez por máquina
claude plugin marketplace add giovani-junior-dev/sdlc && claude plugin install sdlc@sdlc
claude
/sdlc:setup

Confere git, jq, gh e a versão do Claude Code (≥ 2.1.287, README.md:15); instala o time (claude-agent-kit) e as skills de entrevista e TDD; clona o gate de qualidade code-craftsman; grava a persona global. Depois, feche e abra o claude.

Por quê: método e time são dois plugins e uma skill; sem os três os outros comandos não existem.

2

Modelos

uma vez por provedor (pulável se usa só Claude)
/sdlc:models

Pergunta o provedor, o modelo de cada slot e a chave; grava ~/.claude-kit/profiles.json e secrets.env. A chave nunca aparece no chat.

Por quê: dev em modelo barato e planner/reviewer em Claude cortam o custo de um time rodando horas.

3

Projeto

uma vez por repositório
cd <projeto>
claude
/sdlc:adopt

Copia REVIEW.md, intent/, specs/, evals/ e .claude/sdlc/ sem sobrescrever nada; detecta a branch base; pergunta o modelo de cada papel e grava team.json; funde CLAUDE.md e settings.json mostrando o diff.

Por quê: os agentes leem contrato de arquivos, não de conversa.

4

Dia a dia

por demanda
/sdlc:up
# na aba do planner: descreva a demanda

Abre o time do projeto, um por projeto (D57): planner, dev (já num worktree próprio), reviewer, tester-e2e e document. O planner entrevista, planeja, inicia o pipeline e o time trabalha sozinho até done.

Por quê: sessões separadas conversam direto entre si sem passar por você.

+

Jev (opcional)

desde a v0.8.0 · precisa de chave
# em %USERPROFILE%\.claude-kit\secrets.env
TYPESAFE_API_KEY=apikey_...

No fim do build, o Jev confere cada REQ-N do plano contra o diff da branch e anota PASS, RETRY ou HUMAN. Também escolhe o nível de cada parte do dev (D38), filtra curl para fora da máquina (D51) e faz a triagem de risco antes do review (D54). Sem a chave, nada muda. Resultado na aba Jev do /sdlc:painel.

Por quê: pega o "terminei" falso antes de gastar uma rodada do reviewer, por menos de US$ 0,001.

↻

Próxima demanda

no mesmo projeto, sem reabrir o time
# na aba do planner
/clear
# descreva a próxima demanda

O time do projeto fica aberto e executa todas as demandas (D57). No modo autônomo (padrão) o planner puxa a próxima do backlog sozinho; no normal, descreva a próxima na aba do planner. Ninguém roda /sdlc:up de novo. O estado fica em pipeline.json e roster.json, então nada se perde.

Por quê: /clear apaga a conversa, não a sessão: nome, modelo e endereço continuam.

O time de agentes

Cada papel é uma sessão separada do Claude Code. Eles conversam direto entre si, o reviewer nunca é quem escreveu o código e o dev trabalha num worktree próprio.

planner

PLANEJA

Entrevista você até o intent aprovado, gera o plano com o planf3, passa cada plano pelo code-craftsman e conduz o time até a entrega com rubrica. É o único que fala com você (D52).

Nunca: implementa.

Modelo: Claude

dev

CONSTRÓI

Implementa exatamente o que a spec aprovada define, com TDD vermelho-verde, e escreve a evidência na rubrica. Com 2 ou mais partes em arquivos separados, divide o trabalho em subagents (D38, D39).

Nunca: replaneja, inventa requisito ou se declara pronto sozinho.

Modelo: DeepSeek, GLM, Qwen, Kimi…

reviewer

CONFERE

Roda build, lint e testes antes de opinar; quebra o plano em requisitos e julga cada um no código, com arquivo:linha.

Nunca: muda código: cada achado volta ao dev.

Modelo: Claude

tester-e2e

TESTA

Valida na aplicação rodando: caminho feliz e casos de borda via Chrome DevTools/Playwright, com passos de reprodução por falha. Gera um checklist da tarefa e testa cada item no navegador visível, com evidência; item aberto ou falho barra o estágio (D57).

Nunca: conserta nada.

Modelo: barato

document

REGISTRA

Documenta o que foi entregue a partir do diff, da rubrica e da saída dos testes: progresso, ADRs, bugs e mapa do código.

Nunca: especula nem toca em código.

Modelo: barato

ops

VIGIA · OPCIONAL

Vigia CI, Kaneo e PRs paradas; quando algo quebra, escreve um intent novo e avisa o planner.

Nunca: corrige: detecta e descreve.

Modelo: qualquer

Jev

AVALIA · v0.8.0

Classificador que devolve probabilidades; a decisão sai do código. Confere cada REQ-N do plano contra o diff no fim do build, escolhe o nível (haiku, sonnet ou opus) de cada parte do dev, filtra curl para fora da máquina e faz a triagem de risco antes do review (D31, D38, D51, D54). Opcional: precisa de chave.

Nunca: aprova sozinho: só barra ou pede humano.

Modelo: jev-1.13.0 (TypeSafe)

Modelos no harness do Claude Code

O harness é sempre o Claude Code: tools, hooks, skills e comandos. O perfil do provedor só troca o endpoint, que precisa ser compatível com a API da Anthropic. Assim cada papel roda no modelo que você escolher.

Regra que funciona: planner e reviewer em Claude, dev no modelo barato. Julgamento fica com o modelo forte; volume de código com o barato, e o reviewer pega o que ele errar.

Cadastro: /sdlc:models. Troca de um papel: /sdlc:adopt --dev deepseek.

ProvedorModelo padrão do catálogoBom para
Anthropic nativoSonnet · Opus · Haiku · Fableplanner e reviewer (recomendado)
DeepSeek (v4)deepseek-v4-prodev, tester-e2e, document
GLM (Z.ai)glm-5.3dev, tester-e2e, document
Kimi K3k3dev, tester-e2e, document
Qwen (Coding Plan)qwen3.7-maxdev, tester-e2e, document
MiniMaxMiniMax-M2.7dev, tester-e2e, document
OpenCode Goqwen3.8-maxdev, tester-e2e, document

Como o time passa o bastão

  1. dev
  2. Jev
  3. reviewer
  4. tester-e2e
  5. dev (PR)
  6. reviewer (PR)
  7. document
  8. done → /entrega
pass leva ao próximo dono. Cada agente fecha seu estágio com /sdlc:next; o estado vive em specs/<slug>/pipeline.json.
fail volta ao dev com o gap. Feature: até 5 tentativas por estágio; hotfix: até 3. O mesmo gap duas vezes seguidas para o pipeline.
terminal (done, exhausted, thrash, blocked) chama o planner e você. Em done, o planner roda o /entrega. O merge é seu no modo normal; no autônomo (D40, padrão na D57) o planner mergeia pelo merge-pr.sh, que recusa PR sem review aprovado e CI verde.

Travas e autonomia

Skill é conselho; hook é lei. As travas decidem por fato, sem modelo no meio, e nada sai da máquina. É o que deixa o time rodar sozinho sem você vigiar cada passo.

Segredo nunca vai para arquivo

O agent é barrado ao gravar chave real (AWS, GitHub, Stripe live, OpenAI, Anthropic, chave privada) em código ou por comando. Passam o .env ignorado pelo git, a chave de exemplo oficial da AWS e o que o planner libera em .claude/sdlc/permitir-segredo.

D53 · changelog.md:91-94

Teste não some às escondidas

Remover caso de teste, pôr .skip ou .only, ou apagar arquivo de teste é barrado. Se for intencional, o planner libera em .claude/sdlc/permitir-teste. Teste vermelho também não se esconde atrás de tail: npm test | tail roda com pipefail.

D53 · changelog.md:95-96

O mesmo erro não se repete

Mesmo comando, mesma falha e código sem mudar entre uma tentativa e outra: na 2ª vez o agent recebe um aviso, e a 4ª é barrada. Quem edita o código entre as tentativas segue normal, como no TDD.

D53 · changelog.md:97

curl filtrado pelo Jev

curl para localhost passa direto. Para fora, o Jev classifica: teste de API passa; envio de dump, .env ou segredo é bloqueado e vai ao planner. O comando é redigido antes de ir ao Jev.

D51 · changelog.md:120-127

Modo autônomo, padrão desde a D57

Ligado, o time leva cada demanda do plano ao merge sem gate humano de PR e decide sozinho tudo o que está fora da lista fechada de escala (credencial, produção, ação irreversível, regra de negócio ambígua). Só o planner mexe no GitHub (push, PR, merge); force push e push em main são barrados para todos. Desligar: --sem-autonomo.

D40, D57 · changelog.md:28, 214-215

Merge só pelo merge-pr.sh

O merge exige review da PR aprovado, CI verde, sem conflito e base certa (merge-pr.sh recusa PR sem review aprovado e CI verde). Merge recusado devolve a demanda ao dev.

D40 · changelog.md:216

Suíte final 100% verde

No fim do plano, backlog.sh final roda a suíte inteira no código já mergeado e recusa checkout desatualizado. Só com tudo verde sai a rubrica-final.md, e o resultado fica num arquivo protegido.

D57 · changelog.md:35-37

A fábrica no terminal

Mods do Claude Code vêm dentro do plugin sdlc: sem passo extra em máquina nova, só Claude Code ≥ 2.1.287 e uma sessão nova. Faixa e painéis aparecem só na sessão do planner de um projeto adotado, e nada sai da máquina.

OndeO quê
Faixa acima do promptFábrica · backlog 4/9 · 44% ▓▓▓▓░░░░░ · agora: <slug> em review · ⚠ 1, relida a cada 5 s. O ⚠ conta demanda bloqueada e pendência urgente.
/fabricaAbas Backlog (status, PR, merge), Demanda (estágios ✓ ▶ · com tempo) e Pendências.
/pendenciasUrgente e Pode esperar. 1–9 marca, r manda "Resolva as pendências selecionadas…" ao planner, i ignora.
/rubricasPlanos de docs/planos/ com a suíte final (✓ verde, ✕ vermelha, · pendente), fases e rubricas. Enter abre o texto.
/prsPRs do backlog com título, lado, módulo e fase, status, link e SHA do merge, mais recente primeiro.
Rodapé do promptsdlc autônomo on|off · advisor on|off, em toda sessão de projeto adotado. Se a sessão aberta ficou no modo antigo, o rótulo avisa (advisor on (sessão off)): é o sinal de reabrir.

O painel de pendências abre sozinho quando o planner grava uma pendência nova, sem tirar o foco do prompt. Para usar as teclas, digite /pendencias.

Referência rápida dos comandos

ComandoQuem rodaPara quê
/sdlc:setupvocê, uma vez por máquinainstalar e conferir o ambiente
/sdlc:modelsvocê, uma vez por modelocadastrar provedor e chave
/sdlc:adoptvocê, uma vez por repopreparar o projeto e o team.json
/sdlc:upvocê, uma vez por projetoabrir o time (ou religar um papel com --roles)
/sdlc:intentplannerentrevista → intent/<slug>.md
/sdlc:teamplanneriniciar o pipeline com o time do roster
/sdlc:nextcada agentefechar o estágio e passar o bastão
/sdlc:backlogplannermanter o backlog do modo autônomo (init, next, mark, status) e puxar a próxima demanda
/sdlc:niveldevpedir ao Jev o nível (haiku, sonnet ou opus) de cada parte que vai para um subagent
/entregaplannerrubrica final da demanda
/sdlc:opssessão ops, opcionalvigiar CI e PRs e escrever intents novos
/sdlc:painelvocê, quando quiserquem roda ou espera você, pipeline, tokens, custo, aba Fábrica (modo autônomo, backlog, divisão do dev, travas) e aba Jev
/sdlc:metricasvocêcomparar por demanda o modo com e sem advisor: custo, chamadas, duração, reprovações e retries
/fabricaplanner (mod)painel com abas Backlog, Demanda e Pendências
/pendenciasplanner (mod)pendências em Urgente e Pode esperar; marcar, mandar ao planner ou ignorar
/rubricasplanner (mod)planos de docs/planos/ com a suíte final, as fases e as rubricas
/prsplanner (mod)PRs do backlog com status, link e SHA do merge

Como atualizar

claude plugin marketplace update sdlc && claude plugin update sdlc@sdlc
claude plugin marketplace update claude-agent-kit && claude plugin update claude-agent-kit@claude-agent-kit

Depois rode /sdlc:setup. Ele roda o update-all, que atualiza os plugins do usuário e de cada projeto (escopo de projeto incluído), a persona, a atualização automática e os guardrails.

Para aplicar a janela de contexto nova aos perfis de modelo já instalados, rode npx . update na pasta do claude-agent-kit.

Reabra as sessões: sessões abertas só carregam a versão nova quando são reabertas. Reinicie o time inteiro de uma vez; relançar só parte dele mistura versões.

Quando algo dá errado

Um agente caiu ou deu 401
Corrija a chave com /sdlc:models, feche a aba e rode /sdlc:up --roles dev. O pipeline não perde nada: o agente novo recebe a mesma mensagem de estágio.
Plugin atualizado não pegou
Feche e reabra a aba: /clear não carrega versão nova. Se faltar arquivo, reinstale o plugin.
Agentes não se enxergam
Tudo no mesmo ambiente: não misture WSL com Windows nativo. Um nome por papel por máquina.
Aba Jev vazia
Falta TYPESAFE_API_KEY, o plano não tem REQ-N ou ainda não houve build pass. O motivo fica em specs/<slug>/eval.json.