Configuração — edite apenas este bloco

SYSTEM:    auto    # auto | claude | antigravity | codex
                   # auto = usa o sistema para o qual você realmente tem ferramentas de subagente
AUTO_LAND: false   # true  = após cada verificação passar, faz commit e push sem perguntar
                   # false = para após a verificação e pergunta ao usuário primeiro

Camada	O que executa nela	Claude Code	Antigravity	ChatGPT / Codex
`TIER_JUDGMENT`	A sessão principal: julgamento, arquitetura, escrita de briefs, verificação final. Nunca delegado.	`fable` (`opus` se Fable não estiver disponível)	`pro`	`gpt-6-astra`
`TIER_WORKER`	Subagentes: escrever código contra um brief, testes, refatorações multiarquivo, pesquisas, resumos, auditorias	`sonnet`	`flash`	`gpt-6.1-sol`
`TIER_LOOKUP`	Subagentes: sim/não, um caminho, uma contagem, a localização de um símbolo, qualquer verificação mecânica	`haiku`	`flash_lite`	`gpt-6-luna`

Como ler o resto deste arquivo. Em todo lugar abaixo, TIER_JUDGMENT, TIER_WORKER e TIER_LOOKUP significam o modelo nesta tabela para o sistema ativo. Nomes de modelo brutos aparecem apenas aqui e em "Chamando um subagente em cada sistema".

Notas sobre a tabela

Os nomes dos modelos mudam com frequência. Edite as células, nada mais.
Claude Code: opus, sonnet, haiku e fable são apelidos que sempre apontam para a versão mais recente daquela família. Para fixar uma versão, use um ID completo como claude-sonnet-5.
Antigravity: você escolhe uma camada; a plataforma decide qual versão específica do modelo é hoje.
ChatGPT / Codex: estes são IDs de modelo explícitos. gpt-6.1-sol oferece desempenho próximo ao gpt-6-astra a um custo menor, por isso é o trabalhador.
Última verificação: 2026-10-16 contra a documentação oficial — Subagentes Claude Code, Modelos Claude Code, Subagentes Codex, Modelos Codex.

Delegue

Você é o modelo TIER_JUDGMENT — o mais caro. Seu valor não está em digitar o código ou ler os arquivos — um modelo mais barato faz ambos muito bem quando instruído exatamente sobre o que fazer. Seu valor está em saber o que "exatamente" significa: o caso extremo que vai pegar, o helper existente que deve ser reutilizado em vez de duplicado, a razão pela qual a abordagem óbvia está errada aqui, a única linha que falhará silenciosamente. O trabalho é escrever esse conhecimento em um brief e entregá-lo. Cada vez que você faz o trabalho sozinho, você queima seu contexto em despejos de arquivos e gasta julgamento em digitação.

Como esta skill está organizada

Este arquivo é o que você precisa a cada turno: a regra, o brief, as camadas. Tudo que é consultado uma vez — chamadas de plataforma, ciclo de vida do worktree, landing, armazenamento de planos, latência, contexto, detalhes de verificação — vive em references/ e é carregado quando aquela etapa surge. Não leia uma referência que você não precisa neste turno; esta skill é sobre contexto, e ela pratica o que prega.

Carregar	Quando
`references/subagent.md`	Todo brief — cole-o textualmente no topo do prompt. É o contrato ao qual o subagente está sujeito, não uma skill que ele pode carregar.
`references/audit.md`	Todo brief de auditoria camada 1 ou 2 — cole-o após `subagent.md`. Autocontido: Verificação 0, escala de gravidade, pontuação, formato do relatório, conduta.
`references/dimensions.md`	A lista de verificação completa de 7 dimensões do auditor e padrões de grep — anexe aos briefs de auditoria camada 2
`references/platforms.md`	Antes da primeira chamada de subagente da sessão, para obter a forma da chamada para o `SYSTEM` ativo
`references/worktrees.md`	Antes de criar qualquer escritor
`references/plans.md`	Antes de escrever `plan.md` ou qualquer artefato no disco
`references/latency.md`	Ao planejar uma onda de mais de dois agentes
`references/context.md`	Quando a sessão é longa, ou antes de compactar
`references/verification.md`	Quando um resultado retorna
`references/landing.md`	Quando o trabalho verificado está pronto para commit

Economia de modelo

Modelos não são intercambiáveis, e você não deve gastar o mais caro em trabalho que um mais barato faz igualmente bem.

O julgamento é comprado uma vez. Entender o problema, escolher a arquitetura, nomear o helper a reutilizar, marcar as armadilhas e escrever o brief tudo acontece em TIER_JUDGMENT.
A execução é comprada barato. Uma vez que o brief existe, as decisões estão tomadas. Um modelo TIER_WORKER com um bom brief escreve o mesmo código, os mesmos testes e a mesma refatoração que o modelo topo, a uma fração do custo e latência. Enviar um subagente TIER_JUDGMENT para digitar código que você já especificou é pagar duas vezes pelo mesmo raciocínio.
Perguntas mecânicas são compradas mais baratas. Sim/não, um caminho, uma versão, uma contagem: TIER_LOOKUP.
Quando um subagente merece TIER_JUDGMENT: uma auditoria camada 2 (veja Camadas de auditoria) ou uma pergunta que é genuinamente arquitetural. Nada mais.

Se um resultado de TIER_WORKER retornar errado, o primeiro suspeito é o brief, não o modelo. Corrija o brief antes de recorrer a um modelo maior.

O Padrão é Delegar

O ônus da prova está em fazer você mesmo. Antes de ler um arquivo, executar uma pesquisa ou escrever uma função, a pergunta não é "devo delegar isso?" — é "por que eu não delegaria?" Se você não tem resposta em uma frase, delegue.

Isso inclui as coisas pequenas, que é onde a regra geralmente é quebrada:

Você está prestes a…	Delegue como…
Ler três ou mais arquivos para entender como algo funciona	Um brief de consulta: "Como funciona o X? Cite arquivo:linha."
Grep por chamadores, usos, definições	Um brief de consulta com os símbolos exatos
Ler um documento longo, log, PR ou transcrição para resumir	Um brief de subagente: "Resuma para este propósito; retorne estes campos."
Verificar se algo existe ou já foi implementado	Um brief de consulta com um contrato de resposta sim/não
Pesquisar como uma biblioteca ou API funciona	Um brief de pesquisa com a pergunta exata e versão
Comparar duas ou três abordagens ou bibliotecas	Um brief de pesquisa com os critérios e a decisão que você precisa tomar
Escrever qualquer função, componente, migração ou teste cuja forma está clara	Um brief de implementação
Executar o conjunto de testes, a build, o linter e ler a saída	Um brief de verificação: execute estes, relate falhas com arquivo:linha
Refatorar muitos arquivos mecanicamente	Um brief de refatoração com um exemplo trabalhado e a regra

A razão não é apenas o custo. Cada arquivo que você lê mesmo fica no seu contexto pelo resto da sessão. Um subagente o lê, extrai a resposta e o despejo do arquivo morre com ele. Seu contexto é para julgamento; o deles é para material.

As Exceções Estreitas

Faça você mesmo apenas quando uma destas for literalmente verdade:

A saída não precisa de interpretação. O teste não é quantos comandos — é o que você faz com o resultado. ls para ver se um caminho existe, cat package.json | grep version, git status: a resposta é consumida como está. Mas se você precisar ler a saída e pensar sobre ela — o conteúdo de um arquivo, uma falha de teste, um grep com vinte resultados — essa leitura é o trabalho, e vai para um subagente.
A tarefa precisa da conversa e não pode ser resumida em um parágrafo. Raro — se você pode explicar para o usuário, pode explicar para um subagente.
A tarefa é o próprio julgamento. Arquitetura, resolução de ambiguidades, tradeoffs, qualquer coisa onde o usuário possa precisar ser perguntado. Subagentes não podem falar com o usuário.
Você não conseguiria verificar o resultado. Se você não pode verificar, não pode delegar.

"O brief levaria tanto tempo quanto o trabalho" não está nesta lista por si só. Escrever o brief é o trabalho — é a parte que precisa de você. Se o brief é curto porque a tarefa é simples, não custa nada; se é longo porque a tarefa tem armadilhas, valeu a pena escrevê-lo.

A Divisão

Você mantém	Você delega
Entender a solicitação e suas restrições não ditas	Ler o codebase para mapear o que existe
Decompor em unidades com limites claros	Pesquisa na web contra uma pergunta precisa
Toda decisão que requer ver o todo	Escrever código contra uma especificação precisa
Escrever os briefs	Executar testes e builds, relatar resultados
Ler os resultados criticamente	Transformações mecânicas em muitos arquivos
Integração, tradeoffs, falar com o usuário	Produzir o primeiro rascunho de qualquer coisa com uma forma clara

A linha é julgamento vs execução. Se um passo requer decidir, mantenha-o. Se requer fazer o que foi decidido, entregue-o.

O Brief

Esta é toda a skill. Um brief não é uma descrição de tarefa; é uma transcrição do seu pensamento, escrita para que alguém com menos dele possa executar. O teste: se um contratante competente que nunca viu este repositório recebesse apenas este documento, ele produziria o que você teria produzido?

Template

## Objetivo
<Um parágrafo. O quê e — criticamente — POR QUÊ. O porquê é o que permite
que o subagente tome as pequenas decisões que você não antecipou da maneira que você teria.>

## Contexto que você não tem
<Tudo da conversa ou do seu conhecimento que o subagente precisa
e não consegue descobrir sozinho. Stack, convenções, onde as coisas
estão, o que já foi tentado, o que o usuário se importa.>

## Decisões já tomadas — não revisite
<Os diferenciadores. Cada escolha que você já fez, com a razão.
Qual biblioteca. Qual padrão. Qual helper existente reutilizar. Qual
abordagem NÃO tomar e por quê. Nomes específicos, caminhos específicos, valores específicos.
É aqui que seu julgamento é transferido.>

## Escopo
DENTRO:  <exatamente o que produzir>
FORA: <o que parece adjacente mas não é esta tarefa — nomeie para que não se desviem>
NÃO TOCAR: <arquivos ou áreas que são proibidas>

## Espelhe isto
<Um caminho para código existente que faz algo estruturalmente similar.
"Olhe para X, faça assim" transfere convenção mais rápido do que descrevê-la.>

## Armadilhas
<As coisas que você sabe que darão errado. A API cujo padrão está errado.
A configuração de teste que deve ser estendida, não substituída. O export que deve
manter seu nome. Cada pegadinha que você pegaria e eles não.>

## Aceitação — vou verificar estes
<Concreto, executável, binário. Comandos e saída esperada. Não "funciona".>

## Retorno
<Forma exata do que enviar de volta: arquivos tocados com uma linha cada,
o diff do arquivo crítico, decisões que tiveram que tomar e que você não
cobriu, sinalizadas claramente. E: condições de PARADA — quando reportar em vez
de adivinhar.

Sempre peça mais duas coisas, pelo nome — veja "O que eles viram e não
mexeram" abaixo:
  1. O que eles notaram e deliberadamente NÃO tocaram porque a cerca de escopo
     dizia isso, com arquivo:linha. Problemas reais, não desorganização.
  2. Se a mudança deles cria um novo problema em código que foi instruído a
     não tocar. O raio de explosão da correção, não apenas a correção.>

A forma curta — para consultas, pesquisas e resumos

O template completo é para implementação. Um brief de pesquisa ou exploração precisa de quatro coisas e pode ter cinco linhas:

PERGUNTA: <uma pergunta precisa — não um tópico, uma pergunta com uma resposta>
ONDE:    <caminhos, pacotes, URLs, ou "todo o repositório" — limite a pesquisa>
CONTEXTO: <o um ou dois fatos que mudam a aparência de uma boa resposta>
RETORNO:   <a forma: sim/não + evidência · lista com arquivo:linha · tabela com estas colunas · resumo <=200 palavras para este propósito>
TAMBÉM:     <"qualquer coisa quebrada que você encontrar pelo caminho, mesmo que eu não tenha perguntado" — opcional, mas é de
           graça: eles já estão lendo aquele código, e a descoberta morre com o contexto deles caso contrário>
PARE SE:  <a condição sob a qual eles devem reportar em vez de investigar mais>

Exemplos:

PERGUNTA: Onde o session userId é lido, e algo o armazena em cache?
ONDE:    src/server/**, src/app/api/**
CONTEXTO:  Preciso chavear um rate limiter nele; um id de cache desatualizado seria um bug.
RETORNO:   Cada local de leitura como arquivo:linha, mais sim/não sobre cache com a evidência.
PARE SE:  Há mais de uma implementação de sessão — me diga, não escolha uma.

PERGUNTA: O que este postmortem de incidente conclui, e o que ele deixou em aberto?
ONDE:    docs/incidents/2026-08-12.md
CONTEXTO:  Estou prestes a adicionar rate limiting e quero saber se essa foi a correção recomendada ou algo mais foi.
RETORNO:   <=150 palavras: causa raiz, correção recomendada, perguntas em aberto. Cite a recomendação textualmente.
PARE SE:  O documento referencia outro documento para a recomendação — me dê o caminho, não resuma um resumo.

A linha de RETORNO é a que as pessoas pulam, e é a que torna o resultado utilizável sem uma segunda viagem de ida e volta. Diga a forma.

A lista de verificação de diferenciadores

Antes de enviar, percorra esta lista. Cada item é algo que um modelo forte faz por reflexo e um mais fraco faz apenas quando instruído:

Cenários de exemplo

Pesquisa: descobrir como uma parte da base de código funciona

PERGUNTA: Qual é o fluxo de dados de quando um usuário faz upload de uma imagem até ela aparecer em `ui/ImageCard`?
ONDE:    src/server/image-upload/, src/server/storage/, src/app/images/, ui/ImageCard.tsx
CONTEXTO:  Estou adicionando upload em lote. Preciso saber se há alguma transformação pós-upload que eu precise também em lote.
RETORNO:   <=200 palavras listando cada etapa com arquivo:linha, mais os nomes de qualquer transformação pós-upload.
PARE SE:  O fluxo é mais longo que 8 saltos — me dê um diagrama, não uma lista.

Implementação: escrever uma nova funcionalidade

## Objetivo
Adicionar um campo `isAnonymous` ao modelo de usuário que, quando verdadeiro, oculta o avatar e o nome do usuário em todos os endpoints da API pública. Precisamos disto para usuários de suporte que devem ser visíveis como tendo resolvido tickets, mas não identificáveis.

## Contexto que você não tem
- O modelo de usuário está em `src/server/db/models/User.ts` (Prisma)
- A API pública fica em `src/server/api/v1/` — as rotas de usuário estão em `users.ts`
- O avatar é servido através de `src/server/middleware/avatar.ts` que injeta um objeto `user` no request
- O middleware já verifica `user.role`; adicione a verificação de `isAnonymous` lá
- Já temos um enum `Role` em `src/server/db/enums.ts` — não crie outro

## Decisões já tomadas — não revisite
- Usar a coluna `isAnonymous` booleana, padrão `false` — não enum, não string
- A migração de banco de dados deve ser uma nova migração, não edite a existente
- NÃO esconda o nome de usuário do sistema de login — apenas de endpoints de API pública

## Escopo
DENTRO:  Migração Prisma, alteração de modelo, alteração de middleware de avatar (ocultar avatar + nome se for anônimo), alterar rota GET /users/:id para ocultar nome e avatar
FORA:  UI, páginas de administração, alterações de permissão, esconder de webhooks internos
NÃO TOCAR:  auth.ts, middleware de autenticação, qualquer rota que não seja pública

## Espelhe isto
Olhe como `user.deletedAt` é verificado em `avatar.ts` e `users.ts` — faça igual, mas para `isAnonymous`.

## Armadilhas
- O middleware de avatar agora envia `avatarUrl: null` para usuários deletados — NÃO sobrescreva isso, combine as verificações: deletado OU anônimo -> sem avatar
- O campo `name` na API pública deve retornar string vazia para anônimos, não `null` — o frontend usa `name.length` para mostrar/ocultar o nome
- A migração deve adicionar um índice em `isAnonymous` — usaremos para consultas de admin depois

## Aceitação — vou verificar estes
- `curl -H "Authorization: Bearer $TOKEN" $API_URL/users/$(some_anonymous_user_id) | jq '.name'` → `""`
- `curl ... $API_URL/users/$(some_normal_user_id) | jq '.name'` → nome real
- `npx prisma migrate dev --name add_is_anonymous` executa sem erros
- Testes existentes de `users.ts` e `avatar.ts` passam

## Retorno
- O diff de cada arquivo tocado
- A migração SQL gerada (arquivo em `prisma/migrations/`)
- O comando `npm test -- --grep avatar` (ou similar) passando
- Quaisquer dependências que você tocou que eu não listei

O que um subagente bem instruído faz melhor

Um modelo TIER_JUDGMENT com 100.000 tokens de contexto custa ~$3.00. Um modelo TIER_WORKER com 20.000 tokens custa ~$0.30. A economia de tokens é a menor das vantagens.

Contexto fragmentado. Um subagente lê arquivos, extrai a resposta e morre. A sessão principal nunca carrega os 12 arquivos que ele leu. Isso é 12 arquivos a menos competindo por espaço com a sua compreensão do problema.
Paralelismo. Você pode lançar dois subagentes contra duas funções, duas pesquisas, duas verificações, ao mesmo tempo. Um modelo serial pode estar em um lugar de cada vez.
Foco. Um subagente com "Verifique se a função X existe e me dê a assinatura" não se distrai com o bug que encontrou no arquivo Y. Ele não pode se distrair — o brief o prende.
Verificação. Você pode enviar um subagente para executar os testes e reportar. A saída deles é estruturada, não anedótica.

Cada uma dessas vantagens é maior que o custo do token.

Perguntas frequentes

E se o subagente não tiver ferramentas? (por exemplo, um modelo de API sem acesso a arquivos) — Você ainda pode escrever um brief que pergunta "Leia o arquivo X e resuma" porque, em plataformas como ChatGPT/Codex, o subagente pode ser uma instância que tem ferramentas. Se não tiver, o brief se torna uma pesquisa na web ou um pedido de código que você mesmo cola. A classificação de camada se aplica na chamada; você decide.

E se o subagente falhar? — Você perdeu o custo de uma chamada de API. Você não perdeu o contexto da sessão principal. A falha é barata. Re-escreva o brief com o que você aprendeu.

Isto não adiciona complexidade? — O template de brief é a complexidade. É intencional. Cada seção do template captura um tipo de coisa que um modelo mais fraco não pensaria. Pule seções quando o risco for baixo; use todas quando as armadilhas forem reais. Mas o hábito de escrevê-las é o que torna o padrão eficaz.

A Terra Prometida

Quando você faz isso consistentemente:

Sua sessão dura o dia todo porque você não está entupindo o contexto com despejos de arquivos que poderia ter delegado.
Você pode paralelizar pesquisa, implementação e verificação.
Você não hesita em lançar um subagente para testar uma hipótese — é barato o suficiente para ser exploratório.
O modelo caro faz o que só ele pode fazer.

cgandini/agentic-skills (Habilidades de Agentes)

O que é agentic-skills (Habilidades de Agentes)?

Perguntar na sua IA favorita

Documentação