서론

AI 에이전트에게 코드를 작성하게 하는 기회가 늘어남에 따라, PR의 diff 행수가 점점 늘어나고 있습니다. +1,342 -286 같은 숫자를 보고 "윽" 하고 움찔하게 되는 것 — 이것이 m3tech의 야마모토 씨가 **rinkaku(輪郭, 윤곽)**라는 도구를 만든 동기입니다.

rinkaku의 주장은 심플합니다.

"변경의 시그니처(Signature, 함수명, 인자, 반환값)와 그로부터 한 단계만 따라갈 수 있는 의존 관계를 먼저 보여준다. 상세 내용은 궁금하면 읽으면 된다."

이는 합리적으로 보이지만, 몇 가지 궁금한 점이 있습니다.

윤곽만으로 정말 버그를 찾아낼 수 있을까?
기존의 git diff 전체 읽기와 비교했을 때, 무엇이 좋고 무엇이 나쁜가?

이 기사에서는 rinkaku를 실제로 빌드하고, 의도적으로 버그를 심어놓은 샘플 PR에 적용하여, 윤곽 우선 리뷰의 실력을 검증합니다.

rinkaku란

rinkaku는 Rust로 제작된 CLI 도구입니다. PR의 diff를 "변경된 심볼의 시그니처와 1단계의 의존 관계"로만 응축하여 표시합니다.

주요 특징:

• tree-sitter를 이용한 구문 기반 의존성 해결 (LSP 불필요, 빌드 불필요)
• 지원 언어: Rust / Go / Python / TypeScript
• TUI 모드 (의존 순서 트리 + 키보드 점프 + annotation 기능)
• CLI 모드 (Markdown / JSON / digest / mermaid)

GitHub: hiro-o918/rinkaku

검증 준비

빌드

Rust가 설치되어 있다면 특별한 문제 없이 빌드할 수 있었습니다.

git clone https://github.com/hiro-o918/rinkaku.git
cd rinkaku
cargo build --release
...

Homebrew로도 설치할 수 있습니다 (brew install hiro-o918/tap/rinkaku).

심어놓은 버그

"AI가 생성한 여러 파일에 걸친 PR"을 모사한 Rust 샘플 프로젝트를 준비하여, 4개의 버그를 심었습니다.

• before: 기본적인 EC 도메인 (6개 파일, 144행)
• after: 바우처 기능 추가 (8개 파일, 678행 추가, 275행의 diff)

rinkaku의 출력

# sample-pr 리포지토리 내에서
rinkaku --base ac8f0f1 --format md

출력 (일부 발췌):

## Change graph
19 changed symbols in 6 files
- fn main (src/main.rs) — uses: Voucher
...

이것만으로도 "바우처 기능이 추가되어, Database에 vouchers 필드가 늘어나고, CheckoutService에 checkout_with_voucher가 생겼다"는 전체상을 파악할 수 있습니다.

--format digest를 사용하면 더욱 간결한 API 변경 목록이 됩니다. --format json을 사용하면 구조화된 데이터로 출력할 수 있습니다.

검증 결과

좋았던 점: 개관 파악이 압도적으로 빠름

275행의 diff가 Markdown 출력으로 화면 1~2 스크롤 안에 들어왔습니다. digest 형식이라면 2초 만에 모든 변경 시그니처를 파악할 수 있습니다.

특히 뛰어나다고 느낀 점:

1. 시그니처 변경의 가시화

struct Database의 필드 추가가 diff 형식으로 표시되는 점이 훌륭합니다.

-struct Database { users: Vec<User>, orders: Vec<Order> }
+struct Database { users: Vec<User>, orders: Vec<Order>, vouchers: Vec<Voucher> }

git diff의 행 단위로는 「+ vouchers: Vec<Voucher>」라는 한 줄로 흘러가 버리기 쉽지만, 구조체 전체의 시그니처 (Signature) 비교로서 보여주기 때문에 「아, DB 설계가 바뀌었구나」라고 의식하기 쉽습니다.

2. High fan-in의 검출

Voucher가 4곳에서 참조되고 있다고 자동으로 표시되었습니다. 이는 「이 struct의 변경은 영향 범위가 넓다」라는 설계 판단의 트리거가 됩니다. AI 생성 코드에서 흔히 발생하는 「밀결합 (Tight coupling)의 온상」을 조기에 발견하는 데 도움이 될 것 같습니다.

3. 파일 크기의 시각화

각 행에 lines:N이 표시됩니다. 임계값을 초과하면 색상이 표시됩니다. AI 에이전트는 한 파일에 내용을 몰아넣는 경향이 있으므로, 「이 파일은 슬슬 분리하는 편이 좋겠다」라는 판단 근거가 됩니다.

과제: 함수 body의 버그는 전멸

그리고 여기가 가장 중요한 검증 포인트입니다.

심어놓은 4개의 버그는 모두 rinkaku의 윤곽 출력만으로는 전혀 발견할 수 없었습니다.

• B1:
  Voucher::is_valid(&self) -> bool
  — 이 시그니처만 보고 부등호 방향이 반대라는 것을 읽어내는 것은 불가능
• B2:
  CompositeDiscount::calculate(&self, user, order) -> f64
  — sum()이 1.0을 초과할지는 body를 보지 않으면 알 수 없음
• B3:
  EmailService::send_order_confirmation(user, order_id, amount)
  — 이메일 주소 생성 로직의 오류는 body에 달려 있음
• B4:
  checkout_with_voucher(..., voucher_code)
  — 소유권 체크 누락은 body에 달려 있음

이는 당연하다면 당연한 결과입니다. rinkaku는 「함수의 내용은 읽지 않는다」라는 절제를 바탕으로 설계되었기 때문입니다. 공식 문서에서도 명확하게 기재되어 있습니다:

상세한 리뷰를 하는 도구가 아니라, 우선 개요를 파악하고, 신경 쓰이는 부분이나 코드 스멜 (Code smell)의 단서를 잡기 위한 도구

문제는, 이 절제를 이해하지 못한 채 「윤곽만으로 리뷰 완료」라고 해버리면, 함수 body의 버그를 모두 놓치게 된다는 리스크입니다.

git diff와의 비교표

고찰: 윤곽 우선의 최적 워크플로우

이 검증을 통해, rinkaku의 최적의 사용법은 다음과 같은 흐름이라고 생각합니다:

• 윤곽을 훑어보기 (30초): rinkaku --format md | head로 변경의 전체상과 High fan-in 심볼을 파악
• 신경 쓰이는 시그니처에 표시하기: api:1+, High fan-in, lines:큼 등에 주의
• 신경 쓰이는 부분만 상세 diff 읽기: git diff main -- path/to/file로 body를 확인
• 안심하고 싶은 파일은 전체 diff도 읽기: 특히 테스트 파일이나 데이터 처리의 핵심 부분

중요한 것은, 윤곽으로 전모를 파악한 뒤에 「어느 함수의 body를 읽어야 할까」를 취사선택하는 판단 재료로 사용하는 것입니다. 윤곽만으로 리뷰를 끝내지 마십시오.

특히 AI 생성 PR에서는 「시그니처는 올바르지만 body의 로직이 망가져 있는」 경우가 흔한 패턴입니다. 이번 검증에서도 4개의 버그 중 3개가 「시그니처는 완전히 정상, body만 망가져 있는」 버그였습니다. 윤곽만으로는 절대로 알아챌 수 없습니다.

TUI 모드 (미검증)

rinkaku에는 --tui 플래그로 실행하는 대화형 모드도 있습니다. 의존 순으로 정렬된 파일 트리를 상하로 이동하며 gr / gd로 정의/참조 점프, a...

하며 annotation(지적 메모)을 작성해 둘 수 있습니다.

본 검증의 headless 환경에서는 실행할 수 없었습니다(Error: Device not configured). 실제 터미널 세션에서는 핫키(hotkey) 조작을 사용할 수 있을 것이며, 저자의 블로그 기사 스크린샷을 보면 위에서 아래로 이어지는 의존 순서 트리(dependency tree)와 오른쪽 페인의 diff 표시 조합은 매우 강력해 보입니다.

rinkaku의 limitations (코드 리딩을 통한 이해)

tree-sitter를 채택한 것에는 트레이드오프(trade-off)가 있습니다.

장점:

• LSP 불필요, 빌드 불필요 → 어떤 리포지토리(repository)에서도 즉시 동작
• 싱글 바이너리(single binary)로 배포 가능
• 처리가 1초 미만(sub-second)

한계:

• 동일한 이름의 함수를 구분할 수 없음 (타입 정보가 없기 때문)
• 동적 디스패치(dynamic dispatch) 추적 불가
• 매크로(macro)를 통한 호출 해결 불가
• "변경 심볼로부터 딱 1단계만"이라는 제약 (전체를 따라가면 결국 커다란 덩어리를 읽게 된다는 설계 판단)

저자인 야마모토(Yamamoto) 씨도 기사에서 "정밀도가 문제가 된다면 그때 방침을 생각하자"라고 적었습니다. 현시점에서는 "얇은 휴리스틱(heuristic)이지만 실용상 충분하다"는 느낌인 듯합니다.

유사 도구와의 비교

Perplexity API로 선행 기사를 검색한 결과, rinkaku 그 자체를 제삼자가 검증한 기사는 발견되지 않았습니다 (2026년 8월 기준).

비슷한 발상의 도구 및 기사:

• Code Review Graph: tree-sitter로 의존 그래프를 만들어 49배의 토큰 절감을 주장. rinkaku보다 중후한 설계
• PR-Agent: AI를 통한 PR 리뷰 자동화. 코드 스멜(code smell) 탐지 등의 범위는 넓지만, tree-sitter 의존 방식은 아님
• 기존의 "2패스(2-pass) 방식" 기사: 인간을 위한 리뷰 기법으로서 "먼저 전체상 → 상세 내용"은 자주 언급되지만, 도구로 구현된 사례는 적음

**rinkaku의 독자성은 "tree-sitter를 통한 경량 의존성 해결 × 윤곽 우선의 UI/UX"**에 있습니다. LSP 없이 동작하는 간편함과, 시그니처(signature) + 1단계 의존성으로만 범위를 좁힌 결단력이 최대의 차별화 포인트입니다.

요약

윤곽 우선 리뷰는 "빠르지만" "그것만으로는 불충분"합니다

올바른 사용법은 다음의 3층 모델입니다:

1. rinkaku로 윤곽을 잡는다 (출구 전략을 결정한다)
2. 궁금한 시그니처만 상세 diff를 읽는다 (정밀 타격)
3. 중요한 파일은 전체 diff를 통독한다 (보험)

AI가 작성한 코드를 "인간이 리뷰하는" 시대에는 오히려 인간의 판단이 더욱 중요해지고 있습니다. rinkaku는 "어디를 중점적으로 읽어야 하는가"를 판단하기 위한 재료로 사용할 때 가장 효과적이라고 결론짓습니다.

본 기사는 검증을 위한 실험이며, 필자는 rinkaku의 개발자가 아닙니다.

Discussion