Clúsia 소개: 옆에 나만의 AI와 함께하는 사람을 위한 PR 리뷰

과거에는 대부분의 코드 리뷰를 회의 사이에 짬을 내어 브라우저 탭에서 진행하곤 했습니다. 하지만 최근 많은 팀들이 이 작업을 봇에게 맡기는데, 그 결과로 남겨진 댓글들은 읽히지 않은 채 해결되는 경우가 많습니다.

저는 변경 사항을 차분하게 읽고, 옆에 앉아 있는 AI와 함께 작업할 수 있는 환경을 원했습니다. 이 AI는 저의 질문에 답해주고 문제점을 지적하며, 저는 PR에 무엇을 포함시킬지 결정합니다.

이것이 바로 Clúsia입니다. Apache-2.0 라이선스 하에 공개된 무료 macOS 앱이며 Rust로 작성되었으며, 이제 다른 사람들도 사용해 볼 준비가 되었다고 생각합니다.

리뷰 작동 방식

풀 리퀘스트(pull request)를 열고 Clúsia가 이를 로컬 워크트리(local worktree)에서 확인합니다. 특정 줄이나 범위에 댓글을 달거나, 스레드에 답글을 작성하고 해결하며, 이 모든 내용은 사용자 기기 내 초안(draft)으로 유지됩니다. 'Finalize review'를 누르면 이 초안이 하나의 리뷰로 GitHub에 전송됩니다. 그전까지는 아무것도 게시되지 않습니다.

또한, 초안은 새로운 푸시(push)에도 살아남습니다. 만약 작성자가 작업 도중에 푸시하더라도, 사용자의 댓글은 해당 코드가 변경된 위치로 이동합니다. 그리고 만약 리뷰를 저장해 두었다가 며칠 후에 돌아왔다면, 에이전트(agent)는 각 댓글을 새로운 커밋과 비교하여 유지할지, 옮길지, 구식으로 표시할지, 아니면 수정해야 할지 제안할 수 있습니다. 사용자는 이 제안들을 하나씩 검토하거나 한 번에 모두 승인할 수 있습니다.

사용자 계정에서 작동하는 에이전트

Clúsia가 모델을 제공하는 것은 아닙니다. 대신, 사용자가 이미 사용하는 Claude Code나 Codex와 통신하며, 사용자의 자체 로그인 정보를 이용합니다. 또는 작은 JSON-lines 프로토콜을 처리하는 직접 작성한 프로그램과도 연결됩니다. GitHub 토큰은 에이전트에게 절대 전달되지 않으며, 에이전트는 git이나 GitHub에 쓰기 작업을 수행하지 않습니다. 게시(Publishing)는 사용자 본인의 역할입니다.

리뷰를 열면 에이전트가 요약문을 작성하고, 사용자는 그 요약문에 대해 PR(Pull Request) 관련 채팅을 할 수 있습니다. 이 에이전트는 작업 트리(worktree)를 스스로 읽고 검색할 수 있습니다. cargo test 실행이나 파일 편집과 같은 다른 작업을 수행해야 할 경우, 모달 창에 정확한 명령어와 해당 요청을 준 이유, 그리고 카운트다운이 표시됩니다. 사용자가 응답하지 않으면 요청은 거부됩니다. 기본적으로 모든 명령어는 네트워크 연결 없이 샌드박스(sandbox)에서 실행되며, 리뷰의 작업 트리 내부에만 내용을 작성합니다.

보안 검사(Security checks)

리뷰를 열 때, 사용자의 에이전트는 변경 사항을 보안 문제 측면에서도 살펴봅니다. 발견된 각 문제는 심각도(high, medium 또는 low), 해당 라인, 그리고 때로는 사용할 수 있는 코드 제안과 함께 제공되며, 이는 리뷰 코멘트 형태로 작성됩니다. 사용자는 이를 초안에 추가하거나, 먼저 편집하거나, 무시할 수 있습니다. PR이 건드리지 않은 라인에서 발견된 문제는 일반적인 코멘트로 처리됩니다.

저는 이 부분의 문구 선택에 신중을 기했습니다. 아무 문제도 발견되지 않았을 경우, Clúsia는

만약 에이전트가 특정 영역에 대해 답변하지 않았다면, 해당 탭에는 '확인 안 함(Not checked)'이라고 표시됩니다. 저는 침묵하는 '알겠습니다(ok)'라는 응답을 원치 않았습니다.

각 확인은 리뷰의 채팅에서 포크된 세션으로 실행되므로, 에이전트가 무엇을 읽었는지 이미 알고 있으며 작업하는 동안 사용자의 채팅은 자유롭습니다. 모든 리뷰에 걸쳐 동시에 최대 두 개의 확인만 실행될 수 있는데, 이는 각각 계정에서 실제 턴(turn)이기 때문입니다.

변경 사항 다이어그램 (Diagrams of the change)

이 부분이 제가 가장 재미있게 구축했던 부분입니다. Diagrams 탭은 에이전트에게 PR을 최대 여덟 개의 다이어그램으로 설명하도록 요청하며, 변경 사항에 맞는 종류(흐름도(flow), 의존성 그래프(dependency graph), 시퀀스(sequence), 개체-관계 모델(entity-relationship), 유스케이스(use cases), 데이터 흐름(data flow), 상태 머신(state machine) 또는 클래스 다이어그램(class diagram))를 선택합니다.

Clúsia는 모든 그림을 검증하고 스스로 배치하여 화살표가 곧고 읽기 쉽게 유지되도록 합니다. 상자를 클릭하면 해당 그림이 그려진 커밋의 코드를 볼 수 있으며, PR이 추가한 라인이 강조 표시됩니다. 거기서 해당 라인에 대해 댓글을 달면 그 댓글이 바로 초안(draft)으로 전송됩니다. 각 그림은 커밋별로 유지되므로, 새로운 푸시가 이루어진 후에도 버전들을 되돌아가면서 무엇이 추가되었고, 변경되었고, 제거되었는지 확인할 수 있습니다.

목록의 마지막 다이어그램은 제가 '단어들이 살아있는 곳(Where the words live)'이라고 부르는 3D 다이어그램입니다. 에이전트는 변경 사항을 추가하거나 건드린 단어를 선택하고, 이를 가족 단위로 그룹화한 다음 몇 가지 사용 사례와 세 개의 축을 명명합니다. Clúsia는 그 후 해당 단어들이 저장소(repository)의 모든 곳에 나타나는 위치를 찾고, 에이전트는 각 파일과 함수를 이 축 위에 배치합니다. 지도를 돌려보거나 PR이 변경한 내용만 필터링할 수 있으며, 어떤 지점이나 클릭하면 코드를 읽고 댓글을 달 수 있습니다. 제가 작성하지 않은 코드를 검토하면서 이름 변경 전에 다른 곳에서 해당 이름에 의존하는 것이 무엇인지 알고 싶을 때 가장 도움이 됩니다.

메뉴 바와 터미널

메뉴 바의 팝오버에는 기다리는 PR, 오래되어 방치된 검토(review) 기록, 그리고 사용자의 검토 활동 히트맵이 표시됩니다. 검토 요청 알림, 검토했던 PR에 대한 새 커밋, 답글, 언급(mention), 실패한 CI 등 다양한 알림을 받고, 조용한 시간(quiet hours)을 설정할 수 있습니다. 차라리 터미널에서 작업하고 싶다면 CLI도 제공됩니다: clusia prs, clusia open owner/repo#123, clusia review publish.

사용해 보기

Mac, Apple silicon 또는 Intel이 필요합니다. 이 스크립트는 Homebrew나 Rust를 사용하여 Clúsia를 소스에서 빌드하며, sudo를 요구하는 적이 없고, 첫 빌드는 약 5분이 걸립니다:

curl -fsSL https://raw.githubusercontent.com/rzorzal/clusia/main/install.sh | bash

실행하기 전에 스크립트를 읽고 싶다면(공평하게), 먼저 다운로드하세요:

curl -fsSL https://raw.githubusercontent.com/rzorzal/clusia/main/install.sh -o install.sh
less install.sh
bash install.sh

첫 실행 시에는 사용자의 gh 로그인을 사용하고, 클론이 저장된 위치를 물어본 다음 설치된 에이전트를 찾습니다. 그런 다음 트레이에서 PR을 열거나 clusia open owner/repo#123 명령어로 열 수 있습니다.

도움 요청

Clúsia는 아직 초기 단계이며, 지금 여러분이 들려주는 이야기가 앞으로의 방향을 결정할 것입니다. 만약 매일 코드 리뷰를 하신다면, 이 도구가 여러분의 작업 방식에 맞는지 꼭 알려주시면 좋겠습니다.

저장소(repo)는 github.com/rzorzal/clusia입니다. 별점을 눌러주시면 다른 리뷰어들이 Clúsia를 찾는 데 도움이 됩니다. 작동하지 않거나, 혼란스럽거나, 빠진 부분이 있다면 이슈(Issue)로 제보해 주세요. 만약 Clúsia가 아직 지원하지 않는 모델이나 도구와 함께 작동하기를 원한다면, harness 프로토콜이 간결하게 설명되어 있으며 Python으로 작동하는 예시도 있습니다.

그리고 댓글을 통해 오늘날 여러분이 PR을 어떻게 리뷰하는지 알려주세요. 다른 사람들의 설정 방식이 궁금합니다.

스크린샷과 함께 웹사이트는 rzorzal.github.io/clusia에서 확인하실 수 있습니다.