git-pr

name	git-pr
description	PR 제목과 메시지를 정책(Conventional Commits 제목 + 이슈별 비즈니스/테크 관점)에 맞게 작성합니다. PR 작성, PR 메시지·설명 작성, pull request, 풀리퀘스트, PR 올리기 전 정리, 리뷰어용 설명 정리 시 사용합니다. 실제 PR 생성·제출이 아니라 메시지 텍스트 작성용입니다.

개요

동료의 코드 리뷰 시간을 단축하고, 변경 사항에 대한 완벽한 추적성을 제공하는 PR 메시지를 작성합니다. 이슈·브랜치·PR이 각각 1개인 단일 배포이든, 여러 브랜치를 하나의 PR로 통합하는 통합 배포이든, PR에 포함된 각 이슈별로 반드시 '비즈니스 관점'과 '테크 관점' 두 섹션으로 나누어 작성합니다.

관련 skill

• git-commit (권장): PR 제목은 커밋 메시지와 동일한 Conventional Commits 형식을 따릅니다.
• ai-workspace (권장): .ai/50_adr/, .ai/30_contract/, .ai/40_domain/ 경로의 문서를 참조합니다.

참조 문서

• 공통 규칙: .ai/10_rules/context-loading.md — 있으면 따르며, 이미 적재되어 있으면 재로딩하지 않습니다.
• 스킬 고유 추가 참조:
  • .ai/30_contract/index.md, .ai/40_domain/index.md, .ai/50_adr/index.md — 비즈니스·테크 관점 참고사항 작성 및 인용할 파일 식별용 (index 먼저 → 관련 파일만 선택적으로)
  • .ai/60_codebase/index.md — 호출 흐름 작성 참고

---

작성 시점 및 주체

PR을 올리기 전, 작성자 본인이 작성합니다. AI 도구를 활용해 초안을 생성한 뒤 작성자가 검토·수정하여 반영하는 방식을 권장합니다.

---

실행 절차

아래 순서로 작성합니다. 각 단계의 세부 규칙은 같은 이름의 섹션을 참조합니다.

1. 공통 규칙·index.md를 선택 적재한다 ("참조 문서").
2. PR 제목을 작성한다 ("PR 제목").
3. 이슈 목록을 작성한다 ("PR 메시지 구조").
4. 이슈별로 비즈니스 관점·테크 관점을 작성한다.
5. PR 초안을 마친 뒤 마지막 패스로 문서 동기화 점검을 1회 수행한다 ("문서 동기화 점검").

---

PR 제목

PR 제목은 Conventional Commits 1.0.0 형식을 따릅니다. Squash Merge 시 PR 제목이 커밋 메시지로 사용되므로 형식을 일치시켜 이력의 일관성을 유지합니다.

<type>(<scope>): <제목> (#이슈번호)

단일 배포 (이슈 1 : 브랜치 1 : PR 1)

이슈 번호와 scope를 그대로 사용합니다.

feat(order): 주문 생성 API 성능 개선 (#123)
fix(payment): 결제 실패 시 사용자 알림 누락 수정 (#124)

통합 배포 ((이슈 1 : 브랜치 1) × N : PR 1)

포함된 모든 이슈 번호를 나열합니다. scope가 단일 도메인으로 수렴하면 scope를 명시하고, 여러 도메인에 걸쳐 있으면 scope를 생략합니다.

# scope가 하나의 도메인으로 수렴하는 경우
feat(order): 주문 성능 개선 및 결제 알림 추가 (#123, #124)

# scope가 여러 도메인에 걸쳐 있는 경우
feat: 3월 1차 배포 - 주문 성능 개선, 결제 알림 (#123, #124)

---

PR 메시지 구조

[PR 헤더] 이슈 목록

PR에 포함된 이슈를 한눈에 파악할 수 있도록 상단에 목록으로 정리합니다.

## 이슈 목록
- #[이슈번호] - [이슈 제목 또는 핵심 요구사항]
- #[이슈번호] - [이슈 제목 또는 핵심 요구사항]

단일 이슈인 경우에도 동일하게 작성합니다.

---

Issue: #[이슈번호] - [이슈 제목 또는 핵심 요구사항]

이슈가 여러 개인 경우 아래 섹션을 이슈마다 반복합니다.

1. 비즈니스 관점

리뷰어가 "이 코드가 왜 필요한가?"를 이해할 수 있도록 비즈니스 목적과 영향을 요약합니다.

• 목적 및 요약: 이 이슈가 해결하고자 하는 비즈니스 요구사항, 버그, 또는 사용자 가치를 명확히 기재합니다. (무엇을, 왜 변경했는가?)
• 주요 변경 사항: 사용자 경험이나 정책 등 비즈니스 관점에서 어떤 변화가 발생했는지 2~3개의 불릿 포인트로 작성합니다.
• 참고사항: 관련된 기획 문서, 비즈니스 룰, 또는 인증 심사(컴플라이언스)와 관련된 필수 요구사항이 있다면 명시합니다.

2. 테크 관점

리뷰어가 "이 코드가 어떻게 구현되었는가?"를 파악하고 소스 코드를 쉽게 추적할 수 있도록 작성합니다.

• 구현 요약: 비즈니스 요구사항을 코드로 어떻게 풀어냈는지, 추가/변경/삭제된 핵심 로직 위주로 요약합니다.

• 호출 흐름:

  • .ai/60_codebase/index.md에 내용이 있으면 참고하되, SSoT는 소스코드이므로 반드시 실제 코드를 확인하여 작성합니다.
  • 기능(엔트리 포인트)별로 나누어, 주요 컴포넌트 간의 실행 흐름을 디렉토리 트리 형태의 ASCII 다이어그램으로 도식화합니다.
    • 각 노드에 ClassName#methodName 명시, 트리 기호(├──, └──)로 호출 계층 표현, 핵심 로직은 노드 옆 # 설명 주석.
  • 하나의 이슈에 여러 기능이 있으면 기능별로 각각 작성합니다.

  (예)

  - 주문 생성:
    OrderController#create
    ├── OrderValidator#validate        # 필수 필드 및 재고 가용성 검증
    └── OrderService#process           # 주문 생성 트랜잭션 관리
        ├── InventoryService#decrease  # 재고 차감 및 락 획득
        │   └── InventoryRepository#update (DB)
        ├── PaymentService#charge      # 결제 요청 및 실패 시 재고 롤백
        │   └── PgClient#requestPayment (외부 API)
        └── OrderRepository#save (DB)
  

• 참고사항: 구현 시 참고한 아키텍처 결정 기록(ADR), DB 스키마 변경 사항, 사내 가이드, 또는 보안/성능 측면의 특이사항을 명시합니다. 관련 ADR·계약·도메인 문서가 있으면 해당 파일 경로를 함께 적습니다 (경로 안내는 위 "참조 문서" 참고).

---

작성 예시 (템플릿)

## 이슈 목록
- #123 - 주문 생성 API 성능 개선
- #124 - 결제 실패 시 사용자 알림 추가

---

### Issue: #123 - 주문 생성 API 성능 개선

#### 1. 비즈니스 관점
* **목적 및 요약:** 주문 생성 응답 시간이 평균 2초를 초과하여 사용자 이탈이 발생하고 있어, 핵심 경로를 최적화한다.
* **주요 변경 사항:**
  - 주문 생성 응답 시간 2초 → 0.5초 미만으로 단축
  - 재고 조회 로직을 캐시 기반으로 전환하여 DB 부하 감소
* **참고사항:** 기획 문서 `docs/order-performance-spec.md`

#### 2. 테크 관점
* **구현 요약:** 재고 조회 쿼리를 Redis 캐시로 대체하고, 주문 유효성 검증 로직을 병렬 처리로 변경.
* **호출 흐름:**
  - 주문 생성:
    OrderController#create
    ├── OrderValidator#validate     # 필수 필드·재고 가용성 검증(병렬)
    └── OrderService#process        # 주문 생성 트랜잭션 관리
        ├── InventoryCache#get      # 재고 캐시 우선 조회
        │   └── InventoryRepository#findById (DB, 캐시 miss 시)
        └── OrderRepository#save (DB)
* **참고사항:** `.ai/50_adr/adr-cache-strategy.md`, DB 스키마 변경 없음

---

### Issue: #124 - 결제 실패 시 사용자 알림 추가

...

---

문서 동기화 점검 (PR 초안 작성 후)

PR 초안을 마친 뒤 마지막 패스로 1회 수행합니다. 브랜치 diff로 README·AI-CONTEXT·코드베이스 색인이 낡았는지 감지해 갱신 권고만 PR 끝에 덧붙입니다 — 문서 자동 재생성은 하지 않습니다(SSoT는 소스코드). 각 행은 해당 diff 신호가 있을 때만 켜지므로, 신호가 없으면 해당 행은 생략하고 감지 항목이 하나도 없으면 이 섹션 자체를 생략합니다.

diff 신호	낡았을 가능성 있는 문서	권고 스킬
스킬·모듈 디렉토리 추가/삭제/이름변경, 진입 문서(SKILL.md 등) description 변경	README, AI-CONTEXT 목록	/readme-sync, /ai-workspace
디렉토리 구조 변경	AI-CONTEXT 구조 트리	/ai-workspace
호출 흐름·엔트리포인트 변경	.ai/60_codebase/ 색인	/code-map
domain/keywords 변경	AI-CONTEXT + 상위 안내도 Repos 행(멀티 워크스페이스)	/ai-workspace

위 매핑은 이 저장소(스킬 모음) 기준입니다. 다른 프로젝트에선 README/AI-CONTEXT가 기술하는 대상(모듈·패키지·엔트리포인트)에 맞춰 신호를 대응시킵니다.

권고는 PR 끝에 ## 문서 동기화 점검 블록으로 남기고 적용 여부는 작성자가 판단합니다 (예: - AI-CONTEXT 스킬 목록이 낡았을 수 있음 → /ai-workspace). 권고에 그치지 않고 같은 PR에 갱신까지 포함하려면(승인형), 이 단계에서 해당 스킬(/readme-sync·/ai-workspace·/code-map) 실행 여부를 질의해 승인한 것만 같은 브랜치에 반영합니다.