TrackerJo/pr-description

평이한 영어의 PR 설명

변경 사항을 빠르게 이해해야 하는 유지보수자를 위해 작성하세요. 좋은 설명은 첫 화면에서 세 가지 질문에 답합니다:

1. 무엇이 잘못되었거나 누락되었습니까?
2. 왜 변경이 필요했습니까?
3. 지금은 어떤 상태입니까?

작성하기 전에 실제 diff, 현재 PR 본문, 커밋, 테스트 및 PR 상태를 읽으십시오. 이전 본문과 커밋 제목은 의도를 설명하지만 증거는 아닙니다. 작성자가 확인하지 않는 한 수동 테스트, 배포 또는 프로덕션 동작을 주장하지 마십시오.

필수 시작: 변경 사항 및 이유

모든 PR 설명은 모니터 소유의 ## Status 섹션이 있는 경우 그 직후에, 기여자 소유의 ## What Changed and Why 섹션으로 시작해야 합니다. 이는 선택적 형식이 아닌 필수 사항입니다.

다음 순서로 세 개의 짧은 레이블이 있는 단락을 사용하세요:

• Issue: 실제 사용자 또는 운영자의 장애, 또는 누락된 동작.
• Why this change was necessary: 해당 장애가 왜 중요했으며 선택한 경계가 왜 필요한지.
• New status quo: 이 PR 이후의 구체적인 동작.

각 레이블이 있는 단락을 한두 문장으로 유지하세요. 유지보수자는 이 섹션만으로 "이 PR에서 무슨 일이 일어났는가?"에 답할 수 있어야 합니다. 구현 메커니즘, 삭제된 설계 또는 기록 다시 쓰기로 시작하지 마십시오.

부적절한 시작을 검토할 때는 구체적인 대체 텍스트나 실제 diff에 맞춰진 간결한 세 단락 개요를 제시하세요. 단순히 장황하다, 명확하지 않다, 또는 더 나은 설명이 필요하다고 말하지 마십시오.

대부분의 PR에 대해 이 형식을 사용하세요:

## What Changed and Why

**Issue:** [실제 사용자 또는 운영자 장애, 또는 누락된 동작.]

**Why this change was necessary:** [그것이 왜 중요했으며 이 경계가 왜 필요한지.]

**New status quo:** [이 PR 이후의 구체적인 동작.]

## After merge

[남아있는 실제 운영자 또는 리뷰어 작업만. 없으면 이 섹션은 생략.]

## Verification

[확인된 수동 검사와 진정한 병합 후 검사만 명시.]

본질부터 시작하세요. PR 제목을 다시 진술하거나, 서문을 추가하거나, 다음 단락을 반복하는 요약을 작성하지 마십시오.

유지할 사항

• 중요한 변경 사항당 하나의 명확한 최종 상태. 각 단락이나 글머리 기호의 첫 문장을 훑어보는 사람이 병합 후 무엇이 변경되는지 이해할 수 있어야 합니다.
• 실제 결정. 제품 동작, 위험 또는 의미 있는 비용에 영향을 미치는 경우에만 거부된 대안을 언급하세요. 선택한 것과 그 이유를 한 문장으로 말하세요. "핵심 결정" 레이블을 인위적으로 만들지 마십시오.
• 운영 사실. 리뷰어나 운영자가 조치를 취해야 할 때 마이그레이션, 백필, 예약된 작업, 통합, 비밀, 배포 순서 및 장애 동작을 언급하세요.
• 정직한 검증. 누군가가 실제로 수동으로 확인한 것과 진정으로 병합 후까지 기다려야 하는 작업을 분리하세요. 린트, 빌드, CI 또는 테스트 명령어를 나열하지 마십시오. 테스트는 의미 있는 동작을 다룰 때 평이한 영어로 언급할 수 있습니다.
• 공개 호출. 리뷰어가 결정해야 하는 미해결 결정만 포함하세요. 질문을 먼저 넣고, 그 다음 권장 사항과 그 비용을 넣으세요. 결정할 사항이 없으면 섹션을 생략하세요.

변경된 시스템에 대한 필수 증거

사용자 대상 시스템, 중요한 운영자 워크플로 또는 해당 구성을 변경하면서 리뷰어에게 검사 방법을 보여주지 않는 설명은 불완전합니다.

• 스크린샷 또는 짧은 비디오: 시각적 증거는 별도의 ## Visual evidence 섹션에 넣으세요. 변경된 화면의 스크린샷이나 변경된 상호 작용 또는 여러 단계 흐름의 짧은 비디오를 포함하세요. 미디어를 임베드하거나 안정적인 PR 첨부 파일에 링크하세요. 캡션은 무엇이 변경되었고 리뷰어가 무엇을 보고 있는지 설명해야 합니다. 소스 코드, 테스트 보고서 또는 변경되지 않은 화면의 스크린샷으로 대체하지 마십시오. 공개 및 이벤트 표면의 경우 노트북 증거보다 필수 휴대폰 증거를 먼저 넣고 각 뷰포트와 테스트된 상태를 식별하세요. 캡처, 업로드 및 최신 커밋 확인에 대해서는 visual-proof 스킬을 따르세요. PR에 시각적 또는 대화형 표면이 없는 경우에만 이 섹션을 생략하세요.
• 구성, 환경 및 마이그레이션: 실제로 추가, 제거, 이름 변경 또는 동작을 변경하는 환경 변수, 비밀, 대시보드 설정 및 데이터베이스 마이그레이션만 ## Configuration에 넣으세요. 운영자가 취해야 할 한 가지 조치로 시작하세요. 일반적인 외부 설정은 한 문장으로 간결하게 유지하세요. 예: <URL>에서 모니터를 설정하고 https://buildpurdue.org/api/health를 가리키도록 하세요. 내부 변경 사항은 없습니다. 폴링 세부 정보, 다른 곳에서 이미 설명된 근거 또는 중복된 런북에 대한 링크로 섹션을 채우지 마십시오. 실제 마이그레이션의 경우, 커밋된 supabase/migrations/ 경로를 지정하고, 스키마/데이터/정책 변경을 요약하고, 호환성 또는 백필 요구 사항을 명시하고, 확인된 npm run db:verify 재생 결과를 제공하세요. 비밀 값을 절대 출력하지 마십시오. 구성 또는 마이그레이션 변경 사항이 없으면 섹션을 생략하세요.
• 변경된 흐름: 변경되는 중요한 흐름에는 Mermaid 순서도를 사용하세요. 흐름이 여러 단계, 분기, 재시도, 시스템 간 핸드오프 또는 실패 경로가 있을 때 중요합니다. 변경된 경로와 중요한 실패 동작을 리뷰어가 읽을 수 있는 평이한 레이블로 표시하십시오. 변경된 각각의 개별 흐름에 대해 다이어그램을 하나씩 추가하세요. 한 단계 이름 바꾸기 또는 사소한 로컬 계산에는 다이어그램을 사용하지 마십시오.

이는 주요 설명과 별개입니다. 설명은 변경 사항이 존재하는 이유를 말하고, 증거, 구성 및 다이어그램을 통해 리뷰어가 변경 사항을 검사할 수 있습니다.

읽기 쉽게 유지

• 기본적으로 250단어 이하로 작성하세요. 운영자가 짧은 체크리스트를 필요로 할 때 설명이 더 길어질 수 있지만, 모든 문장은 그 자리를 차지할 가치가 있어야 합니다.
• 짧은 단락을 사용하세요. 남은 설정 단계와 같은 실제 목록에만 글머리 기호를 사용하세요. 모든 문장을 레이블이 있는 글머리 기호로 바꾸지 마십시오.
• 이슈, 이유 및 새로운 현 상태를 정상적인 영어로 작성하세요. 누가 무엇을 하는지 말하세요.
• 원시 코드, 쿼리, 설정 조각, 명사로서의 상태 코드, 전문 용어, 비유, 과장된 표현 및 대시(em dash)를 피하세요.
• 모든 메커니즘을 설명하지 마세요. 리뷰어가 알아야 하는 동작을 유지하세요.
• 나중 섹션에서 사실을 반복하지 마세요. 문장이 사라져도 정보 손실이 없다면 제거하세요.

상태는 모니터 소유

기여자는 ## Status를 제외한 PR 설명의 모든 부분을 소유합니다. 해당 섹션을 직접 추가, 제거 또는 편집하지 마십시오. BuildPurdue PR 모니터가 이를 소유하며 현재 검토 상태에 맞게 유지합니다.

모니터는 Status를 변경할 때 일치하는 Status update: PR 댓글도 게시합니다. 작업이 남아 있으면 구체적인 병합 전 다음 조치를, 남은 작업이 없으면 No more remaining work.라는 한 문장의 평이한 영어를 사용합니다. Status는 기여자 대상 설명 검토 댓글에 속하지 않습니다.

Status를 선택적인 미래 아이디어, 기록 메모, 병합 후 전용 작업 또는 이 PR을 차단하지 않는 별도로 추적되는 작업에 사용하지 마십시오.

더 많은 구조가 정당화될 때

주요 설명에 맞지 않는 정보를 전달할 때만 집중 섹션을 추가하세요:

• Database / migrations: 무엇이 실행되어야 하는지, 기존 데이터가 호환되는지, 백필이 필요한지 여부.
• Operational behavior: 무엇이 실행되는지, 언제 실행되는지, 실패가 어떻게 표시되는지, 운영자가 무엇을 구성해야 하는지.
• Verification: 확인된 수동 검사 및 진정한 병합 후 검사.
• Open calls: 미해결 제품 또는 위험 선택.

작은 버그 수정의 경우 다음과 같이 간단히 사용할 수 있습니다:

## Root cause

## Fix

## Verification

게시 전

1. 모든 주장이 현재 diff, 테스트, PR 상태 또는 직접 실행한 명령어에서 비롯되었는지 확인하세요.
2. 첫 화면만 따로 읽어보세요. 문제, 변경이 필요한 이유 및 새로운 현 상태를 명확히 말해야 합니다.
3. 역사적 서술, 체인지로그 스타일의 구현 로그, 반복된 설명 및 관련 없는 작업을 제거하세요.
4. 모든 마이그레이션, 배포, 비밀, 대시보드 또는 병합 후 조치가 명시적이고 실행 가능한지 확인하세요.
5. 소리 내어 다시 읽어보세요. 감사 보고서처럼 들리지 않고 팀원에게 변경 사항을 설명하는 사람처럼 들려야 합니다.
6. 푸시할 때마다 본문을 새 diff와 비교하고 동작, 남은 설정 또는 확인 상태가 변경된 경우 업데이트하세요.

출처

이 사본을 .agents/skills/에서 편집하세요. pre-commit 훅이 이를 .claude/skills/pr-description/에 미러링합니다. 미러를 직접 편집하지 마세요.