커밋 및 PR 작성기
변경 사항 집합을 명확한 커밋 메시지와 리뷰어가 조치를 취할 수 있는 풀 리퀘스트 설명으로 변환합니다. 가치는 변경의 이유와 무엇이 잘못될 수 있는지를 설명하는 데 있으며, diff을 다시 설명하는 것이 아닙니다.
안전 규칙 (먼저 읽기)
- 사용자가 명시적으로 요청하지 않는 한 커밋, 푸시 또는 PR을 열지 마십시오. 명령어를 제안하고 사용자가 직접 실행하도록 하십시오. 커밋과 푸시는 다른 사람에게 보이며 되돌리기가 어렵습니다.
- 메시지나 PR에 비밀 값을 절대 작성하지 마십시오. 스캔 결과 비밀 값이 발견되면, 작성하기 전에 중단하고 사용자에게 알리십시오. 비밀 값은 반드시 교체되어야 하며, 다음 커밋에서 제거하는 것만으로는 충분하지 않습니다.
- 사실을 지어내지 마십시오. 직접 확인하지 않은 이슈 번호, 테스트 결과, 벤치마크 수치 또는 동기를 작성하지 마십시오. 변경 이유가 불분명한 경우, 짧은 질문 하나를 하거나 가정을 명시하십시오.
워크플로우
1. 변경 사항 수집
사용자 저장소에서 명령어를 실행할 수 있다면, 번들된 스캐너를 먼저 사용한 후 실제 diff를 읽으십시오:
python scripts/scan_diff.py # 스테이징된 변경 사항 (스테이징되지 않은 경우 fallback)
python scripts/scan_diff.py main...HEAD # 전체 브랜치, PR용
git diff --staged # 실제 diff 읽기 (크다면 --stat 먼저 사용)
git log --oneline main..HEAD # 브랜치에 이미 있는 커밋들, PR용
scripts/scan_diff.py는 파일을 영역(코드, 테스트, 마이그레이션, 의존성, 설정, CI, 문서)별로 그룹화하고, 가능한 비밀 값, 디버그 잔재, 누락된 테스트, 마이그레이션, 보안에 민감한 경로, 가능한 API 변경, 과도하게 큰 변경 사항을 플래그합니다. 이는 휴리스틱이므로 각 플래그를 diff와 대조하여 확인하십시오.
명령어를 실행할 수 없다면, 사용자에게 git diff --staged (PR의 경우 git diff main...HEAD)와, 관련이 있다면 이슈나 티켓 텍스트를 붙여넣도록 요청하십시오. 코드 실행이 가능한 경우에도 python scripts/scan_diff.py - 명령어로 붙여넣은 텍스트를 스캐너에 전달할 수 있습니다.
2. 의도 이해
어떤 동작이 변경되었고 그 이유가 무엇인지 파악하십시오. 증거의 우선순위: 브랜치 이름 및 티켓 ID, 브랜치에 이미 있는 커밋 메시지, 새로 추가되거나 변경된 테스트, 변경 사항 근처의 주석, 그 다음 사용자의 말. references/guidelines.md 섹션 4를 참조하십시오.
3. 범위 확인
diff가 관련 없는 여러 주제(기능 + 리팩터 + 서식, 또는 관련 없는 모듈)를 혼합하고 있다면, 하나의 모호한 메시지를 작성하는 대신 분할을 제안하십시오: 각 그룹, 각 그룹에 속한 파일, 그룹별 메시지, 그리고 git add -p 단계를 나열하십시오. 하나의 커밋에는 하나의 논리적 변경 사항만 유지하십시오. 이미 하나의 논리적 변경 사항이라면, 하나의 커밋을 작성하십시오.
4. 커밋 메시지 작성
형식: type(scope): subject, 이어서 선택적 본문, 선택적 꼬리말.
- 타입:
feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert. - 제목: 명령형 어조("add", "fix"), 소문자, 끝에 마침표 없음, 약 50자, 최대 72자. 파일이 아닌 동작 변경을 설명하십시오.
- 본문: 이유가 명확하지 않을 때만 추가하십시오. 제목 뒤에 빈 줄을 두고, 이유를 설명하며, 약 72자에서 줄 바꿈하십시오.
- 꼬리말:
Closes #123(확실히 아는 번호만) 및BREAKING CHANGE: ...(클라이언트나 배포가 깨질 경우). 타입이나 스코프 뒤의!도 호환성이 깨지는 변경을 나타냅니다.
그런 다음 확인하십시오. 메시지를 임시 파일에 저장하고 다음을 실행하십시오:
python scripts/lint_commit_message.py message.txt
사용자에게 보여주기 전에 모든 오류와 의미 있는 경고를 수정하십시오.
5. PR 설명 작성 (PR 요청 시)
assets/pr-template.md에서 시작하십시오. 무엇(What), 이유(Why), 테스트 방법(How to test) 을 채우고, 백엔드 영향(Backend impact) 항목 중 해당하는 것(데이터베이스 및 마이그레이션, API 변경, 보안 및 권한, 성능, 설정 및 플래그, 롤아웃 및 롤백)만 남기고 나머지는 삭제하십시오. 규칙:
- 제목: 커밋 헤더와 동일한 형식. 스쿼시 머지 시
main브랜치의 커밋이 되기 때문입니다. - 테스트 방법: 저장소에서 확인할 수 있는 정확한 명령어 (예: 변경된 테스트 파일). 테스트를 실행하지 않았다면 "테스트를 실행하지 않음"이라고 말하고, 통과했다고 암시하지 마십시오.
- 호환성이 깨지는 변경: 영향을 받는 사람, 그들이 해야 할 일, 기간을 명시하십시오.
- 마이그레이션: 배포 중에도 이전 코드가 여전히 작동하는지, 어떻게 롤백하는지 설명하십시오.
- 비례하게 유지하십시오. 한 줄 수정에는 전체 템플릿이 아닌 두 줄 PR이 필요합니다.
6. 결과 제시
다음 순서로 응답하십시오:
- 주의 사항 (스캔 결과 실제 문제가 발견된 경우에만): 비밀 값, 디버그 코드, 누락된 테스트, 매우 큰 diff, 위험한 마이그레이션.
- 커밋 메시지를 코드 블록으로 (또는 각 커밋별 메시지가 포함된 분할 계획).
- PR 제목 및 설명을 마크다운 코드 블록으로, 붙여넣기 준비된 상태로. 본문에 코드 펜스가 포함된 경우 네 개의 백틱으로 감싸십시오.
- 선택적 명령어 사용자가 실행할 수 있는 것, 예를 들어
git commit -F message.txt또는gh pr create --title "..." --body-file pr.md. 제안 사항으로 제시하십시오.
응답을 짧게 유지하십시오. diff를 다시 설명하지 마십시오.
변경 사항에 맞게 출력 크기 조절
- 오타, 문서 또는 설정 조정: 한 줄 커밋, 본문 없음, 두 줄 PR.
- 일반적인 변경: 헤더와 짧은 본문, What / Why / How to test가 포함된 PR.
- 크거나 위험한 변경 (마이그레이션, 인증, 공개 API): 관련 백엔드 영향 섹션이 포함된 전체 PR, 스캔 결과 크다고 판단되면 분할을 제안하십시오.
예시
입력 요약: 스테이징된 diff가 app/auth.py에서 토큰 디코딩 시 exp, iss, aud를 검증하도록 변경하고, tests/test_auth.py::test_expired_token을 추가하며, 브랜치는 fix/42-expired-tokens입니다.
출력:
fix(auth): reject expired refresh tokens
Tokens were accepted after expiry because exp was decoded but never
validated. Validate exp, iss and aud on every decode and return 401.
Closes #42
PR 제목은 fix(auth): reject expired refresh tokens이며, Why에 버그를 명명하고, How to test는 pytest tests/test_auth.py::test_expired_token을 가리키며, Security / authorization 항목에는 이전에 유효했던 만료 토큰이 이제 401을 반환한다고 명시합니다.
번들 파일
scripts/scan_diff.py: diff를 요약하고 위험을 플래그합니다. 사용법:python scripts/scan_diff.py [git-diff-args | -]. 종료 코드 1은 비밀 값 가능성을 의미합니다.scripts/lint_commit_message.py: 메시지를 Conventional Commits 형식에 대해 검사합니다. 사용법:python scripts/lint_commit_message.py message.txt(또는 stdin의 경우-). 종료 코드 1은 오류를 의미합니다.assets/pr-template.md: 채워 넣을 PR 설명 뼈대입니다. 사용자가 저장소에 기본 템플릿을 원하는 경우.github/pull_request_template.md에 복사할 수도 있습니다.references/guidelines.md: 예제가 포함된 커밋 타입, 좋은 메시지와 나쁜 메시지, 호환성이 깨지는 변경, diff 분할 방법, PR 크기, 백엔드 PR 섹션, 이슈 연결 키워드, 작성하지 말아야 할 사항. 위 내용으로 다루지 못하는 경우 여기를 참조하십시오.