---
name: apply-review
description: |
  GitHub PR 리뷰 코멘트를 가져와 분석 보고서를 마크다운 파일로 저장한 뒤, 사용자 승인 후 코드 수정까지 수행.
  "PR 리뷰 반영해줘", "코드리뷰 코멘트 처리해줘", "리뷰 적용해", "리뷰 피드백 수정해줘", "review comment 처리", "리뷰 보고서 만들어줘" 같은 요청에 반드시 이 스킬을 사용할 것.
allowed-tools: Bash, Read, Edit, mcp__claude_ai_Notion__notion-create-pages, mcp__claude_ai_Notion__notion-fetch, mcp__claude_ai_Notion__notion-update-page
argument-hint: (선택) PR 번호. 생략 시 현재 브랜치의 PR을 자동 감지
---

## 요구사항

- Python 설치
- `gh` CLI 인증 완료
- Git 저장소 내에서 실행

## 규칙

- 보고서 생성 후 반드시 멈추고 사용자와 충분히 논의
- 논의가 완료되고 수정 승인을 받으면 이후 모든 항목을 에이전트가 자율 실행
- 각 항목마다 **수정 → 검증 → 커밋** 순서를 반드시 지킨다
- 코드 수정 전 반드시 해당 파일 Read
- 처리 완료한 코멘트는 보고서 내에서 완료 표시로 업데이트

## 작업 순서

### 1. PR 코멘트 수집

- `python "${SKILL_DIR}/scripts/main.py"` 실행 (`SKILL_DIR`은 이 스킬 파일이 위치한 디렉토리)
- PR 없으면 사용자에게 안내 후 종료
- 코멘트 없으면 사용자에게 안내 후 종료

### 2. 코멘트 분류

수집한 코멘트를 아래 기준으로 분류한다. **분류는 에이전트가 직접 판단한다** — Python 스크립트는 수집만 담당한다.

| 분류 | 기준 | 처리 |
|------|------|------|
| **반영** | 버그 지적, 코드 품질 개선, 명확한 수정 제안, 타입·린트 오류 | 코드 수정 |
| **보류** | 설계 방향 의견 충돌, 팀 논의 필요, 스펙 불명확 | 사용자에게 판단 위임 |
| **스킵** | 단순 질문, 칭찬, 감사, 이미 반영된 내용, 봇 코멘트 | 보고서에서 제외 |

**판단 원칙:**
- "이렇게 바꾸세요"처럼 구체적이면 반영
- "이 방향이 맞나요?"처럼 질문형이면 보류
- 셀프 리뷰도 내용이 명확한 개선 제안이면 반영
- "이렇게 구현했습니다" 같은 단순 설명·맥락 공유는 스킵
- 같은 맥락의 코멘트 여러 개는 묶어서 하나의 작업으로 처리
- 의도가 불명확하면 보류로 분류하고 사용자에게 설명 요청

### 3. 보고서 생성 및 저장 [STOP]

분류 결과를 바탕으로 아래 형식의 마크다운 보고서를 생성하고 저장:

- 저장 위치 (우선순위):
  1. **Notion Report DB 우선** — 작업 보고서는 Notion Report DB에 저장한다(사용자 전역 지침). `notion-report` 스킬 또는 `notion-create-pages`로 `유형=분석 · 상태=초안`으로 생성한다(DS_ID는 `~/.claude/settings.json`의 `NOTION_REPORTS_DS_ID`). 4단계(자율 실행) 완료 후 같은 페이지를 갱신한다(상태→검토중, "처리 결과" 섹션 추가).
  2. **로컬 폴백** — Notion 워크플로우 미셋업이거나 사용자가 로컬을 원하면 `{저장소 루트}/review-report-PR{N}-{YYYYMMDD}.md`(프로젝트에 `private/` 규칙이 있으면 그 폴더). 로컬 임시본은 노션 승격 후 정리한다.
- **반영 항목만 상세 분석** — 보류 항목은 이유만 기재, 스킵 항목은 건수만 표기
- 우선순위 기준: 버그·race condition > 접근성 > 문서·주석
- **보고서는 배경지식 없는 독자도 이해할 수 있을 만큼 상세하게 작성**
  - 문제가 왜 발생하는지 원인을 논리적으로 서술
  - 실제 코드를 인용해 어느 부분이 문제인지 명확히 지목
  - 수정 전/후 코드를 모두 전체 맥락과 함께 작성 (수정된 줄만 발췌 금지)
  - 수정 이유와 수정 후 기대 효과를 구체적으로 설명

**보고서 형식:**

```markdown
# PR #N 코드 리뷰 보고서

> 생성일: YYYY-MM-DD  
> 브랜치: `브랜치명`  
> 총 코멘트: N건 (✅ 반영 N · ⏸ 보류 N · ⏭ 스킵 N)

---

## 요약

| # | 분류 | 우선순위 | 파일 | 문제 요약 | 상태 |
|---|------|---------|------|----------|------|
| 1 | ✅ 반영 | 🔴 높음 | `파일명:라인` | 한 줄 요약 | ⬜ 미처리 |
| 2 | ✅ 반영 | 🟡 보통 | `파일명:라인` | 한 줄 요약 | ⬜ 미처리 |
| 3 | ⏸ 보류 | — | `파일명:라인` | 한 줄 요약 | — |

⏭ 스킵: 단순 질문 N건, 칭찬 N건 (생략)

---

## 반영 항목 상세 분석

### [1] 🔴 `파일명:라인` — 한 줄 요약

**원본 코멘트**
> 리뷰어 코멘트 원문 (그대로 인용)

---

#### 배경

이 코드가 어떤 역할을 하는 파일/함수인지, 어떤 흐름에서 호출되는지 간략히 설명.

---

#### 문제 코드

```언어
// 파일: 경로/파일명.kt  라인 N~M
fun someFunction(...) {
    // ... 앞 코드 (컨텍스트)
    val result = problematicCall()  // ← 문제 발생 지점
    // ... 뒤 코드 (컨텍스트)
}
```

---

#### 왜 문제인가

1. **원인**: ...
2. **발생 조건**: ...
3. **영향**: ...

---

#### 수정 방안

**수정 전**
```언어
val result = problematicCall()
doSomething(result.value)
```

**수정 후**
```언어
val result = problematicCall()
if (result == null) {
    Log.e(TAG, "결과가 null입니다.")
    return
}
doSomething(result.value)
```

**수정 이유**  
...

**수정 후 기대 효과**  
...

---

## 보류 항목

### [1] `파일명:라인` — 한 줄 요약

**원본 코멘트**
> 리뷰어 코멘트 원문

**보류 이유**: 설계 방향에 대한 팀 논의가 필요합니다. (구체적 이유)

---
(이하 반복)
```

보고서 저장 후 경로를 안내한다. 이후 사용자와 내용을 충분히 논의한다:
- 반영 항목의 수정 방향이 맞는지 확인
- 보류 항목 중 함께 처리할 것이 있는지 확인
- 생략하거나 우선순위를 바꿀 항목이 있는지 확인
- 추가 컨텍스트나 제약 사항이 있는지 확인

모든 논의가 완료되면 사용자에게 수정 실행 최종 승인을 요청한다. [STOP]

### 4. 자율 실행: 수정 → 검증 → 커밋

승인 후에는 에이전트가 보고서의 우선순위 순서대로 **모든 항목을 자율적으로** 처리한다.
각 항목마다 아래 사이클을 완료한 뒤 다음 항목으로 넘어간다:

#### 4-1. 수정

- 해당 파일 Read 후 Edit으로 수정
- 수정 범위는 지적된 부분에 한정 (불필요한 리팩토링 추가 금지)
- 수정 완료 후 보고서의 해당 항목 상태를 `⬜ 미처리` → `🔧 수정 중`으로 업데이트

#### 4-2. 검증

- 빌드 또는 테스트 명령이 존재하면 실행해 수정이 정상 동작하는지 확인
  - 빌드 실패 시: 원인 분석 후 재수정, 통과할 때까지 반복
- 수정 완료 후 보고서의 해당 항목 상태를 `🔧 수정 중` → `✅ 완료`로 업데이트
- 수정 완료 후 아래 명령으로 해당 스레드 resolve:
  ```bash
  gh api graphql -f query='
    mutation($threadId: ID!) {
      resolveReviewThread(input: {threadId: $threadId}) {
        thread { isResolved }
      }
    }
  ' -F threadId="<thread_id>"
  ```
  (thread_id는 스크립트 출력에 포함된 값 사용)

#### 4-3. 커밋

- `commit` 스킬을 사용해 해당 항목에 대한 커밋 수행
- 커밋 단위는 항목 하나씩 (여러 항목을 하나의 커밋으로 묶지 않는다)

### 5. 완료 보고

모든 항목 처리 후 아래 내용을 출력:
- 처리 완료 수 / 전체 수
- 실패하거나 건너뛴 항목이 있으면 이유와 함께 목록 출력
- 최종 보고서 경로 안내

## 행동 원칙

- 코멘트 분류는 에이전트가 직접 판단한다 — 스크립트는 수집만 담당한다
- 보류 항목은 절대 사용자 승인 없이 수정하지 않는다
- 보고서를 먼저 생성하고 저장한다 — 수정은 사용자와 충분히 논의한 뒤 시작한다
- 논의 승인 이후에는 멈추지 않고 모든 반영 항목을 자율 실행한다
- 각 항목은 반드시 **수정 → 검증 → 커밋** 순서를 지킨다
- 커밋은 항목 하나씩 — 여러 항목을 하나로 묶지 않는다
- 코드 수정 전 반드시 해당 파일을 Read한 뒤 Edit으로 수정한다
- 지적된 범위에 한정하여 수정한다 — 불필요한 리팩토링 추가 금지
- 수정 완료 시 보고서 상태를 즉시 업데이트한다
- 커밋은 `commit` 스킬을 사용한다