Skip to content

CLAUDE.v9.md

Latest commit

 

History

History
90 lines (65 loc) · 13.4 KB

CLAUDE.v9.md

File metadata and controls

90 lines (65 loc) · 13.4 KB
Raw

CLAUDE.md — claude-code-sdd-toolkit

O que é este repo

Coleção de slash commands e skills para Claude Code que implementa um workflow de Pair Programming com TDD (SDD = Spec-Driven Development). Não é uma aplicação — é um toolkit que distribui artefatos (.md) para serem instalados em ~/.claude/commands/ e ~/.claude/skills/.

Versão atual: v9 (pipeline de 2 docs: SPEC de comportamento via /sdd-spec → PLAN técnico via /sdd-plan; + progressive disclosure + knowledge cache na memória; + spec viva em thoughts/capabilities/, mesclada pelo /sdd-close no merge). Detalhes completos em README.md.

Estrutura

commands/             # Slash commands distribuídos (.md). FONTE CANÔNICA.
  references/         # Templates/blocos carregados sob demanda pelos commands (progressive disclosure)
  deprecated/         # Versões antigas de commands (.vN.md) — fallback
skills/               # Skills distribuídas
  deprecated/         # Versões antigas de skills — fallback (mesma lógica)
README.md             # Visão geral em pt-BR
README-en.md          # Versão em inglês
LICENSE

Não existe src/, tests/, package.json etc. — os artefatos são markdown puro, consumidos pelo Claude Code em runtime.

Convenções deste repo (importantes)

  1. Slash commands ficam em commands/ na raiz, NÃO em .claude/commands/. Este repo é o "fonte" — .claude/commands/ é onde o Claude Code procura quando instalado em outros projetos. Aqui mantemos versionados em commands/ e copiamos pra ~/.claude/commands/ na instalação.

  2. Skills ficam em skills/ na raiz, mesma lógica.

  3. Versões antigas vão pra subpasta deprecated/ do tipo correspondente:

    • Command antigo → commands/deprecated/<nome>.vN.md
    • Skill antiga → skills/deprecated/<nome>/ (mesma estrutura da skill original)

    Não deletamos versões antigas — servem de fallback se uma versão nova regredir.

  4. Idioma: documentação e instruções de command em pt-BR. Termos técnicos e identificadores ficam em inglês.

  5. Progressive disclosure: o corpo de um command grande mantém só o protocolo (princípios, fluxo, guardrails). Templates de output e blocos usados num único passo vão pra commands/references/<command>-<tema>.md, carregados via Read no passo que os usa. Todo ponteiro pra reference inclui: busca em .claude/sdd-references/ do projeto → ~/.claude/sdd-references/ → fallback inline resumido (2-4 linhas com as seções). Instalação fica FORA de .claude/commands/ (em sdd-references/): o scanner do Claude Code registra todo .md dentro de commands/ como command namespaced, o que poluiria a lista de skills de toda sessão. Exceção: conteúdo de segurança (JSON de permissões do /modo-livre) não tem fallback improvisado — reference ausente = parar e avisar.

  6. Modelos: frontmatter de command usa ID completo (claude-sonnet-5 etc. — formato documentado); spawns de subagent usam aliases (opus/sonnet/haiku — garantidos pela doc do Agent SDK).

Workflow principal (resumo)

  • /sdd-spec → especificação de comportamento (o QUÊ): pesquisa o codebase e escreve a SPEC (histórias de usuário, critérios de sucesso, requisitos funcionais, testes de aceitação) em thoughts/specs/spec-<ts>-<slug>.md. Nunca escreve código, plano ou tarefas — antecede o /sdd-plan. Capability-first: começa a pesquisa por thoughts/capabilities/<dominio>.md (o que o sistema promete hoje) e marca o delta nos RFs quando toca comportamento existente ([MODIFIED → checkout C1] / [REMOVED → …]; sem marcação = ADDED) — é o que o /sdd-close mescla depois do merge. Lê e marca; nunca escreve capability. --explore é a fase sem compromisso: capabilities + custo estrutural medido via structure-cache → 2-3 direções com recomendação → decisão (SPEC / quick-task / investiga / não fazer, com nota idea). Não escreve arquivo nenhum no modo explore. Inspirado na gist "Formação da especificação" por @parruda
  • /sdd-plan → consome a SPEC de comportamento e gera o plano técnico (o COMO): pesquisa + tarefas TDD num doc auto-sized (Medium/Large/Complex) em thoughts/plans/PLAN-<...>.md, com cada tarefa rastreável a um RF/AT da SPEC (4º check de Cobertura). Lê as convenções de teste do projeto na largada e, antes de quebrar tarefas, faz o pair de testes (Passo 7.5) — interativo, nunca autônomo: inventário do que já é testado → 3 lentes paralelas propõem (Produto/QA, Engenharia de teste, Adversarial) → Mapa de Testes em tela (o que temos / o que não temos / o que a feature adiciona / pra onde caminhamos: cobertura antes→depois, ambiente novo, dívida, risco restante) → discussão ponto a ponto dos ⚠️/❓ com recomendação → fechamento com tabela de decisões e autoria. A IA propõe; corte, prioridade e risco aceito são do usuário — caso cortado vira dívida registrada, não esquecimento. Tipo por necessidade (unit/integração/e2e, não default unit) + Test env:. A quebra herda daí e o painel do Passo 9.5 não reabre o que foi decidido. Registra no ROADMAP 1 item por PR previsto (backlog/) — PLAN que o Check 5 divide em N PRs sequenciais gera N itens (com Depende de: entre slices), pra nenhum PR ficar esquecido. /sdd-plan-eco é a variante econômica pra Medium (main em Sonnet, quebra de tarefas + checks num subagente Opus)
  • /pr-draft → abre PR inicial em draft a partir do plano (branch + empty commit + title/body derivados da SPEC de comportamento), devolve o root pra branch default e cria worktree via /git-worktree. Promove o item do slice no ROADMAP (backlog/ → em-progresso/ + #PR) no vault local — nunca no body. Bloqueado pra criar PR → instrui o usuário comando-por-comando. /pr-draft sync reescreve o body pós-implementação como prévia pro reviewer (O quê / Por quê / Como / Test plan, rastreável a SPEC/PLAN/IMP/diff). Nunca commita código nem sai de draft sozinho
  • /executor-plan → executa TDD autônomo, faz git add por tarefa, nunca commita sozinho. TDD com red verificável (roda o teste, confirma que falha pelo motivo certo antes de implementar; falso-verde = parada dura; evidência do red no log/IMP, auditada pelo validador Haiku). Tipo de teste vem do PLAN (não default unit); quando o PLAN pede integração/e2e, sobe ambiente real (server local em background, Playwright pra telas, sandbox/DB) pra rodar red→green. Exceção ao red só quando a tarefa declara Tests: none justificado
  • /pair-review → companheiro interativo do review manual, em sessão nova: re-hidrata do staged + PLAN/IMP, perguntas de julgamento vão pra subagentes Opus focados, ajustes com gate + test count protection. Com PR sob review do time, valida cada fix contra o comentário humano de origem (modo r). Nunca commita sem escolha explícita, nunca posta no PR
  • /quick-task → atalho pra mudança pequena (≤3 arquivos), sem SPEC/PLAN formal
  • /pr-ready → entrega de PR ponta a ponta: avalia via /sdd-review; se reprovado → loop de correção via /quick-task até convergir (loop nativo no protocolo, não o builtin /goal; para se uma rodada não reduz os must-fix); aprovado → gate de verde (CI passou, deploy incluído; ou, sem CI, suíte local completa — unit+integração+e2e, todos os testes, não só os do PR; server local via memória do projeto) → commit/push humano → /pr-draft sync no body → handoff. Tirar de draft e marcar reviewer são gates AskUserQuestion (cada um com "agora não"), nunca automáticos. Nunca commita/pusha sozinho; saída só com PR aprovado E código pushado
  • /sdd-review → review de PR/branch/diff, oferece gerar fixes via /quick-task
  • /sdd-learning → extrai aprendizados não-óbvios de IMPs/reviews e propõe registro em memória (substitui o /sdd-confirm, depreciado em commands/deprecated/sdd-confirm.v7.md — a fonte GitHub PR cobre o caso de "decisões validadas após merge")
  • /pr-followup-audit → resgate retroativo de dívida de review: varre N PRs mergeados numa janela, extrai o que os revisores levantaram, e verifica ponto por ponto no código atual se ainda vive (arquivo:linha obrigatório — "o autor prometeu no PR" não é estado). Fan-out de subagentes Opus read-only por grupo temático de PRs. Triagem antes de registrar: review pendente de resposta, follow-up com PR aberto e adiamento deliberado não são dívida; fix aceito que nunca executa e regressão de escopo entre PRs são. Detecta tracker desalinhado (item aberto pra problema já resolvido, dependência que já caiu). Alimenta uma issue perene (body = só o que está aberto, pro contador do checklist significar algo; comentário = rodada append-only) sob confirmação — nunca posta nos PRs auditados. Complementar ao /sdd-close: um é profilaxia por PR, o outro é resgate do passivo
  • /sdd-close → fecha o ciclo do trabalho concluído (PR mergeado) em 4 atos: (1) arquiva o par SPEC+PLAN pra closed/ em cada pasta; (2) mescla o delta da SPEC na capability viva (thoughts/capabilities/<dominio>.md) — ADDED cria C<N>, MODIFIED edita e acrescenta ao [Origem] sem apagar rastro, REMOVED vai pra ## Removido; edição cirúrgica e idempotente, C<N> inexistente = para e avisa, nunca inventa requisito, capability nova só sob confirmação; (3) colhe pro backlog/ o que sobreviveria perdido — follow-ups dos comentários de review (inclusive inline, via gh api .../pulls/N/comments) e a dívida de teste da seção 6.6 do PLAN (que já sugeria "item no roadmap" e nada executava), sob confirmação individual e com dedup; (4) conclui o item do roadmap → concluido/ e recalcula os 🔓 desbloqueados. Multi-PR: o sync da capability acompanha o arquivamento da SPEC (todos os slices mergeados), a colheita roda por PR. Risco aceito como permanente não vira item. Nunca posta no PR. Distinto de old/ (descartadas, à mão). Nunca commita (thoughts/ gitignored)
  • /memory-organize → reorganiza auto-memory: detecta órfãs/links quebrados, propõe sub-sumários quando MEMORY.md cresce
  • /verifica → verificação comportamental: roda o app, exercita os fluxos tocados, registra evidência no IMP. Nunca produção; side effects só com confirmação
  • /investiga → root cause de bug não-óbvio: hipóteses com mecanismo causal → evidência em subagents paralelos → causa com fonte → handoff. Alimenta blockers/lessons
  • /sdd-init → audita/prepara projeto-alvo (constitution, thoughts/, Context7, references) sob confirmação por bloco
  • /git-rebase-seguro → atualiza branch com a base: baseline de testes, conflitos sob confirmação, test count protection, rollback garantido. Nunca pusha

Memória persistente

O toolkit usa o auto-memory nativo do Claude Code (~/.claude/projects/<projeto>/memory/) — sem dependências externas. A skill memory-keeper define o contrato (9 tipos, convenção flat, formato tabela do MEMORY.md). A skill vault-memory foi depreciada em favor desse modelo (ver skills/deprecated/vault-memory/ como referência histórica).

Detalhes e fluxo recomendado: README.md.

Princípios não-negociáveis

  • Zero Inferência — Nunca assumir comportamento de API ou padrão. Verificar via Context7 MCP ou no código existente.
  • Constitution-first — Commands leem CLAUDE.md e ARCHITECTURE.md do projeto-alvo antes de agir.
  • TDD como contrato (red verificável) — Testes antes do código; roda e confirma que falha pelo motivo certo antes de implementar (falso-verde = parada dura). Tipo por necessidade (unit/integração/e2e, não default unit). Se quebram, paramos.
  • Commit sob aprovação humana — Commands podem fazer git add, mas git commit e git push sempre precisam de OK explícito do usuário.
  • Atualizar > criar — Em memória, em docs, em commands: prefira atualizar artefato existente a criar duplicado.
  • Spec viva sob merge — thoughts/capabilities/ descreve o que o sistema faz hoje. Só o /sdd-close escreve nela, e só sob PR mergeado: comportamento não entregue nunca entra na spec viva. Todo requisito carrega [Origem: <spec> · PR #N].
  • Arquivar ≠ esquecer — O que o par SPEC+PLAN deixa pendente (follow-up de review, dívida de teste) é colhido pro roadmap no fechamento, sob confirmação. Registrar sem colher é esquecer com etapa extra.

O que NÃO fazer aqui

  • Não criar .claude/commands/ neste repo — usar commands/ na raiz.
  • Não criar .claude/skills/ neste repo — usar skills/ na raiz.
  • Não deletar arquivos de commands/deprecated/ ou skills/deprecated/ — são fallback intencional.
  • Não inventar workflow novo sem antes ler como o atual funciona (README.md + um command/skill existente como modelo).
  • Não commitar/pushar sem o usuário pedir explicitamente.

Pré-requisitos pros commands rodarem (em projetos-alvo)

  • CLAUDE.md e ARCHITECTURE.md no projeto-alvo
  • MCP Context7 configurado pra consultar documentação oficial
  • thoughts/ pra outputs persistentes (specs, IMPs, reviews, capabilities/ spec viva, roadmap/ vault Obsidian)
  • Auto-memory do Claude Code (nativo, em ~/.claude/projects/<projeto>/memory/) — gerenciado pela skill memory-keeper