Guia do Usuário — FASE

Versão: 3.2.0 | Última atualização: 2026-03-25

Referência detalhada de fluxos de trabalho, resolução de problemas e configuração. Para configuração rápida, veja o README.

Índice

• Diagramas de Fluxo de Trabalho
• Referência de Comandos
• Referência de Configuração
• Exemplos de Uso
• Resolução de Problemas
• Referência Rápida de Recuperação

Diagramas de Fluxo de Trabalho

Ciclo de Vida Completo do Projeto

  ┌──────────────────────────────────────────────────┐
  │                  NOVO PROJETO                    │
  │  /fase-novo-projeto                               │
  │  Perguntas -> Pesquisa -> Requisitos -> Plano de Entregas  │
  └─────────────────────────┬────────────────────────┘
                             │
              ┌──────────────▼─────────────┐
              │      PARA CADA FASE:       │
              │                            │
              │  ┌──────────────────────┐  │
              │  │ /fase-discutir-fase   │  │  <- Definir preferências
              │  └──────────┬───────────┘  │
              │             │              │
              │  ┌──────────▼──────────┐   │
              │  │ /fase-planejar-fase  │   │  <- Pesquisa + Plano + Verificação
              │  └──────────┬──────────┘   │
              │             │              │
              │  ┌──────────▼──────────┐   │
              │  │ /fase-executar-fase  │   │  <- Execução paralela
              │  └──────────┬──────────┘   │
              │             │              │
              │  ┌──────────▼────────────┐ │
              │  │ /fase-verificar-trabalho│ │  <- Teste de Aceitação do Usuário manual
              │  └──────────┬────────────┘ │
              │             │              │
              │     Próxima fase?──────────┘
              │             │ Não
              └─────────────┼──────────────┘
                             │
             ┌───────────────▼──────────────┐
             │  /fase-auditar-marco          │
             │  /fase-completar-marco        │
             └───────────────┬──────────────┘
                             │
                    Outro marco?
                        │          │
                       Sim        Não -> Pronto!
                        │
                ┌───────▼──────────────┐
                │  /fase-novo-marco     │
                └──────────────────────┘

Coordenação do Agente de Planejamento

  /fase-planejar-fase N
          │
          ├── Pesquisador de Fase (x4 em paralelo)
          │     ├── Pesquisador de pilha tecnológica
          │     ├── Pesquisador de funcionalidades
          │     ├── Pesquisador de arquitetura
          │     └── Pesquisador de armadilhas
          │           │
          │     ┌──────▼──────┐
          │     │ PESQUISA.md │
          │     └──────┬──────┘
          │            │
          │     ┌──────▼──────┐
          │     │  Planejador │  <- Lê PROJETO.md, REQUISITOS.md,
          │     │             │     CONTEXTO.md, PESQUISA.md
          │     └──────┬──────┘
          │            │
          │     ┌──────▼───────────┐     ┌────────┐
          │     │ Verificador de   │────>│ PASSA? │
          │     │ Plano            │     └───┬────┘
          │     └──────────────────┘         │
          │                             Sim  │  Não
          │                              │   │   │
          │                              │   └───┘  (loop, até 3x)
          │                              │
          │                        ┌─────▼──────┐
          │                        │ Arquivos   │
          │                        │ de PLANO   │
          │                        └────────────┘
          └── Concluído

Arquitetura de Validação (Camada Nyquist)

Durante a pesquisa do planejar-fase, o FASE mapeia a cobertura de testes automatizados para cada requisito da fase antes de qualquer código ser escrito. Isso garante que, quando o executor do Claude fizer commit de uma tarefa, já exista um mecanismo de feedback para verificá-la em segundos.

O pesquisador detecta sua infraestrutura de testes existente, mapeia cada requisito a um comando de teste específico, e identifica qualquer estrutura de testes que deve ser criada antes do início da implementação (tarefas da Onda 0).

O verificador de plano aplica isso como uma 8ª dimensão de verificação: planos onde as tarefas não possuem comandos de verificação automatizados não serão aprovados.

Saída: {fase}-VALIDACAO.md — o contrato de feedback para a fase.

Desabilitar: Defina workflow.nyquist_validation: false em /fase-configuracoes para fases de prototipagem rápida onde a infraestrutura de testes não é o foco.

Validação Retroativa (/fase-validar-fase)

Para fases executadas antes da validação Nyquist existir, ou para bases de código existentes com apenas suítes de testes tradicionais, audite retroativamente e preencha lacunas de cobertura:

  /fase-validar-fase N
          |
          +-- Detectar estado (VALIDACAO.md existe? RESUMO.md existe?)
          |
          +-- Descobrir: escanear implementação, mapear requisitos para testes
          |
          +-- Analisar lacunas: quais requisitos não têm verificação automatizada?
          |
          +-- Criar auditor: gerar testes, executar, depurar (máx. 3 tentativas)
          |
          +-- Atualizar VALIDACAO.md
                |
                +-- CONFORME -> todos os requisitos têm verificações automatizadas
                +-- PARCIAL -> algumas lacunas escaladas para manual apenas

O auditor nunca modifica o código de implementação — apenas arquivos de teste e VALIDACAO.md. Se um teste revelar um bug de implementação, ele é sinalizado como uma escalação para você resolver.

Quando usar: Após executar fases que foram planejadas antes do Nyquist estar habilitado, ou após /fase-auditar-marco detectar lacunas de conformidade Nyquist.

Coordenação de Ondas de Execução

  /fase-executar-fase N
          │
          ├── Analisar dependências do plano
          │
          ├── Onda 1 (planos independentes):
          │     ├── Executor A (contexto fresco de 200K) -> commit
          │     └── Executor B (contexto fresco de 200K) -> commit
          │
          ├── Onda 2 (depende da Onda 1):
          │     └── Executor C (contexto fresco de 200K) -> commit
          │
          └── Verificador
                └── Verificar base de código contra objetivos da fase
                      │
                      ├── PASSA -> VERIFICACAO.md (sucesso)
                      └── FALHA -> Problemas registrados para /fase-verificar-trabalho

Fluxo Brownfield (Base de Código Existente)

  /fase-mapear-codigo
          │
          ├── Mapeador de Pilha Tecnológica     -> codebase/PILHA.md
          ├── Mapeador de Arquitetura           -> codebase/ARQUITETURA.md
          ├── Mapeador de Convenções            -> codebase/CONVENCÕES.md
          └── Mapeador de Preocupações          -> codebase/PREOCUPACOES.md
                 │
         ┌───────▼──────────────┐
         │ /fase-novo-projeto    │  <- Perguntas focam no que você está ADICIONANDO
         └──────────────────────┘

Referência de Comandos

Fluxo de Trabalho Principal

Navegação

Gerenciamento de Fases

Brownfield e Utilitários

Referência de Configuração

O FASE armazena configurações do projeto em .fase-ai-local/config.json. Configure durante /fase-novo-projeto ou atualize depois com /fase-configuracoes.

Esquema Completo do config.json

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "fase/fase-{fase}-{slug}",
    "milestone_branch_template": "fase/{milestone}-{slug}"
  }
}

Configurações Principais

Configurações de Planejamento

Nota: Se .fase-ai-local/ está no .gitignore, commit_docs é automaticamente false independente do valor da configuração.

Opções de Fluxo de Trabalho

Desabilite essas opções para acelerar fases em domínios familiares ou para economizar tokens.

Ramificação Git

Estratégias de ramificação explicadas:

Variáveis de modelo: {fase} = número com zero à esquerda (ex.: "03"), {slug} = nome em minúsculas com hífens, {milestone} = versão (ex.: "v1.0").

Perfis de Modelo (Por Agente)

Filosofia dos perfis:

• quality — Opus para todos os agentes de tomada de decisão, Sonnet para verificação somente-leitura. Use quando há cota disponível e o trabalho é crítico.
• balanced — Opus apenas para planejamento (onde as decisões de arquitetura acontecem), Sonnet para todo o resto. O padrão por boas razões.
• budget — Sonnet para tudo que escreve código, Haiku para pesquisa e verificação. Use para trabalho de alto volume ou fases menos críticas.

Exemplos de Uso

Novo Projeto (Ciclo Completo)

claude --dangerously-skip-permissions
/fase-novo-projeto            # Responda perguntas, configure, aprove o plano de entregas
/clear
/fase-discutir-fase 1        # Defina suas preferências
/fase-planejar-fase 1        # Pesquisa + plano + verificação
/fase-executar-fase 1        # Execução paralela
/fase-verificar-trabalho 1   # Teste de aceitação do usuário manual
/clear
/fase-discutir-fase 2        # Repita para cada fase
...
/fase-auditar-marco          # Verifique tudo que foi entregue
/fase-completar-marco        # Arquive, crie tag, pronto

Novo Projeto a Partir de Documento Existente

/fase-novo-projeto --auto @prd.md   # Executa automaticamente pesquisa/requisitos/plano de entregas do seu documento
/clear
/fase-discutir-fase 1               # Fluxo normal a partir daqui

Base de Código Existente

/fase-mapear-codigo          # Analisar o que existe (agentes em paralelo)
/fase-novo-projeto           # Perguntas focam no que você está ADICIONANDO
# (fluxo de fases normal a partir daqui)

Correção Rápida de Bug

/fase-rapido
> "Corrigir o botão de login que não responde no Safari mobile"

Retomando Após uma Pausa

/fase-progresso              # Veja onde você parou e o que vem a seguir
# ou
/fase-retomar-trabalho       # Restauração completa do contexto da última sessão

Preparando para Lançamento

/fase-auditar-marco          # Verificar cobertura de requisitos, detectar esboços
/fase-planejar-lacunas       # Se a auditoria encontrou lacunas, criar fases para fechá-las
/fase-completar-marco        # Arquive, crie tag, pronto

Predefinições de Velocidade vs Qualidade

Mudanças de Escopo no Meio do Marco

/fase-adicionar-fase         # Adicionar nova fase ao plano de entregas
# ou
/fase-inserir-fase 3         # Inserir trabalho urgente entre fases 3 e 4
# ou
/fase-remover-fase 7         # Remover escopo da fase 7 e renumerar

Resolução de Problemas

"Projeto já inicializado"

Você executou /fase-novo-projeto mas .fase-ai-local/PROJETO.md já existe. Esse é um mecanismo de segurança. Se quiser recomeçar, delete o diretório .fase-ai-local/ primeiro.

Degradação de Contexto em Sessões Longas

Limpe sua janela de contexto entre comandos principais: /clear no Claude Code. O FASE é projetado em torno de contextos frescos — cada subagente recebe uma janela limpa de 200K. Se a qualidade estiver caindo na sessão principal, limpe e use /fase-retomar-trabalho ou /fase-progresso para restaurar o estado.

Planos Parecem Errados ou Desalinhados

Execute /fase-discutir-fase [N] antes do planejamento. A maioria dos problemas de qualidade do plano vem do Claude fazendo suposições que o CONTEXTO.md teria prevenido. Você também pode executar /fase-listar-premissas [N] para ver o que o Claude pretende fazer antes de se comprometer com um plano.

Execução Falha ou Produz Esboços

Verifique se o plano não foi muito ambicioso. Os planos devem ter no máximo 2-3 tarefas. Se as tarefas forem muito grandes, elas excedem o que uma única janela de contexto consegue produzir de forma confiável. Replaneje com escopo menor.

Perdeu o Fio da Meada

Execute /fase-progresso. Ele lê todos os arquivos de estado e diz exatamente onde você está e o que fazer a seguir.

Precisa Mudar Algo Após a Execução

Não reexecute /fase-executar-fase. Use /fase-rapido para correções pontuais, ou /fase-verificar-trabalho para identificar e corrigir problemas sistematicamente via teste de aceitação do usuário.

Custos de Modelo Muito Altos

Mude para o perfil budget: /fase-definir-perfil budget. Desabilite os agentes de pesquisa e verificação de plano via /fase-configuracoes se o domínio for familiar para você (ou para o Claude).

Trabalhando em Projeto Sensível/Privado

Defina commit_docs: false durante /fase-novo-projeto ou via /fase-configuracoes. Adicione .fase-ai-local/ ao seu .gitignore. Os artefatos de planejamento ficam locais e nunca tocam o git.

Atualização do FASE Sobrescreveu Minhas Mudanças Locais

Desde a v1.17, o instalador faz backup de arquivos modificados localmente em fase-local-patches/. Execute /fase-reaplicar-patches para mesclar suas mudanças de volta.

Subagente Parece Ter Falhado Mas o Trabalho Foi Feito

Existe uma solução conhecida para um bug de classificação do Claude Code. Os orquestradores do FASE (executar-fase, rapido) verificam a saída real antes de reportar falha. Se você vir uma mensagem de falha mas commits foram feitos, verifique git log — o trabalho pode ter sido bem-sucedido.

Referência Rápida de Recuperação

Estrutura de Arquivos do Projeto

Para referência, aqui está o que o FASE cria no seu projeto:

.fase-ai-local/
  PROJETO.md              # Visão e contexto do projeto (sempre carregado)
  REQUISITOS.md           # Requisitos v1/v2 com escopo e IDs
  PLANO-ENTREGAS.md       # Divisão de fases com rastreamento de status
  ESTADO.md               # Decisões, bloqueadores, memória de sessão
  config.json             # Configuração de fluxo de trabalho
  MARCOS.md               # Arquivo de marcos concluídos
  pesquisa/               # Pesquisa de domínio do /fase-novo-projeto
  tarefas/
    pendentes/            # Ideias capturadas aguardando trabalho
    concluidas/           # Tarefas concluídas
  debug/                  # Sessões de depuração ativas
    resolvidos/           # Sessões de depuração arquivadas
  codebase/               # Mapeamento brownfield da base de código (de /fase-mapear-codigo)
  fases/
    XX-nome-da-fase/
      XX-YY-PLANO.md      # Planos de execução atômicos
      XX-YY-RESUMO.md     # Resultados de execução e decisões
      CONTEXTO.md         # Suas preferências de implementação
      PESQUISA.md         # Descobertas da pesquisa do ecossistema
      VERIFICACAO.md      # Resultados de verificação pós-execução