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(문자열 리터럴 금지).