---
name: pr-description
description: >
  Pull Request 제목과 본문을 작성하거나 기존 설명을 개선할 때 쓴다. 실제 변경에서 해결할
  문제, 변경 후 동작과 검증을 정리하고 필요한 위험과 관련 링크를 덧붙인다.
  코드의 버그·회귀 검토는 code-review를 쓴다.
compatibility: >
  저장소 서비스나 로컬 변경을 읽을 수 있는 도구를 사용한다. GitHub MCP는 선택 가능한 경로다.
  접근 도구가 없으면 사용자가 제공한 diff·파일 내용·변경 자료로 검토한다.
---

# PR 제목과 본문 작성

리뷰어가 변경의 목적, 결과와 위험을 판단할 수 있도록 쓴다. 현재 diff와 확인된 검증을 기준으로
작성하고 이전 대화의 시행착오나 폐기한 접근은 필요한 경우에만 설명한다.

ISO 24495-1처럼 쉽게 찾고 이해하고 사용할 수 있게, ASD-STE100처럼 짧고 명확하며
모호하지 않게 쓴다. 문제·결과·검증을 찾기 쉽게 배치하고 용어와 변경 조건을 일관되게 적는다.
영어 전용 어휘·단어 수 규칙을 한국어에 강제하지 않는다.

## 변경 파악

1. 대상 저장소와 PR, base/head, 제목·본문과 전체 변경 파일을 확인한다. 제공된 diff로도 시작할 수 있다.
2. 변경된 동작의 정의·호출부·테스트 중 설명을 뒷받침할 부분을 읽는다. 잘린 diff는 파일별로 보완한다.
3. 저장소 지침과 PR 템플릿을 확인한다. 제목 관례가 불분명할 때만 최근 PR 몇 개를 참고한다.
4. 확인된 실행 결과나 CI 상태를 읽는다. 자료가 부족하면 초안에서 미확인 범위를 명시한다.

저장소 서비스나 로컬 도구를 사용할 때는 실제 schema를 따른다. 접근 도구가 없으면 제공 자료를
사용하고 접근할 수 없는 PR 내용을 추측하지 않는다. 변경 근거가 전혀 없으면 diff나 변경 요약을 요청한다.

## 제목

해결하는 문제나 최종 동작을 짧게 적고 저장소의 접두사와 언어 관례를 따른다.
티켓 번호는 대화·브랜치·커밋 등에서 확인된 경우에만 붙인다. 번호가 없으면 생략하고
저장소에서 필수로 요구하는데 확인할 수 없을 때만 묻는다.

## 본문 구성

저장소 템플릿이 있으면 우선한다. 없으면 문제와 결과를 한두 문단으로 설명하고 검증을 덧붙인다.
아래 항목은 변경의 복잡도와 관련성에 따라 절로 나누거나 문단으로 합친다.

| 항목 | 담을 내용 |
|---|---|
| 문제와 해결 | 누구에게 어떤 문제가 있었으며 변경이 어떤 결과를 만드는가 |
| 보장 동작 | 실제 입력·조건에서 밖으로 관측되는 동작과 필요한 예외 |
| 관련 자료 | 확인된 티켓·스펙·동반 변경 링크와 연결 이유 |
| 위험 | 호환성, 데이터, 보안, 성능과 배포에 영향을 주는 변경 및 근거 |
| 머지 전 검증 | 실행한 검사와 결과, 아직 필요한 검증 |
| 머지 후 확인 | 배포·배치 실행 후 확인할 항목과 관측 시점 |

해당 사항이 없는 절은 템플릿이 요구하지 않으면 생략한다. 구현 설명은 결과나 위험을 이해하는 데
필요한 만큼 쓴다. “continue 추가”보다는 “한 클러스터의 실패 후에도 나머지 정리를 계속한다”처럼 쓴다.

머지 후 확인을 머지 전 검사와 섞지 않는다. 후속 추적이 필요하면 기존 티켓을 연결한다.
새 티켓 생성은 사용자에게 허가된 경우에만 한다.

## 검증 표시

- 직접 실행 결과, 현재 PR revision의 CI 결과와 사용자 제공 결과를 구분한다.
- 확인된 항목만 완료로 표시한다. 예전 revision의 통과 결과를 현재 변경의 증거로 쓰지 않는다.
- 실행 도구가 없으면 관측할 수 있는 CI나 제공 결과를 사용한다. 검증을 수행하지 못한 이유를 적는다.
- 남은 검사가 머지 조건이면 미완료로 둔다. 단순 참고나 배포 후 확인을 머지 조건처럼 표시하지 않는다.

## 예시

```markdown
정리 배치가 한 클러스터의 오류로 종료돼 나머지 클러스터의 정리가 누락된다.
클러스터별 실패를 기록하고 다음 대상을 계속 처리하도록 변경한다.
담당자는 결과 알림에서 실패한 클러스터를 확인할 수 있다.

## 검증

- 한 클러스터 실패 후 나머지 처리를 확인하는 회귀 테스트 통과
- 배포 후 다음 정리 배치에서 전체 대상의 결과 알림 확인 예정
```

예시의 사실과 검증 결과는 실제 변경에 맞춰 쓴다. 확인하지 않은 내용을 예시에서 복사하지 않는다.

## 검토와 전달

연결된 `engineering-writing`이 있으면 문장을 다듬는 데 사용한다. 없으면 문제·결과·근거를
구체적으로 쓰고 반복과 홍보 표현을 줄인다. 식별자는 백틱으로 표시하고 링크·표·목록을 확인한다.
표 안의 `|` 등 Markdown 제어 문자가 내용으로 필요하면 이스케이프한다.

기본 산출물은 제목과 Markdown 본문 초안이다. 사용자가 PR 생성이나 기존 본문 수정을 요청한 경우
허가된 대상에 반영하고 URL을 전달한다. 이미 받은 권한은 다시 묻지 않는다.
작성 요청만으로 커밋·푸시·리뷰 게시·머지를 실행하지 않는다.