코드 리뷰 on monkshark.dev

#3 - 요약을 온디바이스로, 네 엔진을 한 입구로

Tue, 23 Jun 2026 12:00:00 +0900

마지막으로 얹은 건 PR 요약이다. 어려운 건 요약 자체가 아니라, “공짜로, 키 없이, diff 를 밖으로 안 보내고"와 “필요하면 최고 품질로"를 한 버튼 뒤에 같이 두는 일이었다.

기본은 온디바이스, 클라우드는 옵트인

PR 을 AI 로 요약하려면 보통 diff 를 외부 모델로 보낸다. 코드 리뷰 도구가 매번 변경 내용을 남의 서버로 흘리는 건 기본값으로 두기엔 부담스러웠다. 그래서 기본 엔진을 브라우저 안에서 도는 모델로 잡았다.

엔진은 넷이다. Chrome 내장 모델(Gemini Nano)은 키도 비용도 없이 기기 안에서 돌고, WebLLM 은 WebGPU 로 브라우저 안에서 도는데 첫 사용 때 가중치를 한 번 받아 캐시한 뒤로는 오프라인으로도 된다. 더 안정적인 클라우드가 필요하면 무료 키의 Gemini, 최고 품질이 필요하면 자기 키의 Claude 를 옵트인으로 고른다. 기본은 아무것도 안 나가고, 무언가 나가는 선택은 사용자가 직접 켠다.

네 엔진을 한 모양으로

엔진마다 호출법이 딴판이다. 내장 모델은 세션을 만들어 스트림을 reader 로 읽고, WebLLM 은 OpenAI 풍 chat.completions 스트림, Gemini 는 날 SSE 를 직접 파싱, Claude 는 공식 SDK 의 messages.stream 을 쓴다. 이걸 호출부에 그대로 노출하면 UI 가 엔진 수만큼 갈라진다.

그래서 전부 같은 모양으로 감쌌다. system·user 프롬프트를 받아, 토큰이 올 때마다 onChunk 로 흘려보내는 함수. 안쪽이 SSE 든 SDK 든, 바깥에서 보면 똑같이 “조각이 스트리밍된다"가 된다.

1
2
3
4
5
6
7


const stream = session.promptStreaming(user)
const reader = stream.getReader()
for (;;) {
 const { done, value } = await reader.read()
 if (done) break
 if (value) onChunk(value)
}

입력은 diff, 출력은 한국어 고정

요약할 재료는 GitHub REST API 에서 가져온다. PR 메타와 변경 파일을 페이지네이션으로 긁고(비공개 저장소나 rate limit 은 PAT 로 푼다), 너무 길면 정해둔 길이에서 자른 뒤 “이후 생략” 을 표시한다.

프롬프트는 출력 형식을 못박는다. UI 언어가 영어든 한국어든 요약 본문은 한국어로 고정하고, “한 줄 요약 / 핵심 변경점 / 리뷰 포인트” 세 섹션의 마크다운으로만 답하게 한다. 작은 온디바이스 모델일수록 형식을 흔들기 쉬워서, 자유도를 줄이는 쪽이 결과가 안정적이었다. 한 번 생성한 요약은 PR 별로 저장해, 다시 들어오면 곧바로 보여준다.

돌아보면

3부의 핵심은 모델이 아니라 입구였다. 성능과 프라이버시가 다른 네 엔진을 같은 한 줄 인터페이스 뒤에 세우고, 그 입구의 기본값을 “기기 안, 무료, 아무것도 안 나감"으로 둔 것. 더 좋은 걸 원하면 키를 꽂아 옵트인하면 되고, 아무것도 안 하면 가장 안전한 쪽이 작동한다. 도구가 사용자 대신 내리는 기본 선택이 가장 정직해야 한다는 게, 이 프로젝트 내내 지킨 원칙이었다.

#2 - 남의 DOM 위에 세 들어 산다

Tue, 23 Jun 2026 11:00:00 +0900

패널을 띄우는 건 쉬웠다. 어려운 건, 그 패널이 남의 페이지 위에서 — GitHub 가 마크업을 바꿔도, diff 를 천천히 그려도 — 깨지지 않고 버티게 하는 것이었다.

셀렉터는 한 곳에 모으고, 사다리로 쌓는다

확장은 GitHub DOM 에 기댄다. 그런데 GitHub 는 자기 마크업을 수시로 바꾼다. 클래스 이름이 갈리고, data-testid 가 생겼다 없어지고, 같은 시기에 옛 마크업과 새 마크업이 섞여 나오기도 한다. 셀렉터를 코드 곳곳에 흩뿌리면 그 변화 한 번에 전부 무너진다.

그래서 DOM 을 읽는 지점을 셀렉터 모듈 하나로 모았다. 파일 컨테이너는 후보를 여러 개 묶어, 신·구 마크업을 한꺼번에 받는다.

1
2
3
4
5
6


fileContainer: [
 'div.file.js-file',
 'div.file[data-tagsearch-path]',
 '[data-testid="file-diff"]',
 '[class*="diffTargetable"]',
].join(',')

파일 경로를 뽑을 때도 한 방법에 걸지 않았다. data-tagsearch-path 속성 → 앵커 텍스트 → Diff for: 표 라벨 → 내부 속성 → 파일 헤더 링크 title 순으로 내려가며, 하나가 실패하면 다음을 시도한다. 수치(+/-)도 같은 식으로 aria-label → 색상 클래스 → 옛 diffstat 까지 폴백을 깔았다.

못 찾으면, 조용히 비운다

폴백을 다 내려가도 아무것도 못 찾는 날은 온다. 그럴 때 절대 하지 말아야 할 건, 에러를 던져 GitHub 페이지 자체를 망가뜨리는 것이다. 그래서 파일을 하나도 못 찾으면 패널은 깨지는 대신 “바뀐 파일 없음” 안내를 띄운다. 내가 못 읽는 게 사용자 페이지를 부수는 일이 되면 안 된다.

내가 일으킨 변화에 내가 반응하지 않기

GitHub 는 diff 를 한 번에 안 그린다. 스크롤하면 파일이 점점 붙는다. 그래서 DOM 변화를 MutationObserver 로 지켜보다 다시 스캔해야 한다. 그런데 함정이 있다. 패널과 체크박스를 주입하는 것도 DOM 변화라, 내 주입이 옵저버를 깨우고, 그게 또 재스캔과 재주입을 부르는 무한 루프가 된다.

두 겹으로 막았다. 변화가 전부 내 패널 안에서 난 거면 무시하고,

1
2
3
4
5
6


function isOwnMutation(records) {
 return records.every((r) => {
 const t = r.target
 return !!(t.closest?.('#gh-prh-panel') || t.closest?.('.gh-prh-seen'))
 })
}

재스캔하는 동안에는 옵저버를 잠시 끊었다가, 끝나고 다시 잇는다. 내가 만든 변화가 나를 다시 깨우지 못하게.

또 매번 목록을 통째로 다시 그리면 깜빡이고 느리다. 그래서 파일 경로와 수치로 시그니처를 만들어, 지난번과 같으면 “봤음” 표시만 토글하고 DOM 은 건드리지 않는다.

돌아보면

2부는 기능이 아니라 규율에 대한 얘기였다. 남의 DOM 위에 세 들어 사는 코드는, 집주인이 벽을 옮겨도 버티고(폴백 사다리), 못 버틸 땐 조용히 비키고(graceful degrade), 자기가 일으킨 먼지에 자기가 기침하지 않아야(자기 변경 무시) 한다. 화면에 안 보이는 이 세 가지가 패널을 오래 살아남게 한 진짜 이유였다.

#1 - 큰 PR 은 어디까지 봤는지부터 잃는다

Tue, 23 Jun 2026 10:00:00 +0900

PR Lens 는 GitHub 의 큰 Pull Request 를 리뷰할 때 “어디까지 봤는지"를 잃지 않게 돕는 Chrome 확장이다. Files changed 페이지에 바뀐 파일 트리를 띄우고, 본 파일을 PR 별로 기억하고, 남은 진도를 항상 보여준다. 한 줄로 줄이면, 수십 개 파일 diff 사이에서 길을 잃지 않게 하는 도구다.

큰 PR 은 기능보다 진도를 먼저 잃는다

파일이 마흔 개쯤 되는 PR 을 열면, 스크롤을 내리다 방금 본 파일이 어디였는지, 무엇이 남았는지 금세 흐려진다. 새로고침하거나 다른 PR 을 들렀다 오면 그 감각은 통째로 리셋된다. 그래서 첫 목표는 화려한 게 아니라 단순했다. 본 파일을 기억하고, 남은 게 몇 개인지 늘 보이게.

패널은 페이지에 얹고, 상태는 PR 에 붙인다

Files changed 페이지에 떠 있는 패널을 하나 주입한다. 바뀐 파일을 전부 나열하고, 각 줄에 +/- 수치와 “본 파일” 체크박스, 위에는 “Seen N/M today” 진행 바를 둔다. 줄을 클릭하면 그 파일 diff 로 곧장 스크롤한다.

기억은 PR 단위로 묶어야 의미가 있다. URL 에서 PR 을 식별해 키로 삼고, 그 키 밑에 본 파일을 저장한다.

1
2
3
4
5
6


export function parsePrUrl(pathname: string) {
 const m = pathname.match(/^\/([^/]+)\/([^/]+)\/pull\/(\d+)/)
 if (!m) return null
 const [, owner, repo, num] = m
 return { owner, repo, number: Number(num), prKey: `${owner}/${repo}#${num}` }
}

상태는 chrome.storage.local 에 pr:owner/repo#번호 키로 들어간다. 체크 한 번이 { seen: true, at } 로 박히고, 새로고침하든 며칠 뒤 다시 오든 그대로 복원된다.

GitHub 는 페이지를 새로 안 띄운다

여기서 막혔다. content script 는 페이지가 로드될 때 한 번 돈다. 그런데 GitHub 는 SPA 라, PR 목록에서 Files changed 로 넘어가도 페이지가 새로 뜨지 않는다. pushState 로 URL 만 갈아끼운다. 그러면 스크립트는 처음 들어온 그 순간에 멈춰 있고, 패널은 영영 안 뜬다.

그래서 history 를 후킹했다. pushState·replaceState 를 감싸 호출될 때마다 자체 이벤트를 쏘고, popstate 까지 묶어 네비게이션을 직접 감지한다.

1
2
3
4
5
6
7
8


for (const key of ['pushState', 'replaceState'] as const) {
 const original = history[key]
 history[key] = function (...args) {
 const result = original.apply(this, args)
 window.dispatchEvent(new Event('gh-prh-loc'))
 return result
 }
}

이벤트가 오면 300ms 디바운스 뒤 현재 경로가 Files changed 인지 확인하고, 맞으면 패널을 띄운다. 같은 PR 안에서의 이동이면 다시 그리지 않고 스캔만 갱신하고, 다른 PR 로 갔으면 헐고 새로 짓는다.

돌아보면

1부에서 만든 건 결국 두 가지다. 본 파일을 PR 에 묶어 기억하는 것, 그리고 페이지가 새로 뜨지 않는 SPA 위에서도 그 기억을 제때 띄우는 것. 리뷰 보조라는 말은 거창하지만, 실제로 사람을 편하게 한 건 “어디까지 봤더라"를 대신 들고 있어 주는 이 단순한 영속성이었다.