Commit pr checklist
커밋·푸시·PR 직전 "ship 가능한가"를 묻는 게이트 오케스트레이터 — *무엇이 들어가나*(필요한 변경만·깨끗한 diff)와 *어떻게 설명하나*(레포 관례 + 독자 본위)를 순서대로 보고, 판정은 형제 스킬에 위임한다. 커밋·PR은 영구 기록이라 작업 *과정*(페이즈·단계·시도·run ID·"오늘 기준")이 아니라 *결과와 정당성*만 남긴다. 트리거 - (1) "이거 커밋/푸시/머지해도 돼?"·"올리기 전/머지 전 점검"·"PR·커밋 메시지 써줘", (2) git commit·gh pr create 직전 staged diff 셀프리뷰·불필요한 파일·시크릿·디버그·무관한 churn 점검, (3) 커밋/PR 형식을 기존 커밋·PR에서 도출해 맞추기, (4) "필요한 것만 커밋"·"atomic commit"·"커밋 쪼개줘"·"작업 흔적(임시·페이즈) 빼기", (5) 유닛·피처 테스트가 스펙-중심으로 붙었는지 확인. 판정은 형제 담당 — 코드는 code-fundamentals(프론트면 + toss-frontend-fundamentals + Vercel react-best-practices·composition-patterns 함께), 테스트는 test-foundations, 스펙 변종은 spec-first, 문장은 technical-writing. 이 게이트는 *언제·순서대로* 부른다. ship 맥락 없는 순수 코드리뷰/글다듬기는 그 단독 스킬이고, 1줄 수정엔 안 쓴다(proportional).From its SKILL.md
npx -y skills add soilSpoon/skills --skill commit-pr-checklistAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
29.2 KB, as published. Nobody here has run it
Commit/PR Checklist — "ship 가능한가"를 묻는 게이트 (오케스트레이터)
커밋·PR은 코드가 아니라 기록이다. 미래의 독자 — 리뷰어, git blame 하는 사람,
6개월 뒤의 나 — 가 이 기록을 읽고 비용을 치른다. 그래서 ship 전에 두 가지만 묻는다:
① 무엇이 들어가는가(필요한 변경만, 깨끗한 diff) · ② 어떻게 설명되는가(레포의
관례를 따른, 독자 본위의 메시지). 작업의 과정은 기록이 아니다.
이 스킬은 게이트를 소유하고 판정을 위임한다. 코드가 좋은지·테스트가 옳은지·문장이 매끄러운지는 형제 스킬이 답한다. 이 스킬은 그것들을 언제·어떤 순서로 부를지, 그리고 diff 위생·메시지 도출·기록 내구성처럼 아무도 소유하지 않는 ship 직전 관심사를 책임진다.
왜 — 게이트의 단 하나의 뿌리
거의 모든 나쁜 커밋·PR은 한 증상이다 — 작업한 사람 본위로 남겼다. 내가 거친 순서대로(페이즈 1, 2차 시도…), 내 작업 흔적을 담아서, 지금 내 머릿속 상태("현재는…")로.
기록은 과정이 아니라 결과와 그 정당성이어야 한다. 어떻게 도달했는지(막다른 길, 단계, 임시 스캐폴드)는 미래 독자에게 잡음이다. 무엇이 바뀌었고 왜 그게 옳은지만 남긴다 — 이게 durability filter(G6)의 뿌리이자, 메시지를 레포 관례로 맞추는(G5) 이유다.
0. 비례 (scope floor) — 게이트보다 먼저
교리가 아니라 비례한다. typo·주석 한 줄·import 정리는 전체 의식이 필요 없다 — diff를 한 번 읽고(G1) 메시지만 맞추면(G5) 끝. 게이트의 무게는 변경의 크기·위험에 비례한다. 보안·데이터 손실·시크릿 노출만은 작은 변경에서도 항상 본다(G2 — scope floor의 바닥은 협상 대상이 아니다, code-fundamentals 상속).
워크플로 — 6 게이트 (순서대로)
기계적 스캔(G1·G2 대부분)은 번들 scripts/preship-scan.sh가 한 번에 리포트한다 — branch·staged/untracked·시크릿/디버그 패턴·최근 커밋&PR 관례. 스크립트 없는 환경이면 아래를 손으로 한다. 스크립트는 best-effort이고, clean 리포트가 ship 보증은 아니다 — 게이트의 판단을 대체하지 않는다.
- G1 · SELF-REVIEW —
git diff --staged를 리뷰어처럼 한 hunk씩 읽는다. 의도와 무관한 줄이 보이면 거기서 멈춘다. ship 전 가장 큰 레버 하나다("look at the target"). - G2 · 무엇이 들어가나 — staged 집합이 필요한 변경만인가:
- stray/artifact — 빌드 산출물·
dist/·.zip·로그·.DS_Store·스냅샷·대용량 바이너리, 실수로 든 임시 파일이 없는가..gitignore를 존중하되, 생성물은 커밋하지 않는다. - secret — 키·토큰·
.env·비밀번호·BEGIN ... PRIVATE KEY가 diff에 새지 않는가. - debug 잔여 —
console.log/print/debugger/주석 처리된 코드/죽은 코드/맥락 없는TODO. - 무관한 churn — 포매터 잡음·import 재정렬·공백만 바뀐 줄로 diff가 부풀지 않는가 (리뷰 비용↑). 의도한 변경만 남긴다.
- 공개 표면 소비처 증명 — 이 diff가 추가·변경한 공개 표면(엔드포인트·파라미터·응답 필드·설정 키·export)마다 실 소비처 grep 결과를 PR 본문에 한 줄로 남긴다 — 계약 상대 저장소(프론트↔API)까지 포함해서. 자기 테스트만 소비하면 red flag다(code-fundamentals "바닥은 드리프트도 본다" 상속). "만들 때는 호출자가 있었다"는 증명이 아니다 — 소비자 쪽을 고친 커밋이 표면 쪽 정리를 건너뛰는 게 이 부류의 발생 경로다.
- 미실존 상태 방어 잔재 → defer. legacy·구·호환·폴백 주석,
expand*/변환 함수, 같은 테이블 연속 마이그레이션, "null이면 기존 값 유지" 분기가 diff에 보이면 unshipped-state-gate로 판정한다 — 방어 대상 상태 명명, 배포 경계는 사람에게(git 병합 ≠ 배포), 미실존이면 사슬째 삭제. - atomic — 한 커밋 = 한 논리적 변경. feature+refactor+fix가 한 덩어리면 쪼갠다.
squash-merge 레포(머지 후 PR이 커밋 1개로 접힘 —
git log의(#N)한 줄이 신호)면 살아남는 단위가 PR이다: 원자성의 진짜 레버는 인트라-PR 커밋 정리가 아니라 1 PR = 1 개념(관심사 여럿이면 스택 PR로 쪼갠다). 봇/AI 루프의 fixup 커밋은 squash가 지우므로 그 정리에 과투자하지 않는다.
- stray/artifact — 빌드 산출물·
- G3 · 코드 품질 → defer. 항상 code-fundamentals로
4축(가독성·예측가능성·응집도·결합도) 점검. 프론트엔드면 네 렌즈를 함께 켠다 —
code-fundamentals(언어 불문 4축) + toss-frontend-fundamentals
(a11y·React 런타임·디자인 토큰) +
vercel-react-best-practices(React/Next 성능: 워터폴·번들· RSC·리렌더) +vercel-composition-patterns(합성 API: compound·render props·context·React 19). 뒤 둘은 외부 스킬(vercel-labs/agent-skills) — 설치돼 있으면 함께 트리거, 없으면 설치 후. 주석은 최소로 — 달아야 한다면 왜를 담고 (무엇은 코드가 말한다), 밀도·스타일은 그 파일의 기존 주석에 맞춘다. 주석이 제값을 하는지의 판정은 code-fundamentals. - G4 · 테스트 → defer. 변경 코드에 테스트가 붙고 green인가. 기능과 1:1로 찍어내지
말고 행동 변종을 덮는다: 유닛(L1)은 순수 로직을 정직하게(억지 green·vacuous·over-fit
금지), 피처(L2, 사용자 여정이 있으면 L3)는 관찰 가능한 결과 = 스펙/의도를 단언(구현·
메커니즘 단언 금지). 계층 최종 배치는 test-foundations에
defer하고(리그·
verify엔트리도), E2E는 여정이 있을 때만이지 전-변경 강제가 아니다 (scope-floor). 스펙-중심 변종 도출은 spec-first. 변경 scope부터 돌린다(verify --changed). - G5 · 메시지 · PR — 아래 "메시지는 레포에서 배운다" 참조.
- G6 · durability filter — 아래 "기록에서 과정을 벗긴다" 참조.
메시지는 레포에서 배운다 (G5)
형식을 발명하지 말고 도출한다. ship 직전 레포가 이미 쓰는 관례를 읽어 맞춘다 — 이게 가장 적은 마찰로 리뷰어를 돕는다.
아래 1~6은 모든 PR에 채우는 서식이 아니라 메뉴다(G0 비례가 본문 구성에도 적용된다) — 이 PR의 크기·위험에 맞는 것만 고른다. 한 줄 fix에 리딩 가이드·스크린샷·범위 설명까지 전부 붙이면 정보가 늘지 않고 신호 대 잡음비만 나빠진다. 항목별로 "해당하면"이 붙은 것은 특히 그렇다 — 해당 안 되면 그 항목 자체를 쓰지 않는다, 빈 칸이나 "없음"으로 채우지 않는다.
-
관례 추출 — 커밋 제목과 PR 제목은 다른 관례다. 각각 자기 소스에서 뽑는다.
- 커밋:
git log --no-merges --format='%s' -30.--no-merges가 중요하다 — 머지 커밋의 subject는Merge pull request #N from owner/branch라서 브랜치명이지 PR 제목이 아니다. 그걸 세면 "이 레포는 영어 소문자 명사구를 쓴다" 같은 결론이 나오는데, PR 제목은 전혀 다를 수 있다(실제로 그렇게 틀린 적이 있다). - PR:
gh pr list --state merged --limit 30 --json number,title. 제목을 쓰기 전에 반드시 이걸 본다. 커밋 관례에서 PR 제목을 유추하지 않는다. - 용어·표현은 리뷰 커멘트에서 배운다 — 제목·형식의 소스가 커밋/PR 목록이라면, 단어의
소스는 과거 PR의 리뷰 커멘트다 — 세 출처를 같이 읽는다:
pulls/{n}/comments(인라인),pulls/{n}/reviews의.body(리뷰 본문 — 인라인에 없는 질문이 여기 온다),issues/{n}/comments(대화). 인라인만 읽고 본문의 4개 질문을 놓친 적이 있다: 리뷰어가 suggestion으로 고쳐 쓴 문장이 곧 팀의 실제 언어다. 프로젝트에 용어집(glossary)이 있으면 그것이 정본 — 코드·주석·메시지의 용어는 용어집을 인용해 판정하고, 없는 개념은 등재를 제안한 뒤 쓴다. ⚠️ 자기(에이전트) 과거 산출물의 사용 빈도는 관례의 근거가 아니다 — 내가 만든 번역어를 여러 PR에서 반복하면 그것이 "기존 용어"로 보이는 순환이 생기고, 실제로 그렇게 발명어("도장"·"갈래")가 수십 곳에 굳은 뒤에야 리뷰에서 전량 교정받은 적이 있다. 발명어와 같은 부류가 개발 은어의 직역이다 — "낙관적 갱신"·"폴백"·"뮤테이션"· "브릿지"·"재검증"·"후보"·"단층/2층" 처럼 개발자끼리는 통하지만 도메인 리뷰어는 멈추는 말. 주석·PR 본문에서는 동작으로 풀어 쓴다("서버 응답 전에 화면을 먼저 바꾼다", "없으면 X를 대신 쓴다", "IPC 메시지로 다시 불러온다", "한 행/두 행"). 판별법: 그 단어를 리뷰어가 질문하면 설명 문장이 필요한가 — 필요하면 그 설명 문장을 처음부터 쓴다. 연결어미 "~해,"로 문장을 잇는 것도 같은 냄새다(명령으로 읽힌다) — 문장을 끊는다. 교정했다는 주장은 추가 라인 grep 으로 증명한다 —git diff BASE -- . | grep -E '^\+.*(피하기 용어들)'이 0건이어야 "전수"다. "다른 PR 이 덮는다"고 넘길 때도 그 PR 의 diff 가 이 PR 의 추가 라인을 실제로 덮는지 대조한다(파일 단위 grep 은 이 PR 이 새로 넣은 줄을 놓친다 — 실제로 그렇게 6곳을 놓친 적이 있다). 용어집이 있으면 "피하기" 목록 전체를 파싱해 자동 대조한다(scripts/avoid_terms_check.py REPO BASE GLOSSARY --extra '→,—'— 0건이어야 통과). 무맥락 패스의 절차와 판정 처리 규칙은 fresh-eyes-review 스킬이 정본이다 — 이 게이트는 그 스킬을 부른다. - 둘 다에서 본다: Conventional Commits인가(
feat(scope):)? 스코프를 다는가? 제목 길이· 대소문자·언어(한/영)? 본문에 이슈 링크·"왜" 단락·테스트 노트가 있나? PR 템플릿이 있나(.github/PULL_REQUEST_TEMPLATE)? - 한국어 제목은 명사형(개조식)으로 끝낸다 —
~ 수정·~ 지원·~ 스크립트.~한다로 끝나는 서술문은 영어 명령형 커밋 관례를 직역한 것이라 한국어 제목으로 어색하다. 그리고feat:접두어가 이미 "추가"를 뜻하므로 제목에서 "추가한다"를 또 쓰지 않는다.
- 커밋:
-
문장 다듬기 → defer(선택 아님). 본문을 쓰거나 고치면 technical-writing을 로드해 적용하고 그 "빠른 자가 점검"을 통과시킨다 — 개인 문체 규칙으로 대체하지 않는다(가치 먼저·독자 본위·메타담화/번역체/한자어 제거). 분량이 짧으면 여는 references는 줄여도, 로드·적용은 건너뛰지 않는다(사소한 변경 제외는 G0 scope-floor가 판정하지, 이 게이트에서 빠져나가지 않는다). 판정 규칙은 technical-writing이 소유하므로 여기 복제하지 않는다.
⚠️ "고칠지 판단"도, 리딩 가이드처럼 새로 쓰는 문장도 이 게이트 안이다. "이 PR 보완할 부분 있나" 같은 진단·감사 요청은 아직 안 고쳤다는 이유로, 앞선 PR 형식을 그대로 베낀 새 문장은 "이미 검증된 패턴"이라는 이유로 이 게이트를 건너뛰지 않는다 — 판단·작성 둘 다 어차피 그 코드를 이미 아는 사람의 시야로 한다. 구조·사실관계 확인이나 형식 맞추기와 별도 패스로 sentence-craft 5원칙 전부(정보밀도·메타담화·구체성· 일관성·주체,
review-checklist.mdStep 3)를 명시적으로 돌리지 않으면 축이 다른 문제가 매번 새로 샌다 — 용어 축(일관성)만 돌려서 즉흥 은어("golden"/"net")는 잡아도 메타담화 축을 안 돌려서 "독자에게 말 거는" 문장("겁먹지 않아도 된다"류 — 사실이 아니라 독자의 감정을 예단하는 문장)은 새로 샌다. 한 축만 기억해 그것만 반복 점검하는 식으로는 안 끝난다. 그 코드를 검증까지 한 사람, 앞선 PR 형식을 베낀 사람일수록 자신에게는 이미 자연스러워 보여서 더 잘 놓친다(curse of knowledge). 대응은 인상이 아니라 절차로: 완성한 문장 전체를review-checklist.mdStep 3의 5개 질문에 하나씩 대조한다 — 용어 자기완결성(백틱 아닌 영단어·축약어가 이 문서 안에서 정의됐는가/보편 용어인가/같은 개념의 다른 표현이 이미 있는가)은 그중 하나일 뿐, 전부가 아니다. -
무엇을 담나 — 제목은 무엇이 바뀌었나를 한 줄로(레포 형식대로). 본문은 왜(이 변경이 푸는 문제) > 무엇(diff가 이미 말함) > 리스크·breaking change·리뷰어가 검증하는 법. 공개 API breaking이면 마이그레이션 노트(프론트면 codemod까지 — toss-frontend 담당). 해당하면, 관련 있어 보이는데 의도적으로 안 건드린 영역이나 실제로 검증 못한 갈래를 짧게 밝힌다("메시 설정은 기존 왕복이라 안 건드림", "wasm 빌드는 안 돌려봄") — 리뷰어가 "이것도 됐겠지"로 잘못 넘겨짚는 것을 막는다. 전부 확인했고 관련 영역을 다 건드렸으면 이 문장 자체를 안 쓴다 — "특별히 제외한 것 없음"류 채움은 정보가 아니라 서식 강박이다.
-
리뷰어를 안내한다 — 제목은 사용자가 겪는 증상으로 연다(내부용어로 열지 않는다: "god-file 분해"가 아니라 "…할 때 …되던 문제"). 본문은 역피라미드 — 상단 3줄을 비저자가 15초에 읽는다 (①한 문장 무엇 ②핵심 파일 1~2개 + 위험 ③스크린샷), 상세 추론·엣지케이스는
<details>아래로 접는다. 파일이 많으면 리딩 가이드로 핵심/부수/노이즈(생성물·기계적 rename·픽스처)를 갈라 지목하되, 파일명을 맨 글자로 두지 않는다 — 리뷰어가 39개 diff를 스크롤해 찾는 사냥이 된다. GitHub PR의 파일 diff는#diff-<sha256(경로)>앵커를 갖는다(echo -n "<repo-relative-path>" | sha256sum) — 파일명을[파일명](.../pull/{n}/files#diff-<hash>)링크로 걸어 클릭 한 번에 그 diff로 이동하게 한다. 각 항목엔 파일명 옆에 한 문장의 해석을 반드시 붙인다 — "이 값이 언제 true/false가 되는지", "이게 왜 맞는지"처럼 Files Changed 탭이 스스로 못 주는 판단을 준다. 파일명만 나열하는 건 리스트일 뿐 안내가 아니다. 여력 되면 핵심 hunk에 자기 diff 인라인 앵커 코멘트(gh api …/pulls/{n}/comments)로 코드 옆에 직접 붙인다.⚠️ 코드 스니펫 임베드(
blob/<sha>#L범위퍼머링크를 단독 줄로 두는 것)는 쓰지 않는다. 시도해봤지만 diff 대비 못한 부분만 보여주고(색상·주변 맥락 없음), 리뷰어가 원하는 건 코드 자체가 아니라 왜 맞는지의 해석이라 실패했다 — 위 "한 문장 해석 + 딥링크"가 낫다. -
프론트·UI 시각 증거 — 폰트·레이아웃·스타일 등 화면이 바뀌는 PR이면 before/after 스크린샷을 남긴다. PNG는
out/pr-screenshots/<slug>/로컬만 —.github/pr-assets/생성· 커밋 금지.preship-scan이 staged PNG·pr-assets 경로를 잡는다. private 레포 PR 본문 인라인은gh-image로user-attachmentsURL을 얻어![...]()로 붙인다(gh image extract-token→GH_SESSION_TOKEN). 일괄 반영은 scripts/pr-inline-images.sh. 세션 없을 때만 blob 링크 테이블 폴백.raw.githubusercontent.com·상대 경로 임베드·orphan 브랜치·PAT-only 업로드는 금지. pr-visual-evidence.md. -
본문의 사실은 push마다 다시 맞춘다. PR 본문은 한 번 쓰고 끝이 아니다 — 리뷰 대응으로 커밋이 쌓이면
## Verification의 테스트 수·red 근거·빌드 결과가 조용히 낡는다. 낡은 검증 숫자는 리뷰어에게 거짓 정보지 오래된 정보가 아니다. push 직전에 본문의 수치와 주장이 현재 HEAD와 맞는지 한 번 훑는다(G6가 지우는 것이 과정이라면, 이건 사실을 갱신하는 것).
1줄 감각:
Phase 2 임시로 우회, 현재는 잘 됨→fix(auth): 토큰 만료 시 재시도 — 상류 race 회피(과정·시간어를 벗고, 무엇 + 왜만).
좋은/나쁜 예시와 learn-from-repo 워크드 예시는 references/messages.md.
기록에서 과정을 벗긴다 (G6 · durability filter)
커밋·PR·코드·주석에서 시간이 지나면 거짓이 되거나, 미래 독자에게 잡음인 것을 걷어낸다. 영구 기록에 휘발성 정보를 박으면 다음 사람이 그 거짓을 디버깅한다.
- 시간 상대어 — "현재는"·"지금"·"최근"·"오늘 기준"·곧 바뀔 버전·날짜. → 절대·무시간으로.
- 작업 과정 흔적 — "Phase 1"·"1단계"·"2차 시도"·"임시"·"우선"·스캐폴드 메모·막다른 길의 잔재. 기록은 결과지 일지가 아니다.
- 휘발성 식별자 — run/agent/job ID(
wf_…), 임시 브랜치명, "어제 논의한 대로"·"슬랙에서 말한"처럼 곧 닿을 수 없어지는 참조. - 남길 가치가 있는 왜는 무시간 명제로 다시 쓴다("X 때문에 Y로 우회" — 과정이 아니라 이유).
문장-수준 메타담화 교정은 technical-writing과 겹친다 — 그쪽은 읽기 쉬움, 여긴 기록의 내구성. 코드 곁 산문엔 둘을 함께 쓴다. 메시지에 적용한 before/after 카탈로그는 references/messages.md §4.
PR 규모면 무맥락 패스로 판정한다. "처음 보는 독자로 다시 읽기"를 작업한 그 컨텍스트가 하면 curse of knowledge를 못 뚫는다 — 과정 서사("새 계약:"·"구 응답 폴백")는 저자에겐 완벽하게 읽히는 게 그 정체다. PR 규모(다파일·공개 표면 변경)면 별도 컨텍스트의 서브에이전트에게 diff와 프로젝트 용어집·리뷰 표준만 주고 "git 이력 없이는 이해되지 않는 문장·용어집 밖 용어"를 찾게 한다. 작업 대화·저자의 결론·설계 문서는 주지 않는다 — 새어 들어가면 같은 맹점이 재생된다. 출력은 판결이 아니라 센서다: 후보를 사람/메인이 판정하고, 기준(용어집·표준의 어느 항목인가)을 인용 못 하는 지적은 버린다. 무맥락 패스를 돌리지 않았으면 "보완 완료"라고 보고하지 않는다 — 보고문에 "무맥락 패스 N건 중 M건 반영" 숫자를 넣는다; 숫자가 없으면 미실행이다. 대상에는 테스트의 assertion 메시지·docblock 과 타 레포(front/api 동시 변경)를 포함한다 — 리뷰어가 찍은 지점만 고치고 같은 단어 grep 으로 끝내자 테스트 서술에서 56묶음이 추가로 나온 적이 있다.
리뷰 지적은 부류로 흡수한다 (ship 이후의 게이트)
지적된 단어를 grep해 지우는 것은 사례 소비다 — 다음 회차에 같은 부류가 새 단어로 태어난다. 리뷰 지적 1건을 받으면 수정 커밋과 같은 날 두 가지를 함께 남긴다:
- 부류 등재 — 프로젝트의 리뷰 표준(부류 카탈로그)에
부류 이름 / 정체 / 처방으로 일반화해 더한다. 용어 교정이면 용어집의 "피하기" 목록과 교정 이력에 등재한다. - 탐지 배선 — 그 부류를 다음에 누가 잡는지 정한다: 자동화(lint·스캔 스크립트)로 내릴 수 있으면 내리고, 아니면 무맥락 패스의 주입 문서에 들어가게 한다.
같은 리뷰어에게 같은 부류를 두 번 지적받으면 이 절차가 누락된 것이다 — 그때는 부류가 아니라 이 절차 자체를 점검한다(패턴의 패턴).
분담 (seams) — 무엇이 아닌가
이 스킬이 소유 = 게이트 시퀀스 + diff 위생(G1·G2) + 메시지 learn-from-repo(G5) + durability filter(G6). 판정은 전부 defer한다.
| 스킬 | 이 게이트가 거기에 defer하는 것 |
|---|---|
| code-fundamentals | 코드 품질 판정(가독성·예측가능성·응집도·결합도), 주석이 제값 하는지, scope-floor 판정 기준. 이 스킬은 무엇이 staged됐나를 보지 코드를 리뷰하지 않는다(단 secret·데이터 손실 바닥은 기준만 상속하고 스캔·실행은 G2가 한다) |
| toss-frontend-fundamentals | 프론트엔드 고유 판정(a11y·React 런타임·디자인 토큰), 공개 API breaking의 codemod·마이그레이션 가이드 |
| vercel-react-best-practices (외부) | 프론트엔드 성능 판정 — 데이터 워터폴 제거·번들 크기·서버(RSC) 성능·리렌더 최적화. vercel-labs/agent-skills |
| vercel-composition-patterns (외부) | React 합성 API 설계 — compound components·render props·context·boolean prop 증식·React 19 API. vercel-labs/agent-skills |
| unshipped-state-gate | 미실존 상태 방어 잔재의 판정 — 방어 대상 상태 명명·배포 경계 질문(사람)·스쿼시/만료 결정. G2는 신호를 넘길 뿐 판정하지 않는다 |
| test-foundations | 테스트 리그(계층·구조·verify 엔트리·2축 신뢰성), 유닛 vs 피처 계층 배치, 정직한 green(vacuous·flake 차단) |
| spec-first | 피처 테스트의 스펙-중심 변종(관찰 가능한 결과 = WHAT, 구현·메커니즘 금지) — "구현 중심 아닌 스펙 중심"의 정본 |
| technical-writing | 메시지·PR 본문의 문장 다듬기(가치>기능·독자 본위·번역체/수동태 교정·문서 유형) |
판정이 아니라 순서와 게이트가 이 스킬의 일이다 — 위 스킬들을 ship 직전 한 번에 엮는다.
체크리스트 (최소 스캔)
[MUST]staged diff를 hunk 단위로 읽었다(G1) · 시크릿/키/.env비노출 · 빌드 산출물·임시 파일 비포함 · 메시지·코드·주석에 휘발성 정보(시간어·페이즈·run ID) 없음[MUST]변경 코드에 테스트가 있고 로컬 green(없으면 이유 명시) · 피처 테스트는 구현이 아니라 스펙/의도를 단언[MUST]PR·커밋 본문은 technical-writing을 로드해 적용했다(개인 규칙 대체 금지) · 이 PR을 처음 보는 독자로 다시 읽어 코드 지식 없이 안 풀리는 문장·내부참조가 없다(문장 판정은 technical-writing)[SHOULD]디버그 잔여(console.log/debugger/주석코드) 제거 · 한 커밋 = 한 논리 변경 (되돌릴 수 있는 단위) · 무관한 churn(포맷·재정렬) 비포함 · squash-merge면 1 PR = 1 개념(스택)이 원자성 단위[SHOULD]리뷰어 안내 — 제목은 증상으로 · 본문 상단 3줄 skimmable(무엇·핵심 파일·스크린샷) · 파일 많으면 리딩 가이드로 핵심/노이즈 갈라 지목하되 파일명은#diff-<sha256>딥링크로(맨 글자 금지) + 항목마다 한 문장 해석 · 코드 스니펫 임베드는 쓰지 않는다(diff보다 못하고 해석을 안 준다) · 여력 되면 핵심 hunk에 인라인 앵커[MUST]PR 제목은gh pr list --state merged에서 도출했다 — 커밋 subject(git log)에서 유추하지 않았다. 둘은 다른 관례이고, 머지 커밋 subject는 브랜치명이라 세면 틀린다[MUST]사라진 export 전수 대조 (스크립트:scripts/removed_defs_check.py REPO BASE paths exts= 삭제된 정의가 HEAD 에서 아직 참조되는지,scripts/pure_del_hunks.py REPO BASE paths= 교체 없이 지워진 코드 hunk 목록 — 하나씩 '의도한 삭제인가' 판정):git diff BASE | grep -E '^-\s*(export|public function|Route::)'의 각 이름을 소비처 grep 한다 — 의도치 않은 삭제(블록 치환 편집 중 옆 함수까지 지움)는 저자가 눈치채지 못하므로 목록 기반으로만 잡힌다. 실제로 설정 탭 3개가 import 하던 요청 함수 6개가 기능 커밋에서 사라진 채 PR 에 올라간 적이 있다(테스트 미커버 영역).[MUST]공개 표면(엔드포인트·파라미터·응답 필드·export) 변경마다 소비처 grep 증거를 본문에 남겼다(계약 상대 저장소 포함) · 잔재 신호(legacy·폴백·연속 마이그레이션)가 보이면 unshipped-state-gate로 판정했다[MUST]PR 규모면 무맥락 패스를 돌렸다 — 별도 컨텍스트에 diff+용어집·리뷰 표준만 주입, 작업 서사 미전달, 출력은 센서로 취급 · 용어는 프로젝트 용어집을 인용해 판정했다[MUST]리뷰 지적을 반영할 때 수정 커밋과 함께 부류 카탈로그·용어집을 같은 날 갱신했다[MUST]리뷰 대응으로 커밋을 더 얹었으면 push 전에 본문의 사실을 HEAD에 맞췄다 —## Verification의 테스트 수·red 근거·빌드 결과. 낡은 숫자는 리뷰어에게 거짓 정보다[SHOULD]메시지 형식·트레일러(Co-authored-by/sign-off)가 레포 관례와 일치(git log/gh pr list에서 도출) · 본문이 왜 > 무엇 · breaking change·리스크·검증법 명시 · CI green 예상 · 안 건드린 관련 영역·미검증 갈래가 있으면(해당할 때만) 짧게 명시[SHOULD]UI·타이포·레이아웃 변경 PR — before/after PNG는 로컬만, 본문은gh-image인라인 (gh image check-token통과 — pr-visual-evidence)[SHOULD]기본 브랜치에 직접 커밋 안 함(브랜치 먼저) · 주석은 최소 + 기존 밀도/스타일에 맞춤
주의 / 비목표
- 교리가 아니다 — proportional. 1줄 수정에 6게이트를 매기지 마라. 게이트는 변경에 비례.
- 브랜치 먼저, 커밋은 요청 시. 기본 브랜치면 먼저 브랜치를 판다. 사용자가 명시적으로 요청할 때만 커밋·푸시한다(외부로 나가는 작업).
- 봇/AI 리뷰 루프는 draft 뒤에서 돈다. 봇 라운드마다 쌓이는 fixup 커밋을 사람이 실시간으로 목격하지 않게 PR을 draft로 열고, 봇이 조용하고 스크린샷·리딩 가이드가 갖춰졌을 때 ready로 flip한다. squash-merge면 그 커밋들은 머지 때 사라진다 — 커밋 정리보다 노출 시점을 관리한다.
- 자동화가 1차 방어선. 린터·포매터·타입·시크릿 스캐너·CI가 먼저 잡는다 — 이 게이트는
그 위의 사람-층(리뷰어 본위·관례·내구성)이다.
preship-scan.sh도 자동화의 보조이지 판정이 아니다. - 판정을 재구현하지 마라. 코드·테스트·문장 규칙은 형제 스킬에 산다 — 여기 복제하면 두 곳이 어긋난다. 이 스킬은 언제 부르나만 안다.