빠른 시작: 5분 안에 Plannotator 시작하기

학습 후 할 수 있는 것

✅ Plannotator의 핵심 기능과 사용 시나리오 이해
✅ 5분 안에 Plannotator 설치 완료
✅ Claude Code 또는 OpenCode 통합 설정
✅ 첫 번째 계획 검토 및 코드 검토 완료

현재 겪고 있는 문제

Plannotator는 Claude Code와 OpenCode를 위해 설계된 대화형 검토 도구로, 다음 문제들을 해결할 수 있습니다:

문제점 1: AI가 생성한 실행 계획을 터미널에서 읽을 때 텍스트 양이 많고 구조가 명확하지 않아 검토가 힘듭니다.

문제점 2: AI에 피드백을 줄 때 "3번째 단락 삭제", "이 함수 수정"과 같이 텍스트로만 설명해야 해서 소통 비용이 높습니다.

문제점 3: 코드 검토 시 여러 터미널이나 IDE를 열어야 하고, 자주 전환해야 해서 집중하기 어렵습니다.

문제점 4: 팀원들이 검토에 참여하고 싶지만 계획 내용을 공유하는 방법을 모릅니다.

Plannotator가 도와드립니다:

터미널 읽기 대신 시각적 UI로 구조 명확
텍스트 선택으로 주석 추가 가능 (삭제, 교체, 댓글), 정확한 피드백
Git diff 시각화 검토, 행 수준 주석 지원
URL 공유 기능으로 백엔드 없이 팀 협업 가능

언제 이 방법을 사용해야 할까요

사용 시나리오:

Claude Code 또는 OpenCode를 사용하여 AI 보조 개발
AI가 생성한 실행 계획 검토 필요
코드 변경 사항 검토 필요
팀원과 계획 또는 코드 검토 결과 공유 필요

적용하지 않는 시나리오:

순수 수동 코드 작성 (AI 생성 계획 없음)
이미 완전한 코드 검토 프로세스가 있음 (예: GitHub PR)
시각적 검토 도구 필요 없음

핵심 아이디어

Plannotator란 무엇인가요

Plannotator는 AI Coding Agent(Claude Code, OpenCode)를 위해 설계된 대화형 검토 도구로, 주로 두 가지 기능을 제공합니다:

계획 검토: AI가 생성한 실행 계획을 시각적으로 검토하고, 주석 추가, 승인 또는 거부 지원
코드 검토: Git diff를 시각적으로 검토하고, 행 수준 주석과 다양한 뷰 모드 지원

작동 원리

┌─────────────────┐
│  AI Agent      │
│  (계획 생성)    │
└────────┬────────┘
          │
          ▼
┌─────────────────┐
│  Plannotator   │  ← 로컬 HTTP 서버
│  (시각적 UI)   │
└────────┬────────┘
          │
          ▼
┌─────────────────┐
│  브라우저        │
│  (사용자 검토)  │
└─────────────────┘

핵심 프로세스:

AI Agent가 계획 또는 코드 변경 완료
Plannotator가 로컬에서 HTTP 서버를 시작하고 브라우저를 엽니다
사용자가 브라우저에서 계획/코드를 보고 주석을 추가합니다
사용자가 승인 또는 거부하면 Plannotator가 결정을 AI Agent에 반환합니다
AI Agent가 피드백에 따라 계속 실행하거나 수정합니다

보안

모든 데이터는 로컬에서 처리되며 클라우드에 업로드되지 않습니다:

계획 내용, 코드 diff, 주석은 모두 로컬 머신에 저장됩니다
로컬 HTTP 서버는 무작위 포트(또는 고정 포트)를 사용합니다
URL 공유 기능은 URL hash에 데이터를 압축하여 구현하며 백엔드가 필요 없습니다

🎒 시작 전 준비

시스템 요구사항:

운영체제: macOS / Linux / Windows / WSL
런타임: Bun (설치 스크립트가 자동 처리)
AI 환경: Claude Code 2.1.7+ 또는 OpenCode

설치 방법 선택:

Claude Code 사용: CLI + 플러그인 설치 필요
OpenCode 사용: 플러그인 설정 필요
코드 검토만 수행: CLI만 설치하면 됨

따라 해보세요

1단계: Plannotator CLI 설치

macOS / Linux / WSL:

bash

curl -fsSL https://plannotator.ai/install.sh | bash

Windows PowerShell:

powershell

irm https://plannotator.ai/install.ps1 | iex

Windows CMD:

cmd

curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

예상 결과: 설치 스크립트가 자동으로 Plannotator CLI를 다운로드하고 시스템 경로에 추가하며, 버전 번호를 표시합니다 (예: "plannotator v0.6.7 installed to ...").

설치 스크립트는 무엇을 하나요?

설치 스크립트는 다음을 수행합니다:

최신 버전의 Plannotator CLI 다운로드
시스템 경로(PATH)에 추가
존재할 수 있는 이전 버전 정리
/plannotator-review 명령 자동 설치 (코드 검토용)

2단계: Claude Code 설정 (선택 사항)

Claude Code를 사용하는 경우 플러그인을 설치해야 합니다.

Claude Code에서 실행:

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

중요: 플러그인 설치 후, Claude Code를 다시 시작해야 hook가 적용됩니다.

예상 결과: 플러그인 설치 성공 후, Claude Code의 플러그인 목록에 plannotator가 나타납니다.

수동 설정 방법 (선택 사항)

플러그인 시스템을 사용하지 않으려면 수동으로 hook를 설정할 수 있습니다. 자세한 내용은 Claude Code 플러그인 설치 장을 참조하세요.

3단계: OpenCode 설정 (선택 사항)

OpenCode를 사용하는 경우 opencode.json 파일을 편집해야 합니다.

opencode.json 편집:

json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}

OpenCode 다시 시작.

예상 결과: 다시 시작 후, OpenCode가 자동으로 플러그인을 로드하고 submit_plan 도구를 사용할 수 있습니다.

4단계: 첫 번째 계획 검토 (Claude Code 예제)

트리거 조건: Claude Code가 실행 계획을 생성하고 ExitPlanMode를 호출하도록 합니다.

예제 대화:

사용자: 사용자 인증 모듈의 실행 계획을 작성해 주세요

Claude: 네, 실행 계획입니다:
1. 사용자 모델 생성
2. 등록 API 구현
3. 로그인 API 구현
...
(ExitPlanMode 호출)

예상 결과:

브라우저가 자동으로 Plannotator UI를 엽니다
AI가 생성한 계획 내용이 표시됩니다
계획 텍스트를 선택하여 주석을 추가할 수 있습니다 (삭제, 교체, 댓글)
하단에 "Approve" 및 "Request Changes" 버튼이 있습니다

작업:

브라우저에서 계획을 확인합니다
계획에 문제가 없으면 Approve 클릭 → AI가 계속 실행합니다
수정이 필요하면 변경할 텍스트를 선택하고 Delete, Replace 또는 Comment 클릭 → Request Changes 클릭

예상 결과: 클릭 후 브라우저가 자동으로 닫히고 Claude Code가 결정을 수신하여 계속 실행합니다.

5단계: 첫 번째 코드 검토

프로젝트 디렉토리에서 실행:

bash

/plannotator-review

예상 결과:

브라우저가 코드 검토 페이지를 엽니다
Git diff가 표시됩니다 (기본값은 커밋되지 않은 변경 사항)
왼쪽은 파일 트리, 오른쪽은 diff 뷰어입니다
행 번호를 클릭하여 코드 범위를 선택하고 주석을 추가할 수 있습니다

작업:

diff 뷰어에서 코드 변경 사항을 봅니다
행 번호를 클릭하여 검토할 코드를 선택합니다
오른쪽 패널에서 주석을 추가합니다 (comment/suggestion/concern)
Send Feedback 클릭하여 agent에 전송하거나 LGTM 클릭하여 승인합니다

예상 결과: Send Feedback 클릭 후 브라우저가 닫히고 터미널에 포맷된 피드백 내용이 출력되며 agent가 자동으로 처리합니다.

체크포인트 ✅

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

[ ] 설치 스크립트가 "plannotator vX.X.X installed to ..." 표시
[ ] Claude Code에서 계획 검토를 트리거하고 브라우저가 자동으로 UI 열기
[ ] UI에서 계획 텍스트를 선택하고 주석 추가
[ ] Approve 또는 Request Changes 클릭하고 브라우저 닫힘 확인
[ ] /plannotator-review 실행하고 코드 검토 인터페이스 표시
[ ] 코드 검토에서 행 수준 주석 추가하고 Send Feedback 클릭

어떤 단계에서든 실패하면 다음을 참조하세요:

주의 사항

일반적인 오류 1: 설치 후 plannotator 실행 시 "command not found" 메시지

원인: PATH 환경 변수가 업데이트되지 않았거나 터미널을 다시 시작해야 합니다.

해결 방법:

macOS/Linux: source ~/.zshrc 또는 source ~/.bashrc 실행하거나 터미널 다시 시작
Windows: PowerShell 또는 CMD 다시 시작

일반적인 오류 2: Claude Code에 플러그인 설치 후 계획 검토가 트리거되지 않음

원인: Claude Code를 다시 시작하지 않아 hook가 적용되지 않았습니다.

해결 방법: Claude Code를 완전히 종료하고 다시 엽니다 (창만 닫지 마세요).

일반적인 오류 3: 브라우저가 자동으로 열리지 않음

원인: 원격 모드(예: devcontainer, SSH)이거나 포트가 사용 중일 수 있습니다.

해결 방법:

PLANNOTATOR_REMOTE=1 환경 변수가 설정되어 있는지 확인
터미널 출력의 URL을 확인하고 브라우저에서 수동으로 엽니다
자세한 내용은 원격/Devcontainer 모드 참조

일반적인 오류 4: 코드 검토에 "No changes" 표시

원인: 커밋되지 않은 git 변경 사항이 없습니다.

해결 방법:

먼저 git status 실행하여 변경 사항이 있는지 확인
또는 git add 실행하여 일부 파일 스테이징
또는 다른 diff 유형으로 전환(예: last commit)

이번 강의 요약

Plannotator는 로컬에서 실행되는 검토 도구로, 시각적 UI를 통해 계획 검토 및 코드 검토 효율을 향상시킵니다:

핵심 기능:

계획 검토: AI가 생성한 계획을 시각적으로 검토하고 정확한 주석 지원
코드 검토: Git diff를 시각적으로 검토하고 행 수준 주석 지원
URL 공유: 백엔드 없이 검토 내용 공유
서드파티 통합: 승인된 계획을 Obsidian/Bear에 자동 저장

핵심 장점:

로컬 실행, 데이터 보안
시각적 UI, 효율 향상
정확한 피드백, 소통 비용 감소
팀 협업, 계정 시스템 불필요

다음 강의 예고

다음 강의에서는 **Claude Code 플러그인 설치**를 학습합니다.
다음을 배우게 됩니다:
자세한 Claude Code 플러그인 설치 단계
hook 수동 설정 방법
설치 성공 여부 확인 방법
일반적인 설치 문제 해결 방법

부록: 소스 코드 참조

클릭하여 소스 코드 위치 확인

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

기능	파일 경로	행 번호
CLI 진입점 (계획 검토)	`apps/hook/server/index.ts`	1-50
CLI 진입점 (코드 검토)	`apps/hook/server/index.ts`	46-84
계획 검토 서버	`packages/server/index.ts`	1-200
코드 검토 서버	`packages/server/review.ts`	1-150
Git 도구	`packages/server/git.ts`	1-100
계획 검토 UI	`packages/editor/App.tsx`	1-200
코드 검토 UI	`packages/review-editor/App.tsx`	1-200

핵심 상수:

MAX_RETRIES = 5: 포트 재시도 횟수 (packages/server/index.ts:80)
RETRY_DELAY_MS = 500: 포트 재시도 지연 (packages/server/index.ts:80)

핵심 함수:

startPlannotatorServer(): 계획 검토 서버 시작 (packages/server/index.ts)
startReviewServer(): 코드 검토 서버 시작 (packages/server/review.ts)
runGitDiff(): git diff 명령 실행 (packages/server/git.ts)

환경 변수:

PLANNOTATOR_REMOTE: 원격 모드 플래그 (apps/hook/server/index.ts:17)
PLANNOTATOR_PORT: 고정 포트 (apps/hook/server/index.ts:18)
PLANNOTATOR_BROWSER: 사용자 정의 브라우저 (apps/hook/README.md:79)
PLANNOTATOR_SHARE: URL 공유 스위치 (apps/hook/server/index.ts:44)

빠른 시작: 5분 안에 Plannotator 시작하기 ​

학습 후 할 수 있는 것 ​

현재 겪고 있는 문제 ​

언제 이 방법을 사용해야 할까요 ​

핵심 아이디어 ​

Plannotator란 무엇인가요 ​

작동 원리 ​

보안 ​

🎒 시작 전 준비 ​

따라 해보세요 ​

1단계: Plannotator CLI 설치 ​

2단계: Claude Code 설정 (선택 사항) ​

3단계: OpenCode 설정 (선택 사항) ​

4단계: 첫 번째 계획 검토 (Claude Code 예제) ​

5단계: 첫 번째 코드 검토 ​

체크포인트 ✅ ​

주의 사항 ​

이번 강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

빠른 시작: 5분 안에 Plannotator 시작하기

학습 후 할 수 있는 것

현재 겪고 있는 문제

언제 이 방법을 사용해야 할까요

핵심 아이디어

Plannotator란 무엇인가요

작동 원리

보안

🎒 시작 전 준비

따라 해보세요

1단계: Plannotator CLI 설치

2단계: Claude Code 설정 (선택 사항)

3단계: OpenCode 설정 (선택 사항)

4단계: 첫 번째 계획 검토 (Claude Code 예제)

5단계: 첫 번째 코드 검토

체크포인트 ✅

주의 사항

이번 강의 요약

다음 강의 예고

부록: 소스 코드 참조