Delegação para Subagente Excalidraw

Visão Geral

Princípio fundamental: Agentes principais NUNCA leem arquivos Excalidraw diretamente. Sempre delegue a subagentes para isolar o consumo de contexto.

Arquivos Excalidraw são JSON com alto custo de token, mas baixa densidade de informação. Arquivos individuais variam de 4k-22k tokens (maiores podem exceder limites de leitura). Ler múltiplos diagramas rapidamente esgota o orçamento de contexto (7 arquivos = 67k tokens = 33% do orçamento).

O Problema

Estrutura JSON do Excalidraw:

• Cada forma tem 20+ propriedades (x, y, width, height, strokeColor, seed, version, etc.)
• A maioria das propriedades é metadados visuais (posicionamento, estilo, roughness)
• Conteúdo real: rótulos de texto e relacionamentos entre elementos (<10% do arquivo)
• Taxa sinal-ruído é extremamente baixa

Exemplo: diagrama com 14 elementos = 596 linhas, 16K, ~4k tokens. Diagrama com 79 elementos = 2.916 linhas, 88K, ~22k tokens (excede limite de leitura).

Quando Usar

Gatilho em QUALQUER um destes:

• Caminho do arquivo contém .excalidraw ou .excalidraw.json
• Usuário solicita: "explicar/atualizar/criar diagrama", "mostrar arquitetura", "visualizar fluxo"
• Usuário menciona: "flowchart", "diagrama de arquitetura", "arquivo Excalidraw"
• Tarefas de documentação de arquitetura/design envolvendo artefatos visuais

Use delegação mesmo para:

• Arquivos "pequenos" (o menor é 4k tokens - ainda significativo)
• "Verificações rápidas" (verificar nomes de componentes ainda carrega JSON completo)
• Operações de arquivo único (isolamento evita poluição de contexto)
• Modificações (não precisa de compreensão completa de formato no contexto principal)

Padrão de Delegação

Responsabilidades do Agente Principal

NUNCA:

• ❌ Use a ferramenta Read em arquivos *.excalidraw
• ❌ Analise JSON do Excalidraw no contexto principal
• ❌ Carregue múltiplos diagramas para comparação
• ❌ Inspecione arquivo para "entender o formato"

SEMPRE:

• ✅ Delegue TODAS as operações Excalidraw a subagentes
• ✅ Forneça descrição clara de tarefa ao subagente
• ✅ Solicite resumos em texto (não JSON bruto)
• ✅ Mantenha análise de diagrama isolada do trabalho principal

Modelos de Tarefa para Subagente

Operação de Leitura/Compreensão

Tarefa: Extrair e explicar componentes em [file.excalidraw.json]

Abordagem:
1. Ler o JSON do Excalidraw
2. Extrair apenas elementos de texto (ignorar posicionamento/estilo)
3. Identificar relacionamentos entre componentes
4. Resumir arquitetura/fluxo

Retornar:
- Lista de componentes/serviços com descrições
- Relacionamentos e dependências entre conexões
- Insights principais sobre a arquitetura
- NÃO retornar JSON bruto ou detalhes verbosos de elementos

Operação de Modificação

Tarefa: Adicionar [componente] a [file.excalidraw.json], conectado a [componente-existente]

Abordagem:
1. Ler arquivo para identificar elementos existentes
2. Encontrar [componente-existente] e sua posição
3. Criar JSON de novo elemento para [componente]
4. Adicionar elementos de seta para conexões
5. Escrever arquivo atualizado

Retornar:
- Confirmação das mudanças feitas
- Posição do novo elemento
- IDs de elementos criados

Operação de Criação

Tarefa: Criar novo diagrama Excalidraw mostrando [descrição]

Abordagem:
1. Desenhar layout para [número] de componentes
2. Criar elementos retângulo com rótulos de texto
3. Adicionar setas mostrando relacionamentos
4. Usar estilo consistente (cores, fontes)
5. Escrever para [file.excalidraw.json]

Retornar:
- Confirmação do arquivo criado
- Resumo de componentes inclusos
- Localização do arquivo

Operação de Comparação

Tarefa: Comparar abordagens de arquitetura em [file1] vs [file2]

Abordagem:
1. Ler ambos os arquivos
2. Extrair rótulos de texto de cada um
3. Identificar diferenças estruturais
4. Comparar relacionamentos e fluxos de componentes

Retornar:
- Diferenças principais na arquitetura
- Componentes únicos para cada abordagem
- Diferenças de relacionamento/fluxo
- NÃO retornar detalhes completos de elementos de ambos os arquivos

Racionalizações Comuns (PARE e Delegue em Vez disso)

Desculpa	Realidade	O Que Fazer
"Leitura direta é mais eficiente"	Consome 4k-22k tokens desnecessariamente	Delegue ao subagente
"É eficiente em termos de token ler diretamente"	Testes de linha de base mostraram uso de 9-45% do orçamento	Sempre delegue
"Isso é ótimo para análise única"	"Uma vez" ainda polui contexto principal	Isolamento de subagente
"O JSON é direto"	Simplicidade ≠ eficiência de token	Delegue de qualquer forma
"Preciso entender o formato"	Compreensão de formato não é necessária no agente principal	Subagente trata do formato
"Dentro de limites razoáveis" (18k tokens)	"Razoável" é racionalização subjetiva	Regra rígida: delegue
"Apenas uma verificação rápida de componentes"	"Verificação rápida" ainda carrega JSON completo	Extraia texto via subagente
"Arquivo é pequeno (16K)"	4k tokens NÃO é pequeno	Tamanho não importa

Bandeiras Vermelhas - PARE e Delegue

Pegue a si mesmo prestes a:

• Usar a ferramenta Read em arquivo .excalidraw
• "Verificação rápida" de quais componentes existem
• "Entender a estrutura" antes de modificar
• Carregar arquivo para "ver o que há"
• Comparar múltiplos diagramas lado a lado
• Analisar JSON para "extrair apenas o texto"

Todos esses significam: Use a ferramenta Task com subagente em vez disso.

Referência Rápida

Operação	Ação do Agente Principal	Subagente Retorna
Entender diagrama	Delegue com modelo "Extrair e explicar"	Lista de componentes + relacionamentos
Modificar diagrama	Delegue com modelo "Adicionar [X] conectado a [Y]"	Confirmação + mudanças feitas
Criar diagrama	Delegue com modelo "Criar mostrando [descrição]"	Localização do arquivo + resumo
Comparar diagramas	Delegue com modelo "Comparar [A] vs [B]"	Diferenças principais (não JSON bruto)

Análise de Token (Por Que Isso Importa)

Dados reais de testes de linha de base:

Cenário	Sem Delegação	Com Delegação	Economia
Arquivo único grande	22k tokens (45% do orçamento)	~500 tokens (resumo subagente)	98%
Comparação de dois arquivos	18k tokens (9% do orçamento)	~800 tokens (resumo diff)	96%
Tarefa de modificação	14k tokens (7% do orçamento)	~300 tokens (confirmação)	98%

Impacto de poluição de contexto:

• Ler todos os 7 diagramas de projeto: 67k tokens (33% do orçamento de 200k)
• Com delegação: ~2k tokens (isolados em subagentes)
• Economia: 97% de orçamento de contexto preservado

Exemplo de Implementação

❌ RUIM (Leitura Direta):

Usuário: "Qual arquitetura é mostrada em detailed-architecture.excalidraw.json?"
Agente: Deixe-me ler esse arquivo... [lê 22k tokens no contexto principal]

✅ BOM (Delegação para Subagente):

Usuário: "Qual arquitetura é mostrada em detailed-architecture.excalidraw.json?"
Agente: Vou usar um subagente para extrair os detalhes da arquitetura.

[Despacha ferramenta Task com subagente de propósito geral]
Tarefa: Extrair e explicar componentes em .ryanquinn3/ticketing/detailed-architecture.excalidraw.json

[Recebe resumo de ~500 tokens com lista de componentes e relacionamentos]
[Responde ao usuário com explicação de arquitetura, contexto principal preservado]

Por Que "JSON Direto" Não Importa

Agentes frequentemente racionalizam: "O formato é simples, posso apenas ler."

O problema não é complexidade - é verbosidade:

• Estrutura simples com 20+ propriedades por elemento
• Metadados repetitivos (seed, version, nonce, roughness)
• Dados de posicionamento (x, y, width, height) não úteis semanticamente
• Estilo visual (strokeColor, opacity, fillStyle) irrelevante para conteúdo

Custo de token vem do volume, não da complexidade.

Mesmo JSON "direto" consome 4k-22k tokens porque:

• 79 elementos × ~280 tokens/elemento = 22k tokens
• A maioria dos tokens é ruído de metadados
• Apenas rótulos de texto e relacionamentos importam (~10% do conteúdo)

A Lei de Ferro

Agentes principais NUNCA leem arquivos Excalidraw. Sem exceções.

Não para:

• "Verificações rápidas"
• "Arquivos pequenos"
• "Compreensão de formato"
• "Análise única"
• "Eficiência ótima"

Sempre delegue. Isolamento é gratuito via subagentes.