adi_dev_workflow 1.0.0 → 1.1.0

package/frameworks/commands/sdd/generate-tech-spec.md

@@ -0,0 +1,218 @@
+---
+description: "Gera SPEC_TECH completo do SDD a partir de PRD aprovado. Param: caminho do prd.md"
+argument-hint: "<prd.md ex: docs/feature-user/v1/prd.md>"
+---
+
+Use a skill **sdd-tech-spec-expert** para gerar o SPEC_TECH.
+
+## Contexto
+
+Voce deve atuar como um **Arquiteto de Software Senior** e seguir todo o processo interativo definido na skill sdd-tech-spec-expert para transformar o PRD aprovado em uma especificacao tecnica completa.
+
+O $ARGUMENTS deve conter:
+1. **caminho do prd.md** (obrigatorio) — ex: `docs/feature-user/v1/prd.md`
+
+O spec_tech.md sera gerado no mesmo diretorio do prd.md.
+
+## Tech Direction (Opcional)
+
+Antes de iniciar, verifique se existe um arquivo `tech_direction.md` no mesmo diretorio do prd.md.
+
+- Se existir, use como **ponto de partida** para decisoes tecnicas — nao como verdade absoluta
+- O arquivo contem decisoes ja tomadas, tecnologias sugeridas, padroes preferidos e restricoes tecnicas
+- Voce pode complementar, ajustar ou questionar qualquer item
+- Se NAO existir, siga o fluxo normal
+
+## Regras Adicionais
+
+- **Claude Code**: use a ferramenta `AskUserQuestion` para esclarecer duvidas com o usuario
+- **NUNCA** deduza escopo ou invente informacoes — na **DUVIDA PERGUNTE AO USUARIO**
+- Foque exclusivamente no **COMO** sera implementado, nunca repita o **O QUE** do PRD
+- **ANTES de definir o SPEC_TECH**, explore as camadas existentes e código reutilizável para propor a melhor solução (rules e CLAUDE.md já estão no contexto — NÃO releia)
+- Se houver **tech_direction.md**, considere-o como ponto de partida para decisoes arquiteturais — nao ignore, mas valide contra o codebase existente e levante conflitos se houver
+- Liste **TODOS** os arquivos envolvidos e as acoes (criar/modificar/referencia) — economiza tokens e scans
+- Mapeie cada **User Story do PRD** para definicoes tecnicas correspondentes
+
+O arquivo deve ser salvo no diretorio `docs/[nome-feature]/vN/spec_tech.md`
+
+---
+
+## Delegacao QA — Secao 14 (Estrategia de Testes)
+
+A **secao 14 (Estrategia de Testes)** do SPEC_TECH NAO deve ser preenchida pelo arquiteto. Voce DEVE delegar para o subagente **qa-staff-engineer** que retorna um JSON estruturado. Depois, voce converte o JSON em markdown para a secao 14.
+
+### Quando executar
+
+Apos coletar todas as decisoes tecnicas e preencher as secoes 1-13 do SPEC_TECH, **ANTES de salvar o arquivo final**.
+
+### Passo 1: Preparar a lista de arquivos
+
+Monte a lista de `arquivos` que o subagente deve ler. Inclua TODOS os caminhos relevantes:
+
+- **PRD aprovado**: `docs/[nome-feature]/vN/prd.md`
+- **Regras do projeto**: `CLAUDE.md`, `.claude/rules/*.md`
+- **Migracoes**: `internal/db/migrations/*.sql` (relacionadas a feature)
+- **Queries SQLC**: `internal/db/queries/*.sql` (relacionadas a feature)
+- **Testes existentes**: busque arquivos `*_test.go` no projeto para o subagente entender padroes
+- **Codigo-fonte existente**: arquivos que serao modificados pela feature
+
+### Passo 2: Preparar as instrucoes
+
+Monte o campo `instrucoes` com:
+
+1. O conteudo completo do **SPEC_TECH parcial (secoes 1-13)** que voce montou ate o momento
+2. Os **criterios de aceitacao (CA-XX)** extraidos do PRD
+3. Os **componentes arquiteturais** envolvidos (handlers, services, repositories)
+4. Qualquer contexto adicional relevante para o QA
+
+### Passo 3: Disparar o subagente
+
+Lance o subagente usando a ferramenta `Agent` com:
+
+- **subagent_type**: `qa-staff-engineer`
+- **description**: "QA gerar testes spec_tech"
+- **prompt**: Monte o prompt com os 3 parametros obrigatorios:
+
+```
+Voce foi invocado com os seguintes parametros:
+
+1. **modo**: GERAR_TESTES
+2. **arquivos**: [lista de caminhos dos arquivos preparados no Passo 1]
+3. **instrucoes**: [conteudo preparado no Passo 2]
+```
+
+### Passo 4: Converter JSON em Markdown (secao 14)
+
+O subagente retorna um JSON com `casos_teste[]`. Voce DEVE converter para o formato markdown da secao 14 usando o mapeamento abaixo:
+
+#### Mapeamento de tipos
+
+| Campo `tipo` no JSON | Subsecao destino |
+|---------------------|-----------------|
+| `UNITARIO` | **14.1 Testes Unitarios** |
+| `INTEGRACAO` | **14.2 Testes de Integracao** |
+| `E2E` | **14.3 Testes End-to-End** |
+| `SEGURANCA` | **14.4 Cenarios de Erro** (subsecao seguranca) |
+| `PERFORMANCE` | **14.4 Cenarios de Erro** (subsecao performance) |
+
+#### Mapeamento de categorias para 14.4
+
+Alem dos testes tipo `SEGURANCA` e `PERFORMANCE`, inclua em 14.4 todos os `casos_teste` com `categoria` igual a:
+- `tratamento_erro`
+- `caso_extremo`
+- `fronteira` (quando o teste foca em comportamento de erro)
+
+#### Formato de saida por subsecao
+
+**14.1 Testes Unitarios** — agrupe os testes por camada arquitetural:
+
+```markdown
+### Apresentacao: [NomeHandler]
+| Cenario | Metodo | Input | Resultado Esperado | Mock |
+|---------|--------|-------|-------------------|------|
+| [titulo do CT] | [extrair do passos] | [dados_entrada] | [resultado_esperado] | [pre_condicoes] |
+
+### Service: [NomeService]
+| Cenario | Metodo | Input | Resultado Esperado | Mock |
+|---------|--------|-------|-------------------|------|
+
+### Dados: [NomeRepository]
+| Cenario | Metodo | Input | Resultado Esperado | Setup |
+|---------|--------|-------|-------------------|-------|
+```
+
+**14.2 Testes de Integracao**:
+
+```markdown
+### Integracao: [Camada A + Camada B]
+- **Setup**: [extrair de pre_condicoes]
+- **Cenarios**:
+  | Cenario | Fluxo | Resultado Esperado |
+  |---------|-------|-------------------|
+  | [titulo] | [passos resumidos] | [resultado_esperado] |
+```
+
+**14.3 Testes E2E**:
+
+```markdown
+### Fluxo: [titulo do CT]
+- **Pre-condicoes**: [pre_condicoes]
+- **Passos**:
+  1. [passo 1]
+  2. [passo 2]
+- **Pos-condicoes**: [resultado_esperado]
+- **Validacoes**: [observacoes]
+```
+
+**14.4 Cenarios de Erro**:
+
+```markdown
+| Cenario | Trigger | Comportamento Esperado | Codigo/Status | Log Esperado |
+|---------|---------|----------------------|---------------|-------------|
+| [titulo] | [dados_entrada] | [resultado_esperado] | [extrair do contexto] | [extrair do contexto] |
+```
+
+#### Tabela de Rastreabilidade
+
+Monte a tabela a partir do campo `criterios_aceitacao_validados` de cada caso de teste:
+
+```markdown
+### Rastreabilidade: Criterios de Aceite -> Testes
+
+| Criterio (CA-XX) | Testes Unitarios | Testes Integracao | Testes E2E |
+|------------------|-----------------|------------------|------------|
+| CA-01            | [CTs tipo UNITARIO com CA-01] | [CTs tipo INTEGRACAO com CA-01] | [CTs tipo E2E com CA-01] |
+```
+
+#### Informacoes adicionais do JSON
+
+- **`cenarios_nao_cobertos`**: adicione como nota apos a tabela de rastreabilidade
+- **`recomendacoes`**: adicione como nota apos cenarios nao cobertos
+- **`erros_leitura`**: se houver, mencione quais arquivos nao puderam ser lidos
+
+### Passo 5: Validar como arquiteto
+
+Antes de integrar a secao 14 no SPEC_TECH:
+
+1. Verifique **coerencia** com as secoes 1-13 (componentes, fluxos, APIs mencionados nos testes existem?)
+2. Verifique que **todos os CA-XX** do PRD tem pelo menos um teste na tabela de rastreabilidade
+3. Ajuste nomenclatura de componentes se o subagente usou nomes diferentes dos definidos nas secoes anteriores
+4. Complemente se algum cenario critico ficou de fora
+
+### Passo 6: Integrar e continuar
+
+1. Insira a secao 14 convertida no SPEC_TECH
+2. Preencha a secao 15 (Arquivos Envolvidos)
+3. Preencha a secao 16 (Checklist Final)
+4. Salve o arquivo e apresente ao usuario
+
+**NAO peca aprovacao isolada da secao 14** — apresente o SPEC_TECH completo para validacao final.
+
+---
+
+## Estado do Pipeline (sdd_state.yaml)
+
+Apos salvar o spec_tech.md com sucesso, atualize o arquivo `sdd_state.yaml` no mesmo diretorio:
+
+```yaml
+# atualizar apenas estes campos:
+current_step: spec_tech
+steps:
+  spec_tech:
+    status: completed
+    summary: "<componentes novos>, <N RPCs/endpoints>, tabelas: <lista tabelas>"
+```
+
+Se o usuario pulou o tech_direction, marque-o como `skipped`:
+
+```yaml
+steps:
+  tech_direction:
+    status: skipped
+```
+
+Se o `sdd_state.yaml` nao existir, nao crie — o generate-prd e responsavel por criar.
+
+## Entrada
+
+$ARGUMENTS

package/frameworks/commands/sdd/generate-tests.md

@@ -1,6 +1,6 @@
 ---
-description: Gera estrategia de testes completa com vies de QA Senior para uma feature ou task
-argument-hint: [caminho do SPEC_TECH/PRD ou descricao da task]
+description: "Gera estrategia de testes QA Senior para feature/task do SDD. Param: caminho do spec_tech.md ou arquivo de task"
+argument-hint: "<spec_tech.md ex: docs/feature-user/v1/spec_tech.md> ou <task ex: docs/feature-user/v1/tasks/T1.md>"
 ---
 
 Use a skill **sdd-qa-expert** para gerar a estrategia de testes.