브랜치 리뷰 트래커은(는) 무엇을 하나요?

여러 라운드에 걸쳐 수정되는 브랜치에 대한 리뷰입니다. 각 라운드는 브랜치를 재검토하고 하나의 페이지를 업데이트합니다: 각각 상태와 증거, 책임 커밋, 확인할 위치를 제공하는 Details 팝업이 있는 번호가 매겨진 이슈 목록입니다.

이 페이지는 claude.ai Artifact이며, 리뷰의 기록입니다. 뷰어에게는 읽기 전용입니다: 리뷰와 수정이 진행됨에 따라 Claude만 상태를 변경합니다. 새 세션은 대화나 로컬 파일이 아닌 페이지의 작은 context.json에서 재개됩니다.

트래커는 세 개의 파일을 보관합니다:

index.html: 페이지, assets/tracker.html의 복사본
issues.json: 모든 이슈 및 세션 로그
context.json: 재개 노트와 다음 세션을 위한 이슈 인덱스, 이를 시작하는 프롬프트, 그리고 페이지가 보여주는 유일한 부분인 사용자에게 대기 중인 짧은 목록

1. 검토할 항목 질문

먼저 후보를 수집한 다음, 하나의 AskUserQuestion 호출로 모든 것을 질문합니다. 예를 들어 PR 번호나 URL과 같이 호출과 함께 제공된 답변이 있는 질문은 건너뜁니다.

git for-each-ref --sort=-committerdate --count=6 --format='%(refname:short)' refs/heads
git symbolic-ref --short refs/remotes/origin/HEAD      # 기본 기준 브랜치
git log --format=%s <base>..<target> | grep -oE '[A-Z]+-[0-9]+' | sort -u
gh pr list --head <target> --json number,url,title     # 또는: glab mr list --source-branch <target>

질문	옵션
대상 브랜치	PR이 주어진 경우 PR의 헤드 브랜치; 그렇지 않으면 기준 브랜치를 제외한 가장 최근에 업데이트된 세 개의 로컬 브랜치
기준 브랜치	원격의 기본 브랜치 (권장), 그 외 장기 브랜치 (있는 경우)
티켓	브랜치 이름과 커밋 제목에서 찾은 ID; `티켓 없음`

사용자는 항상 다른 값을 입력할 수 있습니다. 티켓 질문은 브랜치가 확인된 후에 하거나, 가장 가능성 있는 대상에서 옵션을 파생합니다.

2. 환경 확인

사전 점검 스크립트를 실행하고 그 결과 테이블을 사용자에게 보여줍니다:

<this skill>/scripts/preflight --target <branch> [--base <base>] [--ticket <id>]

저장소, 두 ref, 사용자의 체크아웃, 로컬 브랜치가 PR 헤드와 일치하는지, 호스트의 PR, git worktree를 차단할 수 있는 체크아웃 필터, 그리고 리뷰에 사용되는 CLI를 확인합니다. 종료 코드 2는 차단기(blocker)를 의미하고, 1은 경고만을 의미합니다. 프로젝트의 빌드 도구는 확인하지 않습니다: 이러한 도구는 프로젝트의 헬퍼 스킬에 속합니다.

스크립트는 두 브랜치를 모두 가져옵니다(fetch). 기준 브랜치는 최신 상태인 origin에서 가져오고, 대상 브랜치는 작성자가 푸시했을 수 있는 클론에서 가져옵니다. 스크립트가 출력하는 refs를 기준으로 리뷰합니다. 로컬 브랜치가 PR 헤드와 다르다고 경고하면, PR 헤드를 리뷰합니다: 체크아웃 대신 git show <sha>:<path>로 읽습니다.

그런 다음 스크립트가 볼 수 없는 이 세션의 도구를 확인하고 테이블에 추가합니다:

필요 항목	도구	없을 경우
리뷰	`code-review` 스킬 또는 `Agent` 도구	차단기(blocker)
페이지	`Artifact` 도구	파일을 스크래치패드에 보관하고 각 라운드 후 사용자에게 경로를 알려줌; 그렇게 명시
티켓 컨텍스트 및 티켓 게시	Atlassian 도구 (`getJiraIssue`, `createJiraIssue`)	해당 기능 없이 리뷰 진행; 그렇게 명시
PR 댓글 및 검사	`gh` 또는 `glab`, 인증됨	브랜치만 리뷰; 그렇게 명시

그런 다음 아래 "헬퍼 스킬"에서 설명하는 대로 프로젝트의 헬퍼 스킬을 찾고, 테이블에 헬퍼당 한 행씩 추가합니다: 찾음 (이름 포함) 또는 누락 (리뷰에서 부족할 내용 포함).

차단기(blocker)에서 멈추고 무엇이 누락되었는지 알립니다. 경고의 경우, 리뷰가 다루지 않을 내용을 알리고 계속 진행합니다.

티켓을 읽을 수 있으면 요약과 상태를 가져옵니다. ID 뒤에 괄호 안에 상태를 기록합니다: PROJ-123 (진행 중).

3. 첫 번째 라운드

리뷰. <base>에 대한 <target>에 대해, 또는 PR 번호에 대해 code-review를 호출합니다. 리뷰어에게 다른 커밋은 git show <rev>:<path>로 읽고, 사용자 디렉토리에서 절대 체크아웃하지 말라고 지시합니다.
문서(prose) 리뷰는 아래 "문서 리뷰"에서 설명한 대로 수행합니다. code-review는 코드의 결함을 찾으며 문서는 다루지 않습니다.
모든 발견 사항 검증은 아래 "발견 사항 검증"에서 설명한 대로 수행합니다. 이 단계를 거친 후에만 이슈가 페이지에 등록됩니다. 이 단계를 통과하지 못한 발견 사항은 목록에 올리기 전에 삭제되거나, 목록에 오른 후에는 이유와 함께 dismissed로 설정됩니다.
모든 이슈 분류.
- 책임 커밋: git log -S'<symbol>' <base>..<target>, 또는 git blame -s <target> -- <path>
- 기준 브랜치에도 동일한 이슈가 있는지: git show <base>:<path>. 기준 브랜치에 이미 있는 이슈는 "commitRole": "Pre-existing on" 및 "commit": "<base>"를 갖습니다. 이는 브랜치의 회귀(regression)는 아니지만, 브랜치가 이슈를 악화시키는 경우(예: 더 많은 데이터를 노출) 병합을 차단할 수 있습니다.
- 검토된 커밋의 모든 위치에 대한 file:line
트래커 작성 세션 스크래치패드에 브랜치 이름을 딴 폴더(/는 -로 대체)에 작성:
- index.html: assets/tracker.html의 복사본으로, __TITLE__은 페이지 이름으로 대체됩니다. 이름은 브랜치 주제를 2~4단어로 요약하고 "리뷰"를 붙인 것입니다. 예: API 키 인증 리뷰
- issues.json 및 context.json은 아래 "데이터 파일"에서 설명한 대로
두 파일 검증. 검증기는 스키마, 모든 위치가 검토된 커밋에 존재하는지, context.json의 인덱스가 이슈와 일치하는지 확인합니다:
```
python3 -I <this skill>/scripts/validate-issues.py <dir>/issues.json --repo <repo>
```
게시 Artifact 도구의 게시 액션을 사용하여, file_path를 <dir>/index.html로, files를 {"issues.json": "<dir>/issues.json", "context.json": "<dir>/context.json"}로, icon: "checklist"와 한 문장의 description으로 설정합니다. 반환된 URL을 두 파일("artifact")에 기록하고, 다시 게시한 후 링크를 사용자에게 제공합니다.

4. 이후 라운드

사용자가 브랜치가 업데이트되었다고 말하거나 재검토를 요청하면 라운드를 실행합니다.

브랜치가 이동했는지 확인. PR 헤드 또는 대상 ref를 reviewed와 비교하고 git reflog -3 --date=iso <target>을 확인합니다. 푸시가 지연될 수 있으며 사용자의 로컬 브랜치가 PR보다 뒤쳐질 수 있습니다. 아무것도 이동하지 않았다면 그렇게 말하고 중단합니다.
기준 브랜치 가져오기 (git fetch origin <base>). 기준 브랜치가 이동했다면 기록하고, git range-diff <old-base>..<old-tip> <new-base>..<new-tip>으로 브랜치를 비교합니다.
변경 사항 확인:
- git range-diff <base>..<reviewed> <base>..<target>: 다시 작성, 추가 또는 삭제된 커밋 표시
- git diff <reviewed> <target>: 순 변경 사항(net change) 표시
- PR의 새로운 댓글, 리뷰 및 검사 (gh pr view <n> --json comments,reviews, gh api repos/<owner>/<repo>/pulls/<n>/comments, gh pr checks <n>)
모든 수정 사항 평가. 변경 사항이 해결하는 각 이슈에 대해 수정 사항을 읽고 fix에 수행된 작업과 코드의 현재 동작 방식을 기록합니다. 읽기를 통해 확인된 경우에만 fixed로 설정하고, verified에 어느 정도까지 검증되었는지 명시합니다.
수정으로 인한 문제 찾기. 수정은 종종 문제를 제거하기보다 이동시킵니다. 이전 코드가 우연히 처리했던 입력을 확인합니다:
- 누락, 빈 값 또는 null 값(예: 클라이언트가 설정하지 않은 속성으로, 이전에는 무해한 리터럴을 생성했으나 지금은 "제한 없음"을 의미)
- 값이 대체되는 기본값
- 변경 사항이 도달하지만 건드리지 않는 코드 경로(예: 호출자, 다른 엔드포인트, 이전 클라이언트 및 내보내기의 가져오기 측)
- 변경 사항이 대상으로 하지 않은 요청에 대해 변경하는 동작 각 문제를 새 이슈로 추가하고, 원인 수정을 두 이슈 모두에 기록합니다. 순 변경 사항에 대해 "문서 리뷰"를 실행합니다.
수정되지 않은 모든 이슈를 새 코드에 대해 재평가하고, 코드가 변경된 수정된 이슈를 다시 살펴봅니다.
테스트 실행은 아래 "테스트로 재현"에서 허용하는 경우에만 수행합니다.
트래커 업데이트는 아래 "트래커 최신 상태 유지"에서 설명한 대로 수행합니다:
- reviewed를 새 팁으로 설정합니다.
- commits를 새 해시로 다시 작성합니다. 다시 작성된 커밋은 새 해시를 얻고, 삭제된 커밋은 맵을 떠나며, 새 커밋이 추가됩니다.
- 변경된 이슈의 status, commit, commitRole, note, fix 및 detail을 변경합니다.
- git grep -n을 사용하여 새 팁에서 각 위치의 라인을 다시 찾습니다. 산술로 라인을 이동하지 마십시오.
- 다음 사용 가능한 번호로 새 이슈를 추가합니다. 절대 번호를 다시 매기지 마십시오.
검증 후 동일한 URL에 다시 게시합니다.
사용자에게 보고: 이 라운드에서 수정된 사항, 아직 열려 있는 사항, 새로운 사항을 파일:라인 및 실행된 내용과 함께 알립니다. 페이지 링크로 끝냅니다.

발견 사항 검증

이슈가 페이지에 등록되기 전에 검토된 커밋에서 직접 코드를 읽습니다.

시나리오를 처음부터 끝까지 추적합니다. 입력이 들어오는 지점부터 손상이 발생하는 지점까지 따라가며 각 단계를 file:line으로 명명합니다. 코드가 수행하지 않는 단계가 필요한 발견 사항은 해당 단계를 이유로 기각됩니다.
전제 조건을 확인합니다. 트리거 상태가 어떻게 발생할 수 있는지 질문합니다:
- 누가 입력을 생성할 수 있는지(예: 어떤 API를 통해), 그리고 검증자 또는 기본값이 이를 막는지
- 무제한 수명 또는 지정되지 않은 경우 할당되는 역할과 같은 구성된 기본값이 시나리오에 도달할 수 없게 만들거나 정상 케이스로 만드는지
- 기존 데이터에 이슈가 포함될 수 있는지. 저장소 외부의 데이터만 답변할 수 있는 경우 프로젝트의 데이터 확인 헬퍼를 사용하십시오. 헬퍼가 없으면 사용자에게 확인 방법을 물어보고 답변을 verified와 로그에 기록합니다.
"의도된"과 "허용 가능한"을 구분합니다. 런북, 테스트 또는 코드 주석이 특정 동작이 의도적임을 보여준다고 해서 그것이 해롭지 않다는 것을 의미하지는 않습니다. 이전 버전과의 호환성을 별도로 확인하십시오: 기존 클라이언트 및 배포된 버전, 기존 데이터, 새 기능을 사용해 본 적이 없는 공급업체나 사용자. 기존 워크플로우의 의도적인 중단은 이슈이며, 사용자가 이를 수락하지 않는 한 차단기(blocker)입니다.
검증 방법을 명시합니다. verified에 기록합니다: "컨트롤러 수준 테스트로 재현; 서비스 레이어는 스텁(stub) 처리됨", "코드 읽기 기반; 실행되지 않음", "데이터 확인: 일치하는 레코드 없음". 증거가 입증하는 것을 보고하고 입증하지 못하는 것을 명명합니다. 데이터가 보여주지 않는 인과 관계 또는 비교 판정을 주장하지 마십시오.
기록과 함께 기각합니다. 기각은 status: "dismissed"와 dismissal(결정자, 시기, 이유 포함)을 설정합니다. Claude가 기각할 때는 그렇게 명시하고 누구도 서명하지 않았음을 알립니다. 페이지에 표시됩니다.
이의 제기 시 재검토합니다. 사용자가 기각 또는 판정에 이의를 제기하면, 방어하는 대신 코드에서 다시 확인합니다. 잘못된 경우 이슈를 다시 열고, 기각을 제거하며, 이전 판정이 무엇을 잘못했는지 note에 명확히 기록합니다.

테스트로 재현

빌드 및 테스트는 사용자가 요청하거나 저장소 및 사용자의 지시가 별도의 요청 없이 허용할 때만 실행합니다. 프로젝트를 빌드하고 테스트하는 방법(도구 체인 및 설정 포함)은 이 스킬이 아닌 프로젝트의 빌드-및-테스트 헬퍼와 해당 지침에서 제공됩니다.

절대 사용자의 체크아웃을 사용하지 마십시오. 테스트할 커밋을 별도 디렉토리에 넣습니다:
- git worktree add --detach <scratchpad>/<name>-wt <sha>;
- 워크트리를 차단하는 항목이 있으면 해당 커밋을 내보내고(export) 차단 경로를 제외합니다: git archive <sha> -- . ':(exclude)<blocked-path>' | tar -x -C <dir>. 예를 들어 git-crypt 스머지 필터는 키를 사용할 수 없을 때 암호화된 경로에서 실패합니다. 사전 점검 스크립트는 체크아웃 필터가 있는 경로를 명명합니다.
프로젝트가 명시한 방식으로 빌드하고 실행합니다. 프로젝트가 지원하지 않는 도구 체인과 같은 도구 실패는 테스트 결과가 아닙니다: 프로젝트 헬퍼 또는 지침에 따라 환경을 수정한 후 다시 실행합니다. 헬퍼가 없으면 추측하는 대신 사용자에게 물어보고 프로젝트 노트를 위해 배운 내용을 기록합니다.
올바른 동작을 단언(assert)하도록 테스트를 작성합니다. 실패는 이슈를 재현하며, 동일한 테스트가 수정 사항에 대한 회귀 테스트가 됩니다. 실제 클래스를 경로를 따라 구동하고 시나리오에 필요한 것만 스텁(stub) 처리합니다. 각 스텁이 실제 코드가 하는 일을 반영하도록 하고, 스텁 처리되거나 실행되지 않은 모든 레이어를 verified에 명명합니다(예: HTTP, 보안 체인, 데이터베이스).
가장 좁은 범위를 실행합니다: 새 테스트와 변경된 코드를 포함하는 테스트만 실행합니다.
테스트 소스를 트래커에 보관합니다. 스크래치패드는 세션 간에 지워질 수 있습니다. contentType: "text/plain"으로 files에 테스트를 tests/<Name>.<ext>로 게시하고 이슈에 이름을 명시합니다.
정리합니다. 워크트리 또는 내보내기, 그리고 사용자의 체크아웃에 남은 빌드 출력(예: 컴파일된 테스트 클래스, 이후 빌드에서 선택될 수 있음)을 제거합니다. 그런 다음 git status 및 git worktree list가 사용자의 체크아웃이 변경되지 않았음을 보여주는지 확인합니다.

헬퍼 스킬

리뷰 흐름은 모든 프로젝트에 대해 동일합니다. 프로젝트별 지식은 자체 스킬에 있습니다. 존재할 때 사용하십시오; 이 스킬은 절대 프로젝트 도구를 하드코딩하지 않습니다.

설명을 통해 이 세션에서 사용 가능한 스킬 목록에서 찾으십시오. 이름을 추측하지 마십시오. 단계에서 필요할 때 Skill 도구로 하나를 로드합니다.

헬퍼	용도	없을 경우
리뷰 체크리스트	프로젝트의 위험 영역: 보안 모델, 호환성 약속, API 계약, 마이그레이션	리뷰는 일반 지식에 의존; 누락될 수 있는 영역을 명시
빌드 및 테스트	하나의 커밋을 격리하여 빌드하고 테스트: 명령어, 도구 체인, 설정, 알려진 차단기	테스트는 사용자에게 방법을 묻는 후에만 실행; 발견 사항은 "코드 읽기 기반"으로 남음
데이터 확인	저장소 외부 데이터의 질문에 안전하게 답변	사용자에게 확인 방법을 물어봄
문서 규칙	주석, 독스트링, 변경 로그, 커밋 메시지 및 PR 텍스트(예: 일반적인 오타, 스타일, 관례)	문서 검토는 일반적인 규칙에 의존

문서 리뷰

code-review가 코드 결함에 집중하는 동안, 이 리뷰는 문서(prose)도 다룹니다: 개발자 주석 문서, 사용자에게 표시되는 메시지, 커밋 메시지, PR 설명 및 변경 로그. 다음을 확인하십시오:

오해의 소지가 있거나 정확하지 않은 진술
코드와 충돌하거나 코드와 관련이 없는 주석
불완전하거나 누락된 설명
일반 또는 도메인별 용어 사용의 불일치

문서 검토는 각 이슈에 대해 별도로 실행됩니다. code-review에서 생성된 발견 사항은 해당 발견 사항의 이슈 검증 중에 문서가 확인됩니다.

데이터 파일

issues.json

루트 객체:

키	유형	내용
`issues`	배열	이슈 객체의 배열
`meta`	객체	메타데이터
`log`	배열	감사 로그 항목의 배열

이슈 객체

키	필수	유형	내용
`id`	예	정수	페이지의 숫자
`title`	예	문자열	한 줄 요약
`status`	예	문자열	`"open"`, `"fixed"`, `"dismissed"` 중 하나
`dismissal`	아니오	객체	`by`, `when`, `why`
`category`	예	문자열	`"security"`, `"correctness"`, `"compatibility"`, `"maintainability"`, `"prose"`, `"performance"`, `"testing"` 등
`severity`	예	문자열	`"critical"`, `"major"`, `"minor"` 중 하나
`commit`	예	문자열	책임 커밋의 SHA (전체 40자)
`commitRole`	예	문자열	`"introduced"` (새로운 회귀), `"pre-existing"` (기준에도 있음), `"unknown"` 중 하나
`fix`	아니오	객체	수정 사항이 적용된 경우: `"commit"`, `"summary"`, `"verified"`
`verified`	예	문자열	이슈가 어떻게 확인되었는지 설명
`evidence`	예	배열	증거 스니펫 배열 (각각 `"file"`, `"line"`, `"code"`를 가짐)
`locations`	예	배열	위치 배열 (각각 `"file"`, `"line"`, `"context"`를 가짐)
`note`	아니오	문자열	인간 또는 AI의 자유 텍스트 관찰

메타 객체

키	유형	내용
`repository`	문자열	소유자/저장소
`base`	문자열	기준 브랜치 ref
`target`	문자열	대상 브랜치 ref
`reviewed`	문자열	검토된 커밋 SHA
`ticket`	문자열 또는 null	티켓 ID (있는 경우)
`artifact`	문자열 또는 null	Artifact 페이지 URL
`pr`	정수 또는 null	PR 번호 (있는 경우)

로그 항목

키	유형	내용
`at`	문자열	ISO 타임스탬프
`round`	정수	라운드 번호
`action`	문자열	`"created"`, `"updated"`, `"fixed"`, `"dismissed"`, `"reopened"` 등
`issueId`	정수	관련 이슈 ID
`detail`	문자열	수행된 작업에 대한 설명

context.json

키	유형	내용
`resume`	문자열	다음 세션이 재개할 때 읽을 짧은 마크다운
`issues`	객체	이슈 ID를 제목에 매핑
`pending`	배열	사용자 입력을 기다리는 항목 목록
`round`	정수	완료된 라운드 수
`prompt`	문자열	새 세션을 시작하기 위한 전체 프롬프트

트래커 최신 상태 유지

페이지를 업데이트할 때마다:

issues.json에서 이슈를 수정하고, log에 추가하며, meta를 업데이트합니다.
context.json에서 resume, pending, round를 업데이트합니다. issues 맵은 추가되거나 제거된 이슈를 반영합니다. prompt는 동일하게 유지되거나 새 세션에서 사용할 수 있도록 업데이트됩니다.
아래 "검증"에 설명된 대로 검증합니다.
동일한 artifact URL로 Artifact를 다시 게시합니다.

변경 사항을 게시하기 전에 항상 validate-issues.py를 실행하십시오. 검증이 실패하면 문제를 수정하고 다시 시도하십시오. 덮어쓰기 전에 issues.json 및 context.json의 기존 콘텐츠를 보존하십시오.

프로젝트 노트

각 검토 후, 나중 세션을 위해 프로젝트 노트에 배운 내용을 저장합니다:

프로젝트 특정 테스트 설정
일반적인 함정 또는 반복되는 이슈 패턴
유용한 데이터 확인 쿼리
검토 체크리스트에 대한 예외 또는 추가 사항

이러한 노트는 다음 검토 세션 중에 로드되어 지식과 효율성이 향상됩니다.

보안 고려 사항

사용자 체크아웃을 직접 수정하지 마십시오
절대 사용자 체크아웃에서 테스트를 실행하지 마십시오
작업 트리 또는 아카이브 내보내기를 사용하여 격리
모든 임시 파일 및 디렉토리 정리
검증되지 않은 입력을 코드 평가에 사용하지 마십시오
저장소 외부에서 가져온 민감한 데이터를 로그 또는 페이지에 기록하지 마십시오
증거 스니펫을 관련 코드로 제한하고, 자격 증명이나 시크릿을 노출하지 마십시오

브랜치 리뷰 트래커