Os Dynamic Workflows do Claude Code Chegam em Research Preview

Overview

Ontem eu publiquei um post sobre Por Dentro da Ferramenta de Workflow Determinística e Oculta do Claude Code. A feature foi lançada cerca de 12 horas depois, em research preview. As coisas estão andando rápido e me deixando ocupado, então aqui vai uma versão atualizada.

Uma observação sobre o nome: eu antes chamava isso de “Workflow Determinística”, enquanto a Anthropic está chamando de “Dynamic Workflows”. É tudo uma questão de perspectiva. Da minha, o workflow é determinístico no sentido de que o fluxo é envolvido em código JS em vez de ser gerado pelo LLM. De qualquer forma, de agora em diante vou chamar de Dynamic Workflows para evitar confusão.

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.

Os Dynamic Workflows foram lançados em research preview no Claude Code 2.1.154 (estou usando o 2.1.156 para este post), e agora estão oficialmente documentados em code.claude.com/docs/en/workflows. O build já vem com seis Dynamic Workflows, embora apenas o deep-research apareça em uma sessão local normal; os outros cinco ficam atrás de um gate interno de execução remota (mais sobre isso abaixo). Este post percorre o que esses seis workflows fazem e como escrever o seu próprio.

Habilitando os Workflows

Os Workflows vêm ligados por padrão nos planos pagos, então na maioria das contas basta atualizar para um build atual e o /workflows já está lá. Contas Pro ativam isso em /config, e você pode desativar em todo lugar com CLAUDE_CODE_DISABLE_WORKFLOWS=1. A antiga flag de preview CLAUDE_CODE_WORKFLOWS não existe mais.

Detalhe de implementação: Em uma sessão local normal só o deep-research aparece, e é o único workflow embutido que a Anthropic documenta. Os outros cinco (autopilot, bugfix, dashboard, docs, investigate) se registram apenas quando CLAUDE_CODE_REMOTE está definido, que é um sinal interno de execução remota, e não uma configuração de usuário. Eles abrem PRs e esperam um ambiente remoto capaz de abrir PRs, então virar a variável localmente não vai te entregar um /autopilot funcional. Os seus próprios workflows em .claude/workflows/ não são afetados por esse gate.

A própria tool Workflow fica dormente até você optar por orquestração multi-agent para uma tarefa específica, já que uma execução pode se distribuir por vários agents e queimar muitos tokens. Fora isso, ela deixa a tool em paz, então o uso do dia a dia não é afetado até você de fato querer um workflow. Os gatilhos exatos de opt-in estão na próxima seção.

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ê inclui a palavra “workflow”, liga o Ultracode, 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() sem argumentos são indisponíveis dentro de um script e lançam exceção se chamados, então os resumes conseguem reproduzir resultados de agent() em cache byte a byte. (O loader também faz parse da AST de cada script e exige que export const meta = { … } seja a primeira instrução.)

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.js
• Nível de usuário: ~/.claude/workflows/branch-summary.js

O scanner é um glob *.js plano, sem subdiretórios. Reinicie o Claude Code; o workflow se registra sob o seu meta.name (não o nome do arquivo), então este é invocável como /branch-summary ou Workflow({ name: '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.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 autopilot, deep-research)
// 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 seis workflows prontos para uso. Cinco deles (autopilot, bugfix, dashboard, docs e investigate) se registram apenas quando CLAUDE_CODE_REMOTE está definido. Apenas o deep-research se registra incondicionalmente. A divisão não é estritamente sobre quem abre um PR: o investigate produz um relatório e mesmo assim fica atrás do gate de execução remota, enquanto o deep-research, também um relatório, é o único workflow que está sempre disponível.

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.

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.

O padrão se repete nos seis: distribuir, verificar de forma adversarial, sintetizar. Os estágios de verificação tipicamente usam de 3 a 5 votos. A fase Review do autopilot adiciona o “pigeonhole de saída antecipada”: com uma verificação de 5 votos, se dois votantes refutam um achado os três restantes são pulados, porque nenhuma maioria é possível. O deep-research empurra a verificação até o nível de afirmações individuais: cada afirmação extraída recebe sozinha uma passada de refutação de 3 votos antes de entrar no relatório final.

Conclusão

Embutir uma engine de workflow dinâmica 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.

Agora que foi lançado, mesmo em preview, estou ansioso para ver o que as pessoas vão construir com isso. 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.