코드 변경 리뷰은(는) 무엇을 하나요?
강력한 시니어 엔지니어처럼 변경 사항을 리뷰하세요: 중요한 결함을 찾고, 각각을 증명하며, 작성자가 빠르게 조치할 수 있도록 보고하세요. 세 가지 실제 버그가 있는 짧은 리뷰가 서른 가지 '아마도'가 있는 긴 리뷰보다 낫습니다. 모든 거짓 긍정은 리뷰어가 내용을 대충 훑어보도록 만들기 때문입니다.
워크플로우
1. 변경 세트 확정하기
코드를 읽기 전에 리뷰 대상이 정확히 무엇인지 파악하세요. 사용자가 지정하지 않았다면, 기본적으로 베이스 브랜치에 아직 반영되지 않은 모든 것으로 설정하세요.
| 대상 | 가져오는 방법 |
|---|---|
| 커밋되지 않은 작업 | git diff HEAD (추적되지 않은 파일은 git status로 확인 후 읽기) |
| 스테이징된 것만 | git diff --cached |
| 현재 브랜치 | git diff $(git merge-base HEAD <base>) (여기서 <base>는 보통 main/master) |
| 커밋 범위 | git diff A..B |
| 풀 리퀘스트 (번호 또는 URL) | gh pr view <n-or-url> (설명, 베이스 및 헤드), gh pr diff <n-or-url> (diff), gh pr diff <n-or-url> --name-only (파일 목록) |
| 특정 파일 | 직접 읽고, 필요하다면 무엇에서 변경되었는지 물어보기 |
풀 리퀘스트. "PR 123 리뷰" 또는 "PR #123 리뷰"는 현재 저장소의 PR 123을 의미합니다. URL(https://github.com/<owner>/<repo>/pull/<n>)은 gh에 그대로 전달할 수 있으며, 다른 저장소의 경우라도 모든 디렉토리에서 작동합니다. GitLab 병합 요청의 경우 glab mr view / glab mr diff를 사용하세요. diff만으로는 충분한 컨텍스트(3단계)를 얻을 수 없으므로 PR 버전의 파일도 함께 읽어야 합니다.
-
현재 저장소의 PR인 경우, 브랜치를 전환하지 않고 베이스와 PR을 가져와서 전용 ref에 강제 업데이트합니다(리베이스된 PR이 이전 리뷰의 복사본을 대체하도록). PR의 베이스 저장소를 가리키는 리모트에서 가져옵니다(
git remote -v확인); 포크의 경우 보통upstream이며origin이 아닙니다:git fetch <remote> <base> +refs/pull/<n>/head:refs/review/pr-<n> git rev-parse refs/review/pr-<n> # 다음 값과 반드시 일치해야 함: gh pr view <n> --json headRefOid --jq .headRefOid가져오기가 실패하거나 커밋이
headRefOid와 일치하지 않으면, 잘못된 복사본이나 오래된 복사본을 리뷰하지 말고 중단하고 그 사실을 알리세요. 그런 다음git show refs/review/pr-<n>:<path>로 파일을 읽고$(git merge-base refs/review/pr-<n> <remote>/<base>)와 비교하세요. 사용자가 작업 트리가 변경되는 것을 괜찮아하는 경우에만gh pr checkout <n>을 사용하세요. -
다른 저장소의 경우,
gh api "repos/<owner>/<repo>/contents/<path>?ref=<head-sha>"(인용 필수,?는 zsh에서 glob 문자이므로)를 통해 PR 헤드의 파일을 읽거나, 리뷰에 많은 컨텍스트가 필요한 경우 임시 디렉토리에 클론하세요. -
이미 제기되었거나 답변되었거나 해결된 피드백을 반복하지 않도록 기존 피드백을 읽으세요.
gh pr view <n> --comments는 최상위 수준의 댓글만 표시합니다. 인라인 리뷰 스레드, 답글 및 각 스레드의 해결 여부는 GraphQL에서 가져옵니다:gh api graphql --paginate -F owner=<owner> -F repo=<repo> -F n=<n> -f query='query($owner:String!,$repo:String!,$n:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){totalCount nodes{author{login} body}}}}}}}'--paginate는 처음 100개 이후의 스레드를 따라갑니다.comments.totalCount가 100개를 초과하는 스레드에는 더 많은 답글이 있습니다. 이에 의존하기 전에node(id:<thread id>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}}로 가져오세요.
또한 의도를 파악하세요: PR 설명, 커밋 메시지, 연결된 이슈 또는 없는 경우 한 줄로 사용자에게 물어보세요. 코드가 무엇을 하려는 것인지 모르면 코드가 올바른지 판단할 수 없습니다.
매우 큰 변경 사항(약 1,500줄 이상 변경된 경우)의 경우 먼저 분류하세요. 위험도(인증, 결제, 데이터 마이그레이션, 동시성, 공개 API 및 삭제된 항목이 문서, 생성된 코드 및 잠금 파일보다 우선)별로 파일 순위를 매기고 어떤 파일이 더 가볍게 처리되었는지 말하세요.
2. 변경 사항이 다루는 언어에 대한 가이드 로드하기
변경 세트에 있는 언어 및 파일 유형에 대한 참조 파일만 로드하고, 절대 모두 로드하지 마세요. 각 파일은 리뷰 중인 코드를 밀어내는 컨텍스트를 추가합니다.
Python을 사용할 수 있는 경우(python 또는 python3) 감지기를 실행하세요:
python <skill-dir>/scripts/detect_languages.py --git <base> # 브랜치 vs 베이스
python <skill-dir>/scripts/detect_languages.py --git HEAD # 커밋되지 않은 작업
python <skill-dir>/scripts/detect_languages.py --git <remote>/<base> --head refs/review/pr-<n> # 가져온 PR
git diff --name-only ... | python <skill-dir>/scripts/detect_languages.py # 모든 파일 목록
풀 리퀘스트의 경우 1단계에서 가져온 ref와 함께 --head를 사용하세요. 그러면 감지기가 PR의 커밋에서 shebang을 읽습니다(작업 트리에는 PR의 새로운 스크립트가 없거나 다른 버전이 있을 수 있으므로). 다른 저장소의 PR인 경우 gh pr diff <url> --name-only | python <skill-dir>/scripts/detect_languages.py는 파일 목록을 제공하지만 파일 내용은 볼 수 없습니다. 목록에서 모든 확장자 없는 파일의 첫 줄을 확인하세요(매핑되었든 아니든; migrations/ 아래의 Python 스크립트는 이미 sql.md에 매핑되었지만 python.md도 필요합니다): PR 헤드에서 읽거나, PR이 삭제하는 경우 베이스에서 읽고 아래 shebang 표를 사용하여 라우팅하세요.
참조 파일과 각 파일을 트리거한 변경된 파일을 출력합니다. Python이 없으면 감지기와 정확히 일치하는 이 표를 사용하세요. 파일 이름은 대소문자를 구분하지 않고 일치합니다.
| 변경된 파일 | 읽을 파일 |
|---|---|
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lock | references/languages/python.md |
.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .vue, .svelte, .astro, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, tsconfig.json | references/languages/javascript-typescript.md |
.go, go.mod, go.sum, go.work | references/languages/go.md |
.rs, Cargo.toml, Cargo.lock | references/languages/rust.md |
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.properties | references/languages/java-kotlin.md |
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.json | references/languages/csharp-dotnet.md |
.c, .h, .cc, .cpp, .cxx, .c++, .hpp, .hh, .hxx, .inl, .ipp, .m, .mm, CMakeLists.txt, Makefile, meson.build, conanfile.txt, vcpkg.json | references/languages/c-cpp.md |
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.ru | references/languages/ruby.md |
.php, .phtml, composer.json, composer.lock | references/languages/php.md |
.swift, .pbxproj, Package.swift, Package.resolved, Podfile | references/languages/swift.md |
.sql, .psql, .pgsql, .ddl, 및 migration/, migrations/, migrate/, alembic/versions/, flyway/, liquibase/ 아래의 모든 파일 | references/languages/sql.md |
.sh, .bash, .zsh, .ksh, .fish, .ps1, .psm1, .psd1, .bat, .cmd | references/languages/shell.md |
.tf, .tfvars, .hcl, .dockerfile, Dockerfile, Dockerfile*, Containerfile, .dockerignore, compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml, Chart.yaml, values.yaml, kustomization.yaml, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile, .circleci/ 아래의 모든 파일, 및 .github/workflows/, .github/actions/, k8s/, kubernetes/, helm/, charts/, manifests/, deploy/, deployment/, kustomize/, argocd/ 아래의 YAML | references/languages/infrastructure.md |
확장자가 없는 파일은 shebang 줄(#!/usr/bin/env deno, #!/usr/bin/python3)의 인터프리터를 통해 라우팅됩니다. 버전 접미사는 무시됩니다.
| Shebang 인터프리터 | 읽을 파일 |
|---|---|
python | references/languages/python.md |
node, deno, bun, ts-node, tsx | references/languages/javascript-typescript.md |
ruby | references/languages/ruby.md |
php | references/languages/php.md |
sh, bash, zsh, ksh, dash, fish, pwsh | references/languages/shell.md |
하나의 파일이 두 개의 참조를 필요로 할 수 있습니다. Rails 또는 Alembic 마이그레이션은 해당 언어 파일과 sql.md가 필요하며, 감지기는 둘 다 보고합니다. 참조 파일이 없는 언어도 전체 리뷰를 받습니다. 아래 일반적인 각도가 이를 다루며, 해당 언어의 일반적인 함정에 대해 아는 바를 적용해야 합니다. 내장 언어도 포함됩니다: Python의 SQL 문자열 또는 Go에서 작성된 셸 명령은 sql.md 또는 shell.md를 로드하는 이유가 됩니다.
3. Diff 이상의 컨텍스트 구축하기
Diff는 무엇이 변경되었는지 보여주지만, 무엇에 영향을 미치는지는 보여주지 않습니다. 판단하기 전에:
- 각 헝크의 주변 코드를 읽으세요. 변경된 줄만이 아닙니다. 많은 버그는 새 줄이 기존 줄과 상호 작용하는 방식에 있습니다.
- 변경된 모든 함수, 타입, 스키마, 설정 키 또는 엔드포인트의 호출자와 의존성을 찾으세요(grep, LSP 참조 찾기). 블래스트 반경은 diff에서는 보이지 않습니다.
- 프로젝트의 관례를 파악하세요: 린터 및 포매터 설정,
CLAUDE.md/CONTRIBUTING.md, 그리고 주변 코드가 오류, 로깅 및 테스트를 처리하는 방식. 일반적인 취향이 아닌 이 코드베이스와의 일관성을 기준으로 판단하세요. - 새 유틸리티 코드를 수락하기 전에 기존 도우미를 검색하세요. 저장소에 이미 있는 것을 재구현하는 것은 diff 외부를 살펴볼 때만 드러납니다.
4. 각도별로 리뷰 (우선순위 순서)
이 목록의 위에서 아래로 작업하세요. 티어 1의 버그는 티어 3 노트의 어떤 개수보다 중요합니다. references/review-angles.md에는 각 각도에 대한 전체 체크리스트가 있습니다. 중요하지 않은 리뷰의 경우 읽으세요.
- 올바른가요? 정확성 및 엣지 케이스, 의도 충실도(주장하는 바를 완전히 수행하는가?), 오류 처리 및 실패 모드, 동시성 및 공유 상태, 호출자에 대한 블래스트 반경.
- 출시해도 안전한가요? 보안, API/스키마/와이어 호환성, 데이터 무결성 및 마이그레이션, 운영성(롤아웃, 롤백, 관찰 가능성), 새 종속성, 개인정보 보호.
- 좋은 코드인가요? 성능 및 효율성, 수준(수정이 올바른 계층에 있는가?), 중복 및 재사용, 단순성 대 과도한 엔지니어링, 관례와의 일관성, 가독성.
- 검증되었나요? 변경 없이는 실제로 실패할 테스트, 문서 및 주석이 동기화되었는지 확인.
로드된 언어 파일의 검사를 이러한 각도 내에서 적용하세요. 이는 해당 언어에서 이러한 문제가 취하는 특정 형태입니다.
5. 보고하기 전에 모든 발견 사항 검증하기
각 발견 사항 후보에 대해:
- 실패 시나리오를 작성하세요: 구체적인 입력 또는 상태, 그리고 잘못된 결과. 작성할 수 없다면 아마 버그가 아닙니다.
- 코드를 다시 읽어 문제가 이미 처리되지 않았는지 확인하세요: 업스트림 가드, 유효성 검사기, 이를 배제하는 타입, 이를 다루는 테스트.
- 실행해 보세요 (비용이 저렴하고 안전한 경우: 단위 테스트, REPL 스니펫, 타입 검사기 또는 린터) 발견 사항이 불확실할 때.
- 신뢰도 등급: 확인됨(추적 또는 재현됨) 또는 가능성 있음(완전히 증명할 수 없었지만 그럴듯한 경로). 이보다 약한 것은 삭제하세요. 명확하지 않지만 제기해도 해가 되지 않는 것은 버그라고 단정하기보다 질문으로 제기하세요.
6. 보고
심각도 태그, 댓글 형식 및 출력 템플릿에 대해 references/reporting.md를 사용하세요. 요약:
- 한 줄 평결로 시작하세요: 병합해도 안전한지 여부와 가장 큰 문제(있는 경우).
- 모든 발견 사항은 심각도 태그
[CRITICAL],[MAJOR],[MINOR]또는[NIT]로 시작하며, 그 다음 한 줄 주장과file:line을 포함합니다. 본문은 이 순서대로 설명합니다: 문제가 무엇인지, 왜 문제인지(구체적인 실패 시나리오), 그리고 제안할 수 있는 수정 또는 개선 사항. - 가장 심각한 순서대로 발견 사항을 나열하세요. 기본 상한선은 약 10개입니다. 생략한 낮은 심각도 항목의 수를 언급하고, 사용자가 요청하면 나열하세요.
- 실제 결함이 없거나 사용자가 철저한 검토를 요청하지 않는 한
[NIT]는 제외하세요. - 다루지 않은 내용(스킴한 파일, 실행할 수 없었던 것)으로 끝내세요. 정직한 범위 노트는 리뷰의 일부입니다.
풀 리퀘스트에 게시된 댓글에도 동일한 태그 우선 형식을 사용하여, 발견 사항이 보고서와 PR에서 동일하게 읽히도록 하세요. 사용자가 요청할 때만 PR에 게시하세요. references/reporting.md는 이를 하나의 리뷰로 인라인 댓글과 함께 게시하는 방법을 보여줍니다.
호스트가 구조화된 발견 사항 도구를 제공하는 경우, 목록을 출력하는 대신 동일한 순서로 해당 도구를 통해 보고하고, 각 발견 사항의 요약을 태그로 시작하세요.
원칙
- 증거가 의견보다 우선합니다. 모든 발견 사항은 코드를 인용합니다. 이유 없이 "X를 고려하세요"는 노이즈입니다.
- 코드베이스가 아닌 변경 사항을 리뷰하세요. 변경 사항이 문제를 악화시키거나 이에 의존하는 경우에만 기존 문제에 플래그를 지정하고, 기존 문제로 레이블을 지정하세요.
- 작성자의 선택을 존중하세요. 다르지만 동등하게 유효한 접근 방식은 발견 사항이 아닙니다. 구체적인 비용을 명명할 수 있을 때만 동의하지 마세요.
- 요청하지 않으면 리뷰 중에 수정하지 마세요. 수정을 제안하고, 사용자가 적용 여부를 결정하도록 하세요.