Mesmo Prompt, Mesmo Diagrama

Prateek Rai lançou o tldraw-canvas-kit, uma coleção de 19 “Agent Skills” que permitem que assistentes de IA locais, como o Claude Code ou o Cursor, controlem o aplicativo desktop offline do tldraw e produzam diagramas de engenharia idênticos todas as vezes. O kit funciona sem qualquer conexão com a nuvem ou telemetria, o que significa que as equipes podem manter seus ativos visuais totalmente on-premises.

Por que uma ferramenta de diagramação local e determinística é importante

Equipes de engenharia passam horas movendo fluxogramas, diagramas de classe e mapas de arquitetura entre apresentações, sites de documentação e ferramentas de design. Cada etapa de copiar e colar introduz mudanças sutis — estilos de linha mudam, IDs são regenerados, layouts se deslocam. Quando um diagrama é regenerado por um LLM, o resultado é frequentemente um arranjo diferente, mesmo que o prompt textual permaneça inalterado. Para organizações que precisam de documentação pronta para auditoria ou artefatos de design reproduzíveis, essa variabilidade é um risco.

Prateek construiu o tldraw-canvas-kit para resolver dois problemas: (1) uma ferramenta que roda inteiramente na máquina do usuário e (2) a garantia de que o mesmo prompt produzirá o mesmo diagrama. Ao expor uma API HTTP local que o agente de IA pode chamar, o kit elimina a latência de rede, o risco de exfiltração de dados e a necessidade de uma assinatura SaaS.

Como o kit funciona

  • Núcleo offline – O aplicativo desktop tldraw executa um servidor local que aceita comandos codificados em JSON. Nenhuma chamada externa é feita e nenhum dado de uso sai da máquina.
  • Agent Skills – Cada habilidade codifica uma especificação de estrutura fixa: matemática de layout, escolhas de stencils e IDs estáveis. Quando um agente invoca uma habilidade, ele recebe um conjunto determinístico de instruções de desenho.
  • Atualizações idempotentes – Se uma habilidade for executada em um diagrama existente, ela atualiza as formas no local, remove elementos obsoletos e reancora as arestas. O resultado é uma tela que pode ser atualizada sem acumular objetos duplicados.
  • Formato de arquivo – Os diagramas são armazenados como arquivos .tldraw simples. Como a lógica de layout reside dentro do arquivo, compartilhar um deck inclui automaticamente as regras de navegação necessárias para reproduzir a visualização.

O kit suporta treze categorias de diagramas, variando de sequências e fluxogramas a diagramas ER, máquinas de estado, swimlanes, casos de uso, componentes, pacotes, implantação, arquitetura, mapas mentais e mapas de base de código. Os usuários simplesmente descrevem o diagrama desejado; a habilidade cuida da estrutura subjacente.

Lições aprendidas durante o desenvolvimento

  1. O estilo das setas é definido por padrão como um visual desenhado à mão – Mesmo quando uma linha limpa é solicitada, a API inicialmente cria uma seta no estilo esboço (sketch). A habilidade deve emitir um comando de acompanhamento para alterar o estilo.
  2. As setas podem interceptar formas silenciosamente – A API não gera erros se um conector passar por um nó. A inspeção visual de capturas de tela geradas é necessária para detectar tais colisões.
  3. A quebra de linha do rótulo da aresta falha em setas curtas – Os rótulos podem quebrar de forma inadequada se o conector for muito curto, portanto, a habilidade deve impor um comprimento mínimo ou ajustar o posicionamento do rótulo.

Essas peculiaridades ilustram por que as habilidades foram construídas com base no comportamento real da API, em vez de suposições sobre ela.

Instalando e usando o kit

npx skills add prateek11rai/tldraw-canvas-kit

O comando funciona no macOS e Linux. Após a instalação, um agente de IA na mesma estação de trabalho pode consultar documentos locais, gerar código e enviar comandos de desenho para o servidor tldraw em execução. O resultado é um diagrama reproduzível que pode ser editado posteriormente ou exportado para apresentações sem nunca sair do host.

Quem se beneficia e quais são as compensações

  • Equipes focadas em segurança – Empresas com políticas rigorosas de tratamento de dados podem manter todos os artefatos de design atrás de seus firewalls.
  • Engenheiros de documentação – Aqueles que precisam incorporar diagramas em repositórios controlados por versão ganham uma fonte de verdade determinística.
  • Contribuidores individuais – Desenvolvedores cansados de ajustar layouts manualmente após cada execução de LLM podem automatizar o processo.

A principal limitação é a dependência de uma instância do tldraw rodando localmente. Organizações que já dependem de serviços de diagramação baseados na nuvem precisarão adotar o aplicativo desktop e ajustar seus fluxos de trabalho. Além disso, o conjunto de habilidades atual não cobre bibliotecas de stencils personalizadas; os usuários devem trabalhar dentro das formas predefinidas.

O que vem a seguir

Prateek planeja expandir a biblioteca de habilidades com base no feedback da comunidade e adicionar suporte para Windows, ampliando a base potencial de usuários. Ele também espera ver agentes de terceiros integrando o kit, criando um marketplace de geradores de diagramas especializados que compartilham o mesmo núcleo determinístico.

Conclusão

o tldraw-canvas-kit prova que a criação de diagramas impulsionada por IA não precisa ser um processo exclusivamente em nuvem e probabilístico. Ao ancorar a lógica de desenho em uma API local e impor identificadores estáveis, ele permite que engenheiros gerem visuais repetíveis e prontos para auditoria sem sacrificar a privacidade ou o controle.