커밋, 푸시 및 PR 열기
현재 기능 브랜치에서 작업을 배포합니다: 커밋 → 푸시 → PR. 확인 게이트(6단계)가 푸시를 제어합니다. 같은 차례에 연속으로 호출되더라도 절대 건너뛰지 마십시오.
선택적 인수 하나를 받습니다: 기반 브랜치. 인수가 없으면 5단계에서 기반을 결정합니다.
1. 브랜치 보호
git branch --show-current. main/master인 경우 중지하고 사용자에게 먼저 기능 브랜치를 생성하라고 알리십시오. 절대 main에 직접 커밋하거나 푸시하지 마십시오.
2. 커밋 범위 지정
git status + git diff. 현재 작업에 속한 파일만 스테이징하십시오. 스크래치 출력, 생성된 데이터 또는 로컬 테스트 픽스처(CSV, *_results/*, 로그)로 보이는 추적되지 않은 파일은 자동으로 스테이징하지 말고 나열한 후 사용자에게 포함, 무시 또는 gitignore에 추가할지 물어보십시오.
3. 커밋 전 검사
저장소의 자체 포맷/린트 명령어를 찾으십시오. AGENTS.md, CLAUDE.md, README.md(이 순서대로)에서 문서화된 포매터/린터를 확인하고 거기에 지정된 것을 실행하십시오. 해당 문서 중 어느 것도 명명하지 않은 경우 dotnet format이나 다른 도구별 추측을 기본값으로 사용하지 말고, 포매터/린터가 문서화되지 않았다고 기록하고 계속 진행하십시오.
변경 사항이 테스트된 코드를 건드리고 빠른 타겟 테스트 실행이 가능하다면 실행하십시오. 커밋을 위해 전체 테스트 스위트를 실행하지 마십시오.
4. 커밋 메시지
이 저장소의 git log에 이미 있는 스타일과 일치하는 Conventional Commits(feat|fix|test|docs|refactor(scope): summary) 형식을 사용하십시오. 본문은 diff에서 "이유"가 명확하지 않은 경우에만 추가하십시오.
5. 기반 브랜치 결정
기본 기반은 main입니다. 단, 작업이 스택된 경우는 예외입니다. 아직 병합되지 않은 기능 브랜치 위에 구축되어 main을 기반으로 하면 아래 브랜치가 이 diff로 끌려 들어오는 경우입니다.
- 인수가 주어진 경우 — 그것이 기반입니다.
git rev-parse --verify origin/<base>로 확인하십시오. 참조가 존재하지 않으면 그렇게 말하고main을 사용하십시오. - 인수가 없는 경우 — 하나의 후보를 찾으십시오. 다음 중 하나:
- 대화 내용에서 이 작업이 다른 브랜치에서 만든 커밋 위에 있다고 언급된 경우.
- 작업이 다른 티켓에 의해 차단되거나 의존하는 티켓에서 비롯된 경우. 해당 차단자를 해결하는 브랜치가 후보입니다.
git log --oneline origin/main..HEAD에 이 작업이 생성하지 않은 커밋이 표시되는 경우.git branch -r --contains <sha>로 해당 커밋이 어디서 왔는지 알 수 있습니다.
- 후보 검증. 후보는 원격에 존재해야 하고, 현재 브랜치와 달라야 하며,
git branch -r --merged origin/main에 없어야 합니다. 이미main에 병합된 후보는 유효하지 않습니다. - 후보가 없거나 검증에 실패한 경우 —
main.
검증된 후보는 결정이 아니라 제안입니다. 6단계 게이트에서 main과 함께 제시하고 사용자가 선택하도록 하십시오.
6. 확인 게이트 — 푸시
사용자에게 커밋 메시지, git diff --stat(또는 커밋이 완료된 후의 커밋), 5단계의 기반을 보여주십시오. 5단계에서 후보를 찾은 경우 두 옵션을 모두 보여주십시오. git push -u origin <branch> 전에 명시적 승인을 받으십시오. 푸시는 브랜치를 공개합니다. 단방향으로 취급하십시오. PR 생성은 동일한 승인(7단계 참조)에 의존하며 별도의 승인이 필요하지 않습니다.
7. PR 열기
먼저 이 브랜치에 대한 PR이 이미 존재하는지 확인하십시오: gh pr list --head <branch> --state all.
- 열린 PR 발견 — 재사용하고 중복을 생성하지 마십시오. URL을 보고하십시오.
- 병합된 PR 발견 — 브랜치가 이미 한 번 배포되었습니다. 다른 PR을 생성하기 전에 중지하고 사용자에게 원하는 바를 물어보십시오. (병합 후 새 커밋은 일반적인 경우가 아니므로 기본 케이스가 아닙니다.)
- 열린/병합된 PR 없음 — 6단계의 푸시 확인이 이미 이를 포함합니다. 본문을 작성하고
gh pr create --base <base> --head <branch> --title "<title>" --body "<body>"를 바로 실행하십시오. 추가 승인이 필요하지 않습니다.
가시적인 UI 변경 사항에 대한 스크린샷. 변경 사항이 사용자가 볼 수 있는 것(새 텍스트 필드, 색상 변경, 새 레이아웃 또는 복사본, 새 페이지 또는 컴포넌트)을 변경하는 경우, 해피 패스와 변경 사항이 도입하는 엣지 케이스(빈 상태 및 오류 상태, 길게/오버플로우되는 텍스트, 관련된 경우 반응형 vs 데스크톱)의 스크린샷을 캡처하십시오. gh pr create --attach '<path>#<alt text>'로 업로드하십시오. (이미지당 반복, 기존 PR에 추가하려면 gh pr edit <pr> 사용). 본문이 동일한 경로를 참조하는 경우(예: ## Screenshots 제목 아래 ), gh는 참조를 업로드된 URL로 대체합니다. 그렇지 않으면 첨부 파일이 본문 끝에 추가됩니다. 비공개 저장소에서도 작동합니다. 첨부 파일은 저장소 접근 권한이 있는 모든 사람이 볼 수 있습니다. 파일을 커밋 밖에 두십시오(스크래치 디렉토리). 업로드되며 버전 관리되지 않습니다. gh 2.99 이상 필요; 이전 버전에서는 웹 UI에서 PR 본문으로 이미지를 끌어다 놓으십시오. 변경 사항이 사용자에게 보이지 않는 경우(로직, 테스트, 설정, 문서, CI)에만 건너뛰십시오.
초안을 작성하기 전에 저장소의 자체 PR 설명 표준을 확인하십시오. .github/PULL_REQUEST_TEMPLATE.md, .github/pull_request_template.md, docs/* 또는 CONTRIBUTING.md의 PR 본문 가이드라인. 저장소에 문서화된 템플릿이 있으면 아래 템플릿을 재정의하고 그것을 사용하십시오.
PR 본문 템플릿 (폴백 — 저장소 표준이 있으면 그것이 우선)
## Summary
<무엇이 변경되었고 그 이유, 1-6문장>
## Changes
- <주목할 만한 변경 1>
- <주목할 만한 변경 2>
## Screenshots
<가시적인 UI 변경의 경우: 해피 패스 + 관련 엣지 케이스; 보이지 않는 변경의 경우 생략>
## Design decisions
<주목할 만한 트레이드오프 또는 기각된 대안 — 아래 참조, 큰 기능 변경에만 해당>
## Testing
<실행된 명령어 / 확인 방법>
## Follow-ups
<연기된 작업, 또는 "None">
기반이 main이 아닌 경우, 기반 브랜치 이름과 먼저 병합되어야 할 사항을 명시하여 Summary를 시작하십시오. 리뷰어는 diff가 스택되어 있고 기반이 병합되면 PR이 main으로 다시 타겟팅된다는 것을 알아야 합니다.
Design decisions는 PR이 실질적인 크기의 새로운 기능적 동작(새 모듈, 중요하지 않은 알고리즘, 리뷰어가 묻지 않으면 알 수 없는 트레이드오프)을 도입하는 경우에만 포함하십시오. 문서/설정/잡일/작은 수정의 경우 섹션을 비워두지 말고 완전히 생략하십시오.
8. 리뷰 워크스루 (광범위한 변경만)
다음 중 하나라도 해당할 때 자체 포함된 HTML 워크스루를 작성하십시오:
- diff가 여러 개의 다른 비UI 모듈을 건드리는 경우;
- 데이터베이스 스키마를 변경하는 경우(마이그레이션, 테이블, 컬럼, 인덱스, 제약 조건);
- 여러 레이어를 가로지르는 대규모 엔드투엔드 기능인 경우.
문서, 설정, 잡일, 작은 수정, 하나의 모듈 또는 UI에만 국한된 변경의 경우 건너뛰십시오. 워크스루는 리뷰를 단축하기 위해 존재합니다. 모든 PR에 대해 자동으로 생성하지 마십시오.
커밋 외부의 스크래치 디렉토리(절대 스테이징하지 않음)에 pr-walkthrough.html 파일 하나를 작성하고, open pr-walkthrough.html로 로컬에서 열고, 사용자에게 경로를 알려주십시오. 호스팅하거나, 첨부하거나, 버전 관리하지 마십시오.
네이티브 <details>/<summary> 접을 수 있는 제목 아래 섹션으로 구성하십시오. 첫 번째 섹션은 열려 있고 나머지는 접혀 있어 리뷰어가 제목을 스캔하고 필요한 것만 펼칠 수 있도록 하십시오. JavaScript는 사용하지 마십시오.
diff를 읽지 않은 리뷰어를 위해 작성되었습니다:
- What and why — 몇 문장으로 된 변경 사항과 diff를 읽을 순서.
- Change map — 어떤 모듈이 건드려졌고 어떻게 연결되는지. 파일 목록이 아닌 다이어그램.
- Mechanics — 코드에 명명된 경로와 함께 설명된 각각의 명확하지 않은 로직 또는 데이터 흐름 (
path:line). - Schema changes — 이전/이후 테이블 모양, 마이그레이션 경로 및 위험(잠금, 백필, 롤백).
- Hard parts — 리뷰어가 묻지 않으면 알 수 없는 부분과 주의 깊게 봐야 할 부분.
다이어그램: 모듈 종속성, 요청/시퀀스 흐름 및 스키마에 대해 콘텐츠 크기에 맞게 직접 작성하고 크기 조정된 인라인 SVG를 사용하십시오. 파일을 자체 포함되게 유지하십시오. 외부 JS, CSS 또는 이미지 URL이 없어 오프라인에서 열 수 있습니다. 설명하려는 대상이 시각적인 경우에만 렌더링된 이미지 또는 스크린샷을 사용하십시오.
9. 보고
사용자에게 PR URL과 대상 기반을 알려주십시오. 무엇이 커밋, 푸시, 열렸는지 명확히 진술하십시오. 모호함 없이.