Um modelo por fase: troca automática de modelo no pi

Um modelo para todo tipo de trabalho é a concessão que você deixou de notar. Explorar pede um cérebro diferente de construir. O harness deveria trocar por você, e não depender da sua memória.

Você escolhe um modelo no começo da sessão e usa ele para tudo. Usa para explorar uma base de código desconhecida, para planejar uma mudança, para escrever o código, para revisar o diff, para corrigir o que a review pegou. São cinco trabalhos diferentes, e você entregou todos a um modelo só, numa configuração escolhida antes de saber como seria o trabalho.

Isso é uma concessão, e ela cobra dos dois lados. Nas fases fáceis, você paga caro demais, rodando um modelo forte e caro numa exploração que um barato resolve bem. Nas fases difíceis, você pensa de menos, rodando o último modelo que selecionou em vez do modelo cuidadoso que o trabalho merece. Cansei de pagar esse imposto, então coloquei a troca dentro do harness. Aqui está como, e por que ela pertence ali.

Um modelo para tudo é uma concessão

Pense no que cada fase realmente pede.

Explorar pede um modelo barato, com atenção ampla e solta e bastante orçamento de raciocínio. Ele vai ler muito e não se comprometer com nada. Construir pede o contrário: um modelo de código preciso, que pega um plano aprovado e executa com pouca cerimônia e pouco overhead de raciocínio. Revisar pede um modelo cético em esforço alto, procurando o que vai quebrar. Corrigir pede precisão de novo, com escopo apertado.

Rode um modelo só nas cinco e ele não serve bem para nenhuma. Não é uma ineficiência pequena. Ao longo de uma semana de trabalho real, é a diferença entre uma conta que te incomoda e uma que você esquece, e entre uma review que pega o bug e uma que deixa passar.

✗

Um modelo, todas as fases

1. 01Paga caro rodando um modelo forte na exploração
2. 02Pensa de menos quando a fase difícil pega o seu padrão
3. 03Esquece de trocar, então o modelo raramente combina com o trabalho
4. 04O orçamento de raciocínio erra para os dois lados

✓

Um modelo por fase

1. 01Um modelo barato vasculha enquanto você explora
2. 02Um modelo preciso executa a construção
3. 03Um modelo cuidadoso em esforço alto faz a review
4. 04A troca acontece sozinha, todas as vezes

O OpenCode acertou isso com os modes

A ferramenta que me ensinou isso foi o OpenCode. O valor real dele não está nos modelos que traz, está na ideia de modes. Você define um conjunto de agentes com nome, e cada um tem o próprio modelo, a própria temperatura, o próprio limite de passos, as próprias permissões. Troca de mode e a configuração inteira troca junto.

Este é o formato do meu setup, reduzido ao essencial:

Modes, cada um com seu modelo

O explore lê e não pode editar. O build recebe um modelo de código em temperatura baixa e pode escrever. O mode é a unidade, e trocar o mode troca tudo.

Mode	Modelo	Temp	Pode editar?
explore	glm-5.1	0.7	não
plan	deepseek-v4-pro	0.2	não
build	kimi-k2.6	0.1	sim
review	glm-5.1	0.0	não
fix	deepseek-v4-pro	0.1	sim

O mode é a unidade de trabalho. Troque e você ganha o modelo certo, a criatividade certa e as permissões certas num movimento só. Isso impede você de explorar com o modelo de build e de deixar o modelo de exploração colocar código em produção. A configuração completa, e por que acabei voltando para o Claude Code, está em OpenCode vs Claude Code.

O pi não tem nada disso. O pi é um loop e um comando /model que você opera na mão. Uso o pi como agente do dia a dia exatamente pelos motivos do guia do pi: é mínimo e dá para ver tudo. Mas mínimo significava sem modes, e operar o /model na mão significava que eu esquecia, o tempo todo. Então construí a peça que faltava.

Então liguei as trocas no pi

O pi-skill-model-handoff é um pacote pequeno para o pi. Ele lê dois campos de qualquer skill que você carrega e aplica os dois no instante em que a skill ativa: o modelo e o nível de raciocínio.

O insight é que o trabalho já se anuncia por meio de uma skill. Quando você começa a revisar, carrega a sua skill de review. Quando começa a construir, carrega a skill de build. A skill já sabe que tipo de trabalho é, então o modelo e o esforço de raciocínio pertencem à skill. Coloque os dois ali uma vez, e o harness faz a troca automaticamente toda vez que a skill carrega. Você para de tratar a escolha de modelo como uma tarefa à parte.

Configure em três passos

• ✓Obrigatório:
  Instale o pacoteRode pi install npm:@felipefontoura/pi-skill-model-handoff, depois /reload ou reinicie o pi.
• ✓Obrigatório:
  Adicione model e thinking a cada skillDois campos opcionais no frontmatter do SKILL.md da skill. Aponte cada fase para o modelo e o orçamento de raciocínio que ela merece.
• ✓Obrigatório:
  Carregue uma skill e veja a trocaO pi imprime handoff active: <skill> no momento em que troca. A mudança é visível, não uma mágica pelas suas costas.

A configuração fica no frontmatter da skill. Dois campos, ambos opcionais:

---
name: review
description: Review code changes.
model: openai/gpt-5.5
thinking: high
---

model é qualquer modelo com prefixo de provedor que o pi consiga acessar. thinking é um de off, minimal, low, medium, high, xhigh. Essa é a interface inteira. Nenhum arquivo de configuração para manter, nenhum roteador para entender. A skill que você ia carregar de qualquer jeito agora carrega o próprio modelo e o próprio esforço.

O que acontece quando uma skill carrega

Entrada

Você carrega a skill do trabalho em questão

↓

1. READLer os dois campos

   O pacote lê model e thinking do frontmatter da skill enquanto ela ativa.

   ↓
2. SWITCHAplicar modelo e esforço

   Define o modelo ativo e o orçamento de raciocínio para os turnos seguintes. Nada mais muda.

   ↓
3. CONFIRMImprimir a troca

   O pi mostra handoff active: <skill>, para você ver que a troca aconteceu e para o quê.

↓

Saída

O modelo acompanha o trabalho, e você nunca mais toca no /model

Este é o mapa de trocas que eu uso, as mesmas fases que o OpenCode oferece como modes, expressas como skills:

Um exemplo de mapa de trocas

Os modelos são escolha sua. O ponto é que a fase carrega os modelos, então exploração barata e construção precisa deixam de ser uma decisão que você esquece de tomar.

Skill / fase	Modelo	Esforço
explore	opencode-go/glm-5.1	high
plan	anthropic/claude-sonnet-4-5	high
build	anthropic/claude-sonnet-4-5	minimal
review	openai/gpt-5.5	high
fix	openai/gpt-5.5	medium

Amarrar em skills, e não em modes, de propósito

Um mode é um conceito em que você precisa lembrar de entrar. É mais uma coisa para gerenciar ao lado do trabalho de verdade. Uma skill não. Você carrega uma skill porque o trabalho pediu, então pendurar o modelo e o esforço na skill faz o roteamento vir de graça. Não existe um interruptor separado para ligar e esquecer.

É um botão a menos, e um botão a menos é toda a filosofia de design em que o pi se apoia. O melhor controle é aquele que você não precisa lembrar de usar.

Sendo honesto sobre o que ele não faz

Se você quer um sistema que lê a sua mensagem e escolhe a skill sozinho, não é isso, e eu desconfiaria da versão que é. No momento em que um harness começa a adivinhar em que fase você está, você volta a depurar uma caixa-preta que decidiu algo por você. Prefiro carregar a skill eu mesmo e saber exatamente no que o modelo está prestes a se transformar.

Isto é harness engineering, não truque de plugin

O pacote é pequeno. O ponto não é o pacote. Roteamento de modelo é um mecanismo de controle, uma das partes que compõem um harness, e eu adicionei como umas poucas linhas que consigo ler, em vez de esperar um fornecedor lançar modes numa ferramenta que não controlo. É todo o argumento de harness engineering: o modelo é commodity, e a vantagem está no código que você coloca em volta dele.

Tem um dividendo de custo também. Roteie um modelo barato para explorar e um forte só para construir, e os turnos exploratórios param de ser cobrados a preço premium por um trabalho que nunca precisou disso. É a mesma briga do resto da conta de tokens, travada na camada de roteamento. Um harness mínimo não perdeu para o cheio de features. Ele me deixou adicionar o único controle que eu queria e pular os vinte que não queria.

Troca de modelo, respostas rápidas

O que o pi-skill-model-handoff faz?+

É um pacote do pi que troca automaticamente o modelo ativo e o esforço de raciocínio quando você carrega uma skill. Cada skill declara um modelo e um nível de thinking no frontmatter do SKILL.md, e o pacote aplica os dois no momento em que a skill ativa, imprimindo handoff active: <skill> para a troca ficar visível.

Como instalo?+

Rode pi install npm:@felipefontoura/pi-skill-model-handoff, depois /reload ou reinicie o pi. Em seguida, adicione os campos opcionais model e thinking ao frontmatter de qualquer skill e a troca acontece quando ela carrega.

Quais valores posso usar no nível de thinking?+

Um de off, minimal, low, medium, high ou xhigh. Combine um nível alto com as fases de exploração e review, em que o raciocínio compensa, e um nível low ou minimal com a construção, em que o plano já está feito e você quer execução rápida e precisa.

Ele escolhe a skill por mim com base no meu prompt?+

Não, e isso é de propósito. O pacote é passivo. Quem decide qual skill carrega continua sendo o pi; o pacote só aplica o modelo e o esforço depois que a skill é selecionada.

Um roteamento que lê o seu prompt e adivinha a fase colocaria uma caixa-preta de volta no loop. Você escolhe a fase, o harness cuida da troca mecânica.

Qual a diferença para os modes do OpenCode?+

O OpenCode tem modes como conceito nativo: agentes com nome que carregam, cada um, um modelo, uma temperatura e permissões. O pi não tem modes. Este pacote dá o mesmo roteamento de modelo por fase, mas amarrado às skills que você já carrega, como um pacote open source pequeno que você consegue ler e modificar, em vez de uma feature que você espera um fornecedor lançar.