PR 리뷰의 인지 부하를 줄이기 위해, AI로 diff에 농담(濃淡)을 넣어 보았다

AI 지원으로 코드를 작성할 기회가 늘어나면, Pull Request (PR)의 수나 크기도 늘어납니다.

AI는 구현을 빠르게 해주지만, 최종적으로 "이 변경은 정말 의도대로인가", "이 비즈니스 규칙은 올바른가", "이 경계 조건에서 문제가 없는가"를 판단하는 것은 여전히 인간의 업무로 남아 있습니다.

반면, 인간의 리뷰 시간은 늘어나지 않습니다.

그래서 PR diff 중에서 인간이 주의해서 봐야 할 곳을 눈에 띄게 만드는 뷰어를 만들고 있습니다.

이름은 Attention Diff입니다.

Attention Diff는 GitHub Pull Request의 diff를, 인간의 확인 필요도에 따른 농담(濃淡, 명암)이 있는 뷰로 표시하는 도구입니다.

목적은 AI 리뷰로 인간의 리뷰를 대체하는 것이 아닙니다.

오히려 반대로, 인간이 리뷰할 때,

• 우선 어디를 봐야 하는가
• 어떤 변경은 가볍게 봐도 괜찮을 것인가
• 어떤 행에는 비즈니스·사양·운용상의 판단이 필요한가
• author에게 무엇을 확인해야 하는가

를 판단하기 쉽게 하는 것을 목적으로 하고 있습니다.

일반적인 diff는 "무엇이 바뀌었는가"를 보여줍니다.

Attention Diff에서는 그것에 더해 "어디에 주의를 기울여야 하는가"를 보여주고 싶다고 생각합니다.

처음에는 "위험해 보이는 파일을 진하게 만드는 것"만으로도 괜찮아 보였습니다.

예를 들어, billing, auth, permission, migration 같은 파일들입니다.

하지만 실제로는 그것만으로는 부족합니다.

billing 파일 안에도 기존 패턴을 복사했을 뿐인 낮은 주의도의 변경이 있습니다.

auth 파일 안에도 alias를 하나 추가했을 뿐인 기계적인 변경이 있습니다.

반대로, 언뜻 보기에는 작은 조건식의 변경이라도,

• 대상자가 바뀜
• 권한이 바뀜
• 기본값(default value)이 바뀜
• fallback의 동작이 바뀜
• 비즈니스상의 임계치(threshold)가 바뀜

이라면, 인간이 확인해야 할 변경이 될 수 있습니다.

그래서 Attention Diff에서는 일반적인 리스크가 아니라, 인간에게 남겨진 판단의 크기를 보도록 하고 있습니다.

진하게 표시되는 행은 인간이 확인해야 할 가능성이 높은 행입니다.

연하게 표시되는 행은 기존 패턴의 복사, 기계적인 치환, 테스트상의 정형적인 변경 등 가볍게 봐도 괜찮을 것 같은 행입니다.

중요한 것은 연한 행에도 이유를 부여하는 것입니다.

"연하니까 안 봐도 된다"가 아니라,

"기존 패턴과 일치하므로, 우선 순위를 낮춰도 괜찮을 것 같다"

라는 설명이 있으면 리뷰어의 납득도가 높아집니다.

현재 MVP에서는 Codex / Claude Code용 플러그인으로서 작동시키고 있습니다.

사용자는 GitHub 리포지토리 내에서 다음과 같이 요청합니다.

/attention-diff 190

내부에서는 대략 다음과 같은 흐름으로 작동합니다.

gh pr view / gh pr diff
↓
diff.json 을 생성
...

포인트는 diff 본체와 AI의 평가 결과를 분리하고 있다는 점입니다.

처음에는 AI에게 "diff를 읽고, 표시용 JSON을 전부 만들어 달라고 할까"도 생각했습니다.

하지만 그런 방식이면 코드 본문을 AI가 재출력해야 합니다.

diff가 큰 PR에서는 토큰(token)이 아깝고, 코드 본문을 AI 출력에 포함하면 표시용 데이터의 원본(source of truth)이 모호해집니다.

그래서 MVP에서는 두 개의 JSON으로 나누었습니다.

diff.json
- 기계적으로 생성함
- code 본문, file, hunk, line, 행 번호를 가짐
...

이렇게 분리함으로써 AI에게 시키고 싶은 일을 "어디에 주의해야 하는지의 판단"에 집중시킬 수 있습니다.

코드 본문이나 행 번호 관리는 확실하게 처리할 수 있는 프로그램 측에 맡깁니다.

attention.json에는 hunk 단위의 확인 이유와 행 그룹 단위의 농담(濃淡)을 넣습니다.

{
"fileId": "file_0001",
"attention": 4,
...
}

실제로는 attention은 1부터 5까지의 5단계로 하고 있습니다.

농담(濃淡)은 단순한 "위험도"가 아니라 "인간이 판단해야 할 정도"로 취급합니다.

실제로 PR에 대해 시도해 보니, 단순히 "위험해 보이는 파일"을 보는 것보다 hunk나 행 단위로 농담이 들어가 있는 편이 리뷰하기 쉽다고 느꼈습니다.

특히 좋았던 점은 기존 패턴의 복사나 기계적인 변경이 연하게 표시되는 것입니다.

규모가 큰 PR에서는 모든 변경을 같은 강도로 읽는 것이 힘듭니다.

하지만, 연하게 표시해도 되는 이유가 덧붙여져 있다면 처음에 어디를 읽을지 결정하기가 더 쉬워집니다.

한편, 현재의 로컬 뷰어(viewer)만으로는 과제도 있습니다.

• IDE의 함수 점프(function jump)를 사용할 수 없음
• 참조 검색이나 타입 정보(type information)를 확인하러 가기 어려움
• GitHub Pull Requests 확장 기능과 같은 PR 리뷰 경험에는 아직 미치지 못함

따라서 Attention Diff를 일반적인 리뷰 화면의 대체제로 만들기보다는, 리뷰 전에 확인하는 주의 지도(attention map) 로 사용하는 것이 좋을 것이라고 생각합니다.

최근에는 뷰어(viewer)에서 VS Code로 바로 이동할 수 있는 링크를 추가하고 싶습니다.

예를 들면,

• 헌크(hunk) 헤더에서 해당 파일의 라인을 열기
• 라인 번호를 클릭하여 VS Code의 해당 라인으로 이동하기
• 주의도가 높은 헌크(hunk)만 순서대로 확인하기

와 같은 방식입니다.

Attention Diff 상에서 "어디를 봐야 할지"를 결정하고, 상세한 확인은 VS Code에서 수행한다.

이러한 역할 분담이 현실적일 것 같습니다.

장기적으로는 작은 VS Code 컴패니언 확장 프로그램(companion extension)을 만들어, Attention Diff의 결과를 IDE 내의 사이드바에 표시하는 것도 고려하고 있습니다.

Codex에서는 다음과 같이 설치할 수 있습니다.

codex plugin marketplace add Basio0916/attention-diff --ref main
codex plugin add attention-diff@attention-diff

Claude Code에서는 다음과 같이 설치할 수 있습니다.

claude plugin marketplace add Basio0916/attention-diff
claude plugin install attention-diff@attention-diff

GitHub CLI와 Node.js 20 이상이 필요합니다.

AI가 코드를 작성하는 양이 늘어나더라도, 인간의 리뷰가 불필요해지는 것은 아닙니다.

오히려 인간이 한정된 시간 내에 어디를 봐야 할지를 판단하는 중요성은 더욱 높아지고 있다고 생각합니다.

Attention Diff에서는 diff에 농담(濃淡, 명암)을 부여함으로써, 리뷰의 인지 부하(cognitive load)를 조금이라도 낮출 수 없을지 시도하고 있습니다.

아직 MVP 단계이지만, AI 리뷰 코멘트를 대량으로 게시하기보다는 우선 인간의 주의 배분을 돕는 UI로서 키워나가고 싶습니다.