メインコンテンツまでスキップ

Cursor Canvas を使用したビジュアルプロジェクト計画

Canvas

Cursor Canvas は IDE 内に存在するビジュアル計画サーフェスです。アーキテクチャ図の作成、フィーチャーフローのマッピング、スプリントタスクの計画、チームとのビジュアルコンテキストの共有を、Cursor を離れることなく行えます。静的なホワイトボードとは異なり、Canvas はコードベースと統合されており、図を実際のファイル、関数、データモデルにリンクできます。このガイドは、最初のキャンバスの作成から公開、そして悪名高い「Canvas ファイルが見つかりません」エラーのトラブルシューティングまでを網羅しています。

Cursor Canvas とは？​

Canvas はビジュアルワークスペースで、以下が可能です：

  • アーキテクチャ図の作成 - ボックス、矢印、注釈を使用
  • コードアーティファクトのリンク - ファイル、関数、クラスをキャンバスにドラッグ
  • フィーチャーの視覚的計画 - コードを書く前に
  • チームとの共有 - キャンバスをスタンドアロンリンクとして公開
  • 意思決定の注釈 - ノート、TODO、設計根拠を使用

Miro や Figma などの外部ツールとの主な違いは、Canvas がコンテキスト対応であることです。コンポーネントをキャンバスに配置すると、そのコンポーネントの実際のファイルパス、エクスポート、依存関係を認識します。

前提条件​

  • Cursor バージョン 0.42 以上（Canvas は 2024 年後半に導入）
  • Cursor で開かれたプロジェクトフォルダ（Canvas はプロジェクトコンテキスト内で動作）
  • 公開機能のための Cursor アカウント（フリーティアで十分）

最初のキャンバスの作成​

ステップ 1：Canvas エディタを開く​

新しいキャンバスを開くには 3 つの方法があります：

  1. コマンドパレット： Cmd/Ctrl + Shift + P で Canvas: New Canvas と入力
  2. サイドバー： アクティビティバー（左サイドバー）の Canvas アイコンをクリック
  3. キーボードショートカット： Cmd/Ctrl + Shift + C（設定で構成可能）

ステップ 2：キャンバスに要素を追加​

空白のキャンバスから始めます。以下の要素タイプを追加できます：

要素追加方法目的
ファイルノードエクスプローラーからファイルをドラッグファイルとその関係を表示
関数ノード関数を右クリック > "Add to Canvas"関数コールグラフを可視化
テキストボックス空白のキャンバス領域をダブルクリックノート、ラベル、または決定を追加
シェイプツールバーのシェイプツールをクリックボックス、円、矢印を描画
画像画像ファイルをドラッグまたはクリップボードからペーストスクリーンショットやモックアップを含む

ステップ 3：要素を接続​

要素間に矢印を描いて関係を示します：

  1. 接続ポイントが表示されるまで要素の上にホバー
  2. 接続ポイントから別の要素へクリック＆ドラッグ
  3. リリースして接続を作成
  4. オプションで接続にラベルを付ける（例：「imports」、「calls」、「extends」）

ステップ 4：キャンバスを保存​

キャンバスはプロジェクト内に .canvas ファイルとして保存されます：

my-project/
  .cursor/
    canvases/
      architecture-overview.canvas
      feature-auth-flow.canvas
      sprint-planning.canvas
ヒント

キャンバスに説明的な名前を付けてください。Canvas ファイルはバージョン管理可能なので、チームは図の進化を時間追跡できます。canvases/ フォルダをリポジトリに追加し、コードと一緒にコミットしてください。

Canvas の公開​

キャンバスを公開すると、Cursor がインストールされていなくても、誰もがブラウザで閲覧できる共有可能なリンクが生成されます。これは、ステークホルダーとアーキテクチャの決定を共有したり、新しいチームメンバーのオンボーディングに役立ちます。

公開方法​

  1. 公開したいキャンバスを開く
  2. 右上のツールバーの Publish ボタンをクリック
  3. 可視性を選択：
    • Private - リンクと Cursor アカウントを持つ人のみ閲覧可能
    • Unlisted - リンクを持つ誰もが閲覧可能（アカウント不要）
    • Public - 誰もが発見・閲覧可能
  4. Publish をクリック
  5. 生成された URL をコピーして共有

公開の内部動作​

キャンバスを公開すると、Cursor は以下を行います：

  1. キャンバスをポータブルフォーマットにシリアライズ
  2. Cursor のクラウドストレージにアップロード
  3. 公開バージョン用の固有のプロジェクトキーを生成
  4. そのキーを含む URL を返す
警告

公開されたキャンバスはポイントインタイムのスナップショットです。公開後にキャンバスを更新しても、公開版は自動的に更新されません。最新版を共有するには再公開する必要があります。これは、ステークホルダーが未完成の編集を見るのを防ぐための設計です。

プロジェクトキー管理​

すべてのキャンバスは、ローカルでも公開済みでも、プロジェクトキーに関連付けられています。プロジェクトキーの仕組みを理解することは、公開の問題のトラブルシューティングに不可欠です。

プロジェクトキーとは？​

プロジェクトキーは、キャンバスをプロジェクトコンテキストにリンクする固有の識別子です。公開されたキャンバスが正しいコード構造、ファイルパス、メタデータを参照できるようにします。

起動ごとのテンポラリプロジェクトキーの問題​

フォーラムユーザーは、キャンバスの公開が「Canvas ファイルが見つかりません」で失敗することを頻繁に報告しています。根本原因は、Cursor が永続的なプロジェクトキーを見つけられない場合、起動ごとにテンポラリプロジェクトキーを生成することです。

何が起こるか：

  1. Cursor を開くと、tmp_abc123 のようなテンポラリプロジェクトキーが割り当てられる
  2. キャンバスを作成し作業する。これは tmp_abc123 に関連付けられる
  3. 公開をクリック
  4. 公開エンドポイントが現在のプロジェクトキーでキャンバスを検索
  5. キーが変更されている場合（Cursor が再起動されたため）、検索が失敗
  6. 「Canvas ファイルが見つかりません」が表示される

プロジェクトキーの問題の修正​

解決策 1：永続的なプロジェクトキーを作成​

プロジェクトルートに .cursor/project.json ファイルを追加：

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

これにより、プロジェクトキーが Cursor の再起動後も安定して維持されます。

ヒント

説明的で固有のプロジェクトキーを使用してください。project1 や test のような汎用的な値を使用しないでください。マシン上の 2 つのプロジェクトが同じキーを持つ場合、キャンバスの検索が衝突し、公開が断続的に失敗する可能性があります。

解決策 2：キャンバスを再関連付け​

古いテンポラリキーを持つキャンバスが既にある場合：

  1. Cursor でキャンバスを閉じる
  2. テキストエディタで .canvas ファイルを開く
  3. projectKey フィールドを見つける
  4. 永続キーに一致するよう更新
  5. 保存して Cursor で再度開く
  6. 再度公開を試行

.canvas ファイルは JSON ベースで、関連セクションは以下のようになります：

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

tmp_abc123 を永続キーに変更してください。

解決策 3：キャンバスキャッシュをクリア​

上記の解決策が機能しない場合、ローカルキャンバスキャッシュが破損している可能性があります：

  1. Cursor を閉じる
  2. Cursor キャッシュディレクトリに移動：
    • macOS： ~/Library/Application Support/Cursor/canvas-cache/
    • Windows： %APPDATA%/Cursor/canvas-cache/
    • Linux： ~/.config/Cursor/canvas-cache/
  3. canvas-cache フォルダの内容を削除
  4. Cursor を再度開く
  5. キャンバスファイルを再度開く
  6. 再度公開を試行
警告

キャンバスキャッシュをクリアしても .canvas ファイルは削除されません（それらはプロジェクト内にあります）。プロジェクトキーをキャンバスメタデータにマッピングするテンポラリ検索テーブルのみが削除されます。実際のキャンバスコンテンツは保持されます。

スタンドアロン vs Glass App Canvas​

Canvas は Cursor エコシステム内で 2 つのコンテキストで利用可能であり、重要な違いがあります。

スタンドアロン Canvas（Cursor IDE）​

これは Cursor エディタ内からアクセスするキャンバスです：

  • .cursor/canvases/ ディレクトリに存在
  • 開いているプロジェクトに直接リンク
  • エクスプローラーからファイルをキャンバスにドラッグ可能
  • .cursor/project.json のプロジェクトキーを使用
  • 最適：開発者向け図、アーキテクチャ計画、コードマッピング

Glass App Canvas​

Glass は Cursor のスタンドアロンビジュアルアプリ（IDE とは別）です。Glass 内の Canvas：

  • プロジェクトディレクトリではなく Glass 独自のストレージに存在
  • プロジェクトにリンクできるが独立して動作
  • 異なるプロジェクトキー名前空間を持つ
  • より豊富なビジュアル要素（アニメーション、インタラクティブコンポーネント）をサポート
  • 最適：プレゼンテーション、ステークホルダーデモ、クロスチーム共有

主な違い​

機能スタンドアロン CanvasGlass App Canvas
保存場所.cursor/canvases/Glass クラウドストレージ
プロジェクトキー源.cursor/project.jsonGlass プロジェクト設定
ファイルドラッグ＆ドロップはい、エクスプローラーからいいえ、インポートが必要
リアルタイムコラボレーションいいえはい
公開スコープCursor アカウントGlass ワークスペース
オフライン編集はいいいえ（接続が必要）
ヒント

主に Cursor IDE で作業する場合、開発計画にはスタンドアロン Canvas を使用してください。非技術ステークホルダーへのプレゼンやリアルタイムコラボレーションが必要な場合は Glass App Canvas を使用してください。両者は互換性がなく、Glass Canvas をコードマッピングタスクに使用しようとすると、ライブファイルを参照できないためフラストレーションが生じます。

スタンドアロンと Glass 間の移行​

スタンドアロンキャンバスをエクスポートして Glass にインポートできます：

  1. Cursor でキャンバスを開く
  2. Export > Export as Glass-compatible をクリック
  3. .glass-canvas ファイルを保存
  4. Glass を開く
  5. Import をクリックしてファイルを選択

エクスポートされたキャンバスのファイル参照は静的参照に変換されることに注意してください（基盤となるコードが変更されても更新されません）。

ビジュアルワークフロー設計​

Canvas はアーキテクチャ図だけではありません。汎用ビジュアルワークスペースです。一般的なワークフローパターンを以下に示します。

フィーチャー計画ワークフロー​

  1. feature-[name]-plan.canvas という名前のキャンバスを作成
  2. フィーチャー要件のテキストボックスを追加
  3. 変更されるファイルのファイルノードを追加
  4. データフローを示す矢印を描画
  5. 未解決の質問の TODO テキストボックスを追加
  6. 実装前にチームとキャンバスを共有
  7. 実装中にキャンバスを参照として使用

コードレビューワークフロー​

  1. レビュー中の PR のキャンバスを作成
  2. 変更されたファイルをキャンバスにドラッグ
  3. 変更された関数のコールグラフを描画
  4. 赤いテキストボックスで潜在的な問題に注釈
  5. キャンバスを公開し、PR 説明にリンク

オンボーディングワークフロー​

  1. project-architecture.canvas ファイルを作成
  2. メインエントリーポイント（例：index.ts、app.tsx）を追加
  3. コアモジュールとサービスを追加
  4. 依存関係グラフを描画
  5. 各モジュールの責任を説明する注釈を追加
  6. Unlisted リンクとして公開
  7. 新しいチームメンバーの初日に共有
ヒント

オンボーディングキャンバスは高レベルに保ってください。200 ノードのキャンバスは、コードを直接読むよりも理解が難しいです。全体像を示す 10-20 要素を目指し、詳細は新入社員にコードを掘り下げてもらってください。

高度な Canvas 機能​

コード対応接続​

関数やクラスをキャンバスに追加すると、Canvas は自動的にその依存関係を検出し、追加を提案できます：

  1. 関数ノードを右クリック
  2. Show Dependencies を選択
  3. Canvas がその関数が使用するすべての関数、モジュール、タイプをリスト
  4. 依存関係をクリックすると、自動描画された接続でキャンバスに追加

Canvas テンプレート​

一般的な図タイプの再利用可能なキャンバステンプレートを作成：

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

これを .cursor/canvases/templates/microservice.canvas として保存し、Canvas: New from Template でインスタンス化します。

ドキュメントへのキャンバスの埋め込み​

公開されたキャンバスリンクをプロジェクトドキュメントに埋め込むことができます：

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

一般的な問題のトラブルシューティング​

問題：公開時の「Canvas ファイルが見つかりません」​

これは最も一般的なエラーです。上記のプロジェクトキーのトラブルシューティング手順に従ってください。それでも解決しない場合：

  1. .canvas ファイルがディスクに存在することを確認
  2. ファイルが別のアプリケーションで開かれていない（ファイルロック）ことを確認
  3. .cursor/canvases/ ディレクトリへの書き込み権限があることを確認
  4. インターネット接続を確認（公開にはクラウドへのアップロードが必要）

問題：再起動後にキャンバス要素が消える​

原因： キャンバスファイルは内部 ID で要素を参照しており、基盤となるコード構造が変更された場合（例：ファイルのリネームや削除）、ID が変わる可能性があります。

解決策：

  1. キャンバスを開く
  2. 残っている要素をクリック
  3. Reconnect to file を使用して現在のファイルパスに再リンク
  4. 不足している要素を再追加

問題：公開リンクが空白ページを表示​

原因： 公開 URL のプロジェクトキーが保存されたキャンバスと一致しない。

解決策： 永続プロジェクトキーを設定した後、キャンバスを再公開。テンポラリキーのキャンバスからの古いリンクは解決されません。

問題：キャンバスのパフォーマンス低下​

原因： 100 以上の要素を持つ大きなキャンバスはレンダリングが遅くなる可能性があります。

解決策：

  1. 大きなキャンバスを複数の小さなものに分割
  2. 要素グループに Collapse 機能を使用
  3. 未使用の接続を削除
  4. ディレクトリ全体を単一ノードとして追加しない（個別ファイルを使用）
警告

node_modules/ や他の大きなディレクトリをキャンバスに追加しないでください。各ファイルが別々のノードになり、10,000 ファイルのディレクトリは Cursor を無応答にします。常に特定のファイルや関数を追加し、フォルダ全体ではないようにしてください。

ベストプラクティス​

キャンバスを焦点を絞ったものに​

1 つのキャンバスは 1 つの質問に答えるべきです。「Everything」キャンバスの代わりに、以下を作成：

  • data-flow.canvas - データがシステム内をどう移動するか
  • auth-architecture.canvas - 認証と認可フロー
  • deployment-topology.canvas - インフラとデプロイメントマップ
  • sprint-3-plan.canvas - 現在のスプリントのビジュアル計画

キャンバスをバージョン管理​

.canvas ファイルはテキストベースの JSON です。リポジトリにコミットしてください：

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

これにより、アーキテクチャがどう進化したかの履歴が得られ、チームメンバーは PR を通じて図の変更をレビューできます。

定期的なキャンバスメンテナンス​

毎スプリント、キャンバスをレビュー：

  • 古い図を削除
  • 変更されたアーキテクチャを更新
  • 削除されたファイルへの参照を削除
  • 外部で共有されているものを再公開

まとめ​

Cursor Canvas は、プロジェクト計画を切断された活動から統合されたビジュアルワークフローへと変革します。ユーザーが直面する最も一般的な問題「Canvas ファイルが見つかりません」は、起動ごとのテンポラリプロジェクトキーメカニズムに根ざしており、.cursor/project.json に永続プロジェクトキーを作成することで完全に解決されます。スタンドアロンと Glass App キャンバスの違いを理解することで、各コンテキストに適切なツールを使用でき、このガイドのビジュアルワークフローパターンに従うことで、計画がより効果的になり、アーキテクチャがより伝わりやすくなります。