agenthub

Visão geral da skill agenthub

Para que serve agenthub

agenthub é uma skill de Agent Orchestration para executar vários agentes de IA em paralelo sobre a mesma tarefa de um repositório. Cada agente trabalha em um git worktree isolado, explora uma abordagem diferente, reporta o progresso por meio de um .agenthub/board local e deixa uma branch que pode ser avaliada e mesclada. O trabalho principal aqui não é “pedir uma resposta para uma IA”; é “testar várias soluções plausíveis, compará-las e ficar com a melhor”.

Casos de uso mais indicados

A skill agenthub funciona melhor quando o sucesso pode ser comparado entre tentativas: otimização de performance, refatoração de código, variações de prompt ou conteúdo, exploração de pesquisa, melhoria de testes ou estratégias de implementação concorrentes. Ela é especialmente útil quando um agente pode ficar preso em um ótimo local e você quer diversidade sem precisar gerenciar manualmente branches, anotações de status e ranking de resultados.

Diferenciais importantes e restrições

O principal diferencial é o isolamento baseado em git: as saídas dos agentes ficam separadas em branches hub/{session-id}/agent-{N}/attempt-{M}, em vez de serem misturadas em uma única working tree. AgentHub também inclui referências de coordenação para padrões de fan-out/fan-in, tournament e ensemble, além de scripts para configuração de sessão, gerenciamento do board, análise de DAG, validação em dry-run e ranking de resultados. A principal restrição é que você precisa de um repositório git real; é uma escolha ruim para respostas pontuais em chat sem arquivos, sem caminho de avaliação ou sem tolerância para revisão de merge.

Como usar a skill agenthub

Instalação do agenthub e configuração do repositório

Instale a skill no seu ambiente de skills do Claude com:

npx skills add alirezarezvani/claude-skills --skill agenthub

Depois, use-a a partir do repositório do projeto de destino, não de uma pasta vazia. Antes de criar agentes, garanta que o repositório esteja limpo ou que você saiba intencionalmente quais arquivos não commitados devem fazer parte da baseline. Se quiser inspecionar a implementação primeiro, comece por SKILL.md e depois leia:

• references/agent-templates.md para estilos de dispatch como optimizer, refactorer, explorer e relacionados.
• references/coordination-strategies.md para escolher workflows de fan-out, tournament ou ensemble.
• references/dag-patterns.md para nomenclatura de branches, detecção de frontier e comportamento de merge.
• scripts/hub_init.py, scripts/board_manager.py, scripts/dag_analyzer.py e scripts/result_ranker.py para detalhes operacionais.

Comandos e fluxo de trabalho

No uso normal do agenthub, a skill expõe slash commands como:

• /hub:init para definir a tarefa, a quantidade de agentes, os critérios de avaliação e a sessão.
• /hub:spawn para iniciar subagentes paralelos em worktrees isolados.
• /hub:status para inspecionar o progresso e o estado das branches.
• /hub:board para ler ou escrever notas de dispatch, progresso e resultado.
• /hub:eval para ranquear saídas por métrica ou por julgamento de LLM.
• /hub:merge para mesclar a branch vencedora e arquivar as perdedoras.
• /hub:run para um ciclo de vida em uma única etapa: init, baseline, spawn, evaluate, merge.

Para validação manual, os scripts incluídos mostram a mecânica esperada. Por exemplo, hub_init.py pode inicializar .agenthub/ com uma tarefa, quantidade de agentes, comando de avaliação, métrica e direção; dag_analyzer.py pode mostrar branches de frontier; board_manager.py gerencia publicações de progresso e resultado.

Transforme um objetivo vago em um prompt forte

Um prompt fraco seria: “Use agenthub para melhorar este app.” Um prompt mais forte dá ao coordenador as informações necessárias para distribuir o trabalho e julgar os agentes:

Use agenthub for Agent Orchestration in this git repo.

Task: Reduce API p95 latency for `/search` without changing response schema.
Agents: 4
Template: optimizer
Evaluation command: `pytest tests/test_search.py && python bench/search_latency.py --json`
Metric: `p95_ms`
Direction: lower
Constraints:
- Keep public API compatibility.
- Do not add external services.
- Prefer small commits with clear explanations.
Success bar: at least 15% lower p95 with all tests passing.
After spawning, use the board to track each agent’s strategy and final result, then evaluate and recommend the winning branch before merge.

Isso funciona melhor porque cada agente entende o alvo, a pontuação mensurável, as mudanças permitidas e a condição de parada.

Dicas práticas de qualidade

Use de 2 a 5 agentes na maioria das sessões; a orientação de coordenação do repositório observa retornos decrescentes além disso. Prefira avaliação baseada em métricas sempre que possível, porque ela reduz a subjetividade na escolha do vencedor. Use um LLM judge apenas para tarefas como qualidade de documentação, variações de conteúdo ou síntese de pesquisa, quando não houver uma métrica confiável por linha de comando. Para tarefas grandes, considere um padrão ensemble somente se as subtarefas forem realmente independentes; caso contrário, fan-out/fan-in é mais simples e seguro.

FAQ da skill agenthub

agenthub serve apenas para tarefas de código?

Não. agenthub é centrado em git, mas o trabalho pode ser código, documentação, prompts, notas de pesquisa, benchmarks ou rascunhos de conteúdo, desde que as saídas vivam em um repositório e possam ser comparadas. Ele é mais valioso quando várias tentativas independentes podem gerar resultados significativamente diferentes.

Qual é a diferença entre agenthub e um prompt normal?

Um prompt normal pede que uma execução do modelo resolva uma tarefa. A skill agenthub coordena várias tentativas, isola cada uma em worktrees, registra o progresso por meio de um board, analisa o estado das branches e avalia um vencedor. Essa estrutura faz diferença quando exploração e comparação valem mais do que uma única resposta direta.

Iniciantes conseguem usar a skill agenthub?

Sim, desde que entendam conceitos básicos de git, como branches, commits e revisão de merge. Iniciantes devem começar com /hub:run ou uma sessão simples de /hub:init usando 2 agentes e um comando de avaliação claro. Evite começar com estratégias tournament ou ensemble até se sentir confortável revisando branches concorrentes.

Quando não devo usar agenthub?

Não use agenthub quando a tarefa for minúscula, a resposta desejada for óbvia, o repositório não estiver em git, os critérios de avaliação não estiverem claros ou os conflitos de merge custarem mais do que o benefício da exploração paralela. Para edições simples, um prompt direto com revisão normal é mais rápido.

Como melhorar a skill agenthub

Melhore os inputs do agenthub antes de criar agentes

A melhor forma de melhorar os resultados do agenthub é definir a competição com precisão. Inclua a tarefa, arquivos ou módulos no escopo, áreas excluídas, quantidade de agentes, template, comando de avaliação, nome da métrica, direção da métrica, restrições de qualidade e política de merge. Se os agentes estiverem otimizando, forneça um valor de baseline; se estiverem redigindo, forneça uma rubrica e exemplos de saída aceitável.

Evite modos de falha comuns

Problemas comuns incluem agentes otimizando a métrica errada, produzindo resultados incomparáveis, sobrescrevendo premissas ou deixando branches que passam em um benchmark estreito, mas falham em testes mais amplos. Evite isso exigindo que todos os agentes executem o mesmo comando de avaliação, publiquem progresso em .agenthub/board/progress, escrevam resultados finais em .agenthub/board/results e mantenham commits pequenos o suficiente para revisão. Adicione “all tests must pass” como restrição quando a correção for mais importante que a pontuação bruta.

Itere depois do primeiro resultado

Depois de /hub:eval, não faça merge às cegas. Inspecione o diff vencedor, leia as publicações de resultado dos agentes perdedores e procure ideias parciais úteis. Se o vencedor for bom, mas não decisivo, rode uma segunda rodada em estilo tournament a partir da branch vencedora com restrições refinadas. Se agentes diferentes resolveram partes independentes distintas, considere fazer cherry-pick com uma abordagem ensemble, mas somente depois de verificar conflitos e cobertura de testes.

Use os arquivos de suporte como guia operacional

Para um uso melhor no longo prazo, trate os arquivos de suporte do repositório como playbooks. Use references/coordination-strategies.md para escolher o padrão de orquestração, references/agent-templates.md para alinhar o comportamento do agente à tarefa, references/dag-patterns.md para entender a lógica de branch/frontier e scripts/dry_run.py para validar os arquivos da skill antes de depender da automação. Isso transforma agenthub de uma ideia chamativa de agentes paralelos em um workflow de repositório repetível.