PR 설명기은(는) 무엇을 하나요?
팀원에게 변경 사항을 가르쳐 주는 문서 하나를 생성합니다: 무엇이 잘못되었거나 누락되었는지, 시스템이 어떻게 동작하는지, 변경 사항이 무엇을 하는지, 그리고 작동한다는 것을 어떻게 알 수 있는지.
인수
- 대상: PR 번호, URL, 또는 아무것도 없음.
- PR이 있고
ghCLI를 사용할 수 있는 경우,gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files로 세부 정보를 가져오고gh pr diff <url>로 diff를 가져옵니다. 로컬HEAD가 아닌 PR의 head 커밋(git show <headRefOid>:<path>)에서 주변 코드를 읽습니다. - PR이 없거나
gh가 없는 경우: 로컬 변경 사항을 설명합니다. 커밋의 경우git diff <base>...HEAD를 사용하고, 커밋되지 않은 작업의 경우git diff와git status를 사용합니다. 여기서<base>는 기본 브랜치 또는 첫 번째 커밋입니다.
- PR이 있고
--local: PR이 존재하더라도 로컬 체크아웃을 사용합니다(푸시되지 않은 작업). 페이지에 로컬 변경 사항을 반영한다고 명시합니다.--concise: 약 2분 안에 읽을 수 있는 짧은 버전. 최대 1개의 시각 자료, 최대 3개의 코드 조각, 목차 없음, 섹션당 1~3문장.--md: HTML 대신 Markdown을 작성합니다(사용자가 지정하지 않는 한 기본 파일은 저장소 루트의HANDOVER.md). 핸드오버 시와 브라우저를 사용할 수 없을 때 사용합니다.
대상 독자와 어조
- 독자는 팀의 주니어 엔지니어입니다. 짧은 문장, 평이한 동사, 문단당 하나의 아이디어를 사용하세요.
- 기본 개념(REST, SQL, JWT, React hooks)을 정의하지 말고, 기술적이지 않은 비유를 사용하지 마세요. 실제 모듈, 함수, 라우트, 필드 이름과 실제 숫자를 사용하여 기술적으로 유지하세요.
- 내용이 아닌 표현을 단순하게 만드세요. 처음 나타나는 드문 라이브러리 호출이나 패턴은 설명하세요.
- 최종 초안처럼 작성하세요. 현재 상태를 직접 설명하세요. 변경 로그나 "이전에는 생각했었지만" 식의 표현은 사용하지 마세요.
- 확실성에 대해 솔직하게 표현하세요. 입증되지 않은 주장에는 "가능성이 높지만, 아직 확인되지 않음"이라고 표시하세요.
범위: diff가 아닌 변경 사항을 설명하세요
- 이야기를 전달하는 파일과, 그 안에서 중요한 라인만 선택하세요.
- 파일당 1
3개의 코드 조각을 사용하고, 각 조각은 약 25줄 미만으로 생략된 부분은4문장을 제공하세요....로 표시하세요. 각 조각에 파일 경로와 그것이 하는 일과 이유에 대한 2 - 수정 사항의 경우, 버그를 유발한 코드와 수정 사항의 diff를 보여주세요.
- 코드를 diff 순서가 아닌 런타임 흐름 순서로 정렬하세요.
- 파이프라인, 이름 변경, 포맷팅은 건너뛰세요. 리뷰어가 diff에서 볼 경우 한 줄로 언급하세요.
1. 변경 사항 이해하기
- diff와 주변 코드를 읽으세요. 모드를 결정하세요:
- 피처: 새로운 동작 또는 대규모 리팩터.
- 버그 수정: 증상, 근본 원인 및 수정 사항.
- 최신 검증 실행을 찾으세요: 테스트 명령어와 개수, 그리고 이상적으로는 새로운 회귀 테스트가 수정 사항 없이는 실패하고 수정 사항과 함께 통과한다는 증거. 그 증거가 없고 비용이 적게 든다면 직접 생성하세요:
git stash push -- <src files>, 테스트 실행,git stash pop. 또한 수동 또는 종단 간 확인(CLI 출력, 요청, 스크린샷)을 찾으세요. 각각의 최신 실행만 보여주세요. - 존재하는 경우 대화 내용(근본 원인 분석, QA 보고서, 티켓)의 결과를 사용하세요.
2. 구조
모든 문서는 눈에 띄는 한 줄(repo · PR #n · ticket 또는 repo · local changes), 평이한 언어의 제목, 그리고 1~2문장의 도입부로 시작합니다.
버그 수정
- 무엇이 잘못되었나: 증상, 발견된 위치, 배제된 사항.
- 근본 원인: 데이터 또는 흐름이 깨지는 정확한 위치(
file:line), 도움이 된다면 시각 자료 포함. - 원인이 된 코드: 한두 개의 코드 조각.
- 수정 사항: diff 조각과 그것이 작동하는 이유. 함께 수정된 부작용을 명시하세요.
- 작동 확인 방법: 수정 전후에 실패/통과하는 회귀 테스트, 전체 스위트 개수, 수동 확인.
- 시사점: 주니어가 다른 곳에서 재사용할 수 있는 2~4가지 교훈.
피처
- 이유: 문제 또는 목표, 증거 포함.
- 위치: 아키텍처 또는 모듈 컨텍스트(다이어그램), 의도적으로 변경되지 않은 부분 포함.
- 흐름: 코드 카드와 연결된 단계 또는 순서도.
- 코드 둘러보기: 중요한 파일당 하나의 카드, 흐름 순서로.
- 알아야 할 동작: 엣지 케이스, 상태, 실패 모드(3개 이상인 경우 표 사용).
- 검증: 최신 실행만.
- 리뷰어 시사점: 2~3줄의 정신적 모델과 diff에서 가장 주의 깊게 봐야 할 부분.
핸드오버 추가 사항 (--md에서는 항상 포함, HTML에서는 선택 사항):
- 실행/테스트 방법: 정확한 명령어.
- 가정한 사항: 명세서에 명시되지 않은 부분에서 내린 결정과 그 이유.
- 비즈니스에 대한 미해결 질문: 영향도 순으로 정렬.
- 위험 및 롤백: 프로덕션에서 발생할 수 있는 문제와 되돌리는 방법.
- 다음 단계: 시간이 더 있다면 할 작업.
간결 버전: 무엇이 잘못되었나 / 무엇과 이유, 근본 원인 / 작동 방식, 수정 사항 / 핵심 코드, 작동 확인 방법만 포함.
3. 시각 자료: 텍스트로 설명할 수 없는 경우에만 사용
| 내용 | 사용 방법 |
|---|---|
| 모듈 또는 서비스 아키텍처, 누가 누구를 호출하는지, 요청 순서 | Mermaid flowchart / sequenceDiagram (≤ ~12 노드) |
| 변경 전후에 다르게 동작하는 한 브랜치 | 전후 표 또는 작은 정적 SVG |
| 여러 단계를 거치는 데이터, 필터에 의해 제거된 값 | 예제 입력 → 출력 표, 변경 전후 비교 |
| 상태, 명령어, 위험, 계약 | 표 |
Markdown에서는 펜스 처리된 ```mermaid 블록을 사용하세요(GitHub에서 렌더링). 애니메이션은 사용자가 요청한 경우에만 추가하세요.
4. 빌드
- HTML:
references/page-template.html에서 시작하세요(자체 포함, 라이트/다크 모드, CDN의 Mermaid 및 highlight.js). 티켓 또는 PR 이름을 딴.pr-review/<name>.html에 저장하거나local-<short-desc>로 저장하세요. Git에서 제외하세요:git check-ignore -q .pr-review/가 실패하면.pr-review/를.git/info/exclude에 추가하세요. 요청하지 않는 한.gitignore를 편집하지 마세요.- 코드 조각:
<pre><code class="language-<lang>">…</code></pre>, HTML 이스케이프 처리. 수정 diff의 경우-/+라인과 함께language-diff를 사용하세요. - Mermaid:
<pre class="mermaid">…</pre>. 색상을 하드코딩하지 마세요.
- 코드 조각:
- Markdown (
--md): 일반 GitHub Flavored Markdown, 동일한 구조, HTML 없음.
5. 한 번 확인
- HTML: 브라우저 도구를 사용할 수 있는 경우, 데스크톱 너비와 약 400px 너비로 페이지를 한 번씩 여세요. Mermaid가 렌더링되고 코드가 강조되는지 확인하고, 한 번에 발견한 문제를 수정하고, 반복하지 마세요. 그렇지 않으면 미리보지 않았다고 말하고 페이지를 여는 명령어를 제공하세요(macOS는
open, Windows는start, Linux는xdg-open). - 모든
file:line, 숫자 및 명령어를 코드와 대조하여 다시 읽으세요. 사실은 정확해야 합니다.
6. 결과 보고
다음과 같이 회신하세요:
- 파일 경로
- 모드 및 포함된 섹션
- 사용된 시각 자료와 각각이 설명하는 내용
- 문서가 보여주는 검증 실행
- "아직 확인되지 않음"으로 표시된 모든 사항
미리 묻지 않고 PR 본문을 편집하거나, 댓글을 게시하거나, 무언가를 푸시하지 마세요.