MÉTODO EXPX
01 / 36
PARA O TIME DE ENGENHARIA
COMO VAMOS TRABALHAR COM IA

Planejamento é o produto. Código é a saída.

Por que estamos adotando o método Expx e o expxdev como a forma padrão de construir e manter este sistema com agentes de IA.

MÉTODO EXPX
02 / 36
Pedir a um agente para construir uma feature funciona — até a segunda hora.
O PROBLEMA QUE JÁ VIMOS ACONTECER
MÉTODO EXPX
03 / 36
POR QUE ISSO ACONTECE

O plano vago vira decisão do agente

O que sobra pro agente decidir

  • Escolher um padrão que não é o do projeto
  • Escrever o teste na pasta que o runner não olha
  • Refatorar três arquivos que ninguém pediu

O que o método elimina antes

  • Ambiguidade resolvida na fase de planejamento
  • Convenção do repositório, descoberta e escrita
  • Escopo travado no que a investigação provou
MÉTODO EXPX
04 / 36
Uma pergunta feita durante a execução é sempre uma falha da fase de planejamento.
PRIMEIRA APOSTA DO MÉTODO
MÉTODO EXPX
05 / 36
FUNDAMENTOS

As quatro apostas de onde tudo decorre

01

Esforço no plano

Ambiguidade eliminada antes, ou a execução autônoma é uma aposta, não um processo.

02

Critério verificável

Portão de aceite binário, sem adjetivo. TDD não é sugestão.

03

Escopo travado

Só o que a investigação provou. Melhoria avulsa vira dívida registrada, não brinde.

04

Quem faz não aprova

QA e auditoria são agentes à parte, com acesso só de leitura — tecnicamente, não por promessa.

MÉTODO EXPX
06 / 36
O método não é Claude Code. Não é Cursor. Não é nenhuma IA específica.
A DUAS OBJEÇÕES QUE VÊM AGORA
MÉTODO EXPX
07 / 36
AGNÓSTICO DE FERRAMENTA

O contrato vive no harness, não no modelo

O que muda entre ferramentas

  • Claude Code, OpenCode, ou outro harness compatível
  • Namespace do comando — com ou sem prefixo
  • Qual LLM roda por trás, e a que custo

O que nunca muda

  • Fases sequenciais, TDD obrigatório, portão de aceite
  • Hooks que avisam ou bloqueiam, iguais nos dois harnesses
  • Quem implementa não aprova — regra, não sugestão
MÉTODO EXPX
08 / 36
Sim, o método consome mais token. Essa é a troca certa.
O QUE COMPRA MAIS PLANEJAMENTO
MÉTODO EXPX
09 / 36
A FALÁCIA DA ECONOMIA DE TOKEN

Bom, bonito e barato não coexistem sem método

Economizar token sem método

  • Plano raso, ambiguidade sobra para a execução
  • Retrabalho, bug em produção, ocorrência de suporte
  • O barato de agora vira o caro de depois

Token investido em planejamento

  • Ambiguidade eliminada antes de escrever código
  • Menos ciclo de correção, menos ocorrência aberta
  • O caro de agora evita o caro maior de depois
MÉTODO EXPX
10 / 36
CUSTO × RESULTADO

Quem garante a saída é o método, não o modelo

Se fosse a IA que garantisse

  • Qualidade depende de trocar para o modelo mais caro
  • Cada harness novo reabre a mesma dúvida
  • Nenhum jeito barato de manter o mesmo padrão

Como o método garante

  • Hooks, portões e agentes read-only, não o tamanho do modelo
  • Mesmo contrato roda com LLM mais barato — GLM, MiniMax, outros
  • Token a mais compra planejamento — a fonte do retrabalho caro
MÉTODO EXPX
11 / 36
SEÇÃO 02

O ecossistema: oito skills, um contrato

O que cada peça faz e como elas se encontram sem se conhecer.

MÉTODO EXPX
12 / 36
FLUXO

O método de ponta a ponta

01

prodx

Diz se vale a pena fazer.

02

stackx

Diz como este projeto escreve código.

03

sprintx / runx

Planejam e fazem o trabalho.

04

mergex

Entrega: branch, commit, PR, QA.

legadox mede o quanto ter medo. buildx conduz a cadeia inteira quando o projeto é novo.

MÉTODO EXPX
13 / 36
CATÁLOGO · BASE

As três que fazem o trabalho

BASE

sprintx

Planeja e executa feature nova em seis fases.

BASE

runx

Corrige ocorrência em produção em cinco estágios.

BASE

mergex

Branch, commit por task, PR e pacote de QA.

MÉTODO EXPX
14 / 36
CATÁLOGO · CAMADA E ORQUESTRA

As que mudam o comportamento das três

CAMADA

legadox

Endurece o trabalho proporcional ao raio de impacto.

CAMADA

stackx

Descobre o dialeto técnico real do repositório.

CAMADA

memox

Indexa artefatos fechados e o que já se sabe de um arquivo.

CAMADA

prodx

Recebe o pedido cru e emite veredito com evidência.

buildx orquestra as três acima — não é camada, é a única exceção do método: ela não modifica, invoca.

MÉTODO EXPX
15 / 36
ARQUITETURA

Contratos escritos, não código compartilhado

Como elas se encontram

  • Não se conhecem por código — só por contrato
  • Dá para instalar três e não as outras cinco
  • Dá para atualizar uma sem tocar nas demais

A exceção é a buildx

  • Não modifica ninguém — invoca
  • Exige prodx, sprintx e mergex instaladas
  • Sem elas, o CLI diz exatamente o que falta
MÉTODO EXPX
16 / 36
BUILD E RUN

Mesmo método, gatilho diferente

sprintx · Build

  • Gatilho: feature nova, planejada do zero
  • Entrada: uma ideia, um requisito
  • Seis fases, F1 a F6
  • Saída: a feature entregue

runx · Run

  • Gatilho: ocorrência num sistema em produção
  • Entrada: chamado, ticket ou relato de cliente
  • Cinco estágios, E1 a E5
  • Saída: ocorrência encerrada, com dois relatórios
MÉTODO EXPX
17 / 36
Muda o gatilho. Muda o tamanho. Nunca muda o rigor.
BASE DE CONHECIMENTO · TDD OBRIGATÓRIO · CRITÉRIO VERIFICÁVEL · ORQUESTRADOR
MÉTODO EXPX
18 / 36
SEÇÃO 03

Como isso vira rotina, na prática

Duas entradas reais: a feature que nasce como ideia, e o bug que chega pelo suporte.

MÉTODO EXPX
19 / 36
ENTRADA 01 · IDEIA OU REQUISITO

Da ideia ao merge: a rotina de uma feature

PRODX Pedido veredito com evidência SPRINTX F1–F5 Planejamento base · descoberta · plano · auditoria SPRINTX F6 Execução autônoma TDD, task a task MERGEX Branch → PR commit por task, portão, revisão vale a pena auditoria aprova suíte verde dúvida → BLOQUEIOS.md, segue sem parar → decisão humana no E9
O veredito, a auditoria e o portão são os três pontos onde o método para para checar antes de seguir.
MÉTODO EXPX
20 / 36
MERGEX POR DENTRO

A entrega termina em decisão humana, não em merge automático

E0 Branch nasce com o trabalho, não no fim E2 Portão 10 verificações E3 Atenção humana 3 faixas, por arquivo E9 · MANUAL Revisão e merge nunca automático BLOQUEADO encerra — nunca maquia PRONTO classificado PR aberto
A mergex nunca faz merge sozinha, nunca resolve conflito. Decisão é sempre de quem revisa.
MÉTODO EXPX
21 / 36
ENTRADA 02 · CHAMADO DO SUPORTE

Do relato do cliente à resposta sem jargão

E1 · INVESTIGAÇÃO Causa raiz E2 · PLANO Proporcional ao bug E3 · FIX SOB TDD Regressão nasce antes E4 · QA Independente E5 · RELATÓRIO Dois públicos reprovado regressão passa antes do fix — causa errada
Só bug exige causa raiz comprovada. Quem corrigiu no E3 nunca é quem aprova no E4.
MÉTODO EXPX
22 / 36
O RETORNO AO CLIENTE

O suporte devolve resposta, não diagnóstico técnico

Fica no relatório técnico

  • Causa raiz comprovada, com evidência
  • Arquivos, funções, stack trace
  • Teste de regressão que prova o fix

Vai para o cliente (uso.md)

  • O que mudou, em linguagem do produto
  • Hook sem-jargao-no-uso barra vazamento técnico
  • Ocorrência encerrada, com fechamento visível
MÉTODO EXPX
23 / 36
Em código legado, o comportamento atual é o contrato — bugs inclusive.
POR QUE O LEGADOX EXISTE
MÉTODO EXPX
24 / 36
COMPOSIÇÃO

As camadas mudam sprintx e runx por dentro

PRODX
A única que roda antes: decide se o trabalho deveria existir.
STACKX
Plano define caminho de teste, camada e padrão de erro por task.
LEGADOX
Rigor proporcional ao raio: caracterização, orçamento de diff, plano de reversão.
MEMOX
Indexa o que já foi tentado, decidido ou reprovado antes de planejar de novo.
MÉTODO EXPX
25 / 36
SEÇÃO 04

Guardrails de projeto legado

legadox não substitui sprintx nem runx — endurece os dois, proporcional ao risco.

MÉTODO EXPX
26 / 36
O GATILHO É UM ARQUIVO

O raio de impacto decide o quanto ter medo

GATILHO

PERFIL.md

Sem ele, não existe modo legado. É a primeira coisa a gerar.

8 SINAIS

Raio por evidência

Chamadores, cobertura, zona de risco, churn — nunca por sensação.

SEM DADO

Pior caso conta

Sinal que não pode ser coletado assume o cenário mais arriscado.

FAIXA

BAIXO · MÉDIO · ALTO

BAIXO exige todas as condições juntas; os outros bastam uma.

MÉTODO EXPX
27 / 36
O QUE O RAIO ACIONA

Rigor cresce com o risco, nunca antes

MÉDIO E ALTO

Nada muda sem congelar antes

Teste de caracterização passando no código atual, antes de qualquer alteração.

TODA FAIXA

Orçamento por task

5 arquivos / 150 linhas em BAIXO, até 2 arquivos / 40 linhas em ALTO. Nunca estourado em silêncio.

RAIO ALTO

Aprovação humana obrigatória

Registrada, explícita — e plano de reversão para cada task, efeito irreversível incluído.

MÉTODO EXPX
28 / 36
Nenhuma melhoria colateral. O que incomoda vai para DIVIDA.md, não para o diff.
CÓDIGO MORTO IDENTIFICADO NÃO É REMOVIDO — VIRA ACHADO
MÉTODO EXPX
29 / 36
SEÇÃO 03

Como o método se protege sozinho

Regra escrita é instrução — e instrução se esquece na task 14.

MÉTODO EXPX
30 / 36
GARANTIAS

Três camadas, cada uma cobre o que a anterior não garante

HOOKS

Aviso → bloqueio

Todo hook de método nasce em aviso. Só promove a bloqueio depois de semanas sem falso positivo.

AGENTES

Só leitura

QA e auditoria têm acesso de leitura declarado — "aponta, não corrige" é tecnicamente forçado.

SEGURANÇA

Falha fechada

Hook de segredo nasce em bloqueio. Falso positivo ali é raro; segredo commitado não tem volta.

MÉTODO EXPX
31 / 36
AGENTES

Quem verifica não pode corrigir

  1. 01

    auditor-plano

    Fura o plano antes de virar código — leitura apenas.

  2. 02

    revisor-testes

    Esse teste passaria com a implementação errada?

  3. 03

    qa

    Valida contra os critérios ao fim do runx — não corrige.

  4. 04

    analista-de-conflito

    Explica o que cada lado pretendia num merge — nunca resolve.

MÉTODO EXPX
32 / 36
SEÇÃO 04

O CLI: o que instala e o que observa

expxdev — sete subcomandos, três binários, um plugin local.

MÉTODO EXPX
33 / 36
INSTALAÇÃO

Uma linha declarativa, a mesma no terminal e no CI

# seleciona skills e harness, sem terminal interativo
npx expxdev init --skills sprintx,runx,mergex --harness claude,opencode --yes

# sem --skills e sem TTY: só mostra o que faria, não escreve nada
npx expxdev init

git clone --depth 1 — usa a credencial já configurada, sem token extra.

MÉTODO EXPX
34 / 36
REFERÊNCIA

Sete subcomandos — panel e watch não escrevem no projeto

INIT

expx init

Instala as skills escolhidas neste projeto.

ADD / REMOVE

expx add · remove

Ajusta a seleção e remonta o plugin do zero.

UPDATE

expx update

Atualiza as skills instaladas, com --check antes de aplicar.

DOCTOR

expx doctor

Diagnostica uma instalação quebrada, 16 verificações.

SÓ LEITURA

expx panel

Painel local em 127.0.0.1 — qualquer escrita recebe 405.

SÓ LEITURA

expx watch

Acompanha um trabalho ao vivo, no terminal, sem sair do lugar.

MÉTODO EXPX
35 / 36
O QUE JÁ EXISTE

O expxdev não é conceito — é o CLI já em uso

7
SKILLS NO CATÁLOGO
7
SUBCOMANDOS DO CLI
441
TESTES, SEM REDE
16
VERIFICAÇÕES DO DOCTOR
MÉTODO EXPX
36 / 36
PRÓXIMO PASSO

Rodem o init num projeto real esta semana

Comecem por sprintx, runx e mergex. Adicionem stackx e prodx quando o ritmo pedir mais rigor.

Ver a documentação completa Anatomia do init