코드 리뷰 기초: /plannotator-review로 Git Diff 검토

학습 후 할 수 있는 것

✅ /plannotator-review 명령어로 Git Diff 검토
✅ side-by-side 및 unified 뷰 간 전환
✅ 행 번호 클릭으로 코드 범위 선택, 행 수준 주석 추가
✅ 다양한 유형의 주석 추가 (comment/suggestion/concern)
✅ 다른 diff 유형 전환 (uncommitted/staged/last commit/branch)
✅ 리뷰 피드백을 AI Agent로 전송

현재 겪고 있는 문제

문제 1: git diff로 코드 변경을 확인할 때, 터미널에서 출력이 스크롤되어 변경 내용을 전체적으로 이해하기 어렵습니다.

문제 2: Agent에 코드 문제를 피드백할 때, "10번째 줄에 문제가 있다", "이 함수를 수정하라"와 같이 텍스트로만 설명해야 해서 모호함이 발생하기 쉽습니다.

문제 3: Agent가 구체적으로 어떤 파일을 수정했는지 알 수 없어, 대량의 변경에서 핵심 부분에 집중하기 어렵습니다.

문제 4: 코드를 리뷰한 후, 구조화된 피드백을 Agent에 전송하여 제안에 따라 다시 수정하게 하고 싶습니다.

Plannotator가 도와드립니다:

Git Diff 시각화, side-by-side 및 unified 두 가지 뷰 지원
행 번호 클릭으로 코드 범위 선택, 문제 위치 정확하게 표시
행 수준 주석 추가 (comment/suggestion/concern), 제안 코드 포함
원클릭으로 diff 유형 전환 (uncommitted, staged, last commit, branch)
주석이 자동으로 Markdown으로 변환되어 Agent가 피드백을 정확하게 이해

언제 이 기능을 사용

사용 시나리오:

Agent가 코드 수정을 완료한 후 변경 내용을 검토해야 할 때
코드를 커밋하기 전 자신의 변경을 전체적으로 확인하고 싶을 때
팀과 협업할 때 구조화된 피드백으로 코드 문제를 전달해야 할 때
여러 diff 유형 간에 전환하고 싶을 때 (커밋되지 않음 vs 스테이지됨 vs 마지막 커밋)

사용하지 않는 시나리오:

AI가 생성한 실행 계획을 검토 (계획 리뷰 기능 사용)
터미널에서 직접 git diff 사용 (시각화 인터페이스 불필요)

🎒 시작 전 준비

전제 조건:

✅ Plannotator CLI 설치 완료 (자세한 내용은 빠른 시작 참조)
✅ Claude Code 또는 OpenCode 플러그인 구성 완료 (해당 설치 가이드 참조)
✅ 현재 디렉토리가 Git 저장소에 있음

트리거 방법:

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

핵심 개념

코드 리뷰란

코드 리뷰는 Plannotator가 제공하는 시각화 Git Diff 검토 도구로, 브라우저에서 코드 변경을 확인하고 행 수준 주석을 추가할 수 있습니다.

코드 리뷰가 필요한 이유?

AI Agent가 코드 수정을 완료한 후, 일반적으로 터미널에 git diff 내용을 출력합니다. 이러한 텍스트 방식은 변경 내용을 전체적으로 이해하기 어렵고, 문제 위치를 정확하게 표시하기도 불편합니다. Plannotator는 시각화 인터페이스(side-by-side 또는 unified)를 제공하고, 행 번호 클릭으로 주석 추가를 지원하며, 구조화된 피드백을 Agent에 전송하여 제안에 따라 코드를 다시 수정할 수 있게 합니다.

작업 흐름

┌─────────────────┐
│  사용자          │
│  (명령어 실행)    │
└────────┬────────┘
          │
          │ /plannotator-review
          ▼
┌─────────────────┐
│  CLI          │
│  (git 실행)    │
│  git diff HEAD │
└────────┬────────┘
          │
          │ rawPatch + gitRef
          ▼
┌─────────────────┐
│ Review Server  │  ← 로컬 서버 시작
│  /api/diff     │
└────────┬────────┘
          │
          │ 브라우저에서 UI 열기
          ▼
┌─────────────────┐
│ Review UI     │
│                 │
│ ┌───────────┐  │
│ │ File Tree  │  │
│ │ (파일 목록) │  │
│ └───────────┘  │
│       │         │
│       ▼         │
│ ┌───────────┐  │
│ │ DiffViewer │  │
│ │ (코드 비교) │  │
│ │ split/     │  │
│ │ unified   │  │
│ └───────────┘  │
│       │         │
│       │ 행 번호 클릭
│       ▼         │
│ ┌───────────┐  │
│ │ 주석 추가   │  │
│ │ comment/   │  │
│ │ suggestion/│  │
│ │ concern    │  │
│ └───────────┘  │
│       │         │
│       ▼         │
│ ┌───────────┐  │
│ │ 피드백 전송 │  │
│ │ Send       │  │
│ │ Feedback   │  │
│ │ 또는 LGTM  │  │
│ └───────────┘  │
└────────┬────────┘
          │
          │ Markdown 형식 피드백
          ▼
┌─────────────────┐
│  AI Agent     │
│  (제안에 따라 수정) │
└─────────────────┘

뷰 모드

뷰 모드	설명	사용 시나리오
Split (Side-by-side)	좌우 분할, 이전 코드는 왼쪽, 새 코드는 오른쪽	대량 변경 비교, 수정 전후를 명확하게 확인
Unified	상하 병합, 삭제와 추가가 같은 열에 표시	작은 변경 확인, 수직 공간 절약

주석 유형

Plannotator는 세 가지 코드 주석 유형을 지원합니다:

주석 유형	용도	UI 표현
Comment	특정 행 코드에 대한 댓글, 질문 또는 설명	보라색/파란색 테두리 표시
Suggestion	구체적인 코드 수정 제안 제공	녹색 테두리 표시, 제안 코드 블록 포함
Concern	주의가 필요한 잠재적 문제 표시	노란색/주황색 테두리 표시

주석 유형의 차이점

Comment: 질문, 설명, 일반적인 피드백에 사용
Suggestion: 구체적인 코드 수정 방안 제공 (제안 코드 포함)
Concern: 수정이 필요한 문제 또는 잠재적 위험 표시에 사용

Diff 유형

Diff 유형	Git 명령어	설명
Uncommitted	`git diff HEAD`	커밋되지 않은 변경 (기본값)
Staged	`git diff --staged`	스테이지된 변경
Unstaged	`git diff`	스테이지되지 않은 변경
Last commit	`git diff HEAD~1..HEAD`	마지막 커밋 내용
Branch	`git diff main..HEAD`	현재 브랜치와 기본 브랜치 비교

따라해 보기

1단계: 코드 리뷰 트리거

Claude Code 또는 OpenCode에서 /plannotator-review 명령어를 실행합니다:

사용자: /plannotator-review

CLI: git diff 실행 중...
     브라우저가 열렸습니다

다음을 확인해야 합니다:

브라우저가 자동으로 Plannotator 코드 리뷰 인터페이스를 엽니다
왼쪽에 파일 목록(File Tree)이 표시됩니다
오른쪽에 Diff Viewer가 표시됩니다 (기본값은 split)
상단에 뷰 전환 버튼(Split/Unified)이 있습니다
하단에 "Send Feedback" 및 "LGTM" 버튼이 있습니다

2단계: 파일 목록 탐색

왼쪽 File Tree에서 변경된 파일을 확인합니다:

파일은 경로별로 그룹화되어 표시됩니다
각 파일은 변경 통계(additions/deletions)를 표시합니다
파일을 클릭하면 해당 diff 내용으로 전환됩니다

다음을 확인해야 합니다:

src/
  auth/
    login.ts          (+12, -5)  ← 클릭하여 이 파일의 diff 확인
    user.ts          (+8, -2)
  api/
    routes.ts        (+25, -10)

3단계: 뷰 모드 전환

페이지 상단에서 "Split" 또는 "Unified" 버튼을 클릭하여 뷰를 전환합니다:

Split 뷰(Side-by-side):

이전 코드는 왼쪽(회색 배경, 빨간색 삭제선)
새 코드는 오른쪽(흰색 배경, 녹색 추가선)
대량 변경 비교에 적합

Unified 뷰(병합):

이전 코드와 새 코드가 같은 열에 표시
삭제된 행은 빨간색 배경, 추가된 행은 녹색 배경
작은 변경 확인에 적합

다음을 확인해야 합니다:

Split 뷰: 좌우 분할, 수정 전후를 명확하게 비교
Unified 뷰: 상하 병합, 수직 공간 절약

4단계: 코드 행 선택, 주석 추가

Comment 주석 추가:

코드 행 위에 마우스를 올리면 행 번호 옆에 + 버튼이 나타납니다
+ 버튼을 클릭하거나 행 번호를 직접 클릭하여 해당 행을 선택합니다
여러 행 선택: 시작 행 번호를 클릭하고 Shift를 누른 상태로 끝 행 번호를 클릭합니다
팝업 도구 모음에서 댓글 내용을 입력합니다
"Add Comment" 버튼을 클릭합니다

Suggestion 주석 추가(제안 코드 포함):

위 단계에 따라 주석을 추가합니다
도구 모음에서 "Add suggested code" 버튼을 클릭합니다
팝업 코드 상자에 제안 코드를 입력합니다
"Add Comment" 버튼을 클릭합니다

다음을 확인해야 합니다:

주석이 코드 행 아래에 표시됩니다
Comment 주석: 보라색/파란색 테두리 표시, 댓글 내용 표시
Suggestion 주석: 녹색 테두리 표시, 댓글 내용과 제안 코드 블록 표시
오른쪽 사이드바에 모든 주석 목록이 표시됩니다

5단계: Diff 유형 전환

페이지 상단에서 다른 diff 유형을 선택합니다:

Uncommitted changes(기본값): 커밋되지 않은 변경
Staged changes: 스테이지된 변경
Last commit: 마지막 커밋 내용
vs main(기본 브랜치가 아닌 경우): 기본 브랜치와 비교

다음을 확인해야 합니다:

Diff Viewer가 새로 선택한 diff 내용으로 업데이트됩니다
파일 목록이 새로운 변경 통계로 새로고침됩니다

6단계: Agent에 피드백 전송

Send Feedback(피드백 전송):

필요한 주석을 추가합니다 (Comment/Suggestion/Concern)
페이지 하단의 "Send Feedback" 버튼을 클릭합니다
주석이 없으면 확인 대화 상자가 팝업되고 계속할지 묻습니다

LGTM(Looks Good To Me):

코드에 문제가 없으면 "LGTM" 버튼을 클릭합니다.

다음을 확인해야 합니다:

브라우저가 자동으로 닫힙니다 (1.5초 지연)
터미널에 피드백 내용 또는 "LGTM - no changes requested."가 표시됩니다
Agent가 피드백을 받은 후 코드 수정을 시작합니다

7단계: 피드백 내용 확인(선택 사항)

Plannotator가 Agent에 전송한 피드백 내용을 확인하려면 터미널에서 확인할 수 있습니다:

# Code Review Feedback

## src/auth/login.ts

### Line 15 (new)
여기에 오류 처리 로직을 추가해야 합니다.

### Line 20-25 (old)
**Suggested code:**
```typescript
try {
  await authenticate(req);
} catch (error) {
  return res.status(401).json({ error: 'Authentication failed' });
}

src/api/routes.ts

Line 10 (new)

이 함수는 입력 유효성 검사가 누락되었습니다.


**다음을 확인해야 합니다**:
- 피드백이 파일별로 그룹화되어 있습니다
- 각 주석은 파일 경로, 행 번호, 유형을 표시합니다
- Suggestion 주석은 제안 코드 블록을 포함합니다

## 검토점 ✅

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

- [ ] `/plannotator-review` 명령어를 실행하고 브라우저가 자동으로 코드 리뷰 인터페이스를 엽니다
- [ ] File Tree에서 변경된 파일 목록을 확인합니다
- [ ] Split 및 Unified 뷰 간에 전환합니다
- [ ] 행 번호 또는 `+` 버튼을 클릭하여 코드 행을 선택합니다
- [ ] Comment, Suggestion, Concern 주석을 추가합니다
- [ ] 주석에 제안 코드를 추가합니다
- [ ] 다른 diff 유형으로 전환합니다 (uncommitted/staged/last commit/branch)
- [ ] Send Feedback를 클릭하고 브라우저가 닫히며 터미널에 피드백 내용이 표시됩니다
- [ ] LGTM을 클릭하고 브라우저가 닫히며 터미널에 "LGTM - no changes requested."가 표시됩니다

**특정 단계가 실패하면** 다음을 참조하세요:
- [일반적인 문제](../../faq/common-problems/)
- [Claude Code 설치 가이드](../../start/installation-claude-code/)
- [OpenCode 설치 가이드](../../start/installation-opencode/)

## 주의사항

**일반적인 오류 1**: `/plannotator-review`를 실행한 후 브라우저가 열리지 않습니다

**원인**: 포트가 사용 중이거나 서버 시작 실패일 수 있습니다.

**해결 방법**:
- 터미널에 오류 메시지가 있는지 확인합니다
- 표시된 URL을 브라우저에서 수동으로 열어 봅니다
- 문제가 지속되면 [문제 해결](../../faq/troubleshooting/)을 참조하세요

**일반적인 오류 2**: 행 번호를 클릭한 후 도구 모음이 팝업되지 않습니다

**원인**: 빈 행을 선택했거나 브라우저 창이 너무 작을 수 있습니다.

**해결 방법**:
- 코드가 포함된 행을 선택해 봅니다
- 브라우저 창을 크게 합니다
- JavaScript가 비활성화되지 않았는지 확인합니다

**일반적인 오류 3**: 주석을 추가한 후 주석이 코드 아래에 표시되지 않습니다

**원인**: 빈 행을 선택했거나 브라우저 창이 너무 작을 수 있습니다.

**해결 방법**:
- 코드가 포함된 행을 선택해 봅니다
- 브라우저 창을 크게 합니다
- JavaScript가 비활성화되지 않았는지 확인합니다
- 오른쪽 사이드바에 주석 목록이 표시되는지 확인합니다

**일반적인 오류 4**: Send Feedback를 클릭한 후 터미널에 피드백 내용이 표시되지 않습니다

**원인**: 네트워크 문제 또는 서버 오류일 수 있습니다.

**해결 방법**:
- 터미널에 오류 메시지가 있는지 확인합니다
- 피드백을 다시 전송해 봅니다
- 문제가 지속되면 [문제 해결](../../faq/troubleshooting/)을 참조하세요

**일반적인 오류 5**: Agent가 피드백을 받은 후 제안에 따라 코드를 수정하지 않습니다

**원인**: Agent가 주석의 의도를 올바르게 이해하지 못했을 수 있습니다.

**해결 방법**:
- 더 명확한 주석을 사용해 봅니다 (Suggestion이 Comment보다 더 명확함)
- Comment로 자세한 설명을 추가합니다
- Suggestion에 완전한 제안 코드를 제공합니다
- 문제가 지속되면 `/plannotator-review`를 다시 실행하여 새로운 변경을 검토할 수 있습니다

**일반적인 오류 6**: diff 유형을 전환한 후 파일 목록이 비어 있습니다

**원인**: 선택한 diff 유형에 변경 내용이 없을 수 있습니다.

**해결 방법**:
- "Uncommitted changes"로 다시 전환해 봅니다
- git 상태를 확인하고 변경이 있는지 확인합니다
- `git status`로 현재 상태를 확인합니다

## 이 수업 요약

코드 리뷰는 Plannotator가 제공하는 시각화 Git Diff 검토 도구입니다:

**핵심 작업**:
1. **트리거**: `/plannotator-review`를 실행하고 브라우저가 자동으로 UI를 엽니다
2. **탐색**: File Tree에서 변경된 파일 목록을 확인합니다
3. **뷰**: Split(side-by-side) 및 Unified 뷰 간에 전환합니다
4. **주석**: 행 번호를 클릭하여 코드 행을 선택하고 Comment/Suggestion/Concern 주석을 추가합니다
5. **전환**: 다른 diff 유형을 선택합니다 (uncommitted/staged/last commit/branch)
6. **피드백**: Send Feedback 또는 LGTM을 클릭하고 피드백을 Agent에 전송합니다

**뷰 모드**:
- **Split(Side-by-side)**: 좌우우 분할, 이전 코드는 왼쪽, 새 코드는 오른쪽
- **Unified**: 상하 병합, 삭제와 추가가 같은 열에 표시

**주석 유형**:
- **Comment**: 특정 행 코드에 대한 댓글, 질문 또는 설명
- **Suggestion**: 구체적인 코드 수정 제안 제공 (제안 코드 포함)
- **Concern**: 주의가 필요한 잠재적 문제 표시

**Diff 유형**:
- **Uncommitted**: 커밋되지 않은 변경 (기본값)
- **Staged**: 스테이지된 변경
- **Unstaged**: 스테이지되지 않은 변경
- **Last commit**: 마지막 커밋 내용
- **Branch**: 현재 브랜치와 기본 브랜치 비교

## 다음 수업 예고

> 다음 수업에서는 **[코드 주석 추가](../code-review-annotations/)**를 학습합니다.
>
> 다음을 배우게 됩니다:
> - Comment, Suggestion, Concern 주석을 정확하게 사용하는 방법
> - 제안 코드를 추가하고 서식화하여 표시하는 방법
> - 주석을 편집하고 삭제하는 방법
> - 주석의 모범 사례와 일반적인 시나리오
> - side-by-side 뷰에서 old/new 측을 선택하는 방법

---

## 부록: 소스 코드 참조

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

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

| 기능              | 파일 경로                                                                                              | 행 번호    |
|--- | --- | ---|
| 코드 리뷰 서버     | [`packages/server/review.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/review.ts#L1-L302)           | 1-302   |
| 코드 리뷰 UI       | [`packages/review-editor/App.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx#L1-L150) | 1-150   |
| DiffViewer 컴포넌트    | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L1-L349) | 1-349   |
| Git 도구         | [`packages/server/git.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/git.ts#L1-L148)                 | 1-148   |
| Hook 진입점(review) | [`apps/hook/server/index.ts`](https://github.com/backnotprop/plannotator/blob/main/apps/hook/server/index.ts#L46-L84)         | 46-84   |
| 코드 주석 유형 정의    | [`packages/ui/types.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/ui/types.ts#L53-L83)                  | 53-83   |

**핵심 타입**:
- `CodeAnnotationType`: 코드 주석 유형 열거형 (comment, suggestion, concern) (`packages/ui/types.ts:53`)
- `CodeAnnotation`: 코드 주석 인터페이스 (`packages/ui/types.ts:55-66`)
- `DiffType`: Diff 유형 열거형 (uncommitted, staged, unstaged, last-commit, branch) (`packages/server/git.ts:10-15`)
- `GitContext`: Git 컨텍스트 인터페이스 (`packages/server/git.ts:22-26`)

**핵심 함수**:
- `startReviewServer()`: 코드 리뷰 서버 시작 (`packages/server/review.ts:79`)
- `runGitDiff()`: git diff 명령어 실행 (`packages/server/git.ts:101`)
- `getGitContext()`: Git 컨텍스트 가져오기 (브랜치 정보 및 diff 옵션) (`packages/server/git.ts:79`)
- `parseDiffToFiles()`: diff를 파일 목록으로 파싱 (`packages/review-editor/App.tsx:48`)
- `exportReviewFeedback()`: 주석을 Markdown 피드백으로 내보내기 (`packages/review-editor/App.tsx:86`)

**API 라우트**:
- `GET /api/diff`: diff 내용 가져오기 (`packages/server/review.ts:118`)
- `POST /api/diff/switch`: diff 유형 전환 (`packages/server/review.ts:130`)
- `POST /api/feedback`: 리뷰 피드백 제출 (`packages/server/review.ts:222`)
- `GET /api/image`: 이미지 가져오기 (`packages/server/review.ts:164`)
- `POST /api/upload`: 이미지 업로드 (`packages/server/review.ts:181`)
- `GET /api/agents`: 사용 가능한 agents 가져오기 (OpenCode) (`packages/server/review.ts:204`)

**비즈니스 규칙**:
- 기본적으로 커밋되지 않은 diff 확인 (`apps/hook/server/index.ts:55`)
- vs main diff로 전환 지원 (`packages/server/git.ts:131`)
- 피드백을 Markdown로 서식화 (`packages/review-editor/App.tsx:86`)
- 승인 시 "LGTM" 텍스트 전송 (`packages/review-editor/App.tsx:430`)

</details>

코드 리뷰 기초: /plannotator-review로 Git Diff 검토 ​

학습 후 할 수 있는 것 ​

현재 겪고 있는 문제 ​

언제 이 기능을 사용 ​

🎒 시작 전 준비 ​

핵심 개념 ​

코드 리뷰란 ​

작업 흐름 ​

뷰 모드 ​

주석 유형 ​

Diff 유형 ​

따라해 보기 ​

1단계: 코드 리뷰 트리거 ​

2단계: 파일 목록 탐색 ​

3단계: 뷰 모드 전환 ​

4단계: 코드 행 선택, 주석 추가 ​

5단계: Diff 유형 전환 ​

6단계: Agent에 피드백 전송 ​

7단계: 피드백 내용 확인(선택 사항) ​

src/api/routes.ts ​

Line 10 (new) ​

코드 리뷰 기초: /plannotator-review로 Git Diff 검토

학습 후 할 수 있는 것

현재 겪고 있는 문제

언제 이 기능을 사용

🎒 시작 전 준비

핵심 개념

코드 리뷰란

작업 흐름

뷰 모드

주석 유형

Diff 유형

따라해 보기

1단계: 코드 리뷰 트리거

2단계: 파일 목록 탐색

3단계: 뷰 모드 전환

4단계: 코드 행 선택, 주석 추가

5단계: Diff 유형 전환

6단계: Agent에 피드백 전송

7단계: 피드백 내용 확인(선택 사항)

src/api/routes.ts

Line 10 (new)