Construir

Construir — Orquestrador do Fluxo

Visão geral

Esta é a porta de entrada do fluxo. Ela faz duas coisas:

1. Roteia — se a tarefa precisa de apenas uma skill, identifica qual e a invoca.
2. Orquestra — se a tarefa é um projeto ou funcionalidade completa, executa a esteira inteira (Definir → Planejar → Construir → Verificar → Revisar → Lançar), pausando nos portões de aprovação para o humano decidir antes de avançar.

Todo o progresso é gravado em fluxo/estado.json, o que permite retomar uma execução interrompida e alimentar interfaces externas (dashboard, página web) em tempo real.

Quando usar

• O usuário quer construir algo do zero (projeto, funcionalidade, mudança significativa)
• O usuário não sabe por onde começar
• O usuário pediu explicitamente "o fluxo completo"

Quando NÃO usar: tarefas de uma linha, correções triviais ou quando o usuário já invocou uma skill específica diretamente.

Roteamento — qual skill aplicar?

Quando a tarefa NÃO exige a esteira completa, identifique a fase e invoque a skill certa:

A tarefa chegou
    │
    ├── Nem o usuário sabe direito o que quer? ─────→ entrevistar
    ├── Ideia vaga, precisa de variações? ──────────→ refinar-ideia
    ├── Documento de produto (o quê e por quê)? ────→ prd
    ├── Projeto/funcionalidade nova? ───────────────→ especificar
    ├── Tem spec, falta quebrar em tarefas? ────────→ planejar
    ├── Implementando código? ──────────────────────→ implementar
    │   ├── Trabalho de interface (UI)? ────────────→ frontend
    │   ├── Trabalho de API? ───────────────────────→ design-de-api
    │   ├── Precisa de contexto melhor? ────────────→ contexto
    │   ├── Precisa validar contra docs oficiais? ──→ fontes-oficiais
    │   └── Risco alto / código desconhecido? ──────→ questionar
    ├── Escrevendo/rodando testes? ─────────────────→ teste-primeiro
    │   └── Teste no navegador? ────────────────────→ testar-navegador
    ├── Algo quebrou? ──────────────────────────────→ depurar
    │   └── Quebrou no meio da esteira? ────────────→ recuperar
    ├── Revisando código? ──────────────────────────→ revisar-codigo
    │   ├── Complexo demais? ───────────────────────→ simplificar-codigo
    │   ├── Preocupação com segurança? ─────────────→ blindar
    │   └── Preocupação com performance? ───────────→ otimizar
    ├── Commit, branch, versão? ────────────────────→ git-profissional
    ├── Pipeline de CI/CD? ─────────────────────────→ ci-cd
    ├── Desativar/migrar sistema antigo? ───────────→ migrar
    ├── Documentação e decisões (ADRs)? ────────────→ documentar
    ├── Logs, métricas, alertas? ───────────────────→ observabilidade
    ├── Deploy e lançamento? ───────────────────────→ lancar
    ├── Fechar o ciclo e registrar aprendizados? ───→ memoria
    └── Quanto custou? Onde otimizar tokens? ───────→ telemetria

A esteira completa

Quando a tarefa é um projeto ou funcionalidade inteira, execute as fases em ordem. Os portões (🚪) são paradas obrigatórias: apresente o resultado, aguarde aprovação explícita do humano e só então avance. Nunca pule um portão por conta própria.

FASE 1 — DEFINIR
  entrevistar (se o objetivo estiver vago) → refinar-ideia (se houver alternativas)
  → prd (produto/funcionalidade nova de porte) → especificar (deriva do PRD)
  🚪 PORTÃO 1: o humano aprova o PRD (linguagem de produto); a spec técnica
     deriva dele e é apresentada como anexo. Para correções e ajustes pequenos,
     pule o PRD e aprove a spec direto.

FASE 2 — PLANEJAR
  planejar → salva tarefas/plano.md e tarefas/pendencias.md
  🚪 PORTÃO 2: o humano aprova o plano e a ordem das tarefas

FASE 3 — CONSTRUIR (por tarefa, em fatias verticais)
  contexto → fontes-oficiais (quando usar libs/APIs externas) → implementar
  → questionar (decisões não triviais) → teste-primeiro
  [observabilidade corre em paralelo: instrumente enquanto constrói]

FASE 4 — VERIFICAR
  teste-primeiro (suíte completa) → testar-navegador (se houver UI) → depurar (se falhar)

FASE 5 — REVISAR
  revisar-codigo → simplificar-codigo → blindar → otimizar (se houver meta de performance)
  🚪 PORTÃO 3: o humano aprova o código revisado (mostre o diff resumido e os achados)

FASE 6 — LANÇAR
  git-profissional → documentar → ci-cd (se aplicável) → lancar
  🚪 PORTÃO 4: o humano dá o "vai" final antes do deploy

ENCERRAMENTO
  memoria (registra aprendizados) → telemetria (registra consumo por fase)

Nem toda execução precisa de todas as fases. Uma correção de bug pode ser apenas: depurar → teste-primeiro → revisar-codigo → git-profissional. Anuncie no início quais fases o trabalho exige e por quê.

Estado do fluxo (fluxo/estado.json)

Ao iniciar a esteira, crie a pasta fluxo/ no projeto e mantenha estado.json atualizado a cada mudança de fase, portão ou tarefa:

{
  "projeto": "nome-do-projeto",
  "iniciado_em": "2026-07-06T14:30:00-03:00",
  "fase_atual": "construir",
  "progresso_pct": 45,
  "narrativa": "Construindo a terceira de sete tarefas: a tela de correção. Os testes da lógica já passam.",
  "medidores": {
    "skills_executadas": 5,
    "agentes_ativos": 0,
    "agentes_total": 2,
    "seguranca": "pendente",
    "testes": "14/14",
    "consumo": "—"
  },
  "fases": [
    { "id": "definir", "status": "concluida", "portao": "aprovado" },
    { "id": "planejar", "status": "concluida", "portao": "aprovado" },
    { "id": "construir", "status": "em_andamento", "tarefa_atual": "3/7" },
    { "id": "verificar", "status": "pendente" },
    { "id": "revisar", "status": "pendente", "portao": "aguardando" },
    { "id": "lancar", "status": "pendente", "portao": "aguardando" }
  ],
  "aguardando_humano": false,
  "pergunta_pendente": null,
  "artefatos": ["tarefas/plano.md", "tarefas/pendencias.md"]
}

Este arquivo é o contrato com qualquer interface externa: um dashboard web pode lê-lo para mostrar progresso, portões pendentes e perguntas ao usuário. Quando pausar em um portão, defina aguardando_humano: true e preencha pergunta_pendente.

O campo narrativa é obrigatório em toda atualização: uma ou duas frases, em linguagem leiga (sem jargão técnico), contando o que está acontecendo agora — como se explicasse para alguém que nunca programou. É esse campo que uma interface exibe como "o que a IA está fazendo", e é ele que transforma o fluxo em ferramenta de aprendizado, não só de produção.

Os medidores também devem ser mantidos em toda atualização — são o que dá ao usuário a certeza de que tudo está rodando:

• skills_executadas — quantas skills distintas já foram acionadas no ciclo.
• agentes_ativos / agentes_total — subagentes trabalhando agora e o total usado no ciclo. Atualize ao despachar e ao receber cada subagente.
• seguranca — pendente → rodando (quando blindar inicia) → verificada (sem achados abertos) ou achados (em tratamento).
• testes — resultado da última execução (ex.: "14/14"); "—" antes do primeiro teste.
• consumo — "—" até a telemetria fechar o ciclo; então registre a estimativa (ou o valor real de /cost, se o usuário informar), ex.: "≈150 mil tokens".

Modo painel (interface web)

Quando o usuário quiser acompanhar pela tela ("abre o painel", "quero ver o fluxo", "mostra a esteira") — ou for iniciante e a interface ajudar — ative o modo painel:

1. Suba o servidor (em segundo plano, a partir da pasta do projeto):
   • Windows: node "%USERPROFILE%\.claude\skills\construir\painel\servidor.js"
   • macOS/Linux: node ~/.claude/skills/construir/painel/servidor.js
2. Abra http://localhost:4747 no navegador do usuário.
3. Diário de eventos — além do estado.json, registre cada passo relevante em fluxo/eventos.jsonl (uma linha JSON por evento):

   {"em":"2026-07-06T14:32:00-03:00","fase":"construir","skill":"teste-primeiro","tipo":"info","narrativa":"Escrevendo os testes que descrevem como o quiz deve se comportar."}
   

   Tipos: info, sucesso, alerta, portao. A narrativa é sempre em linguagem leiga — é o que aparece na tela para o usuário.
4. Portões pela tela — ao chegar num portão: preencha pergunta_pendente no estado.json (campos portao, titulo, resumo, aprova), defina aguardando_humano: true e execute:

   node "<caminho do painel>/aguardar-decisao.js" portao-1
   

   O comando bloqueia até o humano decidir na tela e imprime a decisão em JSON (aprovar ou ajustar + comentário). Trate ajustar como reprovação do portão: aplique o comentário e reapresente. Se o comando expirar (30 min), pergunte pela conversa normalmente.

Sem o painel, os portões funcionam pela conversa — o modo painel é opcional e não substitui a regra: nenhum portão avança sem decisão humana explícita.

Economia de tokens (regras da esteira)

1. Passagem de bastão enxuta — ao trocar de fase, não recarregue a conversa inteira: resuma o essencial (decisões, caminhos de arquivos, pendências) em até 20 linhas.
2. Referências sob demanda — os arquivos em referencias/ só são lidos na etapa que os exige, nunca preventivamente.
3. Subagentes para varredura — buscas amplas no código vão para subagentes; o contexto principal recebe só a conclusão.
4. Uma skill por vez — carregue apenas a skill da fase atual.
5. Registre o consumo — ao fechar cada fase, anote na telemetria o esforço gasto, para o próximo ciclo ser mais barato.

Comportamentos permanentes (valem em todas as fases)

1. Declare suposições antes de implementar qualquer coisa não trivial e peça correção.
2. Gerencie a própria confusão — requisito ambíguo ou contraditório: PARE e pergunte; nunca escolha uma interpretação em silêncio.
3. Discorde quando necessário — aponte o problema, quantifique o impacto, proponha alternativa. Concordar com uma má ideia não ajuda ninguém.
4. Imponha simplicidade — se 100 linhas bastam, 1.000 linhas são um defeito.
5. Disciplina de escopo — toque apenas no que a tarefa pede.
6. Verifique, não suponha — "parece certo" nunca encerra uma tarefa; evidência sim (teste passando, build limpo, comportamento observado). O critério global está em referencias/definicao-de-pronto.md.

Sinais de alerta

• Avançar de fase sem parar no portão
• fluxo/estado.json desatualizado em relação ao trabalho real
• Começar a codificar sem spec aprovada ("é óbvio o que construir" não existe)
• Pular a verificação porque "parece certo"
• Fases inteiras rodando sem o humano saber o que está acontecendo

Verificação

• As fases necessárias foram anunciadas no início e justificadas
• Todos os portões pararam e receberam aprovação explícita
• fluxo/estado.json reflete o estado real ao final
• memoria e telemetria foram executadas no encerramento