계획 주석 추가: 네 가지 주석 유형 마스터

학습 후 할 수 있는 것

✅ 계획 텍스트를 선택하여 네 가지 유형의 주석(삭제, 교체, 삽입, 댓글) 추가
✅ type-to-comment 단축키로 직접 댓글 입력
✅ 주석에 이미지 첨부(참조 이미지, 스크린샷 등)
✅ 각 주석 유형의 의미와 사용 시나리오 이해
✅ 주석 내보낸 후의 Markdown 형식 확인

현재 겪고 있는 문제

문제 1: 특정 내용을 삭제해야 한다는 것은 알지만, 텍스트 선택 후 어떤 버튼을 클릭해야 할지 모름.

문제 2: 특정 코드 조각을 교체하고 싶은데, 도구 모음에 "삭제"와 "댓글"만 있고 "교체" 옵션이 없음.

문제 3: 여러 줄 텍스트를 선택하여 직접 댓글을 입력하고 싶은데, 매번 "Comment" 버튼을 먼저 클릭해야 하여 효율이 낮음.

문제 4: 특정 코드에 참조 이미지를 첨부하고 싶은데, 이미지 업로드 방법을 모름.

Plannotator가 도와드립니다:

명확한 버튼 아이콘으로 삭제, 교체, 삽입, 댓글의 차이를 한눈에 식별
type-to-comment 단축키로 버튼 클릭 없이 직접 입력
주석에 이미지 첨부 지원으로 참조 이미지 추가 편리
주석을 자동으로 구조화된 Markdown으로 변환하여 AI가 정확하게 이해

언제 사용하나요

사용 시나리오:

AI가 생성한 실행 계획을 검토하고 정확한 수정 피드백이 필요할 때
특정 내용이 불필요할 때(삭제)
특정 내용을 다른 방식으로 변경해야 할 때(교체)
특정 내용 뒤에 추가 설명이 필요할 때(삽입)
특정 내용에 대한 질문이나 제안이 있을 때(댓글)

사용하지 않는 시나리오:

계획을 전체적으로 승인하거나 거부할 때(주석 불필요, 직접 결정)
이미 코드 변경을 검토 중일 때(코드 검토 기능 사용)

🎒 시작 전 준비

사전 요구사항:

✅ 계획 검토 기초 튜토리얼 완료
✅ Plannotator 계획 검토 인터페이스를 트리거하는 방법 이해

이 수업에서 가정하는 사항:

Plannotator 계획 검토 페이지가 이미 열려 있음
페이지에 AI가 생성한 Markdown 계획이 표시됨

핵심 개념

주석 유형 상세 설명

Plannotator는 네 가지 계획 주석 유형을 지원합니다(전역 댓글 포함):

주석 유형	아이콘	용도	내용 입력 필요 여부
삭제 (DELETION)	🗑️	이 내용을 계획에서 제거해야 함을 표시	❌ 필요 없음
댓글 (COMMENT)	💬	선택한 내용에 대한 질문이나 제안	✅ 댓글 입력 필요
교체 (REPLACEMENT)	댓글로 구현	선택한 내용을 새 내용으로 교체	✅ 새 내용 입력 필요
삽입 (INSERTION)	댓글로 구현	선택한 내용 뒤에 새 내용 삽입	✅ 새 내용 입력 필요
전역 댓글 (GLOBAL_COMMENT)	페이지 하단 입력 상자	전체 계획에 대한 피드백	✅ 댓글 입력 필요

교체와 삽입에 독립 버튼이 없는 이유는 무엇인가요?

소스 코드 구현 관점에서 볼 때, 교체와 삽입은 본질적으로 특수한 댓글 유형(packages/ui/utils/parser.ts:287-296)이기 때문입니다:

교체: 댓글 내용을 교체할 새 텍스트로 사용
삽입: 댓글 내용을 삽입할 새 텍스트로 사용

둘 다 댓글 (COMMENT) 버튼으로 생성하며, 차이점은 의도를 어떻게 설명하느냐입니다.

도구 모음 작업 흐름

텍스트 선택 → 도구 모음 팝업(메뉴 단계)
                  │
                  ├── Delete 클릭 → 삭제 주석 즉시 생성
                  ├── Comment 클릭 → 입력 단계 진입 → 내용 입력 → 저장
                  └── 문자 직접 입력 → type-to-comment → 자동 입력 단계 진입

두 단계의 차이점:

메뉴 단계: 작업 유형 선택(삭제, 댓글, 취소)
입력 단계: 댓글 내용 입력 또는 이미지 첨부(댓글/교체에서 진입)

type-to-comment 단축키

이는 효율을 높이는 핵심 기능입니다. 텍스트를 선택한 후 바로 입력을 시작(아무 버튼도 클릭할 필요 없음)하면 도구 모음이 자동으로:

"댓글" 모드로 전환
입력한 첫 번째 문자를 입력 상자에 넣음
커서를 자동으로 입력 상자 끝에 배치

소스 코드 구현 위치: packages/ui/components/AnnotationToolbar.tsx:127-147

따라 하기

1단계: 계획 검토 시작

이유 주석 추가 연습을 위한 실제 계획이 필요합니다.

작업

Claude Code 또는 OpenCode에서 계획 검토를 트리거:

bash

# Claude Code 예시: AI가 계획을 생성한 후 ExitPlanMode를 호출
"사용자 인증 기능의 실행 계획을 생성해주세요"

# AI가 계획을 완료할 때까지 기다리면, Plannotator가 브라우저에서 자동으로 열림

다음이 보여야 합니다:

브라우저에서 계획 검토 페이지가 열림
페이지에 Markdown 형식의 실행 계획이 표시됨

2단계: 삭제 주석 추가

이유 삭제 주석은 최종 계획에 포함되지 않아야 할 내용을 표시하는 데 사용됩니다.

작업

계획에서 불필요한 단락 찾기(예: 관련 없는 기능 설명)
마우스로 텍스트 선택
도구 모음이 자동으로 팝업되면 삭제 버튼(🗑️) 클릭

다음이 보여야 합니다:

선택된 텍스트가 삭제 스타일로 표시됨(일반적으로 취소선 또는 빨간색 배경)
도구 모음이 자동으로 닫힘

삭제 주석의 특징

삭제 주석은 내용을 입력할 필요가 없습니다. 삭제 버튼을 클릭하면 주석이 즉시 생성됩니다.

3단계: type-to-comment로 댓글 추가

이유 댓글은 가장 많이 사용되는 주석 유형이며, type-to-comment를 사용하면 버튼 클릭 횟수를 줄일 수 있습니다.

작업

계획에서 텍스트 선택(예: 특정 함수명 또는 설명)
아무 버튼도 클릭하지 말고 바로 입력 시작
댓글 내용 입력(예: "이 함수명이 명확하지 않습니다")
Enter 키로 저장 또는 Save 버튼 클릭

다음이 보여야 합니다:

도구 모음이 자동으로 입력 상자 모드로 전환됨
입력한 첫 번째 문자가 이미 입력 상자에 있음
커서가 자동으로 입력 상자 끝에 배치됨
Enter를 누르면 선택된 텍스트가 댓글 스타일로 표시됨(일반적으로 노란색 배경)

type-to-comment 단축키

Enter: 주석 저장(입력 상자에 내용이 있는 경우)
Shift + Enter: 줄 바꿈(여러 줄 댓글 입력 시 사용)
Escape: 입력 취소, 메뉴 단계로 돌아감

4단계: 교체 주석 추가

이유 교체 주석은 선택한 내용을 새 내용으로 교체하는 데 사용되며, AI는 주석에 따라 계획을 수정합니다.

작업

계획에서 텍스트 선택(예: "JWT token을 사용하여 인증")
type-to-comment 또는 댓글 버튼 사용
입력 상자에 새 내용 입력(예: "session cookie를 사용하여 인증")
Enter로 저장

다음이 보여야 합니다:

선택된 텍스트가 댓글 스타일로 표시됨
주석 사이드바에 댓글 내용이 표시됨

내보낸 후 형식(packages/ui/utils/parser.ts:292-296):

markdown

## 1. Change this

**From:**

JWT token을 사용하여 인증


**To:**

session cookie를 사용하여 인증

교체와 삭제의 차이

삭제: 내용을 직접 제거하며, 이유를 설명할 필요 없음
교체: 새 내용으로 이전 내용을 교체하며, 새 내용을 지정해야 함

5단계: 삽입 주석 추가

이유 삽입 주석은 선택한 내용 뒤에 추가 설명이나 코드 조각을 보충하는 데 사용됩니다.

작업

계획에서 텍스트 선택(예: 함수 서명의 끝)
type-to-comment 또는 댓글 버튼 사용
입력 상자에 삽입할 내용 입력(예: ", 인증 실패 처리 필요")
Enter로 저장

다음이 보여야 합니다:

선택된 텍스트가 댓글 스타일로 표시됨
주석 사이드바에 댓글이 표시됨

내보낸 후 형식(packages/ui/utils/parser.ts:287-290):

markdown

## 1. Add this

, 인증 실패 처리 필요

6단계: 주석에 이미지 첨부

이유 때로는 텍스트 설명만으로는 직관적이지 않아 참조 이미지나 스크린샷을 첨부해야 할 때가 있습니다.

작업

텍스트를 선택하고 입력 단계 진입(댓글 버튼 클릭 또는 type-to-comment)
도구 모음 입력 상자 옆에서 첨부 버튼(📎) 클릭
업로드할 이미지 선택(PNG, JPEG, WebP 형식 지원)
댓글 내용 계속 입력 가능
Enter로 저장

다음이 보여야 합니다:

이미지 축소판이 입력 상자에 표시됨
저장 후 이미지가 주석 사이드바에 표시됨

이미지 저장 위치

업로드된 이미지는 로컬 /tmp/plannotator 디렉토리에 저장됩니다(소스 코드 위치: packages/server/index.ts:163). 임시 파일을 정리하면 이미지가 손실됩니다.

7단계: 전역 댓글 추가

이유 전체 계획에 대한 피드백(특정 텍스트에 대한 것이 아닌)이 있을 때 전역 댓글을 사용합니다.

작업

페이지 하단에서 입력 상자 찾기(레이블은 "Add a general comment about the plan..."일 수 있음)
댓글 내용 입력
Enter로 저장 또는 전송 버튼 클릭

다음이 보여야 합니다:

댓글이 페이지 하단의 전역 댓글 영역에 나타남
댓글이 독립 카드로 표시되며, 텍스트 블록과 연결되지 않음

전역 댓글 vs 텍스트 댓글

전역 댓글: 전체 계획에 대한 피드백, 특정 텍스트와 연결되지 않음(예: "전체 계획에 성능 고려가 부족함")
텍스트 댓글: 특정 텍스트에 대한 피드백, 해당 텍스트를 강조 표시

체크포인트 ✅

위 단계를 완료한 후 다음을 수행할 수 있어야 합니다:

[ ] 최소 하나의 삭제 주석 성공적으로 추가
[ ] type-to-comment로 댓글 추가
[ ] 교체 및 삽입 주석 추가
[ ] 주석에 이미지 첨부
[ ] 전역 댓글 추가
[ ] 오른쪽 사이드바에서 모든 주석 목록 확인

주의할 점

문제 1: "교체" 버튼을 찾을 수 없음

잘못된 작업:

텍스트 선택 후 도구 모음에 Delete와 Comment만 있고 Replace 또는 Insert 버튼이 없음

올바른 방법:

교체와 삽입은 댓글 (COMMENT) 버튼으로 구현
댓글 내용에 의도(교체 또는 삽입) 설명
AI가 댓글 내용을 통해 의도 이해

문제 2: type-to-comment 작동 안 함

가능한 원인:

텍스트 선택 안 함
먼저 버튼을 클릭하여 도구 모음이 이미 입력 단계로 진입
특수 키 입력(Ctrl, Alt, Escape 등)

올바른 방법:

먼저 텍스트를 선택하고 도구 모음이 메뉴 단계(Delete, Comment 버튼 있음)에 표시되는지 확인
일반 문자(문자, 숫자, 문장 부호) 직접 입력
기능 키 누르지 않기

문제 3: 이미지 업로드 후 찾을 수 없음

가능한 원인:

이미지가 /tmp/plannotator 디렉토리에 저장됨
시스템이 임시 파일을 정리함

올바른 방법:

이미지를 장기간 보존해야 하는 경우 프로젝트 디렉토리로 복사 권장
주석 내보내기 시 이미지 경로는 절대 경로이며, 다른 도구에서 액세스할 수 있는지 확인

문제 4: `Enter`를 눌러 줄 바꿈했는데 주석이 저장됨

잘못된 작업:

입력 상자에서 줄 바꿈을 위해 Enter를 눌렀는데 주석이 저장됨

올바른 방법:

Shift + Enter로 줄 바꿈
Enter 키는 주석 저장 전용

이 수업 요약

네 가지 주석 유형:

삭제 (DELETION): 계획에 포함되지 않기를 원하는 내용 표시
교체 (REPLACEMENT): 선택한 내용을 새 내용으로 교체(댓글로 구현)
삽입 (INSERTION): 선택한 내용 뒤에 내용 보충(댓글로 구현)
댓글 (COMMENT): 선택한 내용에 대한 질문이나 제안
전역 댓글 (GLOBAL_COMMENT): 전체 계획에 대한 피드백

핵심 작업:

선택 → 도구 모음 팝업 → 작업 유형 선택
type-to-comment: 문자 직접 입력, 자동 댓글 모드 진입
Shift + Enter: 줄 바꿈; Enter: 저장
첨부 버튼: 주석에 이미지 업로드

주석 내보내기 형식:

삭제: ## Remove this + 원본 텍스트
삽입: ## Add this + 새 텍스트
교체: ## Change this + From/To 대비
댓글: ## Feedback on: "..." + 댓글 내용

다음 수업 예고

다음 수업에서는 **이미지 주석 추가**를 학습합니다.
다음을 배우게 됩니다:
계획 검토에서 이미지를 첨부하는 방법
브러시, 화살표, 원 도구를 사용하여 주석 추가
참조 피드백으로 주석 이미지

부록: 소스 코드 참조

소스 코드 위치 보려면 클릭

업데이트 시간: 2026-01-24

기능	파일 경로	행 번호
주석 유형 열거형 정의	`packages/ui/types.ts`	1-7
Annotation 인터페이스	`packages/ui/types.ts`	11-33
주석 도구 모음 컴포넌트	`packages/ui/components/AnnotationToolbar.tsx`	29-272
---	---	---
주석 내보내기 형식화	`packages/ui/utils/parser.ts`	246-323
Markdown을 Blocks로 파싱	`packages/ui/utils/parser.ts`	70-244
Viewer 컴포넌트(텍스트 선택 처리)	`packages/ui/components/Viewer.tsx`	66-350

핵심 상수:

AnnotationType.DELETION = 'DELETION': 삭제 주석 유형
AnnotationType.INSERTION = 'INSERTION': 삽입 주석 유형
AnnotationType.REPLACEMENT = 'REPLACEMENT': 교체 주석 유형
AnnotationType.COMMENT = 'COMMENT': 댓글 주석 유형
AnnotationType.GLOBAL_COMMENT = 'GLOBAL_COMMENT': 전역 댓글 유형

핵심 함수:

exportDiff(blocks, annotations): 주석을 Markdown 형식으로 내보내며, From/To 대비 포함
parseMarkdownToBlocks(markdown): Markdown을 선형 Block 배열로 파싱
createAnnotationFromSource(): 텍스트 선택에서 Annotation 객체 생성

계획 주석 추가: 네 가지 주석 유형 마스터 ​

학습 후 할 수 있는 것 ​

현재 겪고 있는 문제 ​

언제 사용하나요 ​

🎒 시작 전 준비 ​

핵심 개념 ​

주석 유형 상세 설명 ​

도구 모음 작업 흐름 ​

type-to-comment 단축키 ​

따라 하기 ​

1단계: 계획 검토 시작 ​

2단계: 삭제 주석 추가 ​

3단계: type-to-comment로 댓글 추가 ​

4단계: 교체 주석 추가 ​

5단계: 삽입 주석 추가 ​

6단계: 주석에 이미지 첨부 ​

7단계: 전역 댓글 추가 ​

체크포인트 ✅ ​

주의할 점 ​

문제 1: "교체" 버튼을 찾을 수 없음 ​

문제 2: type-to-comment 작동 안 함 ​

문제 3: 이미지 업로드 후 찾을 수 없음 ​

문제 4: Enter를 눌러 줄 바꿈했는데 주석이 저장됨 ​

이 수업 요약 ​

다음 수업 예고 ​

부록: 소스 코드 참조 ​

계획 주석 추가: 네 가지 주석 유형 마스터

학습 후 할 수 있는 것

현재 겪고 있는 문제

언제 사용하나요

🎒 시작 전 준비

핵심 개념

주석 유형 상세 설명

도구 모음 작업 흐름

type-to-comment 단축키

따라 하기

1단계: 계획 검토 시작

2단계: 삭제 주석 추가

3단계: type-to-comment로 댓글 추가

4단계: 교체 주석 추가

5단계: 삽입 주석 추가

6단계: 주석에 이미지 첨부

7단계: 전역 댓글 추가

체크포인트 ✅

주의할 점

문제 1: "교체" 버튼을 찾을 수 없음

문제 2: type-to-comment 작동 안 함

문제 3: 이미지 업로드 후 찾을 수 없음

문제 4: `Enter`를 눌러 줄 바꿈했는데 주석이 저장됨

이 수업 요약

다음 수업 예고

부록: 소스 코드 참조