Jev로 PR에서 변경 이유를 골라 CHANGELOG에 담는 방법

AI 요약

PR에서 변경 내용(WHAT)을 뽑기는 비교적 쉽지만, 왜 바꿨는지(WHY)를 알아내기는 어렵습니다. 글쓴이는 LLM에 PR 전체를 주고 이유를 쓰라고 하면 원문에 없는 의도를 만들어내거나 표현을 바꿀 수 있다고 봅니다. 그래서 changelog-bot은 WHY 추출을 문장 생성이 아니라 근거 선택 문제로 다룹니다.

후보 문장 추리기

먼저 PR 설명에서 why, reason, because, motivation, context, problem, rationale 같은 섹션 이름과 표현을 찾습니다. 체크박스, 자리표시자, 관련 없는 항목은 제거하고, 이유가 될 법한 짧은 문장 후보를 만듭니다. 예를 들어 “공유 런타임 설정을 ProviderBase로 옮긴다”는 구현 내용이고, “중복 설정을 줄이고 새 제공자를 쉽게 추가한다”는 이유에 가까운 후보입니다.

이유인지, 해당 변경의 이유인지 평가하기

Jev는 각 후보에 두 가지 질문을 적용합니다. 첫째, 후보가 변경 이유를 명시적으로 말하는지 평가합니다. 둘째, 그 이유가 이번 CHANGELOG 변경에 실제로 해당하는지 살핍니다. README 설명을 고친 이유가 들어 있어도 캐시 무효화 수정과는 관계가 없을 수 있기 때문입니다. 각 후보에는 명시적 이유 확률과 변경 관련성 확률이 따로 붙습니다. 두 확률을 비교해 가장 나은 후보를 고른 뒤, 각각의 최소 임계값도 넘어야 채택합니다. 어느 기준이든 통과하지 못하면 WHY를 추가하지 않습니다.

채택한 이유는 모델이 다시 쓴 문장이 아니라 PR 작성자가 쓴 원문 그대로입니다. 따라서 믿을 만한 이유가 PR에 없다면 결과도 비워 둡니다. 글쓴이는 그 편이 근거 없는 설명을 만들어 넣는 것보다 낫다고 설명합니다.

결정적 처리와 선택적 AI 보강

글쓴이가 v1 파이프라인에서 내세우는 원칙은 결정적 처리(deterministic-first)입니다. AI를 끄거나 호출에 실패해도 완전한 CHANGELOG가 만들어져야 하며, AI는 결과를 보강하되 결과 자체를 책임지지 않습니다. 변경 정보를 구조화하고 결정적으로 분류해 완성된 ReleaseDraft를 만든 다음, 선택적으로 편집 보강과 WHY 보강을 적용합니다. 마지막 Markdown 출력은 결정적 렌더러가 맡습니다.

기존 일부 흐름은 생성된 Markdown에서 WHY를 넣을 위치를 찾고 나중에 문장을 삽입합니다. v1에서는 그 경계를 없애고 { prNumber, why, confidence } 형태의 구조화된 릴리스 데이터에 이유를 먼저 담습니다. WHY 엔진은 근거를 찾고, 렌더러는 근거를 표시합니다. 글에 따르면 마이그레이션 1~4단계는 구현됐으며, 구조화된 렌더링과 보강 경계는 다음 단계에 포함됩니다.

임계값을 사례로 검증하기

확률 임계값을 감으로 정하지 않도록 처음에는 14개 사례로 평가 도구를 만들었습니다. 구현 내용만 있고 명시적인 이유가 없는 사례에는 정답을 null로 지정합니다. 기여자 John은 이를 약 50개 사례로 확장했고, 명시적 근거, 구현 정보만 있는 경우, 템플릿 잡음, 다국어 PR을 포함했습니다. 정답 데이터는 Jev의 현재 임계값과 독립적으로 정한 뒤, 0.4부터 0.9까지 여러 임계값을 비교해 정밀도(precision), 재현율(recall), F1을 측정합니다. 글쓴이는 이 방식으로 “0.8이면 안전해 보인다”는 추측 대신 성능을 비교하겠다고 설명합니다.

현재 흐름은 PR 본문 정규화, 후보 추출과 잡음 제거, 로컬 신뢰 검사, Jev 평가, 임계값 적용 순입니다. 최종 산출물에는 통과한 후보만 원문 그대로 들어갑니다. changelog-bot과 Jev 지원은 아직 실험 단계입니다.

dev.to 반응

• @johnnylemonny — 따뜻하게 소개해 주고 글로 정리해 줘서 고맙습니다, @nyaomaru! 😸 이 작업을 함께한 경험은 정말 즐거웠습니다. WHY 문제를 다룰 때, LLM이 환각을 일으키거나 이유를 바꿔 쓰게 두지 않고 작성자의 원문을 유지하면서 근거 선택 문제로 다루기로 한 결정이 결과를 믿을 만하게 만듭니다. PR #212에서 50개 사례 평가 도구를 함께 설계한 일도 좋았습니다. 정답 데이터가 특정 임계값과 독립적이어야 한다는 당신의 주장은 정확했습니다. 덕분에 추측 대신 정밀도와 재현율을 측정할 기준이 생겼습니다. Markdown을 나중에 고치는 대신 렌더링 전에 보강 데이터를 구조화하는 결정적 우선 v1 파이프라인에 이 설계가 잘 들어맞는 모습도 좋습니다. changelog-bot을 계속 만들고 다듬을 생각에 기대가 큽니다! 🚀
  • @nyaomaru — 정말 고마워요, John! 😸 함께 작업하는 일이 저에게도 아주 즐거웠습니다! 50개 사례 평가 도구와 임계값 비교를 만들어 준 덕분에 이 실험이 훨씬 탄탄해졌어요. “안전해 보인다”는 감에 기대지 않고 접근 방식을 측정할 방법이 생겼습니다. 결정적 우선 v1 방향이 잡혀 가는 모습이 정말 마음에 들고, changelog-bot을 계속 만들어 갈 생각에 기대가 큽니다! 🚀
  • @antonioprosperi2svg — 이 글 고맙습니다. 정말 유용했어요! 😸 재미있게도 좋은 의미로 제 관심을 다른 데로 돌려놨습니다. WHY 추출 이야기를 읽다가 제 프로젝트에는 기본적인 것, CHANGELOG가 빠졌다는 사실을 깨달았습니다. 바닐라 JS로 만든 작은 2D 게임 엔진 BeeEngine을 관리하는데, README만 둔 채 v2.0에서 v2.10.0까지 왔더라고요 😅 글 덕분에 이제 제대로 된 CHANGELOG.md가 생겼고, 앞으로 개발자들이 무엇이 왜 바뀌었는지 알 수 있게 됐습니다. WHY를 생성 문제가 아니라 선택 문제로 보고 PR 원문을 근거로 남기는 아이디어가 정말 좋습니다. changelog-bot은 규모도 크고 많이 고민한 프로젝트 같네요. v1을 응원하고, 벤치마크를 만든 John에게도 박수를 보냅니다! 🙌
• @fgrandon — Git diff를 요약하는 대신 아키텍처 변경의 ‘이유’를 뽑아내는 일은 자동화된 변경 로그의 성배입니다. 대부분의 LLM 기반 릴리스 도구는 바뀐 함수만 나열해서 사용자에게 잡음이 됩니다. 의미와 사용자 영향을 살피면 결과물이 실제로 읽기 좋아집니다. 이렇게 세심하게 다듬는 모습을 보니 좋네요!
• @codemaster_121482 — 그 링크를 누르지 마세요! 피싱 사기입니다.
  • @nyaomaru — 친절하게 알려주셔서 고맙습니다! 😸
  • @koda2026 — 이 점을 알려줘서 고마워요! 🐯 커뮤니티가 서로 피싱 봇을 조심하고 도와주는 일이 정말 중요합니다. 모두를 안전하게 지키고 피드를 깨끗하게 유지해 줘서 고맙습니다! 🛡️

원문: dev.to / 번역·요약: Trawling