Community라이팅 & 에디팅github.com

PR 설명기

풀 리퀘스트, 버그 수정 또는 로컬 변경 사항을 주니어 엔지니어에게 설명하는 하나의 독립형 HTML 페이지(기본값) 또는 Markdown 핸드오버(--md)를 생성합니다.

PR 설명기란 무엇인가요?

PR 설명기는 개발자가 풀 리퀘스트 또는 로컬 변경 사항을 동료 팀원, 특히 주니어 엔지니어에게 설명하는 문서를 자동 생성하는 AI 에이전트 스킬입니다. 주요 기능은 PR 번호나 URL을 기반으로 `gh` CLI를 통해 세부 정보를 가져오거나, 로컬 변경 사항을 git diff로 분석하여 피처 또는 버그 수정의 맥락을 구조화된 템플릿에 맞춰 문서화합니다. 기본 출력은 자체 포함된 HTML 파일이며, --md 플래그로 Markdown 핸드오버 문서를 생성할 수 있습니다. --concise 플래그로 2분 분량의 요약 버전을 제공하고, --local 플래그로 원격 PR과 독립적으로 로컬 변경 사항을 문서화할 수 있습니다. 모든 문서는 주니어 엔지니어를 대상으로 기술적 정확성을 유지하면서 간결한 문장과 실제 코드 조각, 다이어그램(Mermaid)을 포함하여 변경 사항의 이유, 아키텍처, 흐름, 핵심 코드, 검증 방법을 설명합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

PR 설명기은(는) 무엇을 하나요?

팀원에게 변경 사항을 가르쳐 주는 문서 하나를 생성합니다: 무엇이 잘못되었거나 누락되었는지, 시스템이 어떻게 동작하는지, 변경 사항이 무엇을 하는지, 그리고 작동한다는 것을 어떻게 알 수 있는지.

인수

  • 대상: PR 번호, URL, 또는 아무것도 없음.
    • PR이 있고 gh CLI를 사용할 수 있는 경우, 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>는 기본 브랜치 또는 첫 번째 커밋입니다.
  • --local: PR이 존재하더라도 로컬 체크아웃을 사용합니다(푸시되지 않은 작업). 페이지에 로컬 변경 사항을 반영한다고 명시합니다.
  • --concise: 약 2분 안에 읽을 수 있는 짧은 버전. 최대 1개의 시각 자료, 최대 3개의 코드 조각, 목차 없음, 섹션당 1~3문장.
  • --md: HTML 대신 Markdown을 작성합니다(사용자가 지정하지 않는 한 기본 파일은 저장소 루트의 HANDOVER.md). 핸드오버 시와 브라우저를 사용할 수 없을 때 사용합니다.

대상 독자와 어조

  • 독자는 팀의 주니어 엔지니어입니다. 짧은 문장, 평이한 동사, 문단당 하나의 아이디어를 사용하세요.
  • 기본 개념(REST, SQL, JWT, React hooks)을 정의하지 말고, 기술적이지 않은 비유를 사용하지 마세요. 실제 모듈, 함수, 라우트, 필드 이름과 실제 숫자를 사용하여 기술적으로 유지하세요.
  • 내용이 아닌 표현을 단순하게 만드세요. 처음 나타나는 드문 라이브러리 호출이나 패턴은 설명하세요.
  • 최종 초안처럼 작성하세요. 현재 상태를 직접 설명하세요. 변경 로그나 "이전에는 생각했었지만" 식의 표현은 사용하지 마세요.
  • 확실성에 대해 솔직하게 표현하세요. 입증되지 않은 주장에는 "가능성이 높지만, 아직 확인되지 않음"이라고 표시하세요.

범위: diff가 아닌 변경 사항을 설명하세요

  • 이야기를 전달하는 파일과, 그 안에서 중요한 라인만 선택하세요.
  • 파일당 13개의 코드 조각을 사용하고, 각 조각은 약 25줄 미만으로 생략된 부분은 ...로 표시하세요. 각 조각에 파일 경로와 그것이 하는 일과 이유에 대한 24문장을 제공하세요.
  • 수정 사항의 경우, 버그를 유발한 코드와 수정 사항의 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문장의 도입부로 시작합니다.

버그 수정

  1. 무엇이 잘못되었나: 증상, 발견된 위치, 배제된 사항.
  2. 근본 원인: 데이터 또는 흐름이 깨지는 정확한 위치(file:line), 도움이 된다면 시각 자료 포함.
  3. 원인이 된 코드: 한두 개의 코드 조각.
  4. 수정 사항: diff 조각과 그것이 작동하는 이유. 함께 수정된 부작용을 명시하세요.
  5. 작동 확인 방법: 수정 전후에 실패/통과하는 회귀 테스트, 전체 스위트 개수, 수동 확인.
  6. 시사점: 주니어가 다른 곳에서 재사용할 수 있는 2~4가지 교훈.

피처

  1. 이유: 문제 또는 목표, 증거 포함.
  2. 위치: 아키텍처 또는 모듈 컨텍스트(다이어그램), 의도적으로 변경되지 않은 부분 포함.
  3. 흐름: 코드 카드와 연결된 단계 또는 순서도.
  4. 코드 둘러보기: 중요한 파일당 하나의 카드, 흐름 순서로.
  5. 알아야 할 동작: 엣지 케이스, 상태, 실패 모드(3개 이상인 경우 표 사용).
  6. 검증: 최신 실행만.
  7. 리뷰어 시사점: 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 본문을 편집하거나, 댓글을 게시하거나, 무언가를 푸시하지 마세요.

관련 스킬