개발자 자동화 실습 01 — PR summary를 직접 만들고 실제 PR에서 확인했다

오늘은 PR summary를 공부하고, 이 저장소에 이미 들어와 있는 자동화를 직접 실습했다.

처음에는 단순히 "PR을 요약해 주는 기능" 정도로 생각했다. 그런데 실제로 문서와 코드를 따라가 보니, 이 기능의 목적은 예쁘게 요약문을 만드는 게 아니라 리뷰어가 어디를 먼저 봐야 하는지 구조화해서 보여주는 것에 더 가까웠다.

이 글은 그 흐름을 그대로 정리한 기록이다.

---

PR summary를 처음 이해할 때 생긴 오해

처음에는 이런 식으로 이해했다.

• 올라온 PR을 평가하는 도구인가?
• 좋은 PR이면 코멘트를 안 달고, 문제 있는 PR만 지적하는가?
• 커밋 메시지에도 같이 붙는가?

실제로 확인해 보니 답은 다 달랐다.

PR summary는 평가기보다 리뷰 보조 도구에 가깝다.

• PR이 좋든 나쁘든 같은 형식으로 코멘트를 단다
• 커밋 단위가 아니라 PR 단위로 동작한다
• 작성자가 쓴 PR 본문을 대체하지 않고, 그 위에 리뷰 프레임을 추가한다

즉 이 자동화는 "이 PR이 나쁘다"를 말하는 봇이 아니라, "이 PR은 이런 관점으로 보면 된다"를 먼저 정리해 주는 봇이다.

---

이 저장소의 PR summary는 무엇을 보는가

기준 문서부터 읽었다.

• pr summary
• pull request
• cross repo ai automation lab

핵심은 저장소 역할이었다.

ai-survival-log-site는 runtime, API, build를 먼저 보는 저장소고, ai-survival-log는 raw -> wiki -> output/blog -> publish 계약을 먼저 보는 저장소다.

그래서 이 저장소의 PR summary는 보통 아래를 먼저 묻는다.

• wiki source-of-truth 경계를 흐리는가
• publish contract 또는 downstream 호환성을 깨는가
• wiki/index.md, wiki/log.md, tags 동기화가 필요한가
• 문서와 운영 모델 설명이 어긋나는가

같은 PR summary라도 저장소 역할이 다르면 질문이 달라져야 한다는 점이 이번 실습의 첫 번째 포인트였다.

---

실제 스크립트는 규칙 기반으로 돌아간다

그다음에는 scripts/pr-summary.mjs 를 읽었다.

처음에는 "혹시 이미 LLM이 붙어 있나?"라고 생각했는데, 실제 구현은 그렇지 않았다.

현재 버전은 완전히 규칙 기반이다.

changed files 수집
  → category 분류
  → risk 계산
  → verification impact 생성
  → review points / reviewer questions 생성
  → markdown 출력

예를 들어:

• wiki/ 아래 파일이면 wiki
• docs/publishing-contract.md 나 publish 관련 경로면 publish-contract
• scripts/ 아래 파일이면 script
• AGENTS.md, CLAUDE.md, .claude/, .codex/는 agent-surface

같은 식으로 분류한다.

이 규칙 기반 설계가 좋은 이유는 간단하다.

• 빠르다
• 예측 가능하다
• 왜 이런 결과가 나왔는지 추적하기 쉽다
• API 비용 없이 GitHub Actions에서 바로 돌릴 수 있다

대신 한계도 분명하다.

• 파일 경로 기준이라 실제 diff 의미를 완전히 이해하지는 못한다
• "왜 바뀌었는지"보다는 "어디가 바뀌었는지"에 강하다

그래도 1차 자동화로는 충분히 강력했다.

---

로컬에서 먼저 실습해 봤다

이 자동화가 좋았던 점은, PR을 올리기 전에도 로컬에서 그대로 재현할 수 있다는 점이었다.

예를 들어 이렇게 실행할 수 있다.

node scripts/pr-summary.mjs --files "wiki/concepts/pr-summary.md,wiki/concepts/pull-request.md,wiki/index.md,wiki/log.md,wiki/tags/automation.md,wiki/tags/code-review.md,wiki/tags/github.md,wiki/tags/pull-request.md,wiki/tags/workflow.md"

의미는 단순하다.

"이 9개 파일이 바뀐 PR이 있다고 가정하면 어떤 summary가 나오는가?"

실행 결과는 대략 이런 구조였다.

## PR Summary

- 요약: 9개 파일 변경
- 범주: wiki
- 위험도: medium

## Verification Impact

- wiki 구조 또는 자동화 경로 변경 있음
- 확인 권장: python3 scripts/wiki lint --summary

여기서 중요한 건 문장 품질보다도, 지금 이 변경을 어떤 범주로 읽고 어떤 검증을 먼저 해야 하는지가 바로 보인다는 점이었다.

작성자 관점에서는 이걸 사전 점검 도구로 쓸 수 있다.

• 위험도가 예상보다 높게 나오면 PR을 더 쪼갤지 판단
• review points를 보고 PR 본문에 설명을 더 추가
• 필요한 검증 명령을 PR 열기 전에 먼저 실행

즉 GitHub Actions가 공식 버전이라면, 로컬 실행은 그걸 미리 보는 프리뷰 버전이다.

---

실제 PR을 열고 GitHub comment까지 확인했다

실습은 여기서 끝내지 않았다.

별도 브랜치를 만들고 실제로 PR을 올린 뒤, GitHub Actions가 코멘트를 다는지까지 확인했다.

흐름은 이랬다.

1. 별도 브랜치 생성
2. 위키 문서 추가 및 갱신
3. 원격 브랜치 push
4. GitHub에서 PR 생성
5. pr-summary workflow 실행
6. PR Conversation 탭에서 bot comment 확인

실제로 확인한 결과, PR 페이지에 github-actions가 자동 코멘트를 남겼다.

위 화면에서는 요약, 범주, 위험도, Changed Files 일부가 실제 PR 코멘트에 어떻게 보이는지 확인할 수 있다.

하단에는 Verification Impact, Review Points, Reviewer Questions가 이어진다. 즉 로컬에서 보던 markdown 출력이 실제 GitHub PR 대화 탭에서도 거의 같은 구조로 게시된다.

즉 이 자동화는 문서로만 존재하는 게 아니라:

• 로컬 스크립트로도 재현 가능하고
• GitHub Actions에서도 실제로 돌고
• PR 코멘트까지 자동 게시된다

여기까지 확인하고 나니, PR summary가 추상적인 아이디어가 아니라 팀 리뷰 루틴에 바로 붙일 수 있는 작은 자동화라는 감각이 확실해졌다.

---

LLM을 붙일 수는 있지만, 지금은 규칙 기반이 더 맞다

중간에 자연스럽게 이런 질문도 생겼다.

이걸 나중에 LLM으로 더 똑똑하게 만들 수는 없을까?

답은 "가능하다"였지만, 지금 단계에서는 굳이 그럴 필요는 없다는 쪽으로 정리했다.

이유는 명확하다.

• 현재 구조만으로도 분류, 위험도, 검증 포인트, 리뷰 질문이 충분히 동작한다
• 실제 PR 코멘트 생성까지 이미 검증했다
• LLM을 붙이면 비용, 보안, 출력 흔들림 같은 운영 이슈가 추가된다

그래서 방향은 이렇게 잡는 게 맞아 보였다.

• 지금은 규칙 기반 유지
• 나중에 필요하면 LLM은 설명기로만 붙이기

즉 범주 분류와 필수 검증 명령은 규칙 기반이 잡고, LLM은 나중에 "왜 이 PR이 위험한가"를 더 자연스럽게 설명하는 역할만 맡는 구조다.

이 순서가 좋은 이유는, 자동화의 핵심 계약이 먼저 안정되고 나서야 의미 해석 고도화를 붙일 수 있기 때문이다.

---

FinSight 로드맵과 연결

이번 PR summary 실습은 finsight roadmap의 Project 2 PR Reviewer 에이전트로 이어진다.

이미지에서 Project 2는 네 요소로 구성되어 있었다.

• Rules 컨벤션
• Hooks PR 이벤트
• 심각도 분류
• 코멘트 자동 작성

현재 PR summary 실습은 이 중 Rules 컨벤션, 심각도 분류, 코멘트 자동 작성의 초기 버전이다. 다음 단계는 GitHub PR 이벤트를 받아 같은 구조를 자동 실행하고, repository별 규칙과 required check를 더 정확히 연결하는 것이다.

다만 방향은 그대로 유지한다. 이 자동화는 자동 merge나 자동 reject를 하는 bot이 아니라, 리뷰어가 PR을 빠르게 읽을 수 있게 도와주는 reviewer-facing report다.

---

오늘 실습에서 정리한 핵심

오늘 정리한 결론은 네 가지다.

1. PR summary는 PR 평가기가 아니라 리뷰 보조 도구다.
2. 같은 자동화라도 저장소 역할에 따라 질문이 달라져야 한다.
3. 규칙 기반 1차 버전만으로도 충분히 실용적이다.
4. LLM 연결은 지금 당장 필수가 아니라, 나중에 설명 품질을 높이는 확장 포인트다.

개발자 자동화라고 하면 종종 거대한 에이전트나 멋진 AI 데모부터 떠올리게 된다.

그런데 실제로 생산성에 먼저 닿는 건 오히려 이런 종류의 자동화다.

• PR을 열면 리뷰 포인트가 먼저 보이고
• 검증 명령이 자동으로 정리되고
• 팀이 같은 기준으로 PR을 읽게 되는 것

작지만 바로 쓸 수 있는 자동화.

오늘의 PR summary 실습은 그 출발점으로 아주 괜찮았다.