Pular para o conteúdo principal

Usando Cursor Canvas para Planejamento Visual de Projetos

Canvas

Cursor Canvas é uma superfície de planejamento visual que vive dentro do seu IDE. Ele permite que você esboce diagramas de arquitetura, mapeie fluxos de funcionalidades, planeje tarefas de sprint e compartilhe contexto visual com sua equipe, tudo sem sair do Cursor. Ao contrário de um quadro branco estático, o Canvas se integra à sua base de código, permitindo que você vincule diagramas a arquivos, funções e modelos de dados reais. Este guia cobre tudo, desde a criação do seu primeiro canvas até a publicação e a solução do infame erro "Canvas file not found".

O que é o Cursor Canvas?​

Canvas é um workspace visual onde você pode:

  • Desenhar diagramas de arquitetura com caixas, setas e anotações
  • Vincular artefatos de código arrastando arquivos, funções ou classes para o canvas
  • Planejar funcionalidades visualmente antes de escrever qualquer código
  • Compartilhar com sua equipe publicando canvases como links autônomos
  • Anotar decisões com notas, TODOs e justificativas de design

A principal diferencial em relação a ferramentas externas como Miro ou Figma é que o Canvas é context-aware. Quando você coloca um componente no canvas, ele conhece o caminho do arquivo real, as exportações e as dependências desse componente.

Pré-requisitos​

  • Cursor versão 0.42 ou mais recente (Canvas foi introduzido no final de 2024)
  • Uma pasta de projeto aberta no Cursor (Canvas funciona dentro de um contexto de projeto)
  • Conta Cursor para recursos de publicação (o plano gratuito é suficiente)

Criando Seu Primeiro Canvas​

Passo 1: Abrir o Editor de Canvas​

Existem três maneiras de abrir um novo canvas:

  1. Paleta de Comandos: Cmd/Ctrl + Shift + P e digite Canvas: New Canvas
  2. Barra Lateral: Clique no ícone do Canvas na barra de atividades (barra lateral esquerda)
  3. Atalho de teclado: Cmd/Ctrl + Shift + C (configurável nas configurações)

Passo 2: Adicionar Elementos ao Canvas​

Comece com um canvas em branco. Você pode adicionar os seguintes tipos de elementos:

ElementoComo AdicionarPropósito
Nó de arquivoArraste um arquivo do exploradorMostra o arquivo e suas relações
Nó de funçãoClique direito em uma função > "Add to Canvas"Visualizar grafos de chamadas de função
Caixa de textoDuplo clique em espaço vazio do canvasAdicionar notas, rótulos ou decisões
FormaClique na ferramenta de forma na barra de ferramentasDesenhar caixas, círculos, setas
ImagemArraste um arquivo de imagem ou cole da área de transferênciaIncluir capturas de tela ou mockups

Passo 3: Conectar Elementos​

Desenhe setas entre os elementos para mostrar relacionamentos:

  1. Passe o mouse sobre um elemento até que os pontos de conexão apareçam
  2. Clique e arraste de um ponto de conexão para outro elemento
  3. Solte para criar uma conexão
  4. Opcionalmente rotule a conexão (ex.: "imports", "calls", "extends")

Passo 4: Salvar o Canvas​

Canvases são salvos como arquivos .canvas em seu projeto:

my-project/
  .cursor/
    canvases/
      architecture-overview.canvas
      feature-auth-flow.canvas
      sprint-planning.canvas
dica

Nomeie seus canvases de forma descritiva. Arquivos Canvas são versionáveis, então sua equipe pode rastrear a evolução dos diagramas ao longo do tempo. Adicione uma pasta canvases/ ao seu repositório e faça commit delas junto com seu código.

Publicação de Canvas​

Publicar um canvas gera um link compartilhável que qualquer pessoa pode visualizar em um navegador, mesmo sem o Cursor instalado. Isso é útil para compartilhar decisões de arquitetura com stakeholders ou integrar novos membros da equipe.

Como Publicar​

  1. Abra o canvas que deseja publicar
  2. Clique no botão Publish na barra de ferramentas superior direita
  3. Escolha a visibilidade:
    • Private - Apenas pessoas com o link e uma conta Cursor podem visualizar
    • Unlisted - Qualquer pessoa com o link pode visualizar (sem necessidade de conta)
    • Public - Descobrível e visualizável por qualquer pessoa
  4. Clique em Publish
  5. Copie a URL gerada e compartilhe

Como a Publicação Funciona Internamente​

Quando você publica um canvas, o Cursor:

  1. Serializa o canvas para um formato portátil
  2. Faz upload para o armazenamento em nuvem do Cursor
  3. Gera uma chave de projeto exclusiva para a versão publicada
  4. Retorna uma URL contendo essa chave
aviso

Canvases publicados são instantâneos pontuais. Se você atualizar o canvas após a publicação, a versão publicada não será atualizada automaticamente. Você deve republicar para compartilhar a versão mais recente. Isso é por design, para evitar que stakeholders vejam edições pela metade.

Gerenciamento de Chave de Projeto​

Cada canvas, seja local ou publicado, está associado a uma chave de projeto. Entender como as chaves de projeto funcionam é essencial para solucionar problemas de publicação.

O que é uma Chave de Projeto?​

Uma chave de projeto é um identificador exclusivo que vincula um canvas ao seu contexto de projeto. Permite que o canvas publicado referencie a estrutura de código correta, caminhos de arquivo e metadados.

O Problema da Chave de Projeto Temporária por Inicialização​

Usuários do fórum relatam frequentemente que a publicação do canvas falha com "Canvas file not found". A causa raiz é que o Cursor gera uma chave de projeto temporária a cada inicialização quando não consegue encontrar uma persistente.

Veja o que acontece:

  1. Você abre o Cursor, e ele atribui uma chave de projeto temporária como tmp_abc123
  2. Você cria e trabalha em um canvas, que é associado a tmp_abc123
  3. Você clica em Publicar
  4. O endpoint de publicação procura o canvas pela chave de projeto atual
  5. Se a chave mudou (porque o Cursor foi reiniciado), a pesquisa falha
  6. Você vê "Canvas file not found"

Corrigindo o Problema da Chave de Projeto​

Solução 1: Criar uma Chave de Projeto Persistente​

Adicione um arquivo .cursor/project.json à raiz do seu projeto:

{
  "projectKey": "persistent-key-my-project-2024",
  "projectName": "My Project",
  "createdAt": "2024-01-15T10:00:00Z"
}

Isso garante que a chave do projeto permaneça estável entre reinicializações do Cursor.

dica

Use uma chave de projeto descritiva e exclusiva. Não use valores genéricos como project1 ou test. Se dois projetos na sua máquina tiverem a mesma chave, as pesquisas de canvas podem colidir, e a publicação falhará intermitentemente.

Solução 2: Reassociar o Canvas​

Se você já tem um canvas com uma chave temporária desatualizada:

  1. Feche o canvas no Cursor
  2. Abra o arquivo .canvas em um editor de texto
  3. Encontre o campo projectKey
  4. Atualize-o para corresponder à sua chave persistente
  5. Salve e reabra no Cursor
  6. Tente publicar novamente

O arquivo .canvas é baseado em JSON, e a seção relevante se parece com:

{
  "version": "1.0",
  "projectKey": "tmp_abc123",
  "elements": [...],
  "connections": [...]
}

Mude tmp_abc123 para sua chave persistente.

Solução 3: Limpar o Cache do Canvas​

Se as soluções acima não funcionarem, o cache local do canvas pode estar corrompido:

  1. Feche o Cursor
  2. Navegue até o diretório de cache do Cursor:
    • macOS: ~/Library/Application Support/Cursor/canvas-cache/
    • Windows: %APPDATA%/Cursor/canvas-cache/
    • Linux: ~/.config/Cursor/canvas-cache/
  3. Exclua o conteúdo da pasta canvas-cache
  4. Reabra o Cursor
  5. Reabra seu arquivo de canvas
  6. Tente publicar novamente
aviso

Limpar o cache do canvas não excluirá seus arquivos .canvas (esses estão em seu projeto). Ele apenas remove as tabelas de lookup temporárias que mapeiam chaves de projeto a metadados de canvas. O conteúdo real do seu canvas é preservado.

Canvas Autônomo vs Glass App​

O Canvas está disponível em dois contextos dentro do ecossistema Cursor, e existem diferenças importantes.

Canvas Autônomo (Cursor IDE)​

Este é o canvas que você acessa de dentro do editor Cursor:

  • Reside no seu diretório .cursor/canvases/
  • Diretamente vinculado ao seu projeto aberto
  • Pode arrastar arquivos do explorador para o canvas
  • Usa a chave de projeto de .cursor/project.json
  • Melhor para: diagramas voltados para desenvolvedores, planejamento de arquitetura, mapeamento de código

Canvas Glass App​

Glass é o aplicativo visual autônomo do Cursor (separado do IDE). Canvas dentro do Glass:

  • Reside no armazenamento próprio do Glass, não no seu diretório de projeto
  • Pode ser vinculado a um projeto, mas opera independentemente
  • Tem um namespace de chave de projeto diferente
  • Suporta elementos visuais mais ricos (animações, componentes interativos)
  • Melhor para: apresentações, demos para stakeholders, compartilhamento entre equipes

Principais Diferenças​

RecursoCanvas AutônomoCanvas Glass App
Local de armazenamento.cursor/canvases/Armazenamento em nuvem do Glass
Fonte da chave de projeto.cursor/project.jsonConfigurações de projeto do Glass
Arrastar e soltar arquivosSim, do exploradorNão, deve importar
Colaboração em tempo realNãoSim
Escopo de publicaçãoConta CursorWorkspace do Glass
Edição offlineSimNão (requer conexão)
dica

Se você trabalha principalmente no IDE do Cursor, use o Canvas autônomo para planejamento de desenvolvimento. Use o Canvas Glass App quando precisar apresentar a stakeholders não técnicos ou colaborar em tempo real. Os dois não são intercambiáveis, e tentar usar o Glass Canvas para tarefas de mapeamento de código será frustrante porque ele não pode referenciar arquivos ativos.

Migrando Entre Autônomo e Glass​

Você pode exportar um canvas autônomo e importá-lo para o Glass:

  1. Abra o canvas no Cursor
  2. Clique em Export > Export as Glass-compatible
  3. Salve o arquivo .glass-canvas
  4. Abra o Glass
  5. Clique em Import e selecione o arquivo

Note que as referências de arquivo no canvas exportado serão convertidas em referências estáticas (não serão atualizadas se o código subjacente mudar).

Design de Fluxo de Trabalho Visual​

O Canvas não é apenas para diagramas de arquitetura. É um workspace visual de uso geral. Aqui estão padrões comuns de fluxo de trabalho.

Fluxo de Planejamento de Funcionalidade​

  1. Crie um canvas chamado feature-[name]-plan.canvas
  2. Adicione caixas de texto para os requisitos da funcionalidade
  3. Adicione nós de arquivo para os arquivos que serão modificados
  4. Desenhe setas mostrando o fluxo de dados
  5. Adicione caixas de texto TODO para perguntas em aberto
  6. Compartilhe o canvas com a equipe antes da implementação
  7. Use o canvas como referência durante a implementação

Fluxo de Revisão de Código​

  1. Crie um canvas para o PR em revisão
  2. Arraste os arquivos alterados para o canvas
  3. Desenhe o grafo de chamadas das funções alteradas
  4. Anote problemas potenciais com caixas de texto vermelhas
  5. Publique o canvas e link-o na descrição do PR

Fluxo de Onboarding​

  1. Crie um arquivo project-architecture.canvas
  2. Adicione os principais pontos de entrada (ex.: index.ts, app.tsx)
  3. Adicione os módulos e serviços principais
  4. Desenhe o grafo de dependências
  5. Adicione anotações explicando a responsabilidade de cada módulo
  6. Publique como um link não listado
  7. Compartilhe com novos membros da equipe no primeiro dia
dica

Mantenha os canvases de onboarding de alto nível. Um canvas com 200 nós é mais difícil de entender do que ler o código diretamente. Aponte para 10-20 elementos que mostrem o panorama geral, e deixe os novos contratados explorarem o código para detalhes.

Recursos Avançados de Canvas​

Conexões com Consciência de Código​

Quando você adiciona uma função ou classe ao canvas, o Canvas pode detectar automaticamente suas dependências e oferecer adicioná-las:

  1. Clique direito em um nó de função
  2. Selecione Show Dependencies
  3. O Canvas lista todas as funções, módulos e tipos que a função usa
  4. Clique em qualquer dependência para adicioná-la ao canvas com uma conexão desenhada automaticamente

Modelos de Canvas​

Crie modelos de canvas reutilizáveis para tipos comuns de diagramas:

{
  "version": "1.0",
  "template": "microservice-architecture",
  "elements": [
    {"type": "text", "label": "API Gateway", "x": 400, "y": 50},
    {"type": "text", "label": "Auth Service", "x": 200, "y": 200},
    {"type": "text", "label": "User Service", "x": 600, "y": 200},
    {"type": "text", "label": "Database", "x": 400, "y": 350}
  ],
  "connections": [
    {"from": 0, "to": 1, "label": "routes to"},
    {"from": 0, "to": 2, "label": "routes to"},
    {"from": 1, "to": 3, "label": "reads/writes"},
    {"from": 2, "to": 3, "label": "reads/writes"}
  ]
}

Salve isso como .cursor/canvases/templates/microservice.canvas e use Canvas: New from Template para instanciá-lo.

Incorporando Canvases na Documentação​

Você pode incorporar links de canvas publicados na documentação do seu projeto:

## Architecture Overview

See our [visual architecture diagram](https://canvas.cursor.sh/c/persistent-key-my-project-2024/architecture-overview) for the full system map.

Key components:
- API Gateway handles routing
- Auth Service manages JWT verification
- User Service handles profile CRUD

Solução de Problemas Comuns​

Problema: "Canvas file not found" ao Publicar​

Este é o erro mais comum. Siga as etapas de solução de problemas da chave de projeto acima. Se elas não resolverem:

  1. Verifique se o arquivo .canvas existe no disco
  2. Verifique se o arquivo não está aberto em outro aplicativo (bloqueio de arquivo)
  3. Certifique-se de que você tem permissões de gravação no diretório .cursor/canvases/
  4. Verifique sua conexão com a internet (publicação requer upload para a nuvem)

Problema: Elementos do Canvas Desaparecem Após Reinicialização​

Causa: O arquivo do canvas referencia elementos por IDs internos que podem mudar se a estrutura do código subjacente mudar (ex.: um arquivo foi renomeado ou excluído).

Solução:

  1. Abra o canvas
  2. Clique em qualquer elemento restante
  3. Use Reconnect to file para vinculá-lo novamente ao caminho de arquivo atual
  4. Adicione novamente quaisquer elementos ausentes

Causa: A chave de projeto na URL publicada não corresponde a nenhum canvas armazenado.

Solução: Republique o canvas após garantir que uma chave de projeto persistente esteja definida. Links antigos de canvases com chave temporária não serão resolvidos.

Problema: Degradação de Desempenho do Canvas​

Causa: Canvases grandes com mais de 100 elementos podem tornar a renderização lenta.

Solução:

  1. Divida canvases grandes em múltiplos menores
  2. Use o recurso Collapse em grupos de elementos
  3. Remova conexões não utilizadas
  4. Evite adicionar diretórios inteiros como nós únicos (use arquivos individuais)
aviso

Não adicione node_modules/ ou outros diretórios grandes a um canvas. Cada arquivo se torna um nó separado, e um diretório com 10.000 arquivos tornará o Cursor sem resposta. Sempre adicione arquivos ou funções específicas, não pastas inteiras.

Melhores Práticas​

Mantenha os Canvases Focados​

Um canvas deve responder a uma pergunta. Em vez de um único canvas "Tudo", crie:

  • data-flow.canvas - Como os dados fluem pelo sistema
  • auth-architecture.canvas - Fluxo de autenticação e autorização
  • deployment-topology.canvas - Mapa de infraestrutura e implantação
  • sprint-3-plan.canvas - Plano visual do sprint atual

Controle de Versão dos Seus Canvases​

Arquivos .canvas são JSON baseado em texto. Faça commit deles no seu repositório:

git add .cursor/canvases/
git commit -m "docs: update architecture canvas for new auth flow"

Isso dá a você um histórico de como sua arquitetura evoluiu e permite que membros da equipe revisem mudanças de diagramas através de PRs.

Higiene Regular do Canvas​

A cada sprint, revise seus canvases:

  • Exclua diagramas desatualizados
  • Atualize arquiteturas alteradas
  • Remova referências a arquivos excluídos
  • Republique quaisquer que sejam compartilhados externamente

Resumo​

Cursor Canvas transforma o planejamento de projetos de uma atividade desconectada em um fluxo de trabalho visual integrado. O erro "Canvas file not found", o problema mais comum que os usuários enfrentam, está enraizado no mecanismo de chave de projeto temporária por inicialização e é totalmente resolvido criando uma chave de projeto persistente em .cursor/project.json. Entender as diferenças entre canvases autônomos e Glass App garante que você use a ferramenta certa para cada contexto, enquanto seguir os padrões de fluxo de trabalho visual neste guia tornará seu planejamento mais eficaz e sua arquitetura mais comunicável.