스택된 PR (Stacked PR)
크기 예산 (Size Budget)
PR당 약 300줄 변경을 목표로 하고, 최대 500줄을 넘지 않도록 합니다. 이 정도 크기라면 사람이 전체 변경 사항을 머릿속에 담고 빠르게 검토할 수 있으며, 리뷰 에이전트도 훑어보는 대신 깔끔하고 구체적인 결과를 제공합니다.
포함되는 항목: 직접 작성한 코드와 테스트.
포함되지 않는 항목: 잠금 파일(lockfiles), 생성된 코드(마이그레이션, 코드 생성, OpenAPI 출력), 스냅샷, 픽스처 및 공급업체 파일(vendored files). 이런 파일은 훑어보기만 하지 자세히 읽지 않습니다. 리뷰어가 건너뛰어야 할 생성된 파일은 PR 본문에 목록으로 표시하세요.
작성 후 분할하지 말고, 작성 전에 분할하세요. 분할 방식은 계획(coding-process 참조) 단계에서 결정됩니다. 계획된 단계가 500줄을 초과한다면, 다시 계획하세요. 일반적인 분할 기준:
- 테스트는 별도의 단계로 제출할 수 있습니다. 예를 들어, 로직과 단위/통합 테스트를 먼저 제출하고, 그다음 UI와 E2E 테스트를 제출합니다.
- 스키마 또는 데이터 모델, 그다음 이를 사용하는 서비스, 그다음 API 표면, 마지막으로 UI 순서로 분할합니다.
- 변경 사항을 쉽게 만들기 위한 리팩터링을 먼저 하고, 그다음 실제 변경을 수행합니다.
- 함께 포함하기에는 너무 큰 문서 업데이트는 별도의 문서 전용 단계로 추가합니다.
진정으로 분할할 수 없는 변경 사항(예: 하나의 응집된 마이그레이션이나 80개 파일에 걸친 이름 변경)은 예산을 초과할 수 있습니다. 이 경우 PR 본문에 그 이유를 설명하고, 실제로 검토가 필요한 부분을 리뷰어에게 알려주세요.
각 PR 내에서는 여전히 원자적 커밋(atomic commits)이 적용됩니다. 예산은 PR 단위이며, 커밋 관리(commit hygiene)를 대체하지 않습니다.
스태킹 (Stacking)
여러 단계로 구성된 작업은 전체 계획을 담은 단일 브랜치가 아닌, PR 스택으로 제출됩니다. 각 PR은 하나의 단계이며, main이 아닌 이전 단계의 브랜치를 대상으로 합니다. 따라서 리뷰어가 보는 모든 diff는 해당 단계의 변경 사항뿐이며, 위험한 단계(마이그레이션, 인증 변경 등)는 별도로 리뷰하고 되돌릴 수 있습니다.
- 각 단계는 이전 단계의 최신 커밋에서 브랜치를 생성합니다. 최하위 PR만
main을 대상으로 합니다:gh pr create --base <이전-단계-브랜치> - 각 PR 본문에 스택에서의 위치를 기록하세요(
Stacked on #123). 순서대로 열지 않은 리뷰어가 현재 PR이 무엇인지 알 수 있습니다. - 아래에서 위로 병합하세요. 기본 브랜치가 변경될 경우(리뷰 수정 사항 반영 또는 기본 브랜치 병합), 그 위에 있는 브랜치들을 리베이스하고 강제 푸시하세요. 병합되지 않은 자신의 스택 브랜치에 강제 푸시하는 것은 일상적입니다.
main이나 공유 브랜치에는 절대 강제 푸시하지 마세요. - 스택 내 어떤 PR이 병합된 후에는, 다음 단계를 시작하기 전에 나머지 PR들을 새 기본 브랜치에 동기화하세요.
- 리뷰 또는 검증 과정에서 나온 UI 표면 수정 사항은 상단에 새 단계로 제출하여, 빌드와 수정 사항이 별도로 리뷰 가능하도록 유지하세요.
gh stack, Graphite, git-town과 같은 스태킹 도구는 선택 사항입니다. 일반 git과gh만으로도 충분합니다.
순차적 리뷰 (Sequential Review)
스택은 한 번에 한 단계씩 리뷰합니다. 프로젝트의 리뷰어(AGENTS.md의 Project gates 참조)에게 최하위 PR에 대해서만 리뷰를 요청하고, 다음 단계를 진행하세요:
- 해당 단계의 PR에 대해서만 리뷰를 요청합니다.
- 모든 리뷰 결과를 처리합니다(아래 참조).
- 다시 리뷰를 요청하고, 해당 단계가 승인될 때까지 반복합니다.
- 그런 다음에야 다음 상위 단계에 대한 리뷰를 요청합니다.
전체 스택에 대해 한꺼번에 리뷰를 요청하지 마세요. 1단계의 리뷰 결과가 이미 2~5단계에 작성된 리뷰를 무효화할 수 있으며, 순차적 리뷰는 리뷰어의 노력을 제한적으로 유지합니다.
단계가 지연되는 경우(리뷰가 돌아오지 않거나, 제품 결정이 필요한 리뷰 결과) 해당 단계에 플래그를 표시하고, 그 답변에 의존하지 않는 상위 단계를 로컬에서 계속 개발하세요.
리뷰 결과 처리 방법 (모든 PR, 스택 여부 무관)
- 각 리뷰 결과를 기술적으로 먼저 확인한 후 조치를 취하세요. 지적된 코드를 읽고, 가능하다면 문제를 재현해 보세요.
- 수정하거나, 이유를 들어 반박하세요. 사람이든 봇이든 리뷰어는 일반적인 현상으로 틀릴 수 있습니다. 동의하는 척하기 위해 잘못된 변경을 하는 것은 논쟁하는 것보다 더 나쁩니다. 형식적인 동의는 하지 마세요.
- 리뷰 결과를 실제 발생 가능성으로 판단하세요. 현실적으로 발생할 수 없는 시나리오에 대한 수정이나 실제 이득 없이 복잡성만 추가하는 제안은 반박하세요.
- 실패할 수 없는 테스트는 추가하지 마세요. 버그 존재 여부와 관계없이 통과하는 테스트는 잡음입니다. 먼저 버그가 있는 코드에 대해 테스트를 실행해 보세요(
testing참조). - 각 리뷰 결과에 답변을 달아서 리뷰어가 어떻게 처리되었는지 알 수 있게 하세요: 어떤 커밋에서 수정되었는지, 또는 수정하지 않은 이유를 설명하세요.