---
name: "apply-pr-comments"
description: "GitHub PR 리뷰 댓글을 한 건씩 순차로 검토·합의·일괄 수행하는 team 모드 워크플로우"
argument-hint: "[PR번호 또는 URL]"
---

# Apply PR Comments

> **상호작용 규칙**: 사용자에게 질문, 확인, 선택을 요청할 때는 항상 `AskUserQuestion` 도구를 사용한다.

## 적용 범위

GitHub PR에 달린 리뷰 댓글을 받아, 댓글 1건씩 사용자와 합의하고, 합의된 항목을 일괄 수정·커밋·검증·push·reply하는 워크플로우. 단순 리뷰는 `~/.claude/skills/review/`의 walk·deep을 사용한다 — 이 스킬은 댓글 응답 + 코드 적용까지의 풀 사이클 전용.

## 경로 규칙

> - 메모리 디렉토리: `.claude/pr-comments/{PR번호}/.memory/`
> - 결정 기록: `.claude/pr-comments/{PR번호}/.memory/decisions.jsonl` (append-only)
> - 처리 식별: `.claude/pr-comments/{PR번호}/.memory/processed.jsonl` (append-only)
> - 룰 작성 가이드: `.claude/rules/_meta/authoring.md` (이 스킬 자체와 무관, 참고용 메타)

## 입력 파싱

인자: `$ARGUMENTS`

- `^\d+$` → PR 번호로 직접 사용 (예: `9905`)
- `pull/(\d+)` 패턴 매치 → 캡처 그룹을 PR 번호로 (URL 입력 지원)
- 매치 실패·인자 없음 → `AskUserQuestion`으로 PR 번호·URL 입력 요청

repo는 `git remote get-url origin`을 파싱하여 `{owner}/{repo}` 추출.

## 절차

### Phase 0: 팀 구성

`TeamCreate`으로 팀을 등록한다.

> 아래 역할명(`code-reviewer`, `implementor`, `git-master`)은 `TeamCreate` 팀원에게 붙이는 라벨이며, `Agent` 도구의 built-in `subagent_type` 레지스트리와는 무관하다.

| 역할 | 담당 |
|------|------|
| orchestrator (main) | 워크플로우 통제, Phase 1 수집, Phase 2·4 사용자 인터랙션, decisions·processed 기록 |
| code-reviewer | Phase 2 댓글별 분석 (read-only). Phase 3 검증용 code-reviewer는 별도 프레시 스폰 |
| implementor | Phase 3 코드 수정, lint·tsc 1차 통과 |
| git-master | Phase 3 커밋, Phase 5 push·reply 게시 |

`.memory/` 디렉토리가 없으면 생성한다.

### Phase 1: 댓글 수집

orchestrator가 직접 수행한다.

1. `mcp__github__pull_request_read` (method: `get_review_comments`)로 모든 리뷰 댓글을 가져온다.
2. `.memory/processed.jsonl`을 읽어 이미 처리된 `comment_id` 집합을 만든다.
3. 신규 댓글(처리되지 않은 것)을 추출한다.
4. 신규 댓글이 0건이면 "처리할 신규 댓글이 없습니다"를 출력하고 종료한다.

### Phase 2: 검토 (per-comment 순차 루프)

각 신규 댓글에 대해 아래를 **순차적으로** 1건씩 처리한다. 한꺼번에 여러 댓글을 사용자에게 제시하지 않는다.

1. orchestrator가 댓글 메타데이터를 추출한다: `comment_id`, `author`, `permalink`, `path`, `line` 또는 `original_line`, `body`.
2. orchestrator가 `code-reviewer`에게 6-Section 프롬프트로 위임:
   - **TASK**: 댓글 `{id}` (`{permalink}`)의 코드 위치를 확인하고 영향 범위와 수정 방향 후보를 제시
   - **EXPECTED OUTCOME**: file:line, 댓글 요청의 해석, 영향 범위(직접 변경 파일·간접 영향처), 수정 방향 후보 1-3개와 추천안
   - **REQUIRED TOOLS**: Read, Grep, Glob, Bash(읽기 전용)
   - **MUST DO**: 댓글 원문을 그대로 인용. 수정 방향 후보 각각에 trade-off 한 줄 명시
   - **MUST NOT DO**: 코드 수정·파일 작성. 위임 범위 외 댓글에 대해 자체 분석 시작
   - **CONTEXT**: 댓글 본문, 대상 파일·라인, PR 번호
3. 분석 결과를 사용자에게 제시한다 (본문):
   - 댓글 원문 인용
   - 코드 위치 (`path:line`)
   - 영향 범위 요약
   - 수정 방향 후보 (추천 명시)
4. `AskUserQuestion`으로 처리 결정을 받는다 — "이 댓글을 어떻게 처리할까요?"
   선택지: ["합의 (추천 방향)", "합의 (다른 방향, Other로 서술)", "보류", "기각"]
5. `decisions.jsonl`에 append:
   ```json
   {"ts":"...","comment_id":"...","permalink":"...","status":"agreed|held|rejected","direction":"...","rationale":"..."}
   ```
6. 다음 댓글로 이동.

루프 종료 시 모든 신규 댓글에 대해 결정이 기록된다. 합의된 댓글이 0건이면 Phase 3·4·5를 건너뛰고 종료한다.

### Phase 3: 수행 (일괄)

`status: agreed`인 댓글들에 대해 댓글 1건씩 다음을 수행한다 (커밋이 댓글 단위로 분리되도록).

1. orchestrator가 `implementor`에게 6-Section 프롬프트로 위임:
   - **TASK**: 댓글 `{id}`의 합의된 방향(`{direction}`)대로 코드 수정
   - **EXPECTED OUTCOME**: 수정된 파일 목록, `yarn lint`·`yarn tsc --noEmit` 통과 (수정 파일 한정)
   - **REQUIRED TOOLS**: Read, Edit, Bash(yarn lint, yarn tsc)
   - **MUST DO**: 수정 파일에 한해 lint·타입 검증 실행 후 결과 보고. 합의 방향 외 변경 금지
   - **MUST NOT DO**: 다른 댓글의 수정을 함께 처리. 위임 범위 외 리팩토링
   - **CONTEXT**: 합의 방향, 대상 파일·라인, 댓글 원문, permalink
2. orchestrator가 `git-master`에게 6-Section 프롬프트로 위임:
   - **TASK**: 댓글 `{id}`의 변경을 별도 커밋으로 생성
   - **EXPECTED OUTCOME**: 커밋 SHA, 메시지 본문에 `Comment: {permalink}` trailer 포함
   - **REQUIRED TOOLS**: Bash(git)
   - **MUST DO**: 한국어 커밋 메시지(주제 + 본문). 본문에 댓글 요지와 변경 의도 명시. trailer 형식 일관 유지. 위임 범위 외 파일 staged 금지
   - **MUST NOT DO**: 다른 댓글 변경분과 합쳐 커밋. push (Phase 5에서 수행)
   - **CONTEXT**: 변경된 파일 목록, 합의 방향, permalink
3. orchestrator가 검증용 `code-reviewer`를 **프레시 스폰**한다 (Phase 2의 분석용 code-reviewer와 세션 공유 금지):
   - **TASK**: 커밋 `{sha}`의 변경이 합의 방향과 일치하는지, 부작용이 없는지 검증
   - **EXPECTED OUTCOME**: PASS / FAIL + 사유 (FAIL 시 file:line 증거)
   - **REQUIRED TOOLS**: Read, Grep, Bash(yarn lint, yarn tsc, yarn test)
   - **MUST DO**: 변경 파일 직접 검증. 합의 방향 외 변경 여부 확인
   - **MUST NOT DO**: 코드 수정·재커밋 (FAIL 시 main으로 보고)
4. 검증 PASS 시 `processed.jsonl`에 append:
   ```json
   {"ts":"...","comment_id":"...","permalink":"...","sha":"...","result":"agreed","verified":true}
   ```
5. 검증 FAIL 시 main이 직접 진단 후 implementor에 동일 session_id로 재시도 (최대 3회). 3회 실패 시 BLOCKED — 해당 댓글을 보류 처리하고 다른 댓글 진행.

### Phase 4: 유저 검증

orchestrator가 사용자에게 변경 요약을 제시한다 (본문에 표 형식):

- 새 커밋 목록 (SHA·메시지 주제)
- 각 커밋의 변경 의도 (diff 라인 수 같은 무효화 표현 금지)
- 검증 명령 결과 (lint·tsc·test exit code)
- Phase 5 reply 본문 미리보기 (각 댓글별)

`AskUserQuestion`으로 결정을 받는다 — "이대로 push + reply 게시할까요?"
선택지: ["통과 (Phase 5 진행)", "특정 커밋 수정 필요 (Other로 댓글 ID·수정 사항 명시)", "전체 중단"]

- **통과** → Phase 5
- **특정 커밋 수정 필요** → 해당 댓글의 `processed.jsonl` 줄을 tombstone(`tag: "revoked"`) 엔트리로 무효화하고, 그 댓글에 대해 Phase 3의 1·2·3·4를 재수행. 다른 커밋은 유지
- **전체 중단** → push 없이 종료. `processed.jsonl`은 그대로 보존하여 다음 호출 시 처리된 것으로 인식

### Phase 5: 마무리

orchestrator가 `git-master`에게 위임한다:

1. 현재 브랜치를 원격에 push.
2. 각 합의 댓글에 reply 게시:
   - 도구: `mcp__github__add_reply_to_pull_request_comment` (comment_id, body)
   - 본문: `"Resolved in {sha}: {간단 설명}"` (PR 댓글 언어 일치)
3. 보류·기각 댓글에 reply 게시 (선택, 사용자가 Phase 4에서 선택한 경우):
   - 보류: `"보류: {사유}. 후속 논의 예정"`
   - 기각: `"기각: {사유}"`

완료 메시지: "PR #{번호}: 합의 N건·보류 M건·기각 K건 처리 완료. 커밋 N개 push, reply N+M+K건 게시."

## 출력 / 상태 업데이트

- `.claude/pr-comments/{PR}/.memory/decisions.jsonl`: 모든 댓글의 결정 기록
- `.claude/pr-comments/{PR}/.memory/processed.jsonl`: 완료된 댓글 식별 + 커밋 SHA
- 새 커밋 (합의된 댓글 수만큼) — 본문에 `Comment: {permalink}` trailer
- push + GH reply 게시

## 오류 처리

| 상황 | 동작 |
|------|------|
| GitHub MCP 인증·권한 실패 | 사용자에게 MCP 인증 상태 확인 안내 후 종료 |
| PR 번호 누락·잘못됨 | `AskUserQuestion`으로 재입력 |
| 신규 댓글 0건 | "처리할 신규 댓글이 없습니다" 출력 후 종료 |
| Phase 2 분석 실패 (코드 위치 미식별) | 해당 댓글을 보류 처리, 사유를 사용자에게 통지 |
| Phase 3 수정 실패 (lint·tsc·test FAIL) | implementor에 동일 session_id로 재시도 (최대 3회), 실패 시 해당 댓글 보류 |
| Phase 5 reply 게시 실패 | 실패 목록을 누적, 마지막에 사용자에게 보고 (push는 별도 처리) |
| 워크플로우 중간 중단 | `decisions.jsonl`·`processed.jsonl` 그대로 보존, 다음 호출 시 이어서 처리 |

## 절대 규칙

- GitHub MCP 인증·repo 권한 확인 없이 Phase 1 진행하지 않는다 — 왜: 인증 실패 시 댓글 수집·reply 게시 모두 실패하여 워크플로우가 중간에 깨진다
- Phase 2 검토는 댓글 1건씩 순차. 한꺼번에 다중 댓글을 사용자에게 제시하지 않는다 — 왜: 사용자 요건이 "한번에 하지 말고 댓글별로"이며, 다중 제시는 결정 컨텍스트가 섞여 합의 품질이 저하된다
- Phase 3 수행 후 Phase 4 유저 검증을 건너뛰고 Phase 5로 진행하지 않는다 — 왜: 자동 push는 변경 검토 없이 PR을 어지럽힐 위험이 크다
- 검증용 code-reviewer는 항상 프레시 스폰한다. Phase 2 분석용 code-reviewer 팀원과 세션 공유 금지 — 왜: 같은 세션이면 분석 시점의 가설에 고착되어 독립 검증이 무너진다
- `decisions.jsonl`, `processed.jsonl`은 append-only. 기존 줄 수정 금지, 무효화는 tombstone(`tag: "revoked"`) 엔트리로 — 왜: 이력 추적성이 깨지면 워크플로우 중단·재개 시 상태 복구가 불가능해진다
- 한국어 기본. PR 댓글 언어가 영어이면 reply 본문만 영어 허용 — 왜: PR 컨벤션과 어긋나는 reply는 작성자 의도와 맞지 않아 추가 왕복을 유발한다