SamuelChien/mega-skills-collection

Índice

• Visão Geral
• Quando Usar
• Pré-requisitos
• Arquitetura do Protocolo
• Início Rápido
• Fluxo de Coordenação
• Referência de Módulos
• Integração com Conjure
• Solução de Problemas
• Critérios de Saída

Coordenação de Equipes de Agentes

Visão Geral

O Claude Code Agent Teams permite que múltiplos processos Claude CLI colaborem em trabalhos compartilhados por meio de um protocolo de coordenação baseado em sistema de arquivos. Cada membro da equipe é executado como um processo claude independente em um painel tmux, comunicando-se via arquivos JSON protegidos por locks fcntl. Sem banco de dados, sem daemon, sem camada de rede.

Esta skill fornece os padrões para orquestrar equipes de agentes de forma eficaz.

Quando Usar

• Implementação paralela em múltiplos arquivos ou módulos
• Revisão de código multi-agente (um agente revisa, outro implementa correções)
• Refatoração grande que exige mudanças coordenadas em vários subsistemas
• Tarefas com paralelismo natural que se beneficiam de agentes concorrentes

Quando NÃO Usar

• Alterações em um único arquivo ou tarefas pequenas (a sobrecarga supera o benefício)
• Tarefas que exigem raciocínio sequencial rigoroso (agentes coordenam-se de forma flexível)
• Quando a CLI claude não está disponível ou o tmux não está instalado

Pré-requisitos

# Verifique a CLI do Claude Code
claude --version

# Verifique se o tmux está instalado (necessário para modo de painel dividido)
tmux -V

# Ative o recurso experimental (definido automaticamente pelo spawner)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Arquitetura do Protocolo

~/.claude/
  teams/<team-name>/
    config.json            # Metadados da equipe + lista de membros
    inboxes/
      <agent-name>.json    # Fila de mensagens por agente
      .lock                # Lock exclusivo fcntl
  tasks/<team-name>/
    1.json ... N.json      # Arquivos de tarefas com numeração automática
    .lock                  # Lock exclusivo fcntl

Princípios de design:

• Sistema de arquivos é o banco de dados: Arquivos JSON, escritas atômicas via tempfile + os.replace
• Bloqueio fcntl: Previne corrupção de leitura/escrita concorrente em caixas de entrada e tarefas
• Tarefas numeradas: IDs autoincrementais com nomeação sequencial de arquivos
• Acoplamento flexível: Agentes consultam sua própria caixa de entrada; sem notificações push

Início Rápido

1. Criar uma Equipe

# Configuração programática da equipe (via MCP ou API direta)
# Config da equipe gravada em ~/.claude/teams/<team-name>/config.json

A configuração da equipe contém:

• name, description, created_at (timestamp em ms)
• lead_agent_id, lead_session_id
• members[] — array de objetos LeadMember e TeammateMember

2. Gerar Membros da Equipe

Cada membro é um processo claude CLI separado, iniciado com flags de identidade:

claude --agent-id "backend@my-team" \
       --agent-name "backend" \
       --team-name "my-team" \
       --agent-color "#FF6B6B" \
       --parent-session-id "$SESSION_ID" \
       --agent-type "general-purpose" \
       --model sonnet

Consulte modules/spawning-patterns.md para gerenciamento de painéis tmux e atribuição de cores.

3. Criar Tarefas com Dependências

{
  "id": "1",
  "subject": "Implementar endpoints da API",
  "description": "Criar endpoints REST para gerenciamento de usuários",
  "status": "pending",
  "owner": null,
  "blocks": ["3"],
  "blocked_by": [],
  "metadata": {}
}

Consulte modules/task-coordination.md para máquina de estados e gerenciamento de dependências.

4. Coordenar via Mensagens

{
  "from": "team-lead",
  "text": "Os endpoints da API estão prontos para testes de integração",
  "timestamp": "2026-02-07T22:00:00Z",
  "read": false,
  "summary": "API pronta"
}

Consulte modules/messaging-protocol.md para tipos de mensagens e operações de caixa de entrada.

Fluxo de Coordenação

1. agent-teams:team-created — Inicializar configuração da equipe e diretórios
2. agent-teams:teammates-spawned — Lançar agentes em painéis tmux
3. agent-teams:tasks-assigned — Criar tarefas com dependências, atribuir responsáveis
4. agent-teams:coordination-active — Agentes reivindicam tarefas, trocam mensagens, marcam conclusão
5. agent-teams:team-shutdown — Desligamento gracioso com protocolo de aprovação

Papéis da Equipe

Cada membro da equipe tem um role que determina suas capacidades e compatibilidade com tarefas. Cinco papéis são definidos: implementer (padrão), researcher, tester, reviewer e architect. Os papéis restringem quais níveis de risco um agente pode lidar — consulte modules/crew-roles.md para a matriz completa de capacidades e a tabela de compatibilidade papel-risco.

Monitoramento de Saúde

Os membros da equipe podem ser monitorados quanto à saúde por meio de mensagens de heartbeat e expiração de reivindicações. O líder consulta a saúde da equipe a cada 60 segundos com um protocolo de detecção de travamento em 2 estágios (sonda health_check + espera de 30s). Agentes travados têm suas tarefas liberadas e são reiniciados ou substituídos seguindo a doutrina "substitua, não espere". Consulte modules/health-monitoring.md para o protocolo completo e a máquina de estados.

Referência de Módulos

• team-management.md: Ciclo de vida da equipe, formato de configuração, gerenciamento de membros
• messaging-protocol.md: Tipos de mensagens, operações de caixa de entrada, padrões de bloqueio
• task-coordination.md: CRUD de tarefas, máquina de estados, detecção de ciclos de dependência
• spawning-patterns.md: Geração de painéis tmux, flags da CLI, gerenciamento de painéis
• crew-roles.md: Taxonomia de papéis, matriz de capacidades, compatibilidade papel-risco
• health-monitoring.md: Protocolo de heartbeat, detecção de travamento, recuperação automatizada

Integração com Conjure

O Agent Teams estende o modelo de delegação conjure:

Padrão Conjure	Equivalente no Agent Teams
delegation-core:task-assessed	agent-teams:team-created
delegation-core:handoff-planned	agent-teams:tasks-assigned
delegation-core:results-integrated	agent-teams:team-shutdown
Execução LLM externa	Execução do agente membro da equipe

Use Skill(conjure:delegation-core) primeiro para determinar se a tarefa se beneficia de coordenação multi-agente versus delegação de serviço único.

Alternativa de Isolamento Worktree (Claude Code 2.1.49+)

Para agentes paralelos que modificam arquivos, isolation: worktree fornece uma alternativa leve à coordenação baseada em sistema de arquivos. Cada agente executa em seu próprio worktree git temporário, eliminando a necessidade de bloqueio fcntl ou de evitar conflitos baseados em caixa de entrada em arquivos compartilhados.

• Quando preferir worktrees em vez de mensagens de equipes de agentes: Agentes trabalham em arquivos sobrepostos, mas não precisam de comunicação durante a execução
• Quando preferir mensagens de equipes de agentes: Agentes precisam coordenar descobertas ou ajustar planos com base no progresso uns dos outros
• Combine ambos: Use equipes de agentes para coordenação com isolation: worktree por membro para segurança do sistema de arquivos

Solução de Problemas

Problemas Comuns

tmux não encontrado Instale via gerenciador de pacotes: brew install tmux / apt install tmux

Arquivos de lock obsoletos Se um agente falhar durante a operação, os arquivos de lock podem persistir. Remova manualmente os arquivos .lock de ~/.claude/teams/<team>/inboxes/ ou ~/.claude/tasks/<team>/

Tarefas órfãs Tarefas reivindicadas por um agente que falhou permanecem como in_progress indefinidamente. Use modules/health-monitoring.md para detecção de travamento baseada em heartbeat e liberação automática de tarefas. O protocolo de monitoramento de saúde detecta agentes não responsivos em 60s + janela de sonda de 30s e libera suas tarefas para reatribuição.

Ordenação de mensagens A resolução de timestamp do sistema de arquivos varia (HFS+ = granularidade de 1s). Use nomes de arquivos numerados ou nomes ordenados por UUID para evitar colisões em rajadas rápidas de mensagens.

Erros de modelo no Bedrock/Vertex/Foundry (pré-2.1.39) Agentes membros podem usar identificadores de modelo incorretos em provedores empresariais, causando erros 400. Atualize para Claude Code 2.1.39+ para qualificação correta de ID de modelo em todos os provedores.

Proteção de sessão aninhada (2.1.39+) Se claude se recusar a iniciar dentro de uma sessão existente, certifique-se de estar usando divisão de painel tmux (não invocação de subshell). A proteção é intencional — consulte modules/spawning-patterns.md para detalhes.

Critérios de Saída

• Equipe criada com configuração e diretórios
• Membros gerados e registrados na configuração
• Tarefas criadas com grafo de dependências (sem ciclos)
• Agentes coordenando via mensagens de caixa de entrada
• Desligamento gracioso concluído