증거 검토 (Evidence Review)
배송되는 코드에 대해 책임을 지는 시니어 엔지니어가 수행하는 리뷰를 수행합니다. 즉, 범위 내의 코드를 읽고, 도구를 실행하고, 의심되는 부분을 재현하고, 확인할 수 없었던 부분을 명확히 밝힙니다. 두 가지 표준이 기준을 정의합니다:
- 프로젝트 감사. 범위 내 코드 전체를 읽고, 빌드 및 테스트를 실행하고, 각 심각한 발견 사항을 임시 스크립트로 재현하고, 명확한 심각도 척도, 수정 사항이 적용됨에 따라 진화하는 상태, 그리고 "양호한 상태" 섹션을 포함합니다.
- 엄격한 관리자. 먼저 변경 사항이 이 레이어에 속하는지 묻고, 기존 헬퍼 또는 확장 지점을 파일과 라인으로 가리키고, 무언가를 안전하다고 부르기 전에 공유 상태의 모든 읽기 작업을 추적하고, 차단 vs. 비차단을 분리하며, 의존 관계가 생기기 전에 계약을 명확히 합니다.
깊이는 분량이 아닌 증거에서 나옵니다. 모든 발견 사항이 실제인 짧은 보고서가 철저해 보이려고 늘린 긴 보고서보다 낫습니다.
1. 범위 확인
주어진 인수: "$ARGUMENTS" (빈 따옴표는 인수가 없음을 의미). 만약 이것이 여전히 리터럴 플레이스홀더로 읽힌다면, 에이전트가 인수를 대체하지 않는 것입니다. 대신 사용자 요청에서 인수를 가져오십시오.
| 인수 | 범위 | 모드 | 출력 |
|---|---|---|---|
| 없음 | 전체 저장소, 현재 워킹 트리 상태 그대로 | 프로젝트 | 보고서 파일 |
| 경로 | 해당 경로 전체, 그리고 한 단계 깊이까지 호출하는 정의들 | 프로젝트 | 보고서 파일 |
diff | 스테이징 + 스테이징되지 않은 변경 사항: git diff HEAD | 변경 | 채팅 내 |
branch [base] | git diff <base>...HEAD (점 3개: 병합 기준점(merge-base)부터) | 변경 | 채팅 내 |
pr <n|url> | PR/MR 헤드를 대상 브랜치와 비교 | 변경 | 채팅 내 |
--update <file> | 기존 보고서 재검증; 프로젝트 모드만 가능, 경로 유무 관계 없음 | 업데이트 | 해당 파일 편집 |
- 브랜치의 기본 브랜치(base branch):
git symbolic-ref --short refs/remotes/origin/HEAD; 실패하면main, 그 다음master; 둘 다 없으면 공개 질문입니다(섹션 2). - 프로젝트 모드에서 더티 트리: 워킹 트리를 그대로 리뷰하고, 리비전으로
HEAD <sha> + uncommitted changes를 기록합니다. 수정된 파일은 고정 링크가 아닌path:line으로 표시됩니다. - 인수 없음 및 더티 트리: 공개 질문입니다(프로젝트 또는 diff?).
- 모노레포: 경로의 경우, 해당 패키지가 속한 명령어(가장 가까운
package.json/pyproject.toml/go.mod/Cargo.toml/*.csproj)를 실행하고, 저장소 루트에서 해당 패키지까지 룰 파일을 읽습니다.
변경 모드에서도 주변 코드를 리뷰합니다. 리뷰 단위는 변경된 헝크(hunk) 더하기 해당 헝크가 속한 전체 함수, 변경된 심볼의 모든 호출자, 변경 사항이 영향을 미치는 모든 상태의 모든 읽기 및 쓰기 작업, 이를 커버하는 테스트, 그리고 이를 설명하는 문서입니다. 고립된 diff를 읽는 것은 값비싼 버그가 승인되는 방식입니다.
PR 또는 MR 가져오기
절대 사용자의 워킹 트리 위에서 체크아웃하지 마십시오. 항상 스크래치 위치에 별도의 워크트리를 사용하십시오:
- GitHub:
git fetch origin pull/<n>/head:pr-<n>; GitLab:git fetch origin merge-requests/<n>/head:mr-<n>. 그런 다음git worktree add <scratch>/pr-<n> pr-<n>. - 메타데이터:
gh pr view <n> --json title,body,comments,reviews,baseRefName,headRefName또는glab mr view <n> --comments. 두 CLI 모두 사용할 수 없거나 로그인되지 않은 경우, diff만 리뷰하고 헤더에 토론 기록을 읽지 않았음을 명시하십시오. - 비교를 위한 베이스 실행(섹션 4)을 위해, 병합 기준점(merge-base)에 두 번째 워크트리를 추가하십시오. 헤드 워크트리를 앞뒤로 전환하지 마십시오.
- 마지막에 워크트리를 제거하십시오(
git worktree remove).
2. 컨텍스트 및 한 번의 질문 라운드
수집하여 보고서 헤더에 보관하십시오:
- 리비전(전체 SHA), 브랜치, 원격 URL. 원격이 없으면 이 항목의 나머지를 건너뛰고
path:line을 사용하십시오. 그렇지 않으면 먼저git fetch --quiet를 실행한 다음git branch -r --contains <sha>; 페치가 실패하면 SHA를 푸시되지 않은 것으로 처리하십시오. 링크는 SHA가 푸시되었고 호스트가 GitHub 또는 GitLab인 경우에만 SHA에 고정됩니다(SSH 원격을 https로 변환):- GitHub
https://github.com/<o>/<r>/blob/<sha>/<path>#L<a>-L<b> - GitLab
https://<host>/<group>/<repo>/-/blob/<sha>/<path>#L<a>-<b> - 그 외:
path:line.
- GitHub
- 프로젝트 룰:
CLAUDE.md,AGENTS.md,CONTRIBUTING.md, 린트/타입 설정, PR 템플릿, 상위 디렉토리의 룰 파일. 발견 사항은 먼저 프로젝트 자체 룰에 대해, 그 다음 일반적인 취향에 대해 판단됩니다. - 시스템의 목적: README, 문서, 배포 매니페스트, CI 설정, 진입점.
- PR의 경우: 설명, 연결된 이슈, 기존 리뷰 코멘트 및 해결 상태, 대상 브랜치. 이전 라운드의 리뷰를 읽어 이미 해결된 사항을 다시 제기하지 말고, 요청된 변경 사항이 실제로 적용되었는지 확인하십시오.
- 의도. 코드나 변경 사항이 해결하는 문제를 한 문장으로 명시하십시오. 할 수 없으면 공개 질문입니다. 답변에 따라 연결 방식이 달라질 수 있기 때문입니다.
보고서 언어, 첫 번째 일치 항목이 승리합니다: 사용자의 명시적 요청; 프로젝트의 룰 파일; 상위 디렉토리의 룰; 대상(업스트림 오픈 소스 PR은 영어); 프로젝트 기존 문서의 언어. 아무것도 적용되지 않으면 공개 질문입니다.
공개 질문. 섹션 1과 2의 모든 공개 질문(범위, 기본 브랜치, 대상, 요청자가 다루길 원하는 우려 사항, 언어, 의도)을 모아서 한 번에, 하나의 메시지로 질문하십시오. 스스로 찾을 수 있는 것은 질문하지 마십시오. 아무도 답변할 수 없는 경우(비대화형 실행, 또는 사용자가 질문하지 말라고 한 경우), 다음 기본값을 사용하고 각각을 보고서 헤더의 "가정(Assumptions)" 아래에 나열하십시오: 인수 없음은 프로젝트 모드; 대상은 유지 관리자; 언어는 영어; 명명된 우려 사항 없음; 의도는 PR 설명 또는 README에 명시된 대로.
요청자가 명명한 우려 사항은 심각도와 관계없이 보고서 상단에 자체 섹션을 갖습니다.
3. 예산 및 분류
무엇이 "범위 내"인지 라인별로 읽기 전에 결정하십시오.
- 라인별 읽기에서 제외: 잠금 파일,
vendor/,node_modules/,dist//build/, 생성된 코드, 축소된 파일, 바이너리, 스냅샷, 대형 픽스처, API 컬렉션. 관련된 사항(고정된 취약한 버전, 비밀, 엔드포인트 목록)을 찾기 위해 grep하거나 훑어보십시오. - 남은 것을 계산하고, 비테스트 소스 파일만 계산합니다. 대략 40개 파일 또는 8,000라인을 초과하면 코드를 영역으로 나누고 영역당 하나씩 읽기 전용 하위 에이전트를 파견하여 file:line 및 추론과 함께 후보 발견 사항을 수집합니다. 이는 해당 크기에서 필수이며 선택 사항이 아닙니다: 하나의 컨텍스트로 모두 읽을 수 없으며, 조용히 훑어보는 것은 정직한 분할보다 나쁩니다. 모든 후보는 메인 스레드에서 검증됩니다(섹션 7). 에이전트에 하위 에이전트가 없는 경우, 패스당 하나의 영역을 리뷰하고, 패스 사이에 작성된 후보 목록을 유지하며, 범위(Scope)에서 작업이 어떻게 분할되었는지 명시하십시오.
- 테스트: 가장 위험한 경로를 커버하는 테스트와 발견 사항이 의존하는 모의 객체(mock)가 있는 모든 테스트를 전체적으로 읽고, 나머지는 설정과 커버리지를 위해 훑어보고, 범위(Scope)에서 이를 명시하십시오.
- 위험 순서로 정렬: 진입점 및 인증 먼저, 그 다음 데이터 저장소에 쓰는 모든 것, 그 다음 아웃바운드 호출, 그 다음 나머지.
- 커버리지를 정직하게 기록하십시오. 보고서의 범위(Scope)는 전체로 읽은 것, 훑어본 것, 건너뛴 것을 명시합니다. 수행하지 않은 전체 읽기를 주장하지 마십시오.
4. 기준 상태(Baseline Health)
실행 전 안전
- 사용자가 작성하지 않은 코드(포크 또는 알 수 없는 기여자의 PR, 방금 받은 저장소): 설치, 빌드 및 테스트는 포함된 설치 후크 및 테스트 설정을 포함하여 실행합니다. 실행하려는 명령어와 명령어가 실행하는 것을 나열하고 먼저 질문하십시오. 아무도 답변할 수 없으면 실행하지 마십시오: 정적으로 리뷰하고 헤더에 명시하십시오.
- 테스트가 가리키는 곳을 확인하십시오. 테스트 설정 및 환경 파일을 읽으십시오. 스위트가 localhost 이상(공유 데이터베이스, 스테이징 API, 실제 큐)에 도달한다면 실행하지 마십시오; 이유를 기록하십시오.
- 체크아웃을 깨끗하게 유지하십시오. 잠금 파일을 존중하는 명령어로 설치하십시오(
npm ci, 사용 가능한 해시가 있는pip install -r,uv sync --frozen). 빌드 및 커버리지 출력을 체크아웃 외부로 보내거나 gitignored인지 확인하십시오(테스트 러너는 종종 기본적으로 저장소에 커버리지를 기록합니다: 출력 디렉토리를 전달하십시오(예:jest --coverageDirectory <scratch>). 마지막에git status는 사용자가 만든 변경 사항이 없어야 합니다. - 프로덕션 또는 공유 환경에 대해 절대 실행하지 마십시오. 프로덕션 확인은 정확한 실행 명령어와 함께 권장 사항이 됩니다(예: 라이브 데이터베이스에 대한 쿼리 계획).
실행할 항목
package.json 스크립트 / pyproject.toml / Makefile / CI 설정에서 실제 명령어를 찾은 다음 각 명령어를 정확한 결과와 함께 실행하고 기록하십시오: 타입체크, 린트, 빌드, 파일별 커버리지가 있는 테스트, 그리고 생태계의 종속성 감사(npm audit, pip-audit, cargo audit, govulncheck, bundle audit, dotnet list package --vulnerable; osv-scanner를 대체로 사용). 감사는 네트워크와 잠금 파일이 필요합니다; 둘 중 하나라도 없으면 기록하십시오. 대부분의 감사 도구는 권고 사항을 찾으면 0이 아닌 값을 반환합니다: 이는 명령어 실패가 아니라 결과입니다.
- 테스트, 빌드, 린터가 없는 프로젝트: "설정된 것 없음"을 한 번 기록하십시오. 이는 파일당 하나가 아닌 하나의 발견 사항입니다.
- 오래된 종속성은 알려진 취약점이 있거나, 지원 종료(EOL)되었거나, 필요한 업그레이드를 차단하는 경우에만 보고됩니다.
- 설치할 수 없는 개인 종속성: 기록하고, 사용 가능한 코드(설치된 복사본, 벤더된 복사본)에 대해 리뷰하고, 어떤 라이브러리 동작이 검증되지 않았는지 명시하십시오.
변경 모드에서는 헤드에서 스위트를 실행하고, 실패하는 항목이 있으면 베이스에서도 실행(자체 워크트리에서)하여 모든 실패를 신규(new) 또는 **기존(pre-existing)**으로 레이블하십시오.
5. 시스템 매핑
라인별로 읽기 전에 스스로 기록하십시오:
- 진입점: HTTP 라우트, 프로토콜 핸들러(WebSocket, gRPC, 전화 등), CLI 명령어, 큐 소비자, 크론 작업, 마이그레이션, 시작.
- 신뢰 경계: 각 진입점에 도달할 수 있는 대상, 호출자가 인증되는 방식, 테넌트/사용자 ID가 제공되는 위치.
- 데이터 저장소, 인덱스, 각 컬렉션 또는 테이블을 읽고 쓰는 경로.
- 아웃바운드 호출: 타임아웃, TLS, 재시도, 모호한 실패의 의미.
- 중간에 실패할 수 있는 다중 단계 작업.
- 데이터의 실제 형태. README, API 문서, 픽스처, 시드 데이터, API 컬렉션에서 예제 값을 수집하십시오: 경로 형식, 날짜 형식, ID 형식, 대소문자. 모든 파서와 경로 헬퍼는 나중에 이 모든 값에 대해 실행됩니다.
변경 모드에서는 대신 폭발 반경을 매핑하십시오: 변경 사항이 영향을 미치는 모든 호출자와 모든 읽기 작업을 file:line과 함께 grep하십시오.
6. 심층 읽기 (Deep Read)
지금 reviewer-lens.md를 읽으십시오. 이는 질문 목록이지 할당량이 아닙니다: 대부분의 섹션은 대부분의 파일에 대해 말할 것이 없으며, 말할 것이 없는 섹션은 아무것도 얻지 못합니다. 구체적인 트리거 시나리오가 있는 후보만 보고하십시오.
범위 내의 모든 파일을 발췌가 아닌 전체적으로 읽으십시오. 코드가 의존하는 라이브러리 중 경계면(seam)에서 동작이 중요한 부분(피어 연결이 끊긴 후 클라이언트 라이브러리의 동작, 응답 전송 후 프레임워크가 오류를 처리하는 방식)도 포함하십시오. 많은 실제 버그가 그곳에 있습니다.
좋은 코드를 면제하지 마십시오. 잘 설계된 것으로 보이는 부분도 나머지와 동일한 기계적 검사를 받습니다: 핫 쿼리에 대한 쿼리 계획, 파서를 통한 실제 데이터 형태, 공유 상태의 읽기 작업. 조심스러워 보이는 코드는 아무도 찾지 않은 버그를 숨깁니다.
각 후보의 실행 목록을 유지하십시오: 위치, 무엇이 잘못되는지, 구체적인 시나리오(트리거하는 입력 및 상태), 그리고 어떻게 증명할 것인지.
또한 잘 수행된 사항 목록을 증거와 함께 유지하십시오. "작동 확인됨" 주장은 발견 사항과 동일한 엄격함이 필요합니다: 읽기 작업을 확인하고, 테스트를 실행하고, 라이브러리 코드를 읽었습니다.
7. 검증
High 또는 Critical이 될 수 있는 모든 후보와 비용이 저렴한 Medium에 대해:
- 스크래치 디렉토리에서 임시 스크립트로 재현하고, 저장소 내에서는 절대 하지 마십시오. 작은 규모의 실제 종속성(인메모리 또는 컨테이너화된 데이터베이스, HTTP 경계에서 스텁된 업스트림)을 리뷰 중인 코드의 모의 객체(mock)보다 선호하십시오.
- 성능 주장의 경우 측정하십시오: 쿼리 계획(
explain(),EXPLAIN ANALYZE), 전후 타이밍, 문제가 나타나는 데이터 크기에서. - "이것은 안전하다"는 공유 상태에 대한 주장의 경우 모든 읽기 및 쓰기 작업을 나열하십시오.
- 노력을 제한하십시오: 후보당 약 15분 또는 5번의 시도. 그 이후에는 레이블을 붙이고 이유와 함께 이동하십시오. 모든 Critical/High 후보에 레이블이 있으면 재현을 중단하십시오.
각 발견 사항의 증거에 레이블을 붙이십시오:
- yes: 실행 코드로 재현됨.
- partly: 주장의 일부가 재현됨; 섹션에서 어느 부분인지 명시.
- artifact: 파일, 매니페스트, 이미지 레이어 또는 커밋에 의해 표시됨(여기서 실행할 수 없는 경우: 누락된 배포 변수, 기록의 비밀).
- no: 시도했지만 재현할 수 없음; 그래도 보고된 이유를 말하거나, 또는 삭제.
- not tried: 추론만.
그런 다음 정직하십시오:
- 이 배포에서 실행 가능한 트리거가 없는 후보는 Low로 제출되지 않고 삭제됩니다.
- 추론은 추론으로 레이블이 유지됩니다("아마도", "여기서는 확인할 수 없었습니다").
- 모의 객체(mock)가 실제 코드가 절대 반환하지 않는 것을 반환하기 때문에 통과하는 테스트는 코드에 대한 증거가 아니라 테스트 자체에 대한 발견 사항입니다.
8. 분류
심각도는 이 배포에서의 영향 및 도달 가능성(reachability)으로 판단합니다. 도달 가능성이 확인할 수 없는 것(네트워크 ACL, 포트에 도달할 수 있는 대상)에 의존하는 경우, 도달 가능한 것처럼 심각도를 기록하고, 옆에 낮출 수 있는 조건을 명시하십시오.
- Critical: 지금 악용 가능하며 심각한 영향.
- High: 데이터 손실, 테넌트 간 또는 사용자 간 액세스, 또는 핵심 기능 손상.
- Medium: 특정 조건이 필요한 실제 버그 또는 위험.
- Low: 위생, 유지 관리성, 문서, 종속성 표류.
라이브러리의 경우 일반 소비자에게 미치는 영향으로 판단합니다. 단일 사용자 도구의 경우 데이터 손실은 여전히 High이며, 보안 발견 사항에는 현실적인 공격자가 필요합니다.
변경 모드에서는 각 발견 사항에 다음도 태그하십시오:
- 신규(new): 이 변경 사항으로 도입됨.
- 악화됨(worsened): 기존에 존재했지만 변경 사항이 더 악화시킴.
- 기존(existing): 변경 사항과 무관하게 존재하며 수정이 권장됨.
9. 보고
리뷰를 다음과 같이 구조화하십시오:
# 증거 검토: <짧은 제목>
## 헤더
- **리비전:** <sha> (<푸시됨/푸시되지 않음>)
- **브랜치:** <이름>
- **범위:** <프로젝트/변경/업데이트> <경로 또는 PR 번호>
- **대상:** <유지 관리자 / 요청자 / 공개>
- **모드:** <프로젝트 / 변경 / 업데이트>
- **의도:** <한 문장>
- **가정:** (질문이 답변되지 않은 경우에만)
- **확인:** <재현에 소요된 시간, 중단된 후보 수>
## 범위(Scope)
- **전체 읽기:** <n> 파일, <n> 라인
- **훑어보기:** <n> 파일 (테스트 설정, API 컬렉션)
- **건너뛰기:** <n> 파일 (생성됨, 벤더됨)
- **도구 실행:** 타입체크: 통과 / n 오류; 린트: 통과 / n 경고; 빌드: 통과 / 실패; 테스트: <n> 통과, <n> 실패 (신규/기존); 감사: <n> 취약점
- (변경 모드): **기준 대비:** x 신규, y 악화됨, z 기존
## 우려 사항: <이름> (요청자가 지정한 경우에만)
## 발견 사항
각 발견 사항:
### F-001: [제목] — 심각도
- **위치:** <파일:라인>
- **무엇이 잘못됨:** <재현 시나리오 포함 한 문단>
- **증거:** 예 / 부분적 / 아티팩트 / 아니오 / 시도하지 않음
- **상태:** 공개 / 수용됨 / 수정됨 / 해결 불가
- **검증:** <명령어 출력, 쿼리 계획, 읽기/쓰기 목록>
Mid 또는 Low는 더 짧을 수 있지만 location과 scenario는 항상 포함하십시오.
## 잘된 점
- <구체적 증거와 함께>
## 변경 불가 권장 사항 (프로덕션 전용)
여기에서는 실행 없음 - 각 항목에는 정확한 명령어가 있습니다.
## 체크되지 않은 라이브러리 동작
- <라이브러리 및 확인되지 않은 측면>
PR/MR에서 업데이트 모드 작동 방식: --update는 기존 보고서 파일에 대해 다시 실행하는 것을 의미합니다. 각 이전 발견 사항을 다시 확인하십시오. 재현 가능하면 status를 fixed로 업데이트하십시오. 해결 불가능하면 wont-fix로 업데이트하십시오. 새로운 발견 사항은 새 ID를 받습니다. 변경 모드 PR 리뷰는 status를 사용하지 않지만, 댓글로 해결되었거나 수용되었음을 표시하십시오 - 이는 업데이트 모드에서 주워집니다.
10. 종료
- 리뷰 중인 저장소 또는 패키지를 방해하지 않은 채로 두십시오: 종속성 없음, 설치된 도구 없음, 수정된 파일 없음 (
git status가 이를 보여줍니다). - 1분 내에 제거 가능한 경우가 아니라면(스크래치 디렉토리), 임시 스크립트를 정리하십시오.
- 워크트리를 제거하십시오(
git worktree remove절대 잊지 마십시오). - 보고된 실패가 있는 경우 사용자에게 명령어가 실제로 실패했음을 알리십시오 - 생략하지 마십시오.