이 PR 설명하기
GitHub 풀 리퀘스트를 읽고, 변경 사항을 파악한 후 평문으로 설명을 작성합니다. 리뷰어가 즉시 맥락을 파악할 수 있도록 PR 댓글로 게시합니다.
1단계: 설정 확인
gh가 인증되었는지 확인합니다:
gh auth status
인증되지 않은 경우: gh auth login을 실행하고 안내를 따릅니다.
입력 확인. 사용자는 다음 중 하나를 제공해야 합니다:
- GitHub PR URL (예:
https://github.com/owner/repo/pull/123) - 현재 저장소의 PR 번호 (예:
#123) - 현재 브랜치의 PR을 사용하려면 키워드 "current"
입력이 없으면 질문: "어떤 PR을 설명할까요? URL, PR 번호를 공유하거나 활성 브랜치의 경우 'current'라고 말씀해 주세요."
2단계: PR 컨텍스트 가져오기
PR 메타데이터 가져오기:
gh pr view PR_URL_OR_NUMBER --json number,url,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels,state,isDraft
isDraft가 true이면 사용자에게 알림: "이 PR은 아직 초안 상태입니다. 설명은 현재 상태를 기준으로 작성되었습니다."
diff 가져오기:
gh pr diff PR_URL_OR_NUMBER
diff가 400줄을 초과하면 --stat 요약과 diff의 처음 200줄을 읽습니다:
gh pr view PR_URL_OR_NUMBER --json files
gh pr diff PR_URL_OR_NUMBER | head -200
기존 댓글 가져오기 (중복 방지):
gh pr view PR_URL_OR_NUMBER --json comments --jq '.comments[].body' 2>/dev/null | head -20
3단계: 설명 작성
두 문단을 작성합니다. 작성하기 전에 각 규칙을 읽으십시오.
문단 1: 무엇을 하는가 (기술적)
- 주요 변경 사항당 한 문장
- 변경된 특정 파일, 함수 또는 시스템의 이름을 명시
- diff에서 명확하다면 이전/이후 상태를 설명
- diff에 구체적인 숫자가 있다면 포함 (삭제된 줄, 드롭된 테이블, 추가된 엔드포인트 등)
- 능동태, 현재형 사용
예시:
Replaces the in-memory session cache in auth.middleware.ts with a Redis-backed cache (src/cache/redis.ts). Adds get, set, and invalidate methods to the new Redis module and wraps UserService.getById() with a 5-minute TTL. Removes the Map-based cache that was limited to a single process and caused session drift across multiple instances.
문단 2: 왜 중요한가 (비즈니스/제품 영향)
- 누가 어떤 이점을 얻는지
- 이 PR이 해결하는 문제 또는 줄이는 위험
- 커밋 메시지에 "왜"에 대한 내용이 있다면 그 맥락 사용
- diff나 커밋에 명확한 "왜"가 없다면 추측하지 말고 이 문단 생략
예시:
Users hitting the /api/me endpoint under load were getting inconsistent session data across server instances, causing intermittent 401 errors. This change makes session state consistent across all instances and reduces database load by eliminating one query per authenticated request.
두 문단 모두에 대한 규칙:
- 줄표(--) 사용 금지 — 쉼표나 마침표 사용
- 불용어 금지: "이 PR은", "이 변경은", "보시다시피"
- 허위 결과 금지. diff나 커밋 메시지에서 직접 확인 가능한 영향만 명시
- PR이 순수 리팩터링으로 동작 변경이 없는 경우, 명시적으로 말합니다: "X를 Y로 리팩터링하며 관찰 가능한 동작 변경은 없습니다."
- 총 150단어 미만
4단계: 자체 QA
게시하기 전에 확인:
- 문단 1이 diff에서 특정 파일이나 함수 이름을 명시하는가
- 허위 메트릭이나 결과가 없는가
- 줄표(--)가 없는가
- 불용어가 없는가
- 총 150단어 미만인가
- 명확한 "이유"가 없다면 문단 2를 추측하지 않고 생략했는가
게시 전에 위반 사항을 수정하십시오.
5단계: PR 댓글로 게시
설명을 사용자에게 제시합니다. 질문: "이 설명을 PR 댓글로 게시할까요, 아니면 먼저 수정하시겠습니까?"
확인되면, 백틱, 따옴표, 줄바꿈을 안전하게 처리하기 위해 본문을 stdin으로 전달:
gl pr comment PR_URL_OR_NUMBER --body-file - << 'EOF'
EXPLANATION_HERE
EOF
게시 후: "댓글이 추가되었습니다. 다음에서 확인하세요: [2단계의 url]"
사용자가 "output only"라고 말하면, 게시하지 않고 수동 복사-붙여넣기를 위해 설명을 코드 블록으로 제시합니다.