lingyu9495-source/subagent-first

Subagente Primeiro · Agente Principal Não Entra em Campo

A atenção do agente principal pertence ao usuário, não à tarefa. Todas as tarefas que exigem várias rodadas devem ser delegadas a subagentes em segundo plano; o agente principal apenas divide, delega, verifica e consolida, mantendo sempre a capacidade de responder ao usuário.

Muitos agentes são usados de forma estranha, não porque o modelo não é forte o suficiente, mas porque o agente principal está sobrecarregado com trabalho pesado: o usuário envia uma mensagem, o agente principal mergulha em vinte rodadas de chamadas de ferramentas, sem poder responder ou mudar de direção, e o usuário só pode esperar. Quando ele finalmente termina, os requisitos podem ter mudado.

Esta skill fornece um conjunto de regras operacionais — transformando "quando delegar, como delegar, como verificar" em regras decidíveis, não em intuição. A disciplina é independente de plataforma: qualquer agente de IA que suporte subagentes / tarefas em segundo plano (Claude Code, Codex, Cursor, WorkBuddy, Hermes e outras ferramentas similares) se aplica, a diferença está apenas nos nomes das ferramentas — o mapeamento está na seção "Tabela de Correspondência de Nomes de Ferramentas" deste documento.

Diferenças práticas ao implementar em plataformas específicas: Os nomes dos campos, limites de concorrência, semântica de segundo plano e métricas de custo do Hermes estão organizados em references/hermes-runtime-reality.md (exemplo de implementação, outras plataformas podem ignorar). O texto principal trata apenas da disciplina, não depende dessa página.

---

Condições de Gatilho

Quando qualquer uma das seguintes situações ocorrer, você deve seguir esta skill (em vez de fazer você mesmo):

1. A tarefa é prevista para exigir mais de 2–3 rodadas de chamadas de ferramentas: por exemplo, "ler 8 arquivos e resumir" ou "executar uma rodada de pesquisa e organizar".
2. Uma vez precisa processar múltiplas unidades independentes: múltiplos arquivos, múltiplos diretórios, múltiplos URLs, múltiplos conjuntos de dados, múltiplos candidatos.
3. Pesquisa longa / busca longa: que requer repetidas buscas, capturas, comparações, demorando minutos.
4. Processamento em lote: executar o mesmo conjunto de operações em um lote de entradas (limpeza, transformação, verificação linha por linha, geração linha por linha).
5. O usuário explicitamente pede paralelismo ou "fazer várias coisas ao mesmo tempo".
6. O agente principal está no meio de uma conversa com o usuário: o usuário pode perguntar, mudar de ideia ou inserir uma nova tarefa a qualquer momento.
7. As subtarefas são independentes e podem ser iniciadas simultaneamente: típico como "revisar três documentos separadamente e depois consolidar as conclusões".
8. O trabalho pesado está rodando em segundo plano enquanto o usuário quer continuar conversando sobre outra coisa (este é o principal cenário de benefício desta skill).

Condição para não acionar: Se uma tarefa pode ser concluída com uma única chamada de ferramenta e o usuário não vai falar mais com você depois de enviá-la — faça você mesmo. Forçar a delegação só será mais lento. O critério de decisão está na próxima seção.

---

Princípios Fundamentais

1. O agente principal não entra em campo para trabalho pesado. O agente principal faz apenas quatro coisas: dividir → delegar → consolidar → conversar com o usuário. Deve manter o estado de "pronto para responder a qualquer momento".
2. Trabalho pesado deve ser delegado a subagentes (obrigatório). Se as condições de gatilho acima forem atendidas, delegue. "Acho que sou rápido e farei" não é justificativa. O critério de decisão são as propriedades da tarefa, não a confiança do agente principal.
3. Afirmar não é fato. O subagente dizer "concluído" é apenas sua afirmação; qualquer saída não verificada é considerada não concluída (veja a "Lista de Verificação").
4. O contexto deve ser autocontido. O subagente não vê o histórico da sua conversa com o usuário. O que está na sua mente, ele não recebe. Se a ordem de serviço estiver incompleta, ele certamente se desviará — não é culpa dele, é culpa sua.
5. O paralelismo tem limites. Paralelize apenas tarefas sem dependências; tarefas com dependências de sequência devem ser seriais, ou a saída upstream deve ser alimentada para downstream.
6. Tarefas que exigem aprovação do usuário não são delegadas. Tarefas que exigem confirmação do usuário, consequências irreversíveis ou supervisão imediata devem permanecer nas mãos do agente principal.
7. Tarefas longas entre sessões usam mecanismos diferentes. Tarefas que precisam sobreviver à sessão atual (monitoramento contínuo, gatilhos temporizados, processos residentes) devem usar o mecanismo de temporização / residente da sua plataforma (tarefas agendadas, tarefas programadas, processos em segundo plano), não subagentes — o ciclo de vida de um subagente está vinculado a uma única delegação.
8. Falha deve ser rebaixada, não inventada. Subagente falhou, expirou ou produziu saída insatisfatória: rebaixe e faça você mesmo, ou mude o caminho e delegue novamente. Nunca escreva "resultado obtido" para um "resultado não obtido".

Esses princípios correspondem ao paradigma fork-join / fan-out-fan-in conhecido na engenharia: bifurcar tarefas para múltiplas unidades de execução e depois reunir os resultados (o ForkJoinPool do Java e o MapReduce proposto por Dean e Ghemawat no OSDI 2004 são implementações específicas dessa ideia). Esta skill não inventa novos conceitos, apenas os traduz em regras operacionais executáveis no cenário de agentes.

---

Árvore de Decisão: O Que é Trabalho Pesado, O Que Fazer Sozinho

Responda às seguintes perguntas em ordem. A primeira ramificação com resposta "sim" é a conclusão.

Pergunta 1: Esta tarefa pode ser concluída com uma rodada de chamadas de ferramentas?

Item de Julgamento	Critério
Número de chamadas de ferramentas	Você mesmo pode contar, e ≤ 1 rodada
Precisa ler múltiplos arquivos?	Não (0–1)
Há loops?	Não (não há "para cada...")
Tempo estimado	Segundos

Se todos os quatro itens forem satisfeitos → Faça você mesmo. Qualquer item não satisfeito → vá para a Pergunta 2.

Pergunta 2: Esta tarefa precisa de aprovação do usuário?

• Precisa que o usuário escolha entre várias opções → Faça você mesmo (ou apenas colete informações e apresente as opções).
• Envolve operações irreversíveis (excluir dados, publicar externamente, pagar, enviar mensagens para terceiros) e precisa de supervisão imediata → Faça você mesmo.
• Apenas "precisa que o usuário saiba", sem que ele tome decisões durante o processo → Pode delegar, mas explique claramente na consolidação.

Pergunta 3: Esta tarefa precisa sobreviver à sessão atual?

• Sim (gatilhos temporizados, monitoramento contínuo, serviço residente) → Use o mecanismo de temporização / residente da sua plataforma (tarefas agendadas, tarefas programadas, processos em segundo plano), não subagentes.
• Não, deve ser concluída dentro da sessão atual → Vá para a Pergunta 4.

Pergunta 4: Pode ser dividida em blocos independentes?

• Sim → Delegue para múltiplos subagentes em paralelo, cada um com seus próprios arquivos / diretórios / URLs / conjuntos de dados, e o agente principal combina.
• Não, mas há uma sequência clara → Delegue em série, ou delegue a um único subagente para executar toda a cadeia (ainda é mais leve do que você fazer).
• Não pode ser dividida e não é longa → Volte para a Pergunta 1 para confirmar novamente, provavelmente faça você mesmo.

Tabela de Referência Rápida

Natureza da Tarefa	Tempo Típico	Ação
Verificar um valor, ler uma parte de um arquivo	Segundos	Faça você mesmo
Alterar um texto, executar um comando	Segundos	Faça você mesmo
Ler 3 arquivos e resumir	1–2 minutos	Pode fazer ou delegar; delegue se o usuário estiver esperando
Ler 8 arquivos e fazer resumo de cada um	Alguns minutos	Delegue
Pesquisa em múltiplas fontes + comparação cruzada	Alguns minutos a dezenas de minutos	Delegue (pode dividir em blocos paralelos)
Processamento em lote de N entradas (N ≥ 5)	Cresce com N	Delegue (fatie e paralelize)
Precisa que o usuário escolha entre opções	Variável	Faça você mesmo (colete + apresente opções)
Executar uma vez por dia	Entre sessões	Tarefa agendada (não subagente)

---

Processo de Cinco Etapas

Etapa 1: Dividir

Primeiro, corte a tarefa em unidades com limites claros. Cada unidade deve poder responder independentemente a três perguntas:

• Qual é a entrada: específica para caminho de arquivo, diretório, lista de URLs, nome do conjunto de dados, parâmetros.
• Qual é a saída: específica para nome de arquivo, formato, caminho.
• Como saber se está concluído: critérios decidíveis, não "só terminar".

Ao dividir, siga duas regras:

• Sem conflito de escrita de arquivos: dois subagentes nunca devem escrever no mesmo arquivo. Ou cada um escreve em seu próprio arquivo e o agente principal combina, ou em série.
• Dependências explícitas: se A alimenta B, não pode ser paralelo — deve ser serial, ou um subagente faz A+B.

Critérios de Conclusão (marque cada item)

• Cada unidade tem a entrada claramente escrita (com caminhos / listas específicos)
• Cada unidade tem a saída claramente escrita (nome do arquivo + formato + localização)
• Cada unidade tem critérios de conclusão decidíveis
• Nenhuma unidade escreve no mesmo arquivo que outra
• Todas as dependências estão marcadas (quais devem ser seriais)

Etapa 2: Delegar

Use a ferramenta de subagente / tarefa em segundo plano da sua plataforma para delegar cada unidade (no Hermes é delegate_task, em outras plataformas mapeie conforme a "Tabela de Correspondência de Nomes de Ferramentas"), e escreva a ordem de serviço com os "Quatro Elementos" (veja a próxima seção). Pontos importantes:

• Um subagente assume apenas uma tarefa com limites claros, não coloque três tarefas não relacionadas em uma ordem de serviço.
• Escreva o contexto completo na ordem de serviço — o subagente não vê sua conversa com o usuário.
• Diga claramente onde colocar a saída e o que relatar (caminho do arquivo? número de linhas? saída do comando?).
• Exija explicitamente que ele relate apenas o que pode ser verificado: qual comando foi executado, qual saída foi obtida; se não conseguiu, diga diretamente.
• Se a plataforma suportar relatório estruturado / validação de saída (por exemplo, validar a resposta final do subagente com um JSON Schema) — use estruturado em vez de texto livre.

Critérios de Conclusão

• Cada ordem de serviço tem os quatro elementos completos (objetivo / contexto / estrutura de saída / método de verificação)
• Cada ordem de serviço especifica o caminho da saída
• Cada ordem de serviço exige o relato de evidências verificáveis (comando + saída real)
• A ordem de serviço não contém referências incompletas como "você sabe" ou "como antes"

Etapa 3: Agendamento Paralelo

• Paralelize o que pode ser: delegue unidades independentes de uma só vez, não as coloque em fila.
• Serial para dependências: espere a verificação upstream ser aprovada e depois alimente a saída como contexto para a ordem de serviço downstream.
• O paralelismo deve ter um limite: muitas tarefas concorrentes competem por recursos e aumentam sua carga de consolidação. Três a cinco é um intervalo confortável comum; para mais, considere lotes (os limites variam por plataforma, veja a "Tabela de Correspondência de Nomes de Ferramentas" e a página de realidade da plataforma).
• Após delegar, retorne imediatamente ao usuário: não fique esperando os subagentes. Este é o propósito desta disciplina — quando o usuário está esperando, você deve poder responder.
• Não faça polling, não fique esperando: a chamada de delegação deve retornar imediatamente, o resultado é enviado de volta pela plataforma; durante a espera, o agente principal deve ser capaz de lidar com novas mensagens do usuário. Se sua plataforma bloquear por padrão, coloque a chamada de delegação em modo assíncrono / segundo plano.
• Dê ao usuário um ponto de controle: se a plataforma permitir visualizar subagentes em execução, corrigir um subagente, ou terminar prematuramente e reter resultados parciais, use; se não, degrade para "incluir correções na próxima rodada de ordens de serviço".

Critérios de Conclusão

• Unidades independentes foram delegadas simultaneamente (não uma por uma)
• Unidades com dependências foram delegadas em série na ordem correta, e a downstream recebeu a saída upstream
• O paralelismo está dentro de limites controláveis (não uma dúzia de uma vez)
• Após delegar, o agente principal não está bloqueado esperando e ainda pode responder ao usuário

Etapa 4: Verificar

Este é o passo mais facilmente ignorado e o mais importante. O "concluído" do subagente é uma declaração a ser verificada, não uma conclusão.

Verifique na ordem (veja a "Lista de Verificação")：

1. A saída existe? O arquivo está realmente lá? O caminho está correto? Leia o conteúdo real.
2. A saída está em conformidade? O formato, campos, número de linhas, escopo atendem aos requisitos da ordem de serviço?
3. Há evidência para as conclusões? Os números / conclusões importantes que ele alega têm saída de comando ou fonte correspondente?
4. Verificação aleatória da fonte original: Escolha 1–2 pontos aleatoriamente e verifique com a fonte original.

Qualquer item falhar → Siga o tratamento de falha na Etapa 5.

Critérios de Conclusão

• A saída de cada subagente foi realmente lida de volta usando a ferramenta de leitura de arquivo / execução da plataforma (no Hermes é read_file / terminal)
• O formato e os campos atendem aos requisitos da ordem de serviço
• As conclusões importantes têm evidências rastreáveis
• Pelo menos um ponto da fonte original foi verificado e é consistente com o que o subagente disse
• Saídas com falha / insatisfatórias foram claramente marcadas e não foram misturadas no resultado final

Etapa 5: Consolidar

Ao resumir para o usuário, três coisas são obrigatórias:

• Indique a fonte: quais partes foram feitas por subagentes, quais você fez. O usuário tem o direito de saber.
• Indique o status: quais foram verificadas, quais não foram, quais falharam. Não use "aproximadamente" ou "deveria estar".
• Dê o próximo passo: coloque claramente as decisões que o usuário precisa tomar.

Tratamento de falha (por prioridade):

1. Rebaixe e faça você mesmo — se a tarefa não é grande, faça você mesmo.
2. Mude o caminho e delegue novamente — escreva o motivo da falha na nova ordem de serviço e tente de outra forma.
3. Divida e delegue novamente — se a ordem de serviço era muito grande e causou desvio, divida em pedaços menores e delegue.
4. Relate honestamente — se não funcionar, não funciona. Explique o ponto de obstrução e os caminhos já descartados. Não invente resultados.

Critérios de Conclusão

• O resumo indica a fonte de cada parte (subagente / agente principal)
• O resumo indica o status de verificação de cada parte
• As tarefas com falha foram tratadas (feita você mesmo / delegada novamente / relatada honestamente), não desaparecidas
• As decisões que o usuário precisa tomar estão listadas separadamente
• Nenhuma afirmação não verificada foi escrita como fato

---

Quatro Elementos da Delegação

Cada ordem de serviço deve conter estes quatro itens. Faltar qualquer um aumenta significativamente a probabilidade de acidentes.

1. Objetivo (goal) — O que precisa ser feito

Resuma o objetivo em uma frase, comece com um verbo e seja orientado a resultados.

• Bom: Combinar 3 CSVs em um combined.csv com deduplicação, mantendo a ordem original das colunas
• Ruim: Processar estes arquivos

2. Contexto (context) — Por que fazer, com base no quê (deve ser autocontido)

Este é o elemento mais fácil de errar. Simples:

O subagente não vê o histórico da sua conversa com o usuário. Ele só sabe o que você escreveu na ordem de serviço. O que está na sua mente — preferências do usuário, erros anteriores, por que não pode usar uma solução, a métrica dos dados — ele não recebe.

Portanto, o contexto deve incluir explicitamente:

• Contexto da tarefa: a que objetivo serve, o que o usuário valoriza.
• Restrições rígidas: métricas, formatos, regras de nomenclatura, proibições que devem ser seguidas.
• Lista de entradas: caminhos de arquivos / diretórios / URLs / conjuntos de dados específicos, não escreva "aqueles arquivos".
• Armadilhas conhecidas: o que já foi tentado e não funcionou, onde estão os riscos, pontos que causam confusão.
• Informações do ambiente: diretório de trabalho, ferramentas disponíveis, dependências instaladas.

Método de auto-verificação: Se você enviar esta ordem de serviço para um colega que não tem nenhum contexto anterior, ele pode segui-la? Se sim, é autocontida.

3. Estrutura de Saída (output schema) — Como a saída deve ser

Defina a estrutura da saída para evitar ter que processá-la novamente quando retornar.

• Arquivos: caminho + nome do arquivo + formato (markdown / json / csv) + campos ou seções obrigatórios.
• Relatórios: exija uma estrutura de relatório (conclusão / evidência / fonte / itens não resolvidos), não um texto livre.
• Priorize legível por máquina: se puder dar json, não dê texto livre — economiza seu trabalho de análise secundária.
• Se a plataforma suportar validação de saída (validar a resposta do subagente com um schema), ative-o; se não, repita a estrutura no corpo da ordem de serviço e exija "relate nesta estrutura".

4. Método de Verificação — Como provar que está concluído

Diga com antecedência como você vai verificar; ele vai agir de acordo; descobrir depois que não há evidências significa retrabalho.

• Exija relatar o comando realmente executado e sua saída (não "já verifiquei").
• Exija que o caminho da saída possa ser lido diretamente.
• Exija listar explicitamente as partes não concluídas / duvidosas — é melhor ele confessar do que você descobrir.

Tabela de Referência Rápida dos Quatro Elementos

Elemento	Em uma frase	Defeitos Comuns
Objetivo	O que precisa ser feito, orientado a resultados	Muito genérico: "Organize o material"
Contexto	Contexto + restrições + lista de entradas + armadilhas conhecidas	Só escreve o objetivo, sem contexto, subagente improvisa
Estrutura de Saída	Caminho da saída, formato, campos	Caminho não especificado, saída espalhada e não encontrada
Método de Verificação	Qual comando / padrão usar para julgar	Sem critérios de decisão, liberado com base em "parece ok"

---

Lista de Verificação

Para a saída de cada subagente, passe por cada item. Qualquer item "não" significa que não está concluído.

A. Existência

• O arquivo de saída realmente existe no caminho especificado pela ordem de serviço (verifique com a ferramenta de leitura de arquivo / execução da plataforma, não apenas olhe o nome)
• O arquivo não está vazio, o conteúdo não é placeholder / resíduo de template / truncado visivelmente
• Se for código ou script: pode realmente ser executado (não "parece certo")

B. Conformidade

• Formato, campos, nomenclatura atendem aos requisitos da ordem de serviço
• A quantidade está correta (10 itens solicitados, 10 itens recebidos, não "aproximadamente 8")
• Não ultrapassou os limites: não modificou arquivos que não deveria, não escreveu fora do local especificado
• Tarefas paralelas não se sobrepuseram (verifique o tempo de modificação dos arquivos / integridade do conteúdo)

C. Autenticidade

• Os comandos que o subagente afirma ter executado têm saída real correspondente
• As conclusões importantes podem ser rastreadas até fontes específicas (arquivos, URLs, resultados de comandos)
• Selecione aleatoriamente 1–2 pontos, verifique com a fonte original e a conclusão coincide
• Não há números ou afirmações que "parecem razoáveis, mas não têm origem"

D. Integridade

• Cada item solicitado na ordem de serviço foi entregue
• Partes não concluídas / duvidosas são listadas ativamente, não escondidas
• Itens com falha têm uma explicação clara (onde errou, o que tentou)

E. Última Verificação Antes de Consolidar

• Na minha resposta ao usuário, indiquei a fonte e o status de verificação
• Não usei o "auto-relato de sucesso" do subagente como "concluído" na conclusão

---