🔍

에이전트 너머, 에이전트를 보다

backnotprop/plannotator가 푸는 코드 리뷰의 역설

⭐ 7k+ GitHub Stars
819 Commits
AGPL-3.0

AI 코딩 에이전트가 코드를 쓰는 속도는 인간의 10배다. 그런데 그 코드를 검토하는 속도는? 에이전트 사용이 늘수록, 코드 생산량은 폭발하는데 검토 병목은 그대로다. PR이 쌓이고 리뷰어는 지친다. backnotprop의 Plannotator는 이 간극을 메우는 도구다: 에이전트가 만든 계획과 코드를 브라우저에서 시각적으로 리뷰하고, 피드백을 클릭 한 번으로 에이전트에게 돌려보낸다.

Claude Code, Codex, OpenCode, Gemini CLI, Copilot CLI 등 거의 모든 코딩 에이전트에 붙는 로컬 리뷰 서피스. 7월 첫째 주에 7k 스타를 돌파한 프로젝트를 살펴봤다.

문제: 에이전트는 쓰지만 결과물은 못 믿겠다

코딩 에이전트를 쓰는 사람이라면 누구나 공감할 딜레마다. “얘한테 이 작업을 다 맡겨도 될까?” 에이전트가 작성한 계획을 읽어보고 싶지만, 터미널 출력만으로는 구조把握이 어렵다. PR을 열어서 보자니 에이전트는 이미 다음 작업을 시작했다. 리뷰 피드백을 다시 에이전트에게 전달하는 것도 수작업이다.

backnotprop는 이 문제를 이렇게 정의한다: “코딩 에이전트는 당신을 위해 코딩하지만, 당신은 여전히 그들을 리뷰해야 한다. 그리고 그 리뷰는 당신과 에이전트 모두에게 쉬워야 한다.”

기존 리뷰 도구(GitHub PR, GitLab MR)는 인간-인간 협업을 전제로 설계됐다. 인간-에이전트 리뷰에는 느리고, 맥락이 안 맞고, 피드백 루프가 길다.

Plannotator가 해결하는 것

Plannotator는 세 가지 리뷰 모드를 제공한다:

  • 계획(Plan) 리뷰 — 에이전트가 ExitPlanMode를 호출할 때 훅이 발동, 계획을 브라우저에서 열고 인라인 주석 + 승인/거절
  • 코드 리뷰 — /plannotator-review 명령어로 git diff 또는 GitHub/GitLab PR을 시각적 diff 뷰어에서 검토
  • HTML 아티팩트 주석 — 에이전트가 생성한 HTML을 렌더링한 상태에서 직접 주석

핵심은 피드백이 에이전트에게 돌아간다는 점이다. 승인하면 에이전트가 다음 단계로 진행하고, 거절하면 구조화된 피드백이 세션으로 전달된다. “LGTM” 한 마디로 PR을 머지할 수 있고, “여기 로직 다시 생각해봐”라는 주석이 에이전트에게 그대로 전달된다.

왜 지금 Plannotator인가

코딩 에이전트 시장이 폭발하면서 생긴 블랭크 스팟이다. 코드 생성 도구는 넘쳐나지만, 그 결과물을 검토하는 도구는 없었다. 모든 코딩 에이전트가 “너를 위해 코딩할게”라면, Plannotator는 “니가 확인해, 내가 도와줄게”의 포지션.

이 도구가 흥미로운 이유는 에이전트 생태계 위에 메타 레이어를 쌓기 때문이다. 어떤 에이전트를 쓰든, 어떤 언어를 쓰든, Plannotator는 그 위에서 일관된 리뷰 경험을 제공한다. 이건 Fabric이 프롬프트 관리의 표준을 제시한 것과 같은 패턴이다 — 단일 인터페이스로 여러 도구를 통일하는 것.

어떻게 생겼나

설치는 한 줄이다:

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

설치기가 자동으로 현재 환경의 에이전트를 감지하고 훅, 스킬, 슬래시 커맨드를 설정한다. OpenCode는 opencode.json에 플러그인 추가만 하면 된다:

{
  "plugin": ["@plannotator/opencode@latest"]
}

사용법은 더 직관적이다:

/plannotator-annotate README.md        # 파일 주석
/plannotator-last                      # 에이전트 마지막 메시지 리뷰
/plannotator-review                    # uncommitted 변경 검토
/plannotator-review <pr-url>          # GitHub PR 리뷰

플랜 리뷰는 명령어가 필요 없다. 에이전트가 계획을 세울 때 자동으로 브라우저가 열린다. 리뷰 화면은 직관적이다: 마크다운을 렌더링한 상태에서 드래그로 영역 선택 → 주석 입력 → Approve/Request Changes 버튼.

보안과 프라이버시

Plannotator의 설계 철학 중 가장 마음에 든 것은 프라이버시 우선이다.

  • 모든 리뷰 데이터는 로컬에서 처리된다. 외부 서버로 전송되지 않는다.
  • 공유 기능은 AES-256-GCM 암호화. 서버는 ciphertext만 저장하고, 키는 URL fragment에만 존재한다.
  • 붙여넣기는 7일 후 자동 삭제.
  • 공유를 완전히 비활성화할 수 있다: PLANNOTATOR_SHARE=disabled
  • 모든 릴리스는 SHA256 사이드카 + SLSA provenance 증명서를 제공한다.

이런 설계는 LLM 코드를 다루는 도구에 필수적이다. 코드 자체가 민감한 IP인 경우가 많으니까.

생태계와 통합

Plannotator는 단순한 리뷰 도구를 넘어 통합 생태계를 구축 중이다:

  • VS Code — 에디터 탭에서 계획 열기, 인라인 주석, gutter에서 diff 보기
  • Obsidian — 승인된 계획을 YAML frontmatter + 태그 + 백링크와 함께 vault에 자동 저장
  • Bear — 중첩 태그와 프로젝트 메타데이터와 함께 Bear 노트로 저장
  • GitHub / GitLab — 모든 PR/MR URL을 diff 뷰어로 열어서 리뷰

특히 Obsidian 연동은 Drewgent의 P-layer 구조와 맞닿는 지점이다. “에이전트가 만든 계획을 지식 베이스에 자동 보관” — 이 패턴은 나도 Drewgent에서 고민 중이다. Plannotator는 이미 구현해놨다.

아쉬운 점

  • 멀티플레이어는 아직 베타 — room.plannotator.ai가 공개됐지만 실시간 공동 편집은 Workspaces에서 준비 중이다
  • 모바일 미지원 — 리뷰가 브라우저에서 열리지만 모바일 최적화는 안 돼 있다
  • CI/CD 통합 부재 — 지금은 로컬/SSH 환경 전용. CI 파이프라인에 붙이려면 추가 작업이 필요하다
  • 한국어 문서 부족 — 영어만 지원. 한국어 사용자에게는 진입장벽이 될 수 있다

설계 결정 비교

영역 Plannotator 방식 Drewgent 방식 인사이트
리뷰 대상 계획 + 코드 diff + HTML 코드 리뷰 (graph-rca) Plannotator는 리뷰에 특화, Drewgent는 분석 중심
피드백 루프 브라우저 주석 → 에이전트 세션 human-in-the-loop (Tier 3) 비슷한 방향, 다른 인터페이스
에이전트 지원 Claude Code, Codex, OpenCode, Gemini, Copilot, Pi, Kiro, Droid, Amp opencode + GJC Plannotator는 범용, Drewgent는 opencode 특화
저장/기록 Obsidian/Bear 자동 저장 knowledge.db (SQLite FTS5) 둘 다 지식으로 환원하는 방향
보안 로컬 우선, AES-256-GCM 공유 local 전용, vault 암호화 프라이버시 우선은 공통

써보니

Plannotator는 “에이전트를 신뢰하지만 검증하라”는 원칙의 구체적 구현체다. AI 코딩 에이전트가 코드를 생성하는 속도는 인간을 넘었지만, 그 코드가 의도한 대로 동작하는지 확인하는 과정은 여전히 인간의 몫이다. Plannotator는 이 과정을 에이전트와 인간 사이의 대화로 재정의한다.

처음 설치하고 /plannotator-last를 실행했을 때, 에이전트가 방금 보낸 메시지가 브라우저에 깔끔하게 렌더링되고 내 주석이 그대로 세션으로 돌아가는 걸 보고 “아, 이게 맞는 방향이구나” 싶었다. 단순한 기능이지만, 에이전트 워크플로우에서 리뷰가 얼마나 자연스럽게 녹아들 수 있는지 보여준다.

Trend Keep에 오른 이유도 이해가 간다. 에이전트 도구의 다음 프론티어는 생성 → 검토 → 피드백의 완전한 루프를 만드는 것이고, Plannotator는 그 검토 단계를 담당한다. 7k 스타가 꽤 빨리 쌓인 이유다.

에이전트를 쓰고 있다면 한 번 설치해보길 추천한다. 10초면 끝난다:

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

그리고 /plannotator-last를 쳐봐라. 네 에이전트의 마지막 메시지가 브라우저에 열리고, 거기서 리뷰가 시작된다. 이 경험을 한 번 하면, 리뷰 없는 에이전트 사용은 생각하기 어려워질 테니까.

읽어줘서 고맙다.