Zum Hauptinhalt springen

Verwendung von Cursor Canvas für visuelle Projektplanung

Canvas

Cursor Canvas ist eine visuelle Planungsoberfläche, die in Ihrer IDE existiert. Sie können Architekturdiagramme skizzieren, Feature-Flows abbilden, Sprint-Aufgaben planen und visuellen Kontext mit Ihrem Team teilen, alles ohne Cursor zu verlassen. Im Gegensatz zu einem statischen Whiteboard integriert sich Canvas in Ihre Codebase und ermöglicht es Ihnen, Diagramme mit tatsächlichen Dateien, Funktionen und Datenmodellen zu verknüpfen. Dieser Leitfaden behandelt alles, von der Erstellung Ihres ersten Canvas bis zur Veröffentlichung und der Fehlerbehebung des berüchtigten Fehlers „Canvas file not found".

Was ist Cursor Canvas?​

Canvas ist ein visueller Arbeitsbereich, in dem Sie können:

  • Architekturdiagramme zeichnen mit Kästen, Pfeilen und Anmerkungen
  • Code-Artefakte verknüpfen durch Ziehen von Dateien, Funktionen oder Klassen auf das Canvas
  • Features visuell planen bevor Sie Code schreiben
  • Mit Ihrem Team teilen durch Veröffentlichen von Canvas als eigenständige Links
  • Entscheidungen annotieren mit Notizen, TODOs und Designbegründungen

Der wesentliche Unterschied zu externen Tools wie Miro oder Figma besteht darin, dass Canvas kontextbewusst ist. Wenn Sie eine Komponente auf dem Canvas platzieren, kennt sie den tatsächlichen Dateipfad, die Exporte und die Abhängigkeiten dieser Komponente.

Voraussetzungen​

  • Cursor Version 0.42 oder neuer (Canvas wurde Ende 2024 eingeführt)
  • Ein Projektordner in Cursor geöffnet (Canvas funktioniert innerhalb eines Projektkontexts)
  • Cursor-Konto für Veröffentlichungsfunktionen (kostenlose Version ist ausreichend)

Erstellung Ihres ersten Canvas​

Schritt 1: Canvas-Editor öffnen​

Es gibt drei Möglichkeiten, ein neues Canvas zu öffnen:

  1. Befehlspalette: Cmd/Ctrl + Shift + P und Canvas: New Canvas eingeben
  2. Seitenleiste: Klicken Sie auf das Canvas-Symbol in der Aktivitätsleiste (linke Seitenleiste)
  3. Tastaturkürzel: Cmd/Ctrl + Shift + C (in den Einstellungen konfigurierbar)

Schritt 2: Elemente zum Canvas hinzufügen​

Beginnen Sie mit einem leeren Canvas. Sie können die folgenden Elementtypen hinzufügen:

ElementHinzufügen durchZweck
DateiknotenDatei aus dem Explorer ziehenZeigt die Datei und ihre Beziehungen
FunktionsknotenRechtsklick auf Funktion > "Add to Canvas"Aufrufgraphen von Funktionen visualisieren
TextfeldDoppelklick auf leeren Canvas-BereichNotizen, Beschriftungen oder Entscheidungen hinzufügen
FormAuf das Formwerkzeug in der Symbolleiste klickenKästen, Kreise, Pfeile zeichnen
BildBilddatei ziehen oder aus der Zwischenablage einfügenScreenshots oder Mockups einfügen

Schritt 3: Elemente verbinden​

Zeichnen Sie Pfeile zwischen Elementen, um Beziehungen zu zeigen:

  1. Über ein Element fahren, bis Verbindungspunkte erscheinen
  2. Von einem Verbindungspunkt klicken und zu einem anderen Element ziehen
  3. Loslassen, um eine Verbindung zu erstellen
  4. Optional die Verbindung beschriften (z.B. „imports", „calls", „extends")

Schritt 4: Canvas speichern​

Canvas werden als .canvas-Dateien in Ihrem Projekt gespeichert:

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

Benennen Sie Ihre Canvas beschreibend. Canvas-Dateien sind versionskontrollierbar, sodass Ihr Team die Diagramm evolution über Zeit verfolgen kann. Fügen Sie einen canvases/-Ordner zu Ihrem Repository hinzu und committen Sie sie zusammen mit Ihrem Code.

Canvas-Veröffentlichung​

Das Veröffentlichen eines Canvas generiert einen teilbaren Link, den jeder in einem Browser ansehen kann, auch ohne installiertes Cursor. Dies ist nützlich, um Architekturentscheidungen mit Stakeholdern zu teilen oder neue Teammitglieder einzuarbeiten.

Wie man veröffentlicht​

  1. Öffnen Sie das zu veröffentlichende Canvas
  2. Klicken Sie auf die Schaltfläche Publish in der Symbolleiste oben rechts
  3. Wählen Sie die Sichtbarkeit:
    • Private - Nur Personen mit dem Link und einem Cursor-Konto können ansehen
    • Unlisted - Jeder mit dem Link kann ansehen (kein Konto erforderlich)
    • Public - Von jedem entdeckbar und ansehbar
  4. Klicken Sie auf Publish
  5. Kopieren Sie die generierte URL und teilen Sie sie

Wie Veröffentlichung intern funktioniert​

Wenn Sie ein Canvas veröffentlichen, führt Cursor Folgendes aus:

  1. Serialisiert das Canvas in ein portables Format
  2. Lädt es in den Cloud-Speicher von Cursor hoch
  3. Generiert einen eindeutigen Projektschlüssel für die veröffentlichte Version
  4. Gibt eine URL zurück, die diesen Schlüssel enthält
warnung

Veröffentlichte Canvas sind Momentaufnahmen. Wenn Sie das Canvas nach der Veröffentlichung aktualisieren, wird die veröffentlichte Version nicht automatisch aktualisiert. Sie müssen erneut veröffentlichen, um die neueste Version zu teilen. Dies ist beabsichtigt, um zu verhindern, dass Stakeholder halbfertige Bearbeitungen sehen.

Projektschlüsselverwaltung​

Jedes Canvas, ob lokal oder veröffentlicht, ist mit einem Projektschlüssel verknüpft. Das Verständnis der Funktionsweise von Projektschlüsseln ist wesentlich für die Fehlerbehebung von Veröffentlichungsproblemen.

Was ist ein Projektschlüssel?​

Ein Projektschlüssel ist ein eindeutiger Bezeichner, der ein Canvas mit seinem Projektkontext verknüpft. Er ermöglicht dem veröffentlichten Canvas, auf die richtige Codestruktur, Dateipfade und Metadaten zu verweisen.

Das Problem des temporären Projektschlüssels pro Start​

Forumsbenutzer berichten häufig, dass die Canvas-Veröffentlichung mit „Canvas file not found" fehlschlägt. Die Ursache ist, dass Cursor bei jedem Start einen temporären Projektschlüssel generiert, wenn es keinen persistenten finden kann.

Folgendes passiert:

  1. Sie öffnen Cursor und es wird ein temporärer Projektschlüssel wie tmp_abc123 zugewiesen
  2. Sie erstellen und arbeiten an einem Canvas, das mit tmp_abc123 verknüpft ist
  3. Sie klicken auf Veröffentlichen
  4. Der Veröffentlichungs-Endpunkt sucht das Canvas anhand des aktuellen Projektschlüssels
  5. Wenn sich der Schlüssel geändert hat (weil Cursor neu gestartet wurde), schlägt die Suche fehl
  6. Sie sehen „Canvas file not found"

Behebung des Projektschlüsselproblems​

Lösung 1: Einen persistenten Projektschlüssel erstellen​

Fügen Sie eine .cursor/project.json-Datei zu Ihrem Projekt-Root hinzu:

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

Dies stellt sicher, dass der Projektschlüssel über Cursor-Neustarts hinweg stabil bleibt.

tipp

Verwenden Sie einen beschreibenden, eindeutigen Projektschlüssel. Verwenden Sie keine generischen Werte wie project1 oder test. Wenn zwei Projekte auf Ihrem Computer denselben Schlüssel haben, können Canvas-Suchen kollidieren und die Veröffentlichung wird zeitweilig fehlschlagen.

Lösung 2: Canvas neu verknüpfen​

Wenn Sie bereits ein Canvas mit einem veralteten temporären Schlüssel haben:

  1. Schließen Sie das Canvas in Cursor
  2. Öffnen Sie die .canvas-Datei in einem Texteditor
  3. Suchen Sie das Feld projectKey
  4. Aktualisieren Sie es, um mit Ihrem persistenten Schlüssel übereinzustimmen
  5. Speichern und in Cursor erneut öffnen
  6. Versuchen Sie erneut zu veröffentlichen

Die .canvas-Datei ist JSON-basiert, und der relevante Abschnitt sieht so aus:

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

Ändern Sie tmp_abc123 in Ihren persistenten Schlüssel.

Lösung 3: Canvas-Cache leeren​

Wenn die obigen Lösungen nicht funktionieren, ist der lokale Canvas-Cache möglicherweise beschädigt:

  1. Schließen Sie Cursor
  2. Navigieren Sie zum Cursor-Cache-Verzeichnis:
    • macOS: ~/Library/Application Support/Cursor/canvas-cache/
    • Windows: %APPDATA%/Cursor/canvas-cache/
    • Linux: ~/.config/Cursor/canvas-cache/
  3. Löschen Sie den Inhalt des canvas-cache-Ordners
  4. Öffnen Sie Cursor erneut
  5. Öffnen Sie Ihre Canvas-Datei erneut
  6. Versuchen Sie erneut zu veröffentlichen
warnung

Das Leeren des Canvas-Caches löscht nicht Ihre .canvas-Dateien (diese befinden sich in Ihrem Projekt). Es entfernt nur die temporären Nachschlagetabellen, die Projektschlüssel auf Canvas-Metadaten abbilden. Ihr tatsächlicher Canvas-Inhalt bleibt erhalten.

Standalone- vs. Glass-App-Canvas​

Canvas ist in zwei Kontexten innerhalb des Cursor-Ökosystems verfügbar, und es gibt wichtige Unterschiede.

Standalone-Canvas (Cursor IDE)​

Dies ist das Canvas, auf das Sie innerhalb des Cursor-Editors zugreifen:

  • befindet sich in Ihrem .cursor/canvases/-Verzeichnis
  • Direkt mit Ihrem geöffneten Projekt verknüpft
  • Kann Dateien aus dem Explorer auf das Canvas ziehen
  • Verwendet den Projektschlüssel aus .cursor/project.json
  • Am besten für: entwicklerorientierte Diagramme, Architekturplanung, Code-Mapping

Glass-App-Canvas​

Glass ist Curators eigenständige visuelle App (separat von der IDE). Canvas in Glass:

  • befindet sich in Glasss eigenem Speicher, nicht in Ihrem Projektverzeichnis
  • Kann mit einem Projekt verknüpft werden, arbeitet aber unabhängig
  • Hat einen anderen Projektschlüssel-Namespace
  • Unterstützt reichhaltigere visuelle Elemente (Animationen, interaktive Komponenten)
  • Am besten für: Präsentationen, Stakeholder-Demos, teamübergreifendes Teilen

Wesentliche Unterschiede​

FunktionStandalone-CanvasGlass-App-Canvas
Speicherort.cursor/canvases/Glass-Cloud-Speicher
Projektschlüsselquelle.cursor/project.jsonGlass-Projekteinstellungen
Datei-Drag-and-DropJa, aus ExplorerNein, muss importiert werden
Echtzeit-ZusammenarbeitNeinJa
VeröffentlichungsbereichCursor-KontoGlass-Workspace
Offline-BearbeitungJaNein (Verbindung erforderlich)
tipp

Wenn Sie hauptsächlich in der Cursor-IDE arbeiten, verwenden Sie Standalone-Canvas für die Entwicklungsplanung. Verwenden Sie Glass-App-Canvas, wenn Sie nicht-technischen Stakeholdern präsentieren oder in Echtzeit zusammenarbeiten müssen. Die beiden sind nicht austauschbar, und der Versuch, Glass-Canvas für Code-Mapping-Aufgaben zu verwenden, wird frustrierend sein, da es nicht auf Live-Dateien verweisen kann.

Migration zwischen Standalone und Glass​

Sie können ein Standalone-Canvas exportieren und in Glass importieren:

  1. Öffnen Sie das Canvas in Cursor
  2. Klicken Sie auf Export > Export as Glass-compatible
  3. Speichern Sie die .glass-canvas-Datei
  4. Öffnen Sie Glass
  5. Klicken Sie auf Import und wählen Sie die Datei

Beachten Sie, dass Dateiverweise im exportierten Canvas in statische Verweise umgewandelt werden (sie werden nicht aktualisiert, wenn sich der zugrunde liegende Code ändert).

Visuelles Workflow-Design​

Canvas ist nicht nur für Architekturdiagramme. Es ist ein allgemeiner visueller Arbeitsbereich. Hier sind gängige Workflow-Muster.

Feature-Planungs-Workflow​

  1. Erstellen Sie ein Canvas namens feature-[name]-plan.canvas
  2. Fügen Sie Textfelder für die Feature-Anforderungen hinzu
  3. Fügen Sie Dateiknoten für die zu ändernden Dateien hinzu
  4. Zeichnen Sie Pfeile, die den Datenfluss zeigen
  5. Fügen Sie TODO-Textfelder für offene Fragen hinzu
  6. Teilen Sie das Canvas mit dem Team vor der Implementierung
  7. Verwenden Sie das Canvas als Referenz während der Implementierung

Code-Review-Workflow​

  1. Erstellen Sie ein Canvas für den zu überprüfenden PR
  2. Ziehen Sie die geänderten Dateien auf das Canvas
  3. Zeichnen Sie den Aufrufgraph der geänderten Funktionen
  4. Annotieren Sie potenzielle Probleme mit roten Textfeldern
  5. Veröffentlichen Sie das Canvas und verlinken Sie es in der PR-Beschreibung

Onboarding-Workflow​

  1. Erstellen Sie eine project-architecture.canvas-Datei
  2. Fügen Sie die Haupteinstiegspunkte hinzu (z.B. index.ts, app.tsx)
  3. Fügen Sie die Kernmodule und -dienste hinzu
  4. Zeichnen Sie den Abhängigkeitsgraphen
  5. Fügen Sie Anmerkungen hinzu, die die Verantwortung jedes Moduls erklären
  6. Veröffentlichen Sie als Unlisted-Link
  7. Teilen Sie mit neuen Teammitgliedern an ihrem ersten Tag
tipp

Halten Sie Onboarding-Canvas auf hohem Niveau. Ein Canvas mit 200 Knoten ist schwerer zu verstehen als den Code direkt zu lesen. Zielen Sie auf 10-20 Elemente, die das große Ganze zeigen, und lassen Sie neue Mitarbeiter den Code für Details durchsuchen.

Erweiterte Canvas-Funktionen​

Code-bewusste Verbindungen​

Wenn Sie eine Funktion oder Klasse zum Canvas hinzufügen, kann Canvas automatisch seine Abhängigkeiten erkennen und anbieten, sie hinzuzufügen:

  1. Rechtsklick auf einen Funktionsknoten
  2. Wählen Sie Show Dependencies
  3. Canvas listet alle Funktionen, Module und Typen, die die Funktion verwendet
  4. Klicken Sie auf eine Abhängigkeit, um sie mit einer automatisch gezeichneten Verbindung zum Canvas hinzuzufügen

Canvas-Vorlagen​

Erstellen Sie wiederverwendbare Canvas-Vorlagen für gängige Diagrammtypen:

{
  "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"}
  ]
}

Speichern Sie dies als .cursor/canvases/templates/microservice.canvas und verwenden Sie Canvas: New from Template, um es zu instanziieren.

Einbetten von Canvas in Dokumentation​

Sie können veröffentlichte Canvas-Links in Ihre Projektdokumentation einbetten:

## 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

Fehlerbehebung häufiger Probleme​

Problem: „Canvas file not found" beim Veröffentlichen​

Dies ist der häufigste Fehler. Befolgen Sie die oben genannten Projektschlüssel-Fehlerbehebungsschritte. Wenn diese das Problem nicht lösen:

  1. Überprüfen Sie, dass die .canvas-Datei auf der Festplatte existiert
  2. Stellen Sie sicher, dass die Datei nicht in einer anderen Anwendung geöffnet ist (Dateisperre)
  3. Stellen Sie sicher, dass Sie Schreibrechte auf das .cursor/canvases/-Verzeichnis haben
  4. Überprüfen Sie Ihre Internetverbindung (Veröffentlichen erfordert Upload zur Cloud)

Problem: Canvas-Elemente verschwinden nach Neustart​

Ursache: Die Canvas-Datei referenziert Elemente über interne IDs, die sich ändern können, wenn sich die zugrunde liegende Codestruktur ändert (z.B. eine Datei wurde umbenannt oder gelöscht).

Lösung:

  1. Öffnen Sie das Canvas
  2. Klicken Sie auf ein verbleibendes Element
  3. Verwenden Sie Reconnect to file, um es erneut mit dem aktuellen Dateipfad zu verknüpfen
  4. Fügen Sie fehlende Elemente erneut hinzu

Ursache: Der Projektschlüssel in der veröffentlichten URL stimmt mit keinem gespeicherten Canvas überein.

Lösung: Veröffentlichen Sie das Canvas erneut, nachdem Sie sichergestellt haben, dass ein persistenter Projektschlüssel festgelegt ist. Alte Links von Canvas mit temporärem Schlüssel werden nicht aufgelöst.

Problem: Canvas-Leistungsabfall​

Ursache: Große Canvas mit 100+ Elementen können das Rendern verlangsamen.

Lösung:

  1. Teilen Sie große Canvas in mehrere kleinere auf
  2. Verwenden Sie die Collapse-Funktion für Elementgruppen
  3. Entfernen Sie ungenutzte Verbindungen
  4. Vermeiden Sie das Hinzufügen ganzer Verzeichnisse als einzelne Knoten (verwenden Sie einzelne Dateien)
warnung

Fügen Sie node_modules/ oder andere große Verzeichnisse nicht zu einem Canvas hinzu. Jede Datei wird zu einem separaten Knoten, und ein Verzeichnis mit 10.000 Dateien wird Cursor unansprechbar machen. Fügen Sie immer bestimmte Dateien oder Funktionen hinzu, nicht ganze Ordner.

Best Practices​

Canvas fokussiert halten​

Ein Canvas sollte eine Frage beantworten. Anstatt eines einzigen „Alles"-Canvas erstellen Sie:

  • data-flow.canvas - Wie Daten durch das System fließen
  • auth-architecture.canvas - Authentifizierungs- und Autorisierungsfluss
  • deployment-topology.canvas - Infrastruktur- und Deployment-Karte
  • sprint-3-plan.canvas - Visueller Plan des aktuellen Sprints

Canvas versionskontrollieren​

.canvas-Dateien sind textbasiertes JSON. Committen Sie sie in Ihr Repository:

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

Dies gibt Ihnen einen Verlauf, wie sich Ihre Architektur entwickelt hat, und ermöglicht Teammitgliedern, Diagrammänderungen über PRs zu überprüfen.

Regelmäßige Canvas-Hygiene​

Überprüfen Sie in jedem Sprint Ihre Canvas:

  • Veraltete Diagramme löschen
  • Geänderte Architekturen aktualisieren
  • Verweise auf gelöschte Dateien entfernen | Extern geteilte erneut veröffentlichen

Zusammenfassung​

Cursor Canvas transformiert Projektplanung von einer getrennten Aktivität in einen integrierten visuellen Workflow. Der „Canvas file not found"-Fehler, das häufigste Problem, mit dem Benutzer konfrontiert werden, ist im Mechanismus des temporären Projektschlüssels pro Start verwurzelt und wird vollständig durch die Erstellung eines persistenten Projektschlüssels in .cursor/project.json gelöst. Das Verständnis der Unterschiede zwischen Standalone- und Glass-App-Canvas stellt sicher, dass Sie das richtige Werkzeug für jeden Kontext verwenden, während die Befolgung der visuellen Workflow-Muster in diesem Leitfaden Ihre Planung effektiver und Ihre Architektur kommunizierbarer macht.