Ferramentas de Design & Planejamento (Stream D)

O Stream D contém 7 ferramentas para transformar specs em artefatos de implementação acionáveis — schemas, contratos de UI, decisões de arquitetura, planos de execução e contratos de eventos.

generate_adr

Gere Architecture Decision Records para uma spec.

O que produz: Documentos ADR estruturados cobrindo o contexto da decisão, opções consideradas, decisão tomada e consequências. O formato segue MADR (Markdown Architectural Decision Records).

Quando usar: Quando uma spec envolve uma escolha tecnológica significativa, padrão de arquitetura ou trade-off que desenvolvedores futuros precisam entender.

Prompt: "Gere ADRs para a spec SPEC-004 no projeto proj_abc123"

Exemplo de saída:

# ADR-001: Usar Redis para armazenamento de sessões

## Status: Aceito

## Contexto
A spec de autenticação requer persistência de sessão entre múltiplas instâncias de servidor...

## Decisão
Usar Redis como armazenamento de sessões...

## Consequências
- Positivo: Escalonamento horizontal sem sessões fixas (sticky sessions)
- Negativo: Adiciona Redis como dependência de infraestrutura obrigatória

---

design_schema

Design de schema de banco de dados a partir dos requisitos da spec.

O que produz:

• Definições de tabelas com colunas, tipos e restrições
• Relacionamentos de chaves primárias e estrangeiras
• Sugestões de índices para performance de consultas
• Dicas de migração
• Schema em múltiplos dialetos (SQL, Prisma, SQLAlchemy, GORM, etc.)

Quando usar: Quando uma spec envolve persistência de dados e você precisa de um ponto de partida concreto para a camada de banco de dados.

Prompt: "Design o schema de banco de dados para a spec SPEC-002 no projeto proj_abc123"

---

define_ui_contract

Defina contratos de componentes de UI, fluxo de dados e gerenciamento de estado.

O que produz:

• Definições de interface de componentes (props, eventos, slots)
• Diagrama de fluxo de dados (quais componentes gerenciam qual estado)
• Abordagem de gerenciamento de estado (local, contexto, store)
• Contrato de API entre frontend e backend
• Requisitos de acessibilidade

Quando usar: Para qualquer spec que inclua um componente frontend, formulário ou interação do usuário.

Prompt: "Defina o contrato de UI para o fluxo de login na spec SPEC-001 do projeto proj_abc123"

---

challenge_spec

Teste uma spec sob pressão para falhas, concorrência, escala e casos extremos.

O que verifica:

• Problemas de concorrência (condições de corrida, deadlocks)
• Pontos de ruptura de escala (o que acontece com carga 10x, 100x?)
• Modos de falha (e se o banco de dados estiver indisponível?)
• Casos extremos não cobertos pelos critérios de aceitação
• Superfície de ataque de segurança

Quando usar: Para qualquer spec que rodará em produção com usuários reais. Especialmente valioso para specs envolvendo pagamentos, autenticação ou funcionalidades em tempo real.

Prompt: "Desafie a spec SPEC-003 do projeto proj_abc123"

---

generate_execution_plan

Gere um PLAN.md passo a passo para implementar uma spec — ciclo RED/GREEN/VERIFY com etapas paralelizáveis.

O que produz:

## Fase 1: Fundação (paralelo)
- [ ] Etapa 1a: Criar migração de banco de dados
- [ ] Etapa 1b: Definir interfaces TypeScript
- [ ] Etapa 1c: Escrever testes com falha (RED)

## Fase 2: Implementação (sequencial)
- [ ] Etapa 2a: Implementar camada de repositório (GREEN)
- [ ] Etapa 2b: Implementar camada de serviço

## Fase 3: Verificação
- [ ] Etapa 3a: Executar suite de testes completa (VERIFY)
- [ ] Etapa 3b: Atualizar status da spec para review

Quando usar: Antes de começar a implementação. O PLAN.md se torna o contrato de implementação para o agente de IA ou desenvolvedor.

Prompt: "Gere um plano de execução para a spec SPEC-005 no projeto proj_abc123"

---

generate_orchestration_script

Gere um script de automação paralelo em 3 camadas (worktrees + claude -p) para executar múltiplas specs simultaneamente.

O que produz: Um script shell que:

• Cria git worktrees isolados por spec
• Lança workers claude -p em paralelo
• Gerencia alocação de recursos com base em CPU e RAM disponíveis
• Monitora saúde dos workers e trata falhas

Quando usar: Quando você precisa implementar múltiplas specs independentes simultaneamente e quer máximo paralelismo.

Prompt: "Gere um script de orquestração para as specs SPEC-010, SPEC-011, SPEC-012 no projeto proj_abc123"

---

event_contracts

Gerencie contratos de arquitetura orientada a eventos — gere contratos de eventos com JSON Schema para validação produtor/consumidor.

O que produz:

• Definições de JSON Schema para cada tipo de evento
• Contrato do produtor (o que o emissor garante)
• Contrato do consumidor (o que o assinante espera)
• Estratégia de versionamento
• Notas de compatibilidade retroativa

Quando usar: Para qualquer spec que envolva filas de mensagens, barramentos de eventos (Kafka, RabbitMQ, AWS SQS/SNS, NATS) ou integrações de webhook.

Prompt: "Defina contratos de eventos para o fluxo de processamento de pedidos na spec SPEC-008 do projeto proj_abc123"

Exemplo de saída:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OrderPlaced",
  "version": "1.0.0",
  "type": "object",
  "required": ["orderId", "customerId", "items", "total", "placedAt"],
  "properties": {
    "orderId": { "type": "string", "format": "uuid" },
    "customerId": { "type": "string", "format": "uuid" },
    "items": { "type": "array", "items": { "$ref": "#/definitions/OrderItem" } },
    "total": { "type": "number", "minimum": 0 },
    "placedAt": { "type": "string", "format": "date-time" }
  }
}