GitHub 리뷰 자동화

수강생 저장소를 열 때마다 하는 일은 대부분 반복이다. 이슈 목록을 훑고, PR마다 같은 질문에 같은 답을 다시 쓴다. GitHub CLI로 필요한 내용만 읽고, 에이전트에 리뷰 초안을 맡기면 강사는 판단과 승인에 시간을 쓸 수 있다.

기준일: 2026-09-30.

어떤 문제를 풀었나

수업이 끝나면 저장소 상태가 한꺼번에 몰린다. 과제를 제출한 학생 수만큼 이슈와 PR이 쌓이고, 확인하지 않은 PR은 다음 주에 방치된다. 같은 실수와 같은 질문이 반복되는데 매번 처음부터 다시 읽어야 한다.

리뷰를 사람이 전부 맡기면 확인, 문장 작성, 전달 세 가지 일이 같이 밀린다. 이 중 확인은 사람이 해야 하고, 문장 초안과 전달 준비는 반복되는 부분이다. 여기서 자동화하는 범위는 다음과 같다.

• 이슈와 PR 목록을 읽어 이번 주 볼 대상을 고른다.
• PR의 변경 내용과 설명을 읽어 체크리스트 형태의 리뷰 초안을 만든다.
• 반복된 질문을 묶어 답변 초안과 문서 링크 후보를 만든다.
• 강사가 승인한 내용만 저장소에 코멘트로 남긴다.

승인, 병합 여부, 공개 범위는 사람이 정한다. 자동화가 대신할 수 없는 판단을 목록에 남겨 두면 어느 단계까지 맡겼는지 알 수 있다. 처음에는 공개된 연습 저장소 하나에서 읽기만 해 본다. 목록 읽기가 안 되면 코멘트 남기기도 되돌리기 어려워진다.

무엇을 어떻게 연결하나

리뷰는 저장소의 데이터, 읽기 명령, 판단 기준, 반영 단계로 나뉜다. 아래 Mermaid 그림은 승인 전과 후가 나뉜 지점을 보여 준다.

구성 요소	역할	먼저 확인할 내용
대상 저장소 목록	이번 주 리뷰 범위	공개·비공개가 섞여 있지 않은가
GitHub CLI 인증	읽기와 반영	필요한 권한만 넣었는가
읽기 명령	이슈·PR·변경 내용 수집	출력을 그대로 화면에 담는가
리뷰 기준	무엇을 볼지 정한다	예시 코드나 개인 정보를 요구하지 않는가
리뷰 초안	승인 전 결과	근거가 되는 파일과 줄이 있는가
반영 명령	승인한 내용 전달	되돌릴 수 있는 형태로 남기는가

리뷰 기준을 파일로 두면 매번 긴 요청문을 다시 쓰지 않아도 된다. 기준은 룰에 짧게 두고, 긴 설명은 문서 페이지로 옮긴다.

읽기부터 시작

GitHub CLI 설치·로그인

설치와 기본 사용법은 GitHub CLI 공식 매뉴얼에 정리되어 있다. 설치 후 로그인 상태를 확인한다.

gh auth login
gh auth status

gh auth status에는 계정과 적용된 권한 범위가 함께 나온다. 이슈 코멘트와 PR 리뷰를 남기려면 각각 쓰기 권한이 필요하며, 권한 이름과 범위는 세부 권한이 필요한 API 안내에서 확인할 수 있다. 읽기만 할 저장소라면 쓰기 권한 없이 진행한다. 인증 정보를 요청문이나 저장소에 적지 않는다. 보안 페이지의 원칙대로 토큰 값은 대화나 로그에 남기지 않는다.

목록 읽기

목록, 상세, 변경 내용 순서로 읽는다. 필요한 단계만 읽으면 실패했을 때 원인을 찾기 쉽다.

gh pr list --state open --limit 20
gh issue list --state open --limit 20
gh pr view 42
gh pr diff 42

목록 단계에서 나오는 정보만으로 이번 주 볼 대상을 정한다. 명령별 기능과 옵션은 PR 목록 안내와 이슈 목록 안내에서 확인할 수 있다. gh pr diff의 출력을 그대로 요청문에 붙이지는 않는다. 몇 개 파일이 바뀌었는지, 어느 종류의 파일이 바뀌었는지만 먼저 확인한다.

반영 명령 미리보기

승인한 뒤에 쓸 명령은 미리 알고 있어야 한다. 실행되지 않도록 상태를 직접 지정하는 습관이 필요하다.

gh pr review 42 --comment --body-file review-42.md
gh issue comment 17 --body-file answer-17.md

리뷰 상태는 --comment, --approve, --request-changes 중 하나를 직접 지정한다. 지시를 따로 정하지 않고 상태를 추측하게 두지 않는다. 사용법은 PR 리뷰 명령 안내와 이슈 코멘트 명령 안내에 정리되어 있다.

쓸 만한 요청 만들기

목록만 읽는 첫 요청

목록 읽기가 되는지 먼저 확인한다. 아무것도 남기지 않는 요청에서 시작한다.

아래 저장소의 열린 이슈와 PR 목록을 읽고 표로 정리해 줘.
대상 저장소: <owner>/<repo>
각 20건까지만 확인해 줘.

표 항목: 번호, 제목, 라벨, 마지막 변경 시간
지금 코멘트나 수정은 하지 마.
같은 사람이 반복해서 올린 항목이 있으면 따로 표시해 줘.

표에서 번호와 제목을 고르면 다음 요청의 입력이 정해진다.

단일 PR 근거 달기

리뷰 초안에는 판단뿐 아니라 근거가 붙어야 한다. 근거 없는 지적은 수강생이 확인하기 어렵다.

PR #42의 설명과 변경 내용을 읽고 리뷰 초안을 작성해 줘.

확인 항목:
- 실행 방법이 설명에 있는가
- 오류 메시지에 무엇을 고쳐야 하는지 적혀 있는가
- 입력을 그대로 믿지 않고 검증하는가
- 키나 절대 경로가 코드에 남아 있지 않은가
- 테스트와 실행 방법이 함께 바뀌었는가

조건:
- 항목마다 근거가 되는 파일과 줄을 적어 줘.
- 확실하지 않은 내용은 확인 필요로 표시해 줘.
- 문제가 없으면 없다고만 적고 길게 쓰지 마.
- 코멘트는 남기지 마.

확인이 필요한 부분을 지워 버리면 리뷰의 값이 줄어든다. 확실하지 않다는 표시를 따로 남긴다.

반복 질문 답변화

같은 질문이 반복되면 개별 답변이 아니라 문서로 옮기는 편이 빠르다. 묶음과 링크 후보를 요구한다.

지난 한 주 이슈 10건을 읽고 반복되는 질문을 묶어 줘.

각 묶음마다:
- 질문 내용을 한 문장으로 정리
- 지금 답변된 내용인지 확인
- 기존 문서에서 대응하는 링크 후보

답변이 있는 질문은 답변 초안을 짧게 써 주고,
답변이 없는 질문은 확인할 항목을 적어 줘.
이슈에는 아직 답글을 남기지 마.

링크 후보는 저장소 안의 문서만 고른다. 확인하지 않은 주소를 만들어 넣지 않는다.

승인 내용만 기록

반영 단계는 승인한 텍스트를 그대로 쓴다. 다시 다듬는 과정에서 뜻이 바뀌면 안 된다.

승인한 리뷰 초안만 PR #42에 남겨 줘.

- 상태는 코멘트로 사용해 줘. 승인은 내가 따로 정할 거야.
- 본문은 승인한 텍스트를 그대로 사용해 줘.
- 다른 이슈와 PR은 건드리지 마.
- 라벨 변경과 병합은 하지 마.

남긴 뒤 PR #42의 코멘트 목록을 다시 읽어,
남아 있는 코멘트의 번호와 첫 줄을 보여 줘.

승인 상태를 정하지 않은 채 요청하지 않는다. "승인은 내가 정한다"고 명시하면 임의의 상태가 붙지 않는다.

읽기에서 반영까지

1. 대상과 권한 정하기

이번 주에 볼 저장소 목록을 만든다. 개인 과제 저장소와 팀 저장소가 섞여 있으면 한 번에 처리하지 않는다. 저장소마다 열린 PR 수, 마지막 변경 시간, 지난 주에 남긴 코멘트 수만 세어 둔다. 권한은 필요한 저장소에만 최소한으로 두며, 여러 학생 저장소에 공통 계정으로 쓰기 권한을 넓게 주는 방식은 피한다.

2. 읽기 결과 기록

목록과 변경 내용을 파일로 저장해 두면 다음 요청에서 다시 읽지 않아도 된다. 같은 내용을 매번 다시 읽는 비용은 토큰 절약 페이지에서 다룬다.

gh pr list --state open --limit 20 > pr-list.txt
gh pr diff 42 > pr-42.diff

파일 이름에는 번호와 날짜를 함께 넣는다. 나중에 무엇을 언제 확인했는지 알 수 있다.

3. 리뷰 기준 파일

기준이 없으면 리뷰 결과가 매번 다른 방향으로 기울어진다. 아래와 같이 짧은 목록으로 시작한다.

# 저장소 리뷰 기준

- 실행 방법이 설명에 있는가
- 오류 메시지에 무엇을 고쳐야 하는지 적혀 있는가
- 입력을 그대로 믿지 않는가
- 키와 절대 경로가 코드에 남아 있지 않은가
- 테스트와 실행 방법이 함께 바뀌었는가

하지 말 것:

- 실행하지 않은 것을 통과라고 표현하지 않는다
- 학생 이름을 본문에 옮기지 않는다
- 근거 없는 개선 제안을 강요하지 않는다

기준이 길어지면 기준 문서 자체가 관리 대상이 된다. 스킬에 읽기 명령과 기준 파일 경로를 함께 적어 두면 같은 순서로 같은 기준으로 읽게 할 수 있다.

4. 근거 줄 기록

초안의 각 지적에는 파일 경로와 줄 번호를 붙인다. 근거가 없는 지적은 코멘트에 남기지 않는다.

리뷰 항목	근거 형태	남길 말
실행 방법 없음	README의 실행 명령 부분	무엇을 추가해야 하는지
입력값 검증 없음	입력을 읽는 함수	어느 입력이 위험한지
하드코딩된 경로	경로가 있는 줄	무엇으로 바꾸어야 하는지
테스트 미변경	테스트 디렉터리 목록	어떤 경우를 추가해야 하는지

5. 승인 후 반영

코멘트 본문을 파일로 남기고, 파일을 먼저 읽은 뒤 gh pr review 42 --comment --body-file review-42.md를 실행한다. 되돌리기가 어려운 일은 한 번에 하지 않는다. 반영 뒤에는 코멘트 목록을 다시 읽어 남은 내용을 확인한다. 확인하지 않은 반영은 다음 주에 중복으로 반복된다.

6. 주간 루틴 고정

반복 순서는 짧게 정한다. 목록을 읽고 이번 주 대상을 고르고, 대상마다 리뷰 초안을 만든다. 강사가 확인하고 승인한 내용만 코멘트로 남긴 뒤, 반복된 질문을 문서로 옮긴다. 요청이 안정되면 이 순서를 실행 스크립트나 CI 단계로 옮긴다. 기준과 금지 목록은 그대로 두고, 사람이 확인할 일은 승인 한 번으로 줄인다.

자주 막히는 지점과 주의점

변경 내용만 판단

코드가 바뀌었다는 사실만으로는 충분하지 않다. 실행 방법이 바뀌었는지, 테스트가 함께 바뀌었는지, 문서에 적은 명령이 남아 있는지를 함께 본다. 변경 내용이 긴 경우 어떤 종류의 파일이 몇 개 바뀌었는지부터 확인하고, 기준에 해당하는 파일만 깊게 읽는다. 사람이 실행해 본 결과는 자동화 범위 밖이다.

리뷰의 수업 활용

코멘트가 길어지면 강사가 쓴 글이 아니라 수업 시간이 된다. 초안 길이를 정해 둔다. 전체 길이는 화면 두 화면 안으로 제한하고, 심각도가 높은 항목 세 개까지만 적는다. 같은 부류의 지적은 하나로 묶고, 나머지는 "확인 후 회신 드리겠습니다"로 남긴다. 수강생이 고칠 수 있는 범위 밖의 제안은 하지 않는다.

반복 질문은 개별 코멘트가 아니라 문서로 옮긴다. 문서에 없다면 이번 주 답변으로 답하면서 문서 항목도 함께 만든다. 매주 같은 질문이 다시 나오면 문서 링크가 학생에게 닿지 않았다는 뜻이므로 링크 위치를 함께 확인한다.

과도한 권한 범위

읽기만 하면 되는 단계에서 쓰기 권한을 쓰지 않는다. 목록과 diff를 먼저 확인하고, 반영 단계에서만 쓰기 권한이 필요하다. 권한 범위를 넓게 주는 이유는 대개 한 번의 실수를 피하려고서다. 대신 승인 단계를 거치고 반영 로그를 남기면 같은 실수를 되돌릴 수 있다. 개인 저장소와 조직 저장소의 권한은 따로 관리한다.

누락 기록 착각

요약본이 아니라 실제 코멘트를 확인한다. 반영 명령 실행 뒤 코멘트 목록을 다시 읽고, 남지 않았거나 잘못 남긴 경우 바로 고친다. 이슈에 답글을 남기면 학생에게 알림이 가므로 확인을 거친 뒤에 남긴다.

로그·리뷰의 개인정보

오류 메시지에는 파일 경로와 사용자 이름이 함께 찍힌다. 리뷰 본문과 작업 기록에 토큰 값, 학생의 개인 정보를 옮기지 않는다. 코멘트 원고를 파일로 남긴다면 .gitignore에서 제외 대상인지 확인한다. 강사가 직접 남겼다는 사실은 남기되 계정 공유는 피한다.

자동화 이후의 사람

승인 없이 반영되는 절차가 자리 잡으면 수강생이 무엇을 받았는지 알기 어렵다. 승인 단계와 남긴 기록은 남겨 둔다. 다음 학기에 같은 기준을 쓰려면 리뷰 기준 파일과 남긴 코멘트를 함께 남긴다. 이때 쓰는 기준과 연결은 하네스 스스로 개선하기 페이지에서 다룬다.