Por Dentro da Ferramenta de Workflow Determinística e Oculta do Claude Code

Atualização: as coisas mudam rápido por aqui :) Desde que isto foi escrito, surgiu um post mais novo que o substitui: Os Dynamic Workflows do Claude Code Chegam em Research Preview. Vá até lá para o passo a passo atual. Esta página continua no ar para fins de registro.

Overview

Boa parte do que você pede para o Claude Code fazer segue o mesmo formato: levantar requisitos, rascunhar um plano, escrever o código, rodar os testes, fazer uma rodada de validação, abrir o PR. Os passos não mudam muito de uma tarefa para outra; a ordem é determinística mesmo quando o trabalho dentro de cada passo não é.

Você pode pedir para uma Skill cuidar desse fluxo, mas uma Skill é um prompt: ela consegue descrever os passos, não forçá-los. Quando você quer ordenação estrita ou branching, acaba colando Skills umas nas outras com hooks. Funciona, mas fica frágil rápido.

É essa a lacuna que um Workflow nativo preenche. Um Workflow no Claude Code é um pequeno arquivo .js que define o próprio fluxo (quando distribuir agents em paralelo, quando travar em um resultado, quando avançar para a próxima fase), enquanto o LLM cuida do trabalho de cada agent dentro dos passos que o script decide.

Essa feature foi introduzida silenciosamente no Claude Code 2.1.147. Não foi divulgada e não está documentada, mas já vem hoje com dez workflows embutidos. Este post percorre o que esses dez workflows fazem e como escrever o seu próprio.

Habilitando a Feature Oculta de Workflows

Eu testei isso no Claude Code 2.1.150 e 2.1.152.

Na data de publicação deste post (28 de maio de 2026), a feature de Workflows não está oficialmente lançada no Claude Code. Ela vem no binário, mas permanece atrás de um feature gate, sem anúncio ou documentação da Anthropic. Tudo abaixo é o que funciona hoje; espere que os detalhes mudem quando ela for lançada de verdade.

Para habilitar, defina CLAUDE_CODE_WORKFLOWS=1 no seu ambiente e reinicie o Claude Code. Então o /workflows fica disponível. Também existe um feature gate no lado do servidor (tengu_workflows_enabled) que a Anthropic controla por conta, então na maioria das contas a variável de ambiente sozinha ainda não vai fazer o slash command aparecer; se for o seu caso, o resto do post continua valendo assim que a flag for ligada.

Uma pegadinha extra se você tem uma assinatura do Claude: quando o Claude Code inicia, o $HOME/.claude.json pode ser reescrito com tengu_workflows_enabled definido como false. A solução mais simples é iniciar o Claude Code com:

CLAUDE_CODE_WORKFLOWS=1 DISABLE_GROWTHBOOK=1 claude

Isso ignora completamente o cliente de feature-flag GrowthBook. O Claude Code volta para os defaults definidos no código em vez de ler as flags do .claude.json, e o default de tengu_workflows_enabled é true. A flag fica ligada durante todo o tempo de vida daquele processo, sem precisar editar nenhum arquivo.

A Ferramenta Workflow

Workflow é a tool invocável pelo modelo que roda um script de workflow. Ela é controlada por opt-in explícito do usuário (o modelo só a chama quando você diz “ultrawork”, invoca um slash command de workflow, ou pede diretamente por orquestração multi-agent) e roda em background: a tool retorna um task ID imediatamente, e depois uma notificação dispara quando o script termina.

Schema de entrada:

O runtime impõe determinismo (Date.now, Math.random e new Date() são bloqueados tanto por uma verificação estática de regex quanto por stubs em runtime), então os resumes conseguem reproduzir resultados de agent() em cache byte a byte.

A API do Script

O script roda em um contexto separado com apenas estes globals disponíveis:

agent

agent(prompt: string, opts?: {
  label?: string,
  phase?: string,
  schema?: object,          // JSON Schema -> forces StructuredOutput tool call
  model?: string,           // haiku | sonnet | opus | full ID
  isolation?: 'worktree',   // fresh git worktree per agent
  agentType?: string,       // 'Explore', 'code-reviewer', etc.
}): Promise<any>

Cria um subagent. Retorna texto por padrão, um objeto validado quando schema é definido, ou null se o usuário pular o agent no meio da execução.

parallel

parallel(thunks: Array<() => Promise<any>>): Promise<any[]>

Roda os thunks concorrentemente e aguarda todos eles. Um thunk que lança exceção resolve para null no array de resultado; a própria chamada nunca é rejeitada.

pipeline

pipeline(items, stage1, stage2, ...): Promise<any[]>

Roda cada item por todos os stages de forma independente, sem barreira entre os stages: o item A pode estar no stage 3 enquanto o item B ainda está no stage 1. Cada stage recebe (prevResult, originalItem, index).

Padrão canônico:

export const meta = {
  name: 'review-changes',
  description: 'Review changed files across dimensions, verify each finding',
  phases: [{ title: 'Review' }, { title: 'Verify' }],
}

const DIMENSIONS = [{key: 'bugs', prompt: '...'}, {key: 'perf', prompt: '...'}]

const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, {label: `review:${d.key}`, phase: 'Review', schema: FINDINGS_SCHEMA}),
  review => parallel(review.findings.map(f => () =>
    agent(`Adversarially verify: ${f.title}`, {label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT_SCHEMA})
      .then(v => ({...f, verdict: v}))
  ))
)
const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
return { confirmed }
// Dimension 'bugs' findings verify while dimension 'perf' is still reviewing.

phase, log, workflow, args, budget

• phase(title): agrupa as chamadas agent() seguintes sob um título no display de progresso.
• log(message): emite uma linha de progresso acima da árvore de agents na TUI do /workflows.
• workflow(nameOrRef, args?): chama outro workflow inline como um sub-passo; apenas um nível de aninhamento.
• args: o valor passado como input args do Workflow.
• budget: teto rígido de tokens atrelado a uma diretiva do usuário no estilo +500k:

budget: {
  total: number | null,
  spent(): number,
  remaining(): number,
}

Padrão loop-until-budget:

const bugs = []
while (budget.total && budget.remaining() > 50_000) {
  const result = await agent("Find bugs in this codebase.", {schema: BUGS_SCHEMA})
  bugs.push(...result.bugs)
  log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k remaining`)
}

Defina o Seu Próprio Workflow

Para deixar isso concreto, aqui está o branch-summary, um workflow minúsculo que lê o diff da branch atual e produz um resumo polido de um parágrafo mais uma headline no formato de título de PR. Três fases, uma escada linear de agent().

Coloque o arquivo em um destes locais:

• Nível de projeto: .claude/workflows/branch-summary.workflow.js
• Nível de usuário: ~/.claude/workflows/branch-summary.workflow.js

O scanner é um glob *.js plano, sem subdiretórios. Reinicie o Claude Code; o nome do arquivo menos a extensão vira o slash command, então este registra como /branch-summary.

Os workflows rodam em background. Para acompanhar uma execução, digite /workflows, que abre uma TUI listando cada fase. Entre em uma fase para ver os detalhes de execução por agent.

// branch-summary — the smallest useful 3-phase workflow.
//
// Drop in `.claude/workflows/branch-summary.workflow.js` and run via
// `Workflow({ name: 'branch-summary' })`. Reads the current branch diff and
// produces a polished one-paragraph summary plus a headline.
//
// Uses only the three primitives a linear workflow needs: phase(), agent(),
// log(). No parallel, no pipeline. No external MCP or GitHub CLI — the diff
// step uses git via Bash, which the workflow-subagent already has.

export const meta = {
  name: 'branch-summary',
  description: 'Linear 3-phase summary of the current branch: diff, summarize, polish. Returns a headline and a 3-5 sentence paragraph.',
  whenToUse: 'When the user wants a quick written summary of what changed on the current branch — for PR descriptions, stand-ups, or sharing with a teammate. Produces a report, not a PR.',
  phases: [
    { title: 'Diff', detail: 'Find the diff base, list changed files, capture a rough summary from commit messages' },
    { title: 'Summarize', detail: 'Read the changed files and turn the rough summary into a focused paragraph' },
    { title: 'Polish', detail: 'Tighten the paragraph and add a one-line headline' },
  ],
}

// ═══ Schemas ═══
// Kept deliberately light. Production-shaped workflows (see bughunt, autopilot)
// validate far more — for a demo, two object shapes is enough.
const DIFF_SCHEMA = {
  type: 'object',
  required: ['diffBase', 'files', 'rawSummary'],
  properties: {
    diffBase: { type: 'string', description: 'Branch this was diffed against, e.g. origin/main' },
    files: { type: 'array', items: { type: 'string' } },
    rawSummary: { type: 'string', description: 'One paragraph drawn from commit messages and the stat output' },
  },
}

const RESULT_SCHEMA = {
  type: 'object',
  required: ['summary'],
  properties: {
    headline: { type: 'string', description: 'One short line, sentence-case, suitable as a PR title' },
    summary: { type: 'string', description: '3-5 sentence paragraph for a teammate skim-reading the PR' },
  },
}

// ═══ Phase 1: Diff ═══
phase('Diff')
const diff = await agent(
  "Discover the scope of changes on the current branch.\n\n" +
  "1. Diff base: run `git merge-base HEAD origin/main`. If origin/main does not exist, try `main`. Return whichever resolves.\n" +
  "2. Changed files: `git diff --name-only <diffBase>...HEAD`\n" +
  "3. Rough summary: skim `git log --oneline <diffBase>...HEAD` and `git diff --stat <diffBase>...HEAD`. Write one paragraph capturing the gist from the commit messages.\n" +
  "Structured output only.",
  { label: 'diff', schema: DIFF_SCHEMA }
)
if (!diff) return { error: 'Diff step skipped.' }
if (diff.files.length === 0) {
  return { summary: `No changes on this branch vs ${diff.diffBase}.`, diffBase: diff.diffBase, filesChanged: 0 }
}
log(`${diff.files.length} files changed vs ${diff.diffBase}`)

// ═══ Phase 2: Summarize ═══
phase('Summarize')
const summary = await agent(
  "Read the changed files and turn the rough summary into a focused paragraph for a teammate skim-reading the PR.\n\n" +
  `Diff base: ${diff.diffBase}\n` +
  `Files (${diff.files.length}): ${diff.files.join(', ')}\n` +
  `Rough summary: ${diff.rawSummary}\n\n` +
  "Cover: what changed, why (if clear from commits), risk areas worth a second look. 3-5 sentences. Use concrete file paths and function names — no vague language like 'updates' or 'improvements'.",
  { label: 'summarize', schema: RESULT_SCHEMA }
)
if (!summary) return { error: 'Summarize step skipped.', diff }

// ═══ Phase 3: Polish ═══
phase('Polish')
const polished = await agent(
  "Tighten this branch summary. Same content, less filler.\n\n" +
  `Summary: ${summary.summary}\n\n` +
  "Drop hedge words ('seems to', 'might'), kill obvious sentences ('This PR changes some files'), keep the file/function names. " +
  "Add a one-line headline (sentence case, no trailing period, under 70 chars) suitable as a PR title.",
  { label: 'polish', schema: RESULT_SCHEMA }
)

return {
  headline: polished?.headline ?? summary.headline ?? null,
  summary: polished?.summary ?? summary.summary,
  diffBase: diff.diffBase,
  filesChanged: diff.files.length,
}

Workflows Embutidos no Claude Code

O Claude Code já vem com dez workflows prontos para uso. Cinco se registram apenas quando CLAUDE_CODE_REMOTE está definido: os que produzem um PR no final e precisam de execução remota. Os outros cinco se registram incondicionalmente e produzem relatórios, não commits.

autopilot

Descrição. Um executor de tarefas de ponta a ponta. Constrói um plano com uma crítica adversarial de 5 ângulos, ajusta o plano, implementa, usa uma revisão bughunt-lite + checagem de completude da feature, corrige os problemas, e então abre um PR.

Quando usar. Quando o usuário dá uma tarefa de código autocontida que quer ver concluída de ponta a ponta sem supervisão. Melhor para tarefas longas que exigem alguma ou grande quantidade de planejamento e verificação. Este workflow delimita o problema, robustece o plano usando 5 críticos, implementa, roda uma varredura de caça a bugs e uma checagem de completude da feature, corrige os problemas, e então abre um PR.

Fases.

• Plan: Escopo + rascunho, 5 críticos (escopo/simplicidade/reuso/verificação/correção), robustecer
• Implement: Um único agent executa o plano robustecido
• Review: 3 finders rápidos + 2 profundos, verificação por 5 votos com pigeonhole, + completude vs tarefa
• Fix: Resolver os problemas confirmados (pulada se estiver limpo)
• PR: Lint, typecheck, abrir PR, inscrever-se no auto-fix

Técnicas. Crítica de plano de 5 ângulos; embute o bughunt-lite para revisão; fase de fix pulada quando está limpo.

Saída. PR com inscrição em auto-fix. Requer CLAUDE_CODE_REMOTE.

bugfix

Descrição. Corretor de bugs que reproduz primeiro. Escreve um repro que falha, encontra a causa raiz da falha, aplica a correção mínima, converte o repro em um teste de regressão, e então abre um PR.

Quando usar. Quando o usuário reporta um bug específico para corrigir. Melhor quando o bug é concreto o suficiente para reproduzir. Este workflow escreve primeiro um repro que falha, rastreia a causa raiz, aplica a menor correção que faz o repro passar, fixa isso como um teste de regressão, e abre um PR.

Fases.

• Reproduce: Escrever um script ou teste que falha e demonstra o bug
• Root-cause: Rastrear a falha, dar grep nos callers, identificar o culpado mínimo
• Fix: O menor diff que faz o repro passar
• Regress: Converter o repro em um teste permanente, rodar a suíte tocada
• PR: Lint, typecheck, abrir PR

Técnicas. Ordenação com repro que falha primeiro; conversão em teste de regressão; viés de diff mínimo.

Saída. PR com novo teste de regressão. Requer CLAUDE_CODE_REMOTE.

dashboard

Descrição. Gerador de dashboard. Descobre fontes de dados e convenções de dashboard já existentes no repo, projeta um layout de painéis, implementa, faz dry-run das queries e checa a renderização do resultado, e então abre um PR.

Quando usar. Quando o usuário quer construir um dashboard, uma view de monitoramento ou uma página de métricas. Este workflow encontra os dados disponíveis e os padrões de dashboard existentes, especifica os painéis e o layout, implementa, valida as queries e a renderização, e abre um PR.

Fases.

• Discover: Fontes de dados, libs/padrões de dashboard existentes no repo
• Design: Painéis, métricas, spec de layout
• Implement: Construir o dashboard
• Verify: Dry-run das queries, render/screenshot se possível
• PR: Abrir PR

Técnicas. Descoberta de convenções antes do design; gate de checagem de renderização antes do PR.

Saída. PR. Requer CLAUDE_CODE_REMOTE.

docs

Descrição. Gerador de documentação. Descobre a superfície da feature e as convenções de documentação existentes, monta um outline para o público-alvo, escreve ou atualiza a documentação, verifica exemplos de código e links, e então abre um PR.

Quando usar. Quando o usuário quer documentação escrita ou atualizada para uma feature, API ou module. Este workflow encontra o código relevante e os padrões de documentação existentes, rascunha um outline, escreve o conteúdo, checa que os exemplos rodam e que os links resolvem, e abre um PR.

Fases.

• Discover: Superfície da feature, documentação existente, convenções de localização
• Outline: Estrutura e público
• Write: Criar ou atualizar os arquivos de documentação
• Verify: Exemplos compilam/rodam, links resolvem, precisão vs código
• PR: Abrir PR

Técnicas. Outline-depois-escrita; roda exemplos e checa links no Verify.

Saída. PR. Requer CLAUDE_CODE_REMOTE.

investigate

Descrição. Investigação de causa raiz. Reúne evidências, gera hipóteses concorrentes em paralelo, refuta cada uma de forma adversarial, e produz um relatório escrito de causa raiz com uma correção sugerida.

Quando usar. Quando o usuário quer encontrar a causa raiz de um incidente, erro, log, trace ou comportamento intrigante, sem necessariamente corrigir. Este workflow coleta evidências, roda agents de hipótese em paralelo, tenta refutar cada hipótese, e escreve a causa raiz sobrevivente com os próximos passos. Ele produz um relatório, não um PR.

Fases.

• Gather: Logs, traces, repro, timeline
• Hypothesize: 3 agents de hipótese em paralelo
• Verify: Um refutador adversarial por hipótese
• Report: Texto da causa raiz, correção sugerida, próximos passos

Técnicas. Geração de hipóteses em paralelo; refutador adversarial por hipótese; o sobrevivente leva tudo.

Saída. Relatório (sem PR). Requer CLAUDE_CODE_REMOTE, agrupado com os workflows de PR mesmo que nunca faça commit.

bughunt

Descrição. Varredura de bugs multi-agent da branch atual. Um pool de finders que se re-spawn (3 rápidos + profundos-até-sequência-seca) flui para uma verificação adversarial de 5 votos com pigeonhole de saída antecipada, e depois síntese.

Quando usar. Quando o usuário pede para caçar bugs, auditar a qualidade do código, ou rodar uma varredura de bugs de alta precisão na branch atual.

Fases.

• Scope: Descobrir a base do diff, arquivos alterados, convenções
• Find: 3 rápidos + profundos-até-sequência-seca(3), pool que se re-spawn
• Verify: Adversarial de 5 votos, pigeonhole de saída antecipada (2 refutam → morto, pula 3)
• Synthesize: Dedup semântica no conjunto confirmado, relatório final

Técnicas. Pool de finders que se re-spawn; término por sequência seca; pigeonhole de saída antecipada; dedup semântica no conjunto confirmado.

Saída. Relatório. Registra-se incondicionalmente.

bughunt-lite

Descrição. Varredura de bugs mais leve: finders fixos (3 rápidos + 2 profundos) fluem para uma verificação adversarial de 5 votos (pigeonhole de saída antecipada) e depois síntese. Mais simples que o bughunt: sem re-spawn, sem sequência seca.

Quando usar. Quando o usuário quer uma varredura de bugs mais rápida e limitada da branch atual. Prefira em vez do bughunt para diffs pequenos a médios em que um pool fixo de finders é suficiente.

Fases.

• Scope: Descobrir a base do diff, arquivos alterados, convenções
• Find: 3 finders rápidos + 2 profundos, fluindo para o verify conforme cada um termina
• Verify: 5 votos adversariais, pigeonhole de saída antecipada (2 refutam → pula 3)
• Synthesize: Dedup semântica no conjunto confirmado, relatório final

Técnicas. Pool fixo de finders (sem respawn); pipeline em streaming para o verify; pigeonhole de saída antecipada.

Saída. Relatório. Registra-se incondicionalmente.

deep-research

Descrição. Harness de pesquisa profunda: distribui buscas na web, busca fontes, verifica afirmações de forma adversarial, sintetiza um relatório com citações.

Quando usar. Quando o usuário quer um relatório de pesquisa profundo, de múltiplas fontes e com checagem de fatos sobre qualquer tópico. ANTES de invocar, verifique se a pergunta é específica o suficiente para pesquisar diretamente; se estiver subespecificada (por exemplo, “qual carro comprar” sem orçamento/caso de uso/região), faça de 2 a 3 perguntas de esclarecimento para estreitar o escopo. Depois passe a pergunta refinada como args, incorporando as respostas.

Fases.

• Scope: Decompor a pergunta (a partir de args) em 5 ângulos de busca
• Search: 5 agents de WebSearch em paralelo, um por ângulo
• Fetch: Dedup de URLs, buscar as 15 melhores fontes, extrair afirmações falsificáveis
• Verify: Verificação adversarial de 3 votos por afirmação (precisa de 2/3 refutações para derrubar)
• Synthesize: Mesclar duplicatas semânticas, ranquear por confiança, citar fontes

Técnicas. Decomposição em múltiplos ângulos; dedup de URLs com limite top-N; verificação adversarial em nível de afirmação; citação ranqueada por confiança.

Saída. Relatório de pesquisa com citações. Registra-se incondicionalmente.

plan-hunter

Descrição. Harness de planejamento exaustivo. Gera 4 rascunhos de plano independentes (MVP-primeiro, risco-primeiro, dependência-primeiro, usuário-primeiro), pontua cada um com 4 juízes em paralelo, escolhe o vencedor por votação, e então sintetiza um plano final polido enxertando as melhores ideias dos vice-colocados.

Quando usar. Quando o usuário tem uma ideia que quer planejar a fundo. ANTES de invocar este workflow, faça de 2 a 3 perguntas de esclarecimento se a ideia estiver subespecificada: (1) escopo/cronograma, (2) restrições rígidas ou não-objetivos, (3) critérios de sucesso. Depois passe a ideia esclarecida como a string args.

Fases.

• Scope: Entender a ideia, extrair restrições, anotar premissas
• Draft: 4 planejadores em paralelo: lentes MVP / Risco / Dependência / Usuário
• Judge: 4 juízes em paralelo ranqueiam os 4 rascunhos
• Synthesize: Polir o vencedor, enxertar as melhores ideias dos vice-colocados

Técnicas. Rascunho em paralelo com 4 lentes; votação de 4 juízes; síntese de vencedor-mais-enxerto.

Saída. Plano polido (relatório). Registra-se incondicionalmente.

review-branch

Descrição. Revisa a fundo a branch atual em busca de bugs, simplicidade, arquitetura, código morto, boas práticas e consistência de padrões. Cada achado é verificado de forma adversarial antes de ser reportado.

Quando usar. Quando o usuário pede para revisar a branch, fazer um code review das mudanças recentes, ou auditar a qualidade de um PR antes de shipar.

Fases.

• Scope: Descobrir a base do diff, arquivos alterados, convenções
• Review: Seis revisores de dimensão em paralelo
• Verify: Verificação adversarial de cada achado
• Report: Dedup, ranquear e resumir

Técnicas. Revisão em paralelo de seis dimensões (bugs / simplicidade / arquitetura / código morto / boas práticas / consistência); verificação adversarial por achado.

Saída. Relatório. Registra-se incondicionalmente.

O padrão se repete: distribuir, verificar de forma adversarial, sintetizar. Os estágios de verificação tipicamente usam de 3 a 5 votos; bughunt e bughunt-lite adicionam o “pigeonhole de saída antecipada”: se dois de cinco votantes refutam um achado, os três restantes são pulados porque nenhuma maioria é mais possível. O workflow plan-hunter é o mais distinto: 4 planejadores independentes (MVP-primeiro, risco-primeiro, dependência-primeiro, usuário-primeiro), 4 juízes em paralelo ranqueando os 4 rascunhos, e então um sintetizador que pole o vencedor e enxerta as melhores ideias dos vice-colocados.

Conclusão

Embutir uma engine de workflow determinística diretamente no Claude Code é um movimento interessante da Anthropic. Isso empurra a camada de orquestração para fora do modelo e para dentro de código que você pode ler, versionar e raciocinar sobre, que é exatamente o lugar certo para “o que distribui, o que verifica, o que sintetiza” morar.

Eu avaliei alguns dos workflows embutidos. Eles dão conta do recado. O ponto de atenção é o consumo de tokens: o padrão de harness é a razão de existir dos workflows, mas algumas das implementações atuais são agressivas o suficiente para se beneficiarem de um ajuste ou de dar ao usuário final um controle. Uma execução simples de /deep-research que eu testei queimou quase 12 milhões de tokens, a maior parte na fase de verificação adversarial, onde cada afirmação extraída recebe sozinha uma passada de refutação de 3 votos.

Estou ansioso pelo lançamento oficial e, mais do que isso, para ver o que as pessoas vão construir com isso assim que o gate for ligado para todos. Também espero que os workflows acabem podendo ser empacotados como parte dos plugins do Claude, para que um harness bem feito possa ser distribuído e instalado com a mesma facilidade que uma skill é hoje.