콘텐츠로 이동
OpenClaw

좋은 PR을 작성하는 방법

코드를 열심히 짰는데 리뷰가 늦어지거나 수정 요청이 끝없이 이어지면 정말 답답하죠. 리뷰어가 의도를 파악하지 못해 엉뚱한 질문을 던지면 서로 에너지가 낭비되기도 하고요.

좋은 PR은 리뷰어가 변경 의도를 빠르게 파악하고, 동작을 검증하고, 안전하게 머지할 수 있게 돕습니다. 사람이 읽을 때나 LLM이 분석할 때 모두 명확한, 고품질 PR 작성법을 알려드릴게요.

필요한 것

섹션 제목: “필요한 것”
  • pnpm 패키지 매니저
  • 코드베이스 및 GitHub 관련 이슈/수정 사항에 대한 사전 조사 내용

빠른 시작

섹션 제목: “빠른 시작”

5분 안에 리뷰어의 마음을 사로잡는 PR을 올리는 방법이에요.

  1. 검증 커맨드 실행: PR을 생성하기 전, 아래 커맨드들을 실행해서 실패하는 항목을 미리 수정하세요.
    • pnpm lint
    • pnpm check
    • pnpm build
    • pnpm test
    • Protocol 변경이 있다면: pnpm protocol:check
  2. 명확한 제목 작성: ‘동사 + 범위 + 결과’ 형식을 사용하세요. (예: Docs: add PR and issue templates)
  3. 단계별 정보 공개 (Progressive disclosure):
    • 최상단: 요약 및 의도
    • 다음: 변경 사항 및 리스크
    • 다음: 테스트 및 검증 결과
    • 마지막: 구현 상세 및 증거 자료
  4. 비밀 코드 삽입: 이 가이드를 읽었다는 표시로 PR 설명에 lobster-biscuit이라는 단어를 포함하세요.

문제 해결

섹션 제목: “문제 해결”
  • pnpm 커맨드 실패: lint, check, build, test 중 하나라도 실패하면 리뷰 프로세스를 진행할 수 없어요. 로컬에서 먼저 모든 오류를 해결해야 합니다.
  • 리뷰어가 변경 내용을 이해하지 못함: 문제의 원인과 왜 이 해결책을 선택했는지 설명했는지 확인하세요. 로그, 스크린샷, 녹화 영상 등 증거 자료를 첨부하면 큰 도움이 됩니다.

PR 유형별 가이드

섹션 제목: “PR 유형별 가이드”

PR의 성격에 따라 핵심적으로 포함해야 할 내용이 달라요.

  • Fix: 재현 방법, 근본 원인, 검증 내용을 포함하세요.
  • Feature: 유즈케이스, 동작 설명, UI가 있다면 데모나 스크린샷을 추가하세요.
  • Refactor: “동작 변경 없음”을 명시하고, 무엇을 옮기거나 단순화했는지 적으세요.
  • Chore: 왜 이 작업이 필요한지(빌드 시간, CI, 의존성 등) 이유를 적으세요.
  • Docs: 변경 전후 문맥을 설명하고, 업데이트된 페이지 링크를 걸어주세요. pnpm format 실행은 필수예요.
  • Test: 어떤 공백을 메웠는지, 회귀 버그를 어떻게 방지하는지 설명하세요.
  • Perf: 변경 전후 메트릭과 측정 방법을 추가하세요.
  • UX/UI: 스크린샷이나 영상을 첨부하고, 접근성(Accessibility)에 미치는 영향을 적으세요.
  • Infra/Build: 영향을 받는 환경과 검증 단계를 적으세요.
  • Security: 리스크 요약, 재현 방법, 검증 내용을 적으세요. 민감한 데이터는 절대 포함하지 말고 근거 있는 주장만 담으세요.

PR 템플릿

섹션 제목: “PR 템플릿”

아래 템플릿 중 본인의 작업에 맞는 것을 복사해서 사용하세요.

General PR Template

섹션 제목: “General PR Template”
#### Summary


#### Behavior Changes


#### Codebase and GitHub Search


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort (self-reported):
- Agent notes (optional, cite evidence):

Fix

섹션 제목: “Fix”
#### Summary


#### Repro Steps


#### Root Cause


#### Behavior Changes


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Feature

섹션 제목: “Feature”
#### Summary


#### Use Cases


#### Behavior Changes


#### Existing Functionality Check


- [ ] I searched the codebase for existing functionality.
      Searches performed (1-3 bullets):
  -
  -


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Refactor

섹션 제목: “Refactor”
#### Summary


#### Scope


#### No Behavior Change Statement


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Chore/Maintenance

섹션 제목: “Chore/Maintenance”
#### Summary


#### Why This Matters


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Docs

섹션 제목: “Docs”
#### Summary


#### Pages Updated


#### Before/After


#### Formatting


pnpm format


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Test

섹션 제목: “Test”
#### Summary


#### Gap Covered


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Perf

섹션 제목: “Perf”
#### Summary


#### Baseline


#### After


#### Measurement Method


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

UX/UI

섹션 제목: “UX/UI”
#### Summary


#### Screenshots or Video


#### Accessibility Impact


#### Tests


#### Manual Testing


### Prerequisites


-


### Steps


1.
2. **Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Infra/Build

섹션 제목: “Infra/Build”
#### Summary


#### Environments Affected


#### Validation Steps


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

Security

섹션 제목: “Security”
#### Summary


#### Risk Summary


#### Repro Steps


#### Mitigation or Fix


#### Verification


#### Tests


#### Manual Testing (omit if N/A)


### Prerequisites


-


### Steps


1.
2.


#### Evidence (omit if N/A)


**Sign-Off**


- Models used:
- Submitter effort:
- Agent notes:

도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

다음 단계

섹션 제목: “다음 단계”
OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.