현재 사용법 (2026-09-10, 6fbaee7f): 문서 작성·이미지·갱신 책임 · 기능 마스터. 아래는 작성 당시의 변경 설명이며 현재 전체 동작·재측정 결과를 뜻하지 않습니다.

PR 본문을 한글 하나로 통일하고, 그 안을 code-explainer가 채우게 합니다

앱 동작은 바뀌지 않습니다. PR을 여는 사람과 읽는 사람에게만 보이는 변경으로, 앞으로 PR 본문은 한글로 한 번만 쓰고 영문 ## Summary 섹션은 쓰지 않으며, ## 요약 안이 파일 목록 대신 설명으로 채워집니다.

두 변경은 같은 자리를 다룹니다. PR 본문 안에 무엇이 들어가는가입니다.

배경

이 저장소에서 PR 본문을 규정하던 것은 세 곳이었습니다.

첫째는 CLAUDE.md의 "Commit & PR Conventions" 절입니다. 섹션이 ## Summary(영문 불릿), ## 요약(한글), ## Test plan(한글 체크리스트) 세 개이고 이 순서라는 것만 정했습니다. 둘째는 .github/pull_request_template.md입니다. GitHub이 PR을 열 때 자동으로 채워 넣는 빈 뼈대로, 같은 세 섹션과 체크박스 여섯 개를 담고 있었습니다. 셋째는 frontend-pr-preflight 스킬입니다. 이 스킬은 커밋 전과 PR 전에 변경 내용의 위험을 검사하는 리뷰 도구인데, 본문에 대해서는 "세 섹션으로 써라"와 "본문이 비었거나 체크박스가 전부 미체크면 경고한다" 두 가지만 봅니다.

세 곳 모두 뼈대와 사후 검사만 규정했습니다. 그 안에 무엇을 어떻게 쓰는지는 규정된 적이 없습니다. 그래서 본문이 변경된 파일을 나열하는 것으로 채워져도 걸리는 곳이 없었고, 리뷰어는 변경의 이유를 diff에서 직접 역추적해야 했습니다.

강제 장치도 없습니다. commit-msg 훅이 없고 commitlint도 쓰지 않습니다. .husky/pre-commit은 lint-staged와 색상·네이티브 다이얼로그·모달 검사만 돌립니다. 커밋 메시지와 PR 본문은 전적으로 규약과 준수에 의존합니다. 최근 머지된 PR 12건을 확인했을 때 ## Summary가 비어 있던 것이 4건이었던 것도 이 때문으로 보입니다.

code-explainer는 hereby-sign 저장소에서 쓰던 스킬입니다. PR 본문의 내용을 어떻게 구성할지 규정합니다. 사용자가 보는 변화를 한 문장으로 먼저 쓰고, 그다음에 변경이 놓인 자리를 구체적인 이름으로 설명하며, 데이터 흐름은 변경 전과 변경 후를 각각 별도의 mermaid 블록으로 그리고, 마지막으로 파일 순서가 아니라 개념 순서로 변경을 서술하게 합니다. 이 스킬 파일은 hereby-sign의 원본과 바이트 단위로 동일하게 유지합니다. 고칠 일이 있으면 원본을 고치고 다시 복사합니다.

변경 전

변경 후

개념 흐름별 변경

## 요약 안의 내용을 처음으로 규정합니다. code-explainer 스킬을 .claude/skills/code-explainer/에 넣고, CLAUDE.md의 PR 규약에서 이 스킬을 가리키게 했습니다. 다중 파일 변경이거나 인과가 자명하지 않은 변경이면 이 스킬로 ## 요약을 씁니다. 한 줄짜리 변경, 서식 정리, 기계적 이름 변경, 의존성 버전 올리기에는 적용하지 않습니다. .gitignore가 .claude/skills/를 제외하고 있어 git add -f로 추적에 넣었습니다. 이 저장소에서 frontend-pr-preflight가 추적되는 방식과 같습니다.

본문을 한글 하나로 통일합니다. ## Summary(영문)와 ## 요약(한글)이 같은 변경을 두 번 설명하는 구조였습니다. 두 섹션 중 하나가 비거나 서로 내용이 어긋나는 경우가 생겼습니다. 영문 섹션을 없애고 ## 요약과 ## Test plan 두 개만 남겼습니다. 제목은 Conventional Commits 형식(type(scope): subject)이므로 영문을 그대로 유지합니다.

세 섹션을 지시하던 곳을 모두 맞춥니다. 규약만 고치고 나머지를 두면 도구가 서로 다른 형식을 지시하게 됩니다. CLAUDE.md의 PR 절, .github/pull_request_template.md, frontend-pr-preflight 스킬의 3번 절차와 12번 점검 항목, 그리고 preflight.sh가 출력하는 12번 리마인더 문구를 함께 고쳤습니다. docs/superpowers/plans/ 아래의 과거 기록은 작성 시점의 사실이므로 고치지 않았습니다.

이 변경으로 code-explainer 스킬 57번째 줄의 "No English ## Summary"가 이 저장소에서도 문자 그대로 맞는 문장이 됩니다. 스킬을 처음 넣을 때는 이 문장이 저장소 규약과 충돌했고, 그때는 스킬 21번째 줄("PR 래퍼는 각 저장소의 규약을 따른다")을 근거로 세 섹션을 유지했습니다. 이제 그 예외가 필요 없어졌습니다.