Cursor Canvas를 사용한 시각적 프로젝트 계획

Cursor Canvas는 IDE 내부에 존재하는 시각적 계획 표면입니다. 아키텍처 다이어그램을 스케치하고, 기능 흐름을 매핑하며, 스프린트 작업을 계획하고, 팀과 시각적 컨텍스트를 공유할 수 있으며, 이 모든 것을 Cursor를 떠나지 않고 할 수 있습니다. 정적인 화이트보드와 달리 Canvas는 코드베이스와 통합되어 다이어그램을 실제 파일, 함수, 데이터 모델에 연결할 수 있습니다. 이 가이드는 첫 번째 캔버스 생성부터 게시, 그리고 악명 높은 "Canvas file not found" 오류 문제 해결까지 모든 것을 다룹니다.

Cursor Canvas란?

Canvas는 다음을 할 수 있는 시각적 작업 공간입니다:

• 아키텍처 다이어그램 그리기 박스, 화살표, 주석 사용
• 코드 아티팩트 연결 파일, 함수 또는 클래스를 캔버스로 드래그
• 기능 시각적 계획 코드를 작성하기 전에
• 팀과 공유 캔버스를 독립 링크로 게시
• 결정 주석 노트, TODO, 설계 근거 사용

Miro나 Figma와 같은 외부 도구와의 핵심 차이점은 Canvas가 컨텍스트 인식이라는 것입니다. 컴포넌트를 캔버스에 배치하면 해당 컴포넌트의 실제 파일 경로, 내보내기, 종속성을 알고 있습니다.

사전 요구 사항

• Cursor 버전 0.42 이상 (Canvas는 2024년 후반에 도입됨)
• Cursor에서 열린 프로젝트 폴더 (Canvas는 프로젝트 컨텍스트 내에서 작동)
• 게시 기능을 위한 Cursor 계정 (무료 티어로 충분)

첫 번째 캔버스 만들기

1단계: Canvas 에디터 열기

새 캔버스를 여는 세 가지 방법이 있습니다:

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 file not found"로 실패한다고 자주 보고합니다. 근본 원인은 Cursor가 영구 프로젝트 키를 찾을 수 없을 때 실행마다 임시 프로젝트 키를 생성하는 것입니다.

다음이 발생합니다:

1. Cursor를 열면 tmp_abc123과 같은 임시 프로젝트 키 할당
2. 캔버스를 만들고 작업하며 tmp_abc123과 연결
3. 게시 클릭
4. 게시 엔드포인트가 현재 프로젝트 키로 캔버스 조회
5. 키가 변경된 경우 (Cursor가 재시작되었기 때문) 조회 실패
6. "Canvas file not found" 표시

프로젝트 키 문제 수정

해결책 1: 영구 프로젝트 키 만들기

프로젝트 루트에 .cursor/project.json 파일 추가:

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

이렇게 하면 프로젝트 키가 Cursor 재시작 후에도 안정적으로 유지됩니다.

팁

설명적이고 고유한 프로젝트 키를 사용하세요. project1이나 test와 같은 일반적인 값을 사용하지 마세요. 머신의 두 프로젝트가 같은 키를 가지면 캔버스 조회가 충돌할 수 있으며 게시가 간헐적으로 실패합니다.

해결책 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 생태계 내에서 두 가지 컨텍스트로 사용 가능하며, 중요한 차이점이 있습니다.

독립형 Canvas (Cursor IDE)

이것은 Cursor 에디터 내에서 액세스하는 캔버스입니다:

• .cursor/canvases/ 디렉토리에 존재
• 열린 프로젝트에 직접 연결
• 탐색기에서 캔버스로 파일 드래그 가능
• .cursor/project.json의 프로젝트 키 사용
• 최적: 개발자용 다이어그램, 아키텍처 계획, 코드 매핑

Glass App Canvas

Glass는 Cursor의 독립형 시각 앱 (IDE와 분리)입니다. Glass 내의 Canvas:

• 프로젝트 디렉토리가 아닌 Glass 자체 저장소에 존재
• 프로젝트에 연결할 수 있지만 독립적으로 작동
• 다른 프로젝트 키 네임스페이스를 가짐 | 더 풍부한 시각적 요소(애니메이션, 인터랙티브 컴포넌트) 지원 | 최적: 프레젠테이션, 이해관계자 데모, 크로스 팀 공유

주요 차이점

기능	독립형 Canvas	Glass App Canvas
저장 위치	.cursor/canvases/	Glass 클라우드 저장소
프로젝트 키 소스	.cursor/project.json	Glass 프로젝트 설정
파일 드래그 앤 드롭	예, 탐색기에서	아니오, 가져오기 필요
실시간 협업	아니오	예
게시 범위	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 file not found"

이것은 가장 일반적인 오류입니다. 위의 프로젝트 키 문제 해결 단계를 따르세요. 해결되지 않으면:

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를 응답 불가능하게 만듭니다. 항상 전체 폴더가 아닌 특정 파일이나 함수를 추가하세요.

모범 사례

캔버스 집중 유지

하나의 캔버스는 하나의 질문에 답해야 합니다. 단일 "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 file not found" 오류는 실행마다 임시 프로젝트 키 메커니즘에 뿌리를 두고 있으며 .cursor/project.json에 영구 프로젝트 키를 만들어 완전히 해결됩니다. 독립형과 Glass App 캔버스의 차이점을 이해하면 각 컨텍스트에 올바른 도구를 사용할 수 있으며, 이 가이드의 시각적 워크플로 패턴을 따르면 계획이 더 효과적이고 아키텍처가 더 전달 가능해집니다.