apply-review— agent skill

요구사항

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

규칙

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

작업 순서

1. PR 코멘트 수집

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

2. 코멘트 분류

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

판단 원칙:

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

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

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

• 저장 위치: {git 루트}/private/analysis-pr{N}-{YYYYMMDD}.md (private/가 없으면 mkdir -p로 생성). 루트는 git rev-parse --show-toplevel로 판별한다. 보고서 본문 위에 아래 YAML 프론트매터를 얹는다(report 스킬과 동일 컨벤션):

  ---
  type: analysis
  title: PR #{N} 코드 리뷰
  project: <레포명>
  created: YYYY-MM-DD
  status: 초안
  ---

4단계(자율 실행) 완료 후 같은 파일을 Edit으로 갱신한다(프론트매터 status→검토중, 각 항목 ✅, 말미에 "처리 결과" 섹션 추가).

• 반영 항목만 상세 분석 — 보류 항목은 이유만 기재, 스킵 항목은 건수만 표기
• 우선순위 기준: 버그·race condition > 접근성 > 문서·주석
• 보고서는 배경지식 없는 독자도 이해할 수 있을 만큼 상세하게 작성
• 문제가 왜 발생하는지 원인을 논리적으로 서술
• 실제 코드를 인용해 어느 부분이 문제인지 명확히 지목
• 수정 전/후 코드를 모두 전체 맥락과 함께 작성 (수정된 줄만 발췌 금지)
• 수정 이유와 수정 후 기대 효과를 구체적으로 설명

보고서 형식:

---
type: analysis
title: PR #N 코드 리뷰
project: <레포명>
created: YYYY-MM-DD
status: 초안
---

# PR #N 코드 리뷰 보고서

> 브랜치: `브랜치명`  
> 총 코멘트: 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:

  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 스킬을 사용한다