코드 주석 추가: 라인별 코멘트, 제안 및 관심 사항

이 강의를 마치면 할 수 있는 것

✅ 코드 diff에서 라인별 주석 추가 (comment/suggestion/concern)
✅ 코드 수정에 대한 제안 코드(suggestedCode) 제공
✅ 주의가 필요한 코드 구간 표시 (concern)
✅ 모든 주석 조회 및 관리 (사이드바)
✅ 세 가지 주석 유형의 사용 시나리오 이해
✅ 피드백을 Markdown 형식으로 내보내기

현재 겪고 있는 어려움

문제 1: 코드 변경 사항을 리뷰할 때 터미널에서 diff만 볼 수 있고, "3번째 줄에 문제가 있습니다", "XXX로 수정하는 것이 좋겠습니다"라고 작성해야 하는데 위치가 정확하지 않습니다.

문제 2: 어떤 코드는 단순히 코멘트(comment)만 달고 싶고, 어떤 것은 수정 제안(suggestion)을 하고 싶고, 어떤 것은 심각한 문제라 주의(concern)가 필요한데, 이를 구분해주는 도구가 없습니다.

문제 3: 특정 함수에 수정 제안을 하고 싶은데, 코드 스니펫을 AI에게 어떻게 전달해야 할지 모르겠습니다.

문제 4: 여러 주석을 추가한 후, 어디를 리뷰했는지 잊어버리고 전체 개요가 없습니다.

Plannotator가 도와드립니다:

라인 번호를 클릭하면 코드 범위를 선택할 수 있어 라인 단위로 정확합니다
세 가지 주석 유형(comment/suggestion/concern)이 각각 다른 시나리오에 대응합니다
제안 코드를 첨부할 수 있어 AI가 수정 방안을 직접 볼 수 있습니다
사이드바에 모든 주석이 나열되어 원클릭으로 이동할 수 있습니다

언제 이 기능을 사용하나요

사용 시나리오:

/plannotator-review 명령 실행 후 코드 변경 사항 확인
특정 코드 라인에 피드백을 제공해야 할 때
AI에게 코드 수정 제안을 제공하고 싶을 때
잠재적 문제나 위험 지점을 표시해야 할 때

적합하지 않은 시나리오:

AI가 생성한 구현 계획 리뷰 (계획 리뷰 기능 사용)
diff를 빠르게 훑어보기만 할 때 (코드 리뷰 기본 기능 사용)

🎒 시작하기 전 준비

사전 조건:

✅ Plannotator CLI 설치 완료 (빠른 시작 참조)
✅ 코드 리뷰 기본 학습 완료 (코드 리뷰 기본 참조)
✅ 로컬에 Git 저장소가 있고 커밋되지 않은 변경 사항이 있음

실행 방법:

OpenCode 또는 Claude Code에서 /plannotator-review 명령 실행

핵심 개념

코드 주석이란

코드 주석은 Plannotator 코드 리뷰의 핵심 기능으로, Git diff에서 라인별 피드백을 추가하는 데 사용됩니다. 라인 번호를 클릭하여 코드 범위를 선택하면 특정 코드 라인에 정확하게 코멘트, 제안 또는 관심 사항을 추가할 수 있으며, 주석은 diff 아래에 표시되어 AI가 피드백 의도를 정확하게 이해할 수 있습니다.

왜 코드 주석이 필요한가요?

코드 리뷰에서 특정 코드 라인에 피드백을 제공해야 합니다. "5번째 줄에 문제가 있습니다", "XXX로 수정하는 것이 좋겠습니다"라고 텍스트로만 설명하면 AI가 직접 코드를 찾아야 하므로 오류가 발생하기 쉽습니다. Plannotator를 사용하면 라인 번호를 클릭하여 코드 범위를 선택하고 해당 위치에 직접 주석을 추가할 수 있습니다. 주석은 diff 아래에 표시되며(GitHub 스타일), AI가 어떤 코드에 대한 제안인지 정확하게 볼 수 있습니다.

워크플로우

┌─────────────────┐
│  /plannotator-   │  명령 실행
│  review 명령      │
└────────┬────────┘
         │
         │ git diff 실행
         ▼
┌─────────────────┐
│  Diff Viewer    │  ← 코드 diff 표시
│  (split/unified) │
└────────┬────────┘
         │
         │ 라인 번호 클릭 / Hover +
         ▼
┌─────────────────┐
│  코드 범위 선택   │
│  (lineStart-    │
│   lineEnd)      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  주석 추가       │  ← 툴바 팝업
│  - Comment     │     코멘트 내용 입력
│  - Suggestion  │     선택: 제안 코드 제공
│  - Concern     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  주석 표시       │  diff 아래에
│  (GitHub 스타일) │  사이드바에 모든 주석 나열
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  피드백 내보내기  │  Send Feedback
│  (Markdown)     │  AI가 구조화된 피드백 수신
└─────────────────┘

주석 유형

Plannotator는 세 가지 코드 주석 유형을 지원하며, 각각 다른 용도가 있습니다:

주석 유형	용도	일반적인 시나리오	제안 코드
Comment	코드에 대한 일반적인 피드백 제공	"이 로직을 단순화할 수 있습니다", "변수 이름이 명확하지 않습니다"	선택
Suggestion	구체적인 코드 수정 제안 제공	"for 루프 대신 map 사용 권장", "Promise.then 대신 await 사용"	권장
Concern	잠재적 문제나 위험 지점 표시	"이 SQL 쿼리에 성능 문제가 있을 수 있습니다", "오류 처리가 누락되었습니다"	선택

주석 유형 선택 가이드

Comment: "제안하지만 강제하지 않음"에 사용, 예: 코드 스타일, 최적화 방향
Suggestion: "수정을 강력히 권장"하고 명확한 수정 방안이 있을 때 사용
Concern: "반드시 주의해야 할 문제"에 사용, 예: 버그, 성능 위험, 보안 취약점

Comment vs Suggestion vs Concern

시나리오	선택 유형	예시 텍스트
코드가 작동하지만 최적화 여지가 있음	Comment	"이 부분은 async/await로 단순화할 수 있습니다"
코드에 명확한 개선 방안이 있음	Suggestion	"`Array.from()` 사용을 권장합니다 (스프레드 연산자 대신)" (코드 첨부)
버그나 심각한 문제 발견	Concern	"여기에 null 체크가 누락되어 런타임 오류가 발생할 수 있습니다"

따라하기

1단계: 코드 리뷰 시작

터미널에서 실행:

bash

/plannotator-review

확인해야 할 것:

브라우저가 자동으로 코드 리뷰 인터페이스를 엽니다
git diff 내용이 표시됩니다 (기본값은 git diff HEAD)
왼쪽은 파일 트리, 가운데는 diff viewer, 오른쪽은 주석 사이드바입니다

2단계: diff 내용 탐색

브라우저에서 코드 변경 사항 확인:

기본값은 split 뷰 (좌우 비교)
unified 뷰 (상하 비교)로 전환 가능
파일 트리에서 파일명을 클릭하여 보는 파일 전환

3단계: 코드 라인 선택 및 주석 추가

방법 1: Hover하여 "+" 버튼 클릭

주석을 추가할 코드 라인에 마우스를 올립니다
오른쪽에 + 버튼이 나타납니다 (diff 라인에서만 표시)
+ 버튼을 클릭합니다
주석 툴바가 팝업됩니다

방법 2: 라인 번호 직접 클릭

라인 번호를 클릭합니다 (예: L10), 단일 라인 선택
다른 라인 번호를 클릭합니다 (예: L15), 여러 라인 범위 선택
범위 선택 후 툴바가 자동으로 팝업됩니다

확인해야 할 것:

툴바에 선택된 라인 번호가 표시됩니다 (예: Line 10 또는 Lines 10-15)
툴바에 텍스트 입력 상자가 있습니다 (Leave feedback...)
선택적으로 "Add suggested code" 버튼이 있습니다

4단계: Comment 주석 추가

시나리오: 코드에 제안을 제공하지만 수정을 강제하지 않음

툴바의 텍스트 상자에 코멘트 내용을 입력합니다
선택: Add suggested code를 클릭하여 제안 코드를 입력합니다
Add Comment 버튼을 클릭합니다

예시:

코멘트 내용: 이 함수의 매개변수 이름이 명확하지 않습니다. fetchUserData로 이름을 변경하는 것이 좋겠습니다

확인해야 할 것:

툴바가 사라집니다
주석이 diff 아래에 표시됩니다 (파란색 박스)
사이드바에 새 주석 기록이 추가됩니다
제안 코드를 제공한 경우 주석 아래에 표시됩니다 (코드 블록 형식)

5단계: Suggestion 주석 추가

시나리오: 명확한 코드 수정 방안을 제공하고 AI가 직접 채택하기를 원함

툴바의 텍스트 상자에 제안 설명을 입력합니다 (선택)
Add suggested code를 클릭합니다
나타나는 코드 입력 상자에 제안 코드를 입력합니다
Add Comment 버튼을 클릭합니다

예시:

제안 설명: async/await를 사용하여 Promise 체인 단순화

제안 코드:
async function fetchData() {
  const response = await fetch(url);
  const data = await response.json();
  return data;
}

확인해야 할 것:

주석이 diff 아래에 표시됩니다 (파란색 박스)
제안 코드가 코드 블록 형식으로 표시되며 "Suggested:" 라벨이 붙습니다
사이드바에 제안 코드의 첫 번째 줄이 표시됩니다 (말줄임표 포함)

6단계: Concern 주석 추가

시나리오: 잠재적 문제나 위험 지점을 표시하여 AI에게 주의를 환기

참고: 현재 버전의 Plannotator UI에서 주석 유형은 기본적으로 Comment입니다. Concern을 표시해야 하는 경우 주석 텍스트에 명시적으로 표시할 수 있습니다.

툴바의 텍스트 상자에 관심 사항 설명을 입력합니다
Concern: 또는 ⚠️ 등의 마커를 사용하여 이것이 관심 사항임을 명확히 합니다
Add Comment 버튼을 클릭합니다

예시:

Concern: 여기에 null 체크가 누락되어 user가 null이면 런타임 오류가 발생합니다

추가 권장:
if (!user) return null;

확인해야 할 것:

주석이 diff 아래에 표시됩니다
사이드바에 주석 내용이 표시됩니다

7단계: 주석 조회 및 관리

사이드바에서 모든 주석 조회:

오른쪽 사이드바에 모든 주석 목록이 표시됩니다
각 주석에 표시되는 내용:
- 파일명 (마지막 경로 구성 요소만 표시)
- 라인 번호 범위 (예: L10 또는 L10-L15)
- 작성자 (협업 리뷰인 경우)
- 타임스탬프 (예: 5m, 2h, 1d)
- 주석 내용 (최대 2줄 표시)
- 제안 코드 미리보기 (첫 번째 줄)

주석 클릭하여 이동:

사이드바에서 주석을 클릭합니다
Diff viewer가 자동으로 해당 위치로 스크롤됩니다
해당 주석이 하이라이트됩니다

주석 삭제:

사이드바에서 주석에 마우스를 올립니다
오른쪽 상단의 × 버튼을 클릭합니다
주석이 삭제되고 diff의 하이라이트가 사라집니다

확인해야 할 것:

사이드바에 주석 수가 표시됩니다 (예: Annotations: 3)
주석 클릭 후 diff viewer가 해당 라인으로 부드럽게 스크롤됩니다
주석 삭제 후 수가 업데이트됩니다

8단계: 피드백 내보내기

모든 주석을 완료한 후 페이지 하단의 Send Feedback 버튼을 클릭합니다.

확인해야 할 것:

브라우저가 자동으로 닫힙니다
터미널에 Markdown 형식의 피드백 내용이 표시됩니다
AI가 구조화된 피드백을 받아 자동으로 응답할 수 있습니다

내보내기된 Markdown 형식:

markdown

# Code Review Feedback

## src/app/api/users.ts

### Line 10 (new)
이 로직을 단순화할 수 있습니다. async/await 사용을 권장합니다

### Lines 15-20 (new)
**Suggested code:**
```typescript
async function fetchUserData() {
  const response = await fetch(url);
  return await response.json();
}

Line 25 (old)

Concern: 여기에 null 체크가 누락되어 user가 null이면 런타임 오류가 발생합니다


::: tip 피드백 복사
피드백 내용을 수동으로 복사해야 하는 경우 사이드바 하단의 **Copy Feedback** 버튼을 클릭하여 Markdown 형식의 피드백을 클립보드에 복사할 수 있습니다.
:::

## 체크포인트 ✅

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

- [ ] 코드 diff에서 라인 번호 클릭 또는 Hover "+" 버튼으로 코드 라인 선택
- [ ] Comment 주석 추가 (일반적인 코멘트)
- [ ] Suggestion 주석 추가 (제안 코드 첨부)
- [ ] Concern 주석 추가 (잠재적 문제 표시)
- [ ] 사이드바에서 모든 주석 조회, 클릭하여 해당 위치로 이동
- [ ] 불필요한 주석 삭제
- [ ] 피드백을 Markdown 형식으로 내보내기
- [ ] 피드백 내용을 클립보드에 복사

**특정 단계가 실패한 경우** 참조:
- [자주 묻는 질문](../../faq/common-problems/)
- [코드 리뷰 기본](../code-review-basics/)
- [문제 해결](../../faq/troubleshooting/)

## 주의사항

**일반적인 오류 1**: 라인 번호를 클릭해도 툴바가 팝업되지 않음

**원인**: 파일명을 클릭했거나 라인 번호가 diff 범위 내에 없을 수 있습니다.

**해결 방법**:
- diff 라인의 라인 번호를 클릭했는지 확인합니다 (녹색 또는 빨간색 라인)
- 삭제된 라인(빨간색)의 경우 왼쪽 라인 번호를 클릭합니다
- 추가된 라인(녹색)의 경우 오른쪽 라인 번호를 클릭합니다

**일반적인 오류 2**: 여러 라인 선택 후 주석이 잘못된 위치에 표시됨

**원인**: side(old/new)가 올바르지 않습니다.

**해결 방법**:
- 이전 코드(deletions)를 선택했는지 새 코드(additions)를 선택했는지 확인합니다
- 주석은 범위의 마지막 라인 아래에 표시됩니다
- 위치가 잘못된 경우 주석을 삭제하고 다시 추가합니다

**일반적인 오류 3**: 제안 코드 추가 후 코드 형식이 깨짐

**원인**: 제안 코드에 특수 문자나 들여쓰기 문제가 있을 수 있습니다.

**해결 방법**:
- 제안 코드 입력 상자에서 들여쓰기가 올바른지 확인합니다
- 고정폭 글꼴을 사용하여 제안 코드를 편집합니다
- 줄 바꿈이 있는 경우 직접 Enter 대신 `Shift + Enter`를 사용합니다

**일반적인 오류 4**: 사이드바에서 새로 추가된 주석이 보이지 않음

**원인**: 사이드바가 새로고침되지 않았거나 주석이 다른 파일에 추가되었을 수 있습니다.

**해결 방법**:
- 파일을 전환한 후 다시 돌아옵니다
- 주석이 현재 보고 있는 파일에 추가되었는지 확인합니다
- 브라우저 페이지를 새로고침합니다 (제출되지 않은 주석이 손실될 수 있음)

**일반적인 오류 5**: 피드백 내보내기 후 AI가 제안대로 수정하지 않음

**원인**: AI가 주석의 의도를 올바르게 이해하지 못했거나 제안이 실행 불가능할 수 있습니다.

**해결 방법**:
- 더 명확한 주석을 사용합니다 (Suggestion이 Comment보다 더 명확함)
- 제안 코드에 이유를 설명하는 주석을 추가합니다
- 문제가 지속되면 피드백을 다시 보내고 주석 내용을 조정합니다

## 이번 강의 요약

코드 주석은 Plannotator 코드 리뷰의 핵심 기능으로, 코드 문제를 정확하게 피드백할 수 있습니다:

**핵심 작업**:
1. **실행**: `/plannotator-review` 실행, 브라우저가 자동으로 diff viewer 열기
2. **탐색**: 코드 변경 사항 확인 (split/unified 뷰 전환)
3. **선택**: 라인 번호 클릭 또는 Hover "+" 버튼으로 코드 범위 선택
4. **주석**: Comment/Suggestion/Concern 주석 추가
5. **관리**: 사이드바에서 주석 조회, 이동, 삭제
6. **내보내기**: Send Feedback, AI가 구조화된 피드백 수신

**주석 유형**:
- **Comment**: 일반적인 코멘트, 제안하지만 강제하지 않음
- **Suggestion**: 수정을 명확히 권장, 제안 코드 첨부
- **Concern**: 잠재적 문제나 위험 지점 표시

**모범 사례**:
- Suggestion 사용 시 가능한 완전한 실행 가능 코드 제공
- 성능이나 보안 문제는 Concern으로 표시
- 주석 내용은 구체적으로, 모호한 설명 피하기 (예: "이건 좋지 않습니다")
- 이미지를 첨부하여 설명 보완 가능 (이미지 주석 기능 사용)

## 다음 강의 예고

> 다음 강의에서는 **[Diff 뷰 전환](../code-review-diff-types/)**을 배웁니다.
>
> 배울 내용:
> - 다양한 diff 유형 전환 방법 (uncommitted/staged/last commit/branch)
> - 각 diff 유형의 사용 시나리오
> - 여러 diff 유형 간 빠른 전환 방법

---

## 부록: 소스 코드 참조

<details>
<summary><strong>클릭하여 소스 코드 위치 보기</strong></summary>

> 업데이트 날짜: 2026-01-24

| 기능 | 파일 경로 | 라인 번호 |
| --- | --- | --- |
| CodeAnnotation 타입 정의 | [`packages/ui/types.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/ui/types.ts#L53-L56) | 53-56 |
| CodeAnnotation 인터페이스 | [`packages/ui/types.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/ui/types.ts#L55-L66) | 55-66 |
| DiffViewer 컴포넌트 | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L1-L349) | 1-349 |
| ReviewPanel 컴포넌트 | [`packages/review-editor/components/ReviewPanel.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/ReviewPanel.tsx#L1-L211) | 1-211 |
| 피드백 Markdown 내보내기 | [`packages/review-editor/App.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx#L86-L126) | 86-126 |
| Hover "+" 버튼 | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L180-L199) | 180-199 |
| 주석 툴바 | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L267-L344) | 267-344 |
| 주석 렌더링 | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L140-L177) | 140-177 |

**주요 타입**:
- `CodeAnnotationType`: 코드 주석 유형 ('comment' | 'suggestion' | 'concern') (`packages/ui/types.ts:53`)
- `CodeAnnotation`: 코드 주석 인터페이스 (`packages/ui/types.ts:55-66`)
- `SelectedLineRange`: 선택된 코드 범위 (`packages/ui/types.ts:77-82`)

**주요 함수**:
- `exportReviewFeedback()`: 주석을 Markdown 형식으로 변환 (`packages/review-editor/App.tsx:86`)
- `renderAnnotation()`: diff에서 주석 렌더링 (`packages/review-editor/components/DiffViewer.tsx:140`)
- `renderHoverUtility()`: Hover "+" 버튼 렌더링 (`packages/review-editor/components/DiffViewer.tsx:180`)

**API 라우트**:
- `POST /api/feedback`: 리뷰 피드백 제출 (`packages/server/review.ts`)
- `GET /api/diff`: git diff 가져오기 (`packages/server/review.ts:111`)
- `POST /api/diff/switch`: diff 유형 전환 (`packages/server/review.ts`)

**비즈니스 규칙**:
- 기본적으로 커밋되지 않은 diff 조회 (`git diff HEAD`) (`packages/server/review.ts:111`)
- 주석은 범위의 마지막 라인 아래에 표시 (GitHub 스타일) (`packages/review-editor/components/DiffViewer.tsx:81`)
- 주석에 제안 코드 첨부 지원 (`suggestedCode` 필드) (`packages/ui/types.ts:63`)

</details>

코드 주석 추가: 라인별 코멘트, 제안 및 관심 사항 ​

이 강의를 마치면 할 수 있는 것 ​

현재 겪고 있는 어려움 ​

언제 이 기능을 사용하나요 ​

🎒 시작하기 전 준비 ​

핵심 개념 ​

코드 주석이란 ​

워크플로우 ​

주석 유형 ​

Comment vs Suggestion vs Concern ​

따라하기 ​

1단계: 코드 리뷰 시작 ​

2단계: diff 내용 탐색 ​

3단계: 코드 라인 선택 및 주석 추가 ​

4단계: Comment 주석 추가 ​

5단계: Suggestion 주석 추가 ​

6단계: Concern 주석 추가 ​

7단계: 주석 조회 및 관리 ​

8단계: 피드백 내보내기 ​

Line 25 (old) ​

코드 주석 추가: 라인별 코멘트, 제안 및 관심 사항

이 강의를 마치면 할 수 있는 것

현재 겪고 있는 어려움

언제 이 기능을 사용하나요

🎒 시작하기 전 준비

핵심 개념

코드 주석이란

워크플로우

주석 유형

Comment vs Suggestion vs Concern

따라하기

1단계: 코드 리뷰 시작

2단계: diff 내용 탐색

3단계: 코드 라인 선택 및 주석 추가

4단계: Comment 주석 추가

5단계: Suggestion 주석 추가

6단계: Concern 주석 추가

7단계: 주석 조회 및 관리

8단계: 피드백 내보내기

Line 25 (old)