pr-checklist

이 문서는 한글로 작성되어 있으나, 사용자가 사용하는 언어에 맞게 읽고 번역하여 전달할 것. (This document is written in Korean; read it and translate to the user's language when relaying.)

pr-checklist — PR 올리기 전 검토

기여 변경을 main에 PR로 올리기 전에 통과해야 할 항목을 순서대로 검증한다. 규칙의 본문(왜/무엇)은 CONTRIBUTING.md가 단일 소스이며, 이 스킬은 그 규칙을 실제로 검증하는 절차다. 상세 근거는 CLAUDE.md 참조.

트리거

• 사용자가 "PR 올리기 전", "PR 전 검토", "기여 전 체크", "피알 검토", "PR 준비 됐어?" 등을 말할 때
• 브랜치 작업을 마치고 PR 생성/업데이트 직전

검증 절차

각 항목을 실제 명령으로 검증하고, 통과/실패를 근거와 함께 보고한다. 실패 항목은 고치도록 안내한다.

1. 최신 main 리베이스 (필수)

PR은 반드시 main의 최신 커밋 위에 리베이스된 상태여야 한다. 오래된 base에서 PR을 열지 않는다.

git fetch origin
git rebase origin/main

• 리베이스 후 충돌이 있으면 해결하고, 3레이어 빌드/테스트를 다시 돌린다.
• 이미 push한 브랜치라면 리베이스 후 force-push(--force-with-lease)가 필요함을 안내한다.

2. 기능 PR엔 기능 문서 (필수)

사용자 대면 기능은 docs/features/NNN-feature_name/ 폴더에 언어별 문서(en.md / ko.md …)를 작성하고, docs/features/CLAUDE.md 색인에 한 줄 추가해야 한다. 작성 규칙은 docs/CLAUDE.md를 따른다.

기능 문서는 공식 기능 문서이자 동시에 공식 블로그다. 온보딩·완전한 스펙·고객 서비스 세 가지가 이 문서 하나로 끝나야 하므로, 릴리즈 노트를 옮겨 적는 것으로는 부족하다.

UI가 아주 사소하게라도 관여되면 스크린샷이 필수다. 화면에 아무것도 드러나지 않는 기능만 예외다. 이미지는 기능 폴더 안 assets/에 두고, 언어별 문서가 같은 파일을 공유하며 alt 텍스트만 각 언어로 쓴다.

ls docs/features/                                   # 다음 번호(NNN) 확인

# 스크린샷이 실제로 들어갔는지 (UI가 관여되는 기능이라면 0이면 안 된다)
find docs/features/<NNN-이름>/assets -type f | wc -l
grep -c '!\[' docs/features/<NNN-이름>/*.md

검수하며 띄운 화면을 그 자리에서 찍어둔다. 나중에 쓰려고 미루면 같은 상태를 다시 만들어야 한다.

3. 마켓플레이스 금지 API 미사용 (필수)

JetBrains Internal API(@ApiStatus.Internal, impl 패키지 내 클래스)는 사용 금지 — Marketplace Plugin Verifier가 오류로 잡아 배포가 거부된다. Deprecated API도 지양(경고 발생). 네이티브 기능에 위험한 API가 필요하면 reflection 또는 public 대체 API로 우회한다.

# 정적 점검(로컬 스킬 precheck과 동일한 grep 계열)
grep -rn "@ApiStatus.Internal\|StartupManager\|PluginManagerConfigurable" src/main/kotlin --include="*.kt"

3.5. 커밋 제목 72자 (필수, 커밋할 때마다)

이 항목은 PR 직전이 아니라 커밋할 때 지킨다. 여기까지 와서 발견하면 이미 push된 뒤라 메시지를 다시 쓰고 force-push해야 하는데, 그 재작성이 실제로 사고를 냈다(브랜치가 main 위로 리셋되어 백업에서 복구). 커밋 전에 재면 비용이 0이다.

# 커밋 직전 — 제목만 재본다
printf '%s' "<제목>" | wc -c

# 이미 쌓인 커밋 점검
git log origin/main..HEAD --format='%s' | awk '{ print length($0)"자  "$0 }'

로컬에는 commit-msg 훅이 걸려 있어 73자 이상이면 커밋 자체가 거부된다 (.git/hooks/commit-msg, 워크트리 전체 공유). 훅은 추적되지 않으므로 새로 클론한 환경에는 없다 — 그런 환경에서는 위 명령으로 직접 확인한다. 훅 설치:

ls .git/hooks/commit-msg 2>/dev/null || echo "훅 없음 — 새 클론이면 직접 만들어 둘 것"

제목이 길어지는 원인은 대개 한 줄에 두 가지를 담으려는 것이다(A, and B). 그럴 땐 줄이지 말고 본문으로 내리거나 커밋을 쪼갠다.

4. 3레이어 테스트 + lint + build 통과 (필수)

"테스트"는 별도 명시가 없으면 WebView / Backend / Kotlin 3개 레이어 전부를 의미한다. 모든 개발은 TDD(테스트 먼저 → 실패 확인 → 구현)를 따른다.

bash ./scripts/build.sh wv-test
bash ./scripts/build.sh wv-lint
bash ./scripts/build.sh be-lint
bash ./scripts/build.sh full-build

5. OS/환경별 동작 보장 (크로스 플랫폼) (필수)

OS와 맞닿을 확률이 조금이라도 있는 코드는 Windows·macOS·Linux 모두에서 안전하게 동작해야 한다. 특히 Windows는 단일 환경이 아니다 — cmd / PowerShell / WSL / WSL2를 각각 별도 셸로 취급하고, 새 외부 명령은 이 전 환경 체크리스트로 점검한다. 비관적 관점에서 검토한다.

• 경로: / 하드코딩 대신 path.join(). 경로 비교 시 대소문자 정규화(Windows/APFS insensitive vs Linux sensitive).
• 셸 명령: Unix 전용 명령(which, chmod, kill, POSIX 파이프) 지양. 셸 토큰화 회피가 이 프로젝트의 확립된 패턴.
• 환경 변수: HOME(Unix) vs USERPROFILE/HOMEDIR(Windows). 단독 사용 금지.
• 줄바꿈: \n 하드코딩 금지, Windows \r\n 고려. 임시 디렉토리는 os.tmpdir(), 실행 파일 확장자(.sh vs .cmd/.bat) 주의.
• 프로세스: Unix 시그널(SIGTERM/SIGKILL)은 Windows 미지원 — 분기 필요.
• WSL/WSL2: claude/node 탐색 시 PATH 비대칭 주의. 로그인 셸(bash -lic)로 .bashrc를 상속해 PATH를 확보한다.

6. 프로젝트 고유 원칙 준수 (필수)

• CLI 동등성 & 공식 SDK/내부 프로토콜 비의존: 공식 claude CLI 명령을 기준선으로. 참고 앱은 UX만 모방.
• 원본 데이터 보존: JSONL 엔트리 등 원본 구조를 편집·리네임 없이 WebView까지 전달(범위 분할은 허용).
• 일관 작명: 같은 동작엔 같은 verb. IPC type은 MessageType enum(문자열 리터럴 금지).

7. PR 본문 / 커밋 메시지 (필수)

• PR 본문은 영어로 작성한다. (한국어 본문 금지)
• 커밋 메시지는 영어 + conventional 스타일(fix:, feat:, refactor:, docs:, chore: …). 첫 줄 72자 제한은 항목 3.5에서 다룬다 — 여기서 처음 발견하면 이미 늦다.
• PR 본문은 무엇을, 왜 바꿨는지 명확히 설명한다.
• 이슈를 해결하는 변경이면 종료 플래그 필수 — Closes #N / Fixes #N. (#N) 참조만으로는 이슈가 자동으로 닫히지 않는다. push 전에 빠졌으면 git commit --amend로 보강한다.

7.1. 마일스톤 대조 (에이전트 전용)

이 항목은 메인테이너의 릴리즈 관리 절차다. 마일스톤 지정에는 저장소 write 권한이 필요하므로 외부 기여자가 수행할 수 없고, 요구하지도 않는다. 조회·변경 명령은 로컬 운영 문서에만 둔다.

이슈를 해결하는 PR이면 그 이슈의 마일스톤과 PR을 대조한다.

• 종료 플래그의 이슈 번호와 착수 때 기록한 이슈 번호가 일치하는지 확인한다. 다르면 둘 중 하나가 틀린 것이므로 사용자에게 보고한다.
• 해결하는 이슈에 마일스톤이 없으면 지금 붙일지 확인한다. 마일스톤이 없으면 그 이슈는 릴리즈 노트 생성에서 누락된다.
• 붙은 마일스톤이 이미 배포된 버전이면 틀린 상태다. 아직 배포 안 된 가장 가까운 마일스톤으로 재지정할지 확인한다. 배포 여부는 state가 아니라 릴리즈 태그로 판정한다.
• 붙은 마일스톤이 아직 배포 전이면 현재 패치와 달라도 그대로 둔다. 다음 마이너로 미뤄둔 의도일 수 있으므로 임의로 바꾸지 않는다.

8. 학습 내용 메모리 기록 (필수, 에이전트 전용)

이 항목은 에이전트의 작업 규율이다. 외부 기여자에게 요구하는 절차가 아니므로 CONTRIBUTING.md(공개 기여 가이드)에는 두지 않는다.

PR을 올리기 전, 이번 작업에서 기억해야 할 점이나 배운 점을 정리해 메모리에 기록한다. 이 항목은 매 PR마다 빠짐없이 반복 실행한다.

왜: 같은 조사를 반복하지 않기 위해서다. 특히 "한 번 확인해두면 다음에 바로 쓸 수 있는 사실" (공식 스키마·API 계약·플랫폼 함정·검증 방법)은 기록하지 않으면 다음 세션에서 처음부터 다시 파야 한다.

무엇을 기록하나 — 아래에 해당하면 기록한다:

• 판정 근거와 그 확보 방법: 무엇을 1차 근거로 삼았고 어떻게 받아왔는지(예: 스키마 원문 URL + 파싱 명령). 특히 틀린 정보원을 만났다면 그 사실 자체를 기록한다 — 다음에 같은 함정에 빠지지 않게.
• 아키텍처 결정과 그 이유: 왜 A가 아니라 B인지. 나중에 "왜 이렇게 했지?"가 나올 지점.
• 함정·역직관적 제약: 순환 의존, 화이트리스트 때문에 순서를 바꿔야 하는 것, 플랫폼별 차이 등.
• 미해결로 남긴 것과 그 한계: 무엇을 왜 못 했고, 어떤 조건에서 문제가 되는지.

무엇을 기록하지 않나: 코드·git 히스토리·CLAUDE.md를 보면 바로 아는 것(파일 구조, 이번에 고친 코드 자체), 이번 대화에서만 의미 있는 진행 상황.

기록 방법: 기존 메모리에 같은 주제가 있으면 새 파일을 만들지 말고 그 파일을 갱신한다 (중복 방지). 새로 만들 때만 MEMORY.md 색인에 한 줄 추가한다.

결과 보고

각 항목을 PASS / FAIL 테이블로 보고한다. FAIL이 하나라도 있으면 PR을 열지 말고 먼저 수정하도록 안내한다. 모든 항목 PASS면 "PR 준비 완료"로 마무리한다.