pr-diagram: 풀 리퀘스트 다이어그램 그리기
목표: 리뷰어가 변경 사항의 내용과 흐름을 10초 안에 파악할 수 있는 하나의 다이어그램을 만듭니다. 전체 코드베이스의 지도가 아닙니다.
가드레일 (절대 규칙)
- 코드를 절대 수정하지 않습니다. 리포지토리 내 파일을 편집, 생성, 삭제하지 않으며, 커밋, 푸시, 브랜치 체크아웃도 하지 않습니다.
.mmd파일은 임시 또는 스크래치패드 디렉토리에 저장하며, 리포지토리에는 절대 저장하지 않습니다. - 절대 승인, 변경 요청, 병합을 하지 않습니다.
gh pr review,gh pr merge,gh pr close를 실행하지 않으며, PR 댓글을 작성하지 않습니다. 이 스킬이 수행하는 유일한 쓰기 작업은gh pr edit --body-file을 통한 설명 업데이트입니다. - 한 번의 승인 단계: 전체 새 설명을 보여주고 같은 메시지에서 게시를 요청합니다. "게시할까요?"라고 먼저 묻고 나서 설명을 보여주지 마세요. 그러면 승인 라운드가 두 번 생깁니다. 추가된 섹션만이 아니라 전체 본문을 보여주고, 메시지 끝에 질문을 덧붙이세요. 해당 메시지에 "좋아요", "게시", 또는 "네"라고 답하면 승인으로 간주합니다. 침묵, 질문, 또는 수정 요청은 승인으로 간주하지 않습니다. 수정 후에는 전체 본문과 질문을 다시 함께 보여주세요.
- 추가하는 모든 내용에 다음 정확한 줄을 추가된 블록의 마지막 줄로 서명하세요:
- Generated by Claude Code
인수
/pr-diagram은 현재 브랜치의 PR을 사용하거나, PR이 없으면 로컬 브랜치 diff를 사용합니다./pr-diagram 123또는 PR URL은 해당 PR을 대상으로 합니다 (URL을 통해 다른 리포지토리도 가능).type=td|lr|sequence|state|er는 다이어그램 유형을 강제로 지정합니다.
1단계: diff 수집
PR이 있는 경우 (모든 읽기 전용):
gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>
PR이 없는 경우: 베이스 찾기 (gh repo view --json defaultBranchRef -q .defaultBranchRef.name), 그 다음
git diff --stat $(git merge-base origin/<base> HEAD) 및 git diff $(git merge-base origin/<base> HEAD).
큰 diff (>1500 변경 라인 또는 >30 파일): 먼저 --stat과 PR 본문을 읽고, 로직이 담긴 파일만 읽습니다. 잠금 파일, 생성된 코드, 스냅샷, 순수 이름 변경은 건너뜁니다.
2단계: 흐름 식별
diff는 라인이지 관계가 아닙니다. 각 수정된 파일의 현재 버전을 읽고 (읽기 전용) 다음을 파악합니다:
- 흐름: 무엇이 트리거되고(요청, 작업, 이벤트, 사용자 액션), 어떤 순서로 실행되며, 어디서 끝나는지(응답, DB 쓰기, 메시지, 외부 호출).
- 각 단계의 상태: 새로운 (이 PR에 의해 추가됨), 변경된 (기존에 있던 것, 수정됨), 또는 변경되지 않은 (변경 사항을 배치하기 위해 리뷰어가 필요한 컨텍스트).
- 리뷰어에게 필요한 한 문장 요약 ("결제 호출 전에 재시도 단계를 추가합니다").
PR 제목과 본문을 의도로 사용하지만, 코드가 이와 다를 경우 코드를 신뢰하세요. 모든 노드와 엣지는 읽은 코드로 추적 가능해야 합니다. 그림을 깔끔하게 만들기 위해 단계를 절대 만들어내지 마세요. 불확실한 것이 있으면 생략하고 그렇게 말하세요.
제거된 코드: 리뷰어에게 중요한 제거된 단계가 있다면 회색 노드에 "(removed)" 레이블과 점선 엣지로 표시하세요. 그렇지 않으면 생략하세요.
3단계: 다이어그램 유형 선택
출력은 항상 .mmd 파일의 Mermaid입니다. 흐름과 일치하는 유형을 선택하세요:
| 변경 사항이 주로... | 다이어그램 |
|---|---|
| 단계별 프로세스 또는 의사 결정 로직 | flowchart TD (위에서 아래로) |
| 컴포넌트 또는 서비스가 서로 연결되거나 파이프라인 | flowchart LR (왼쪽에서 오른쪽) |
| 시간 경과에 따른 3개 이상 참여자 간 요청 또는 메시지 전달 | sequenceDiagram |
| 상태 또는 라이프사이클 변경 (대기 중 → 승인됨 → …) | stateDiagram-v2 |
| 테이블, 컬럼, 또는 관계 (마이그레이션) | erDiagram |
하나의 다이어그램을 사용하세요. PR이 구조와 런타임 흐름을 모두 명확히 변경하는 경우에만 두 개를 사용하세요. PR이 너무 작아서 그림이 필요 없으면 (1-2개 파일, 새로운 흐름 없음), 그렇게 말하고 중단하세요.
4단계: 다이어그램 구축
레이블: 평범한 영어로, 짧게.
- 단계가 무엇을 하는지 쓰세요. 코드 식별자가 아닙니다:
CardValidator.validateExpiry()대신Check card is not expired. 이름이 도움이 될 때는 짧은 형식을 사용하세요:PaymentReconciliationService는Payment reconciler. - URL을 경로로 줄이세요:
api.example.com/v2/orders/{id}/refunds는POST /orders/:id/refunds. - 직사각형 노드
A["..."]: 줄당 최대 35자. - 스타디움
A(["..."])및 둥근A("...")노드: 줄당 최대 25자. - 노드에 더 많은 세부 정보가 필요하면
<br/>로 줄을 나누세요 (각 줄은 제한 내). 최대 3줄까지 사용. - 도형 의미: 직사각형 = 단계 또는 컴포넌트, 스타디움 = 시작 또는 끝 (트리거, 응답), 둥근 = 외부 시스템, 다이아몬드
A{"..."}= 결정 (최대 25자), 실린더A[("...")]= 데이터 저장소. - 최대 15개 노드. 약 8개 이상일 때는
subgraph를 사용하여 서비스 또는 영역별로 그룹화하세요. - 엣지 레이블을 평범한 영어로 간결하게 (
sends,on failure,saves), 최대 20자. - 시퀀스 다이어그램: 참여자 및 액터 이름 최대 25자. 메시지,
loop,alt,opt레이블,Note텍스트는 줄당 최대 35자 (<br/>로 분할, 최대 3줄). 메시지 텍스트에;또는#를 사용하지 마세요. 파싱이 깨집니다.
색상 (GitHub 라이트 모드와 다크 모드 모두에서 읽기 가능). 진한 테두리와 함께 밝은 채움색과 어두운 텍스트를 사용하세요:
classDef new fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#0b3d17
classDef changed fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#4a2b00
classDef unchanged fill:#e9ecef,stroke:#868e96,stroke-width:1px,color:#343a40
class StepA,StepB new
class StepC changed
class StepD unchanged
모든 노드는 정확히 하나의 클래스를 가집니다. stateDiagram-v2에서는 classDef와 함께 class StateName new를 사용하세요.
시퀀스 다이어그램: 클래스가 적용되지 않습니다. rect는 배경색만 설정하며, 텍스트 색상은 GitHub 테마에서 가져옵니다 (다크 모드에서 밝은 회색). 불투명한 밝은 채움색은 다크 모드에서 텍스트를 읽을 수 없게 만듭니다. 따라서 항상 반투명 색조를 사용하세요:
- new:
rect rgba(46,160,67,0.18) - changed:
rect rgba(210,153,34,0.22) - unchanged:
rect없음
불투명한 rect rgb(...)를 절대 사용하지 마세요. 주요 변경 사항에 대해 Note over를 추가하세요.
모두 새로운 PR (변경되거나 변경되지 않은 것 없음): 녹색 색조를 유지하고, 요약에 "이 다이어그램의 모든 것은 새로운 코드입니다"라고 말하세요. 대비할 것이 없기 때문입니다.
구문 함정 (GitHub 렌더링이 깨집니다). 모든 것을 확인하세요:
- 노드 ID는 일반 영숫자여야 합니다 (
ChkCard). 레이블은 항상 따옴표로 묶어야 합니다:ChkCard["Check card"]. - 레이블 내에서 리터럴
"를 사용하려면#quot;를 사용하세요.<br/>는 레이블에서 허용되는 유일한 HTML입니다. end(소문자)를 ID로 절대 사용하지 마세요. 화살표 주위에는 항상 공백을 두세요 (A --> B).A---oB는 원형 엣지로 구문 분석되기 때문입니다.subgraph Id["Label"]…end. 각 서브그래프에는 자체end가 필요합니다.- 시퀀스 참여자:
participant API as Orders API(ID에 공백 없음). erDiagram속성 유형은 단일 단어여야 합니다 (varchar(255)가 아닌varchar).%%{init}%%테마 블록 없음.classDef색상이 두 모드를 모두 처리합니다.
저장 다이어그램을 pr-<N>-diagram.mmd (또는 branch-<name>-diagram.mmd)로 임시 또는 스크래치패드 디렉토리에 저장하세요. 전체 경로를 제공하세요.
5단계: 제시 전 자체 점검
- 모든 레이블 줄의 문자 수를 제한(직사각형은 35, 스타디움, 둥근, 다이아몬드 노드는 25, 엣지 레이블은 20; 시퀀스 다이어그램에서는 참여자 25, 메시지, 블록, 노트는 35)에 맞춰 세세요. 초과하는 항목을 수정하세요.
- 레이블에 일반 영어로 대체 가능한 원시 코드 식별자(camelCase,
Foo.bar(), snake_case)가 없는지 확인하세요. - 각 노드의 색상을 확인하세요: diff에서 정말 새로운, 변경된, 또는 변경되지 않은 것인가요?
- 선택적 렌더링 확인:
npx -y @mermaid-js/mermaid-cli -i <file>.mmd -o <file>.svg. 첫 번째 실행은 Chromium을 다운로드하므로(~150 MB), 실행하기 전에 물어보세요.
6단계: 제시
채팅에서 다음 형식을 사용하세요:
**<PR이 수행하는 작업에 대한 한 문장 요약>**
<2-3문장: 단어로 된 흐름, 변경 사항이 위치한 곳, 생략되거나 불확실한 내용>
```mermaid
...
```
**범례:** 초록 = 새 코드 · 노랑 = 변경된 코드 · 회색 (또는 색조 없음) = 변경되지 않은 컨텍스트
저장 위치: <전체 .mmd 경로>
7단계: 전체 설명을 보여주고 게시 요청 (6단계와 동일한 메시지)
응답하기 전에 이 작업을 수행하여 다이어그램, 전체 새 설명, 질문이 모두 함께 전송되도록 하세요:
-
현재 본문을 임시 파일로 가져오기:
gh pr view <N> --json body -q .body > <tmp>/body-old.md -
<tmp>/body-new.md에 새 본문을 작성하세요. 블록을 마커 사이에 넣어 재실행 시 쌓이지 않고 대체되도록 하세요:<!-- pr-diagram:start --> ## 변경 다이어그램 <요약 문장> ```mermaid ...범례: 초록 = 새 코드 · 노랑 = 변경된 코드 · 회색 (또는 색조 없음) = 변경되지 않은 컨텍스트 (색상 이모티콘이 아닌 단어를 사용하세요. 이모티콘은 OS마다 다른 색상으로 렌더링됩니다. 예: ⬜는 Windows에서 라벤더로 표시됩니다.)
- Generated by Claude Code
마커가 이미 존재하면 마커 사이의 텍스트만 바꾸세요. 그렇지 않으면 빈 줄 다음에 블록을 추가하세요. 원본 본문의 다른 모든 바이트는 변경하지 않고 유지하세요. -
새 본문이 전체 원본 본문으로 시작하는지 확인하세요. 바이트 단위로 보존되어야 합니다.
-
펜스 블록 안에 전체 새 설명, PR URL, 그리고 질문으로 메시지를 끝내세요: "에 게시할까요?" 그런 다음 멈추고 기다리세요 (가드레일 3).
8단계: 게시 (7단계 메시지에 '예'라고 답한 후에만)
gh pr edit <N> --body-file <tmp>/body-new.md. 인라인 텍스트로--body를 절대 사용하지 마세요. 셸 따옴표가 백틱과$를 망가뜨리기 때문입니다.gh pr view <N> --json body -q .body로body-new.md와 일치하는지 확인한 다음 PR URL을 제공하세요. 비교 시 후행 공백은 무시하세요.-q가 개행 문자를 추가하기 때문입니다. 예를 들어, Python에서 둘 다.rstrip()하여 비교하세요.
아직 PR이 없는 경우 (로컬 브랜치만)? 사용자가 PR을 열 때 붙여넣을 블록을 제공하세요. PR을 만들지 마세요.
금지 사항
- 모든 파일을 다이어그램으로 만들지 마세요. 모든 것을 보여주는 다이어그램은 아무것도 보여주지 않습니다.
- 레이블에 비밀, 내부 호스트 이름, 토큰이나 쿼리 문자열이 포함된 전체 URL, 또는 고객 데이터를 넣지 마세요.